Sketches and workplanes

CadFlow separates coordinate context from geometry. A Workplane converts local points and vectors into the model frame; it never mutates an existing shape. A SketchDocument stores declarative 2D entities and constraints, and lowers a solved profile to native geometry only when requested.

Construct on a local plane

import cadflow as cad


with cad.Model() as model:
    with model.workplane(
        origin=(10, 0, 5),
        normal=(0, 1, 0),
        x_dir=(1, 0, 0),
    ) as plane:
        wire = plane.polyline(
            ((0, 0, 0), (30, 0, 0), (30, 15, 0), (0, 15, 0)),
            closed=True,
        )
        face = model.face(wire)
        body = plane.extrude(face, (0, 0, 8))

Local Z is the plane normal. plane.point() and plane.vector() are useful when a mixed workflow needs explicit world coordinates.

Create a constrained sketch

Sketch documents are immutable values: each method returns an updated document.

with cad.Model() as model:
    with model.workplane(origin=(10, 0, 5), normal=(0, 1, 0)) as plane:
        sketch = plane.sketch("mounting_profile")
        sketch = sketch.add_point("a", 0, 0).add_point("b", 20, 0)
        sketch = sketch.add_point("c", 20, 10).add_point("d", 0, 10)
        sketch = (
            sketch.add_line("ab", "a", "b")
            .add_line("bc", "b", "c")
            .add_line("cd", "c", "d")
            .add_line("da", "d", "a")
            .constrain_horizontal("ab")
            .constrain_vertical("bc")
            .constrain_fix("a")
        )

        result = sketch.inspect(strict=False)
        assert result.status in {"solved", "underconstrained"}
        face = sketch.to_native_face(model, strict=False)

    body = model.extrude(face, 0, 8, 0)

Use strict=True when underconstrained sketches must stop the pipeline. During interactive or agent-driven repair, strict=False exposes solver diagnostics while preserving inspectable state.

Constraint vocabulary

The public sketch layer supports geometric and dimensional relationships:

Type	Examples
Incidence	coincident, connect, point-on, midpoint
Orientation	horizontal, vertical, parallel, perpendicular, collinear
Curves	tangent, concentric, equal radius
Symmetry	symmetric, equal length
Dimensions	distance, X/Y distance, length, angle, radius, diameter
Grounding	fix

Lowering boundary

Constraint solving remains in Python through py-slvs; OpenCascade construction remains in the native session. Native lowering currently handles circle and line-loop profiles directly. Use the complete compatibility path for richer arc or B-spline sketch profiles that are not yet covered by the small native facade.

Practical guidance

• Name points, entities, and sketches for useful diagnostics.
• Inspect solver status before lowering a sketch.
• Fix only enough geometry to remove rigid-body freedom; avoid redundant constraints.
• Keep the workplane attached to the same Model that receives the native face.
• Treat the sketch document as source state and the resulting Shape as derived geometry.