Jerry
106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# Modeling Workflows
|
|
|
|
## Modeling Mental Model
|
|
|
|
- Model the part as a sequence of intentional operations, not as one opaque final shape.
|
|
- Use the standard parts library first when a requested standard component is available and does not need complex custom geometry changes.
|
|
- Start from profiles and reference geometry, then create solids with features such as extrude, revolve, loft, and sweep.
|
|
- Use booleans and detail features after the base form is clear: cut openings, union intended merged bodies, then apply fillets, chamfers, or shell operations.
|
|
- Use `GraphSession` whenever the result should be replayable, inspectable, serialized, or translated.
|
|
- Use QL for grounding and selection. Query the facts you need, such as face normals, centers, areas, edge lengths, curve types, and tags.
|
|
- Use indexed child-geometry getters such as `get_edges(index)` and `get_faces(index)` when an indexed topology pick is intentional.
|
|
- Use semantic tags for design intent and anchors. Keep numeric measurements and geometry facts in metadata or model JSON payloads.
|
|
- Treat `export_model_json()` as the interchange boundary for replay and CAD translation.
|
|
- Validate incrementally: after each major step, print small QL-derived facts such as selected face count, top face center, edge count, volume, or replay result count.
|
|
|
|
## 1) Capture a replayable modeling flow
|
|
|
|
```python
|
|
from simplecadapi import GraphSession, export_model_json
|
|
|
|
with GraphSession() as session:
|
|
...
|
|
|
|
payload = export_model_json(session=session)
|
|
```
|
|
|
|
## 2) Import and use in Python
|
|
|
|
```python
|
|
import simplecadapi as scad
|
|
from simplecadapi import GraphSession, export_model_json
|
|
```
|
|
|
|
## 3) Keep replay payloads as the interchange boundary
|
|
|
|
- Prefer `export_model_json()` output instead of hand-written payloads.
|
|
- Use `replay_model_json()` when you need deterministic reconstruction.
|
|
- Use `import_model_json()` when consuming previously exported payloads.
|
|
|
|
## 4) Use standard parts when they fit
|
|
|
|
```python
|
|
import simplecadapi as scad
|
|
|
|
gear = scad.std.gear.make_spur_gear_rsolid(
|
|
n_teeth=24,
|
|
module=1.5,
|
|
gear_height=8.0,
|
|
)
|
|
rack = scad.std.gear.make_spur_rack_rsolid(module=1.5, n_teeth=18)
|
|
bearing = scad.std.bearing.make_ball_bearing_rassembly(
|
|
8.0,
|
|
22.0,
|
|
7.0,
|
|
3.5,
|
|
)
|
|
```
|
|
|
|
- Read `references/docs/stdlib/README.md` before hand-modeling a standard mechanical part.
|
|
- Use `references/docs/stdlib/<function_name>.md` for exact standard-library signatures.
|
|
- Continue with core geometry APIs when the standard part requires substantial custom geometry beyond the provided parameters.
|
|
|
|
## 5) QL-grounded feature workflow
|
|
|
|
```python
|
|
import simplecadapi as scad
|
|
from simplecadapi import ql
|
|
|
|
with scad.GraphSession() as session:
|
|
profile = scad.make_circle_rface(center=(0, 0, 0), radius=1.0)
|
|
body = scad.extrude_rsolid(
|
|
profile=profile,
|
|
direction=(0, 0, 1),
|
|
distance=4.0,
|
|
)
|
|
end_face = (
|
|
ql.faces()
|
|
.where(ql.tag("face.extrusion.end"))
|
|
.exactly(1)
|
|
.resolve(body)[0]
|
|
)
|
|
print("end face center", end_face.get_center())
|
|
path = scad.make_segment_rwire(start=(0, 0, 4), end=(0, 0, 8))
|
|
swept = scad.sweep_rsolid(profile=end_face, path=path)
|
|
|
|
payload = scad.export_model_json(session=session)
|
|
rebuilt = scad.replay_model_json(json_str=payload)
|
|
print("rebuilt", len(rebuilt))
|
|
```
|
|
|
|
## 6) Selection and tag discipline
|
|
|
|
- Prefer QL selectors for semantic/geometric feature input selection.
|
|
- Use `get_edges(index)`, `get_faces(index)`, `get_wires(index)`, or `get_vertices(index)` for intentional indexed picks in examples.
|
|
- Attach semantic tags with `apply_tag(shape=..., tag=...)` and inspect with `list_tags(shape=...)`.
|
|
- Use tags for intent, roles, anchors, groups, and topology names.
|
|
- Store dimensions, positions, measured geometry, and descriptive payloads in metadata or model JSON, not in tags.
|
|
- Keep QL result prints concise: selected count, centers, normals, areas, lengths, or tags.
|
|
|
|
## 7) Boolean and body discipline
|
|
|
|
- Use `union_rsolid(...)` when multiple solids should become one integrated body.
|
|
- Ensure bodies that should union into one solid have real geometric overlap or embedding.
|
|
- Use `cut_rsolid(...)` for subtractive features and `intersect_rsolid(...)` for common-volume workflows.
|
|
- Validate body count and volume after major boolean operations.
|