version: "1.0.0" name: freecad-sketch description: >- Build constrained 2D PartDesign sketches: create a sketch on a named plane, add typed geometry, add geometric and dimensional constraints, and read back degrees of freedom before the sketch is used as a feature profile. Use after freecad-session has created or inspected a durable FCStd document. license: MIT compatibility: "Python 3.7+; FreeCAD 1.0.x or 1.1.x (see compat_matrix.json); meshy-dcc-core 0.2.x" allowed-tools: "python" metadata: meshy-dcc: dcc: freecad layer: domain version: "0.1.0" tags: [freecad, cad, parametric-modeling, sketch, constraints] depends: [freecad-session] search-hint: >- FreeCAD PartDesign sketch create geometry rectangle circle line arc point constraint coincident horizontal vertical parallel perpendicular tangent concentric radius distance angle degrees of freedom DOF fully constrained tools: tools.yaml

FreeCAD Sketch

Build a parametric profile the typed way: create_sketch attaches a Sketcher::SketchObject to a datum plane inside a PartDesign::Body, add_sketch_geometry adds typed elements, add_sketch_constraint constrains them, and get_sketch_info reports what the solver thinks of the result.

Constraints are not optional decoration. The adapter accepts no arbitrary Python, so there is no way to repair a sketch afterwards: an under-constrained sketch solves differently on the next host version, which is why get_sketch_info reports dof and feature_ready and why a sketch with unconstrained degrees of freedom is never reported as usable for a feature.

Arc direction

An arc is specified by start_angle_degrees and end_angle_degrees, and the pair must be ascending: start is below end, and the arc is swept from start to end anticlockwise.

A descending pair is refused, not reinterpreted. FreeCAD stores an arc's parameter range in ascending order and cannot record which end you called the start, so a 90 -> 0 request would come back as the complementary 270° arc — with both endpoints looking exactly as requested while the body of the arc runs the other way round. The restated pair expresses the same arc:

The read-back compares the start point, the midpoint and the end point, so an arc is only ever reported as stored if all three match. An arc whose start and end land on the same point is refused — use circle for a full turn.

Constraints are the contract

• dof counts unconstrained degrees of freedom. feature_ready is true only

when dof is 0 and the sketch contains geometry.

• A constraint that references an element index which does not exist is refused

with sketch_element_not_found. Nothing is silently dropped.

• A constraint applied to geometry that cannot carry it (a radius on a line, a

horizontal on a circle) is refused rather than reinterpreted.

• Pass require_fully_constrained=true to get_sketch_info to turn an

under-constrained sketch into an explicit error carrying the error code instead of a report the caller has to interpret.

• A host that will not report degrees of freedom yields dof: null and

feature_ready: false, never a zero that was not measured.

Every mutation runs on a staging copy and replaces the document only after the write has been read back, so a failed sketch edit leaves the original bytes untouched.