create_sketch_on_face
Anchor a sketch to a body face by selecting it via centroid or intent. Draw geometry and extrude to create features like holes, pockets, or bosses.
Instructions
Croquis sobre cara — start a new sketch on a body face.
Unlike create_sketch (default planes only), this anchors a sketch to a face on an existing body. After this, draw geometry with create_circle / create_rectangle / create_line / create_slot, then close with extrude_sketch / extrude_cut — same as a default-plane sketch.
selector (recommended) — pick the face by INTENT instead of reading
list_faces() and copying a centroid, e.g. the top planar face:
create_sketch_on_face(selector={"filter": {"geom": "planar",
"normal_axis": "+z"}, "sort": {"axis": "z", "dir": "desc"},
"pick": "first"})
Closed schema: filter{geom:planar|cylindrical|conical|spherical|other|any,
body, normal_axis:+x/-x/+y/-y/+z/-z, axis:x|y|z + at_mm/tol_mm or
min_mm/max_mm, min_area_mm2/max_area_mm2}, sort{axis:x|y|z|area, dir},
pick:all|first|last|int|[int]. Must resolve to EXACTLY ONE face (add
pick:'first' or refine if it matches several). Mutually exclusive with
face_centroid_mm. The result echoes selector_matched {n, sample_points_mm}.
Args:
face_centroid_mm: [x, y, z] coords in mm — the centroid of the
target face. Get this from list_faces() — pass the
centroid_mm value verbatim. (Omit when using selector.)
Returns: - name: the new sketch's SW-assigned name (e.g., "Croquis5"). - face_centroid_mm: round-trip of the input centroid. - body_name: which body the face belongs to. - sketch_axis_mapping: dict mapping sketch (X, Y) coords to world coords (or None for cylindrical / non-planar faces). Use this to translate sketch-local positions to world coordinates without guessing — closes a real failure mode where the LLM assumed the wrong axis convention and built geometry in the wrong place.
Schema:
{
"sketch_x_world_direction": [x, y, z], # unit vector
"sketch_y_world_direction": [x, y, z], # unit vector
"sketch_origin_world_mm": [x, y, z], # world coords
# of sketch (0,0)
}Common autoparts use: counterbore on top of a flange, hole pattern on a bracket's side face, pocket on a sub-face from a previous cut.
Gotcha — extrude direction default after this call:
For raised features (hubs, bosses, sello salientes), the next
extrude_sketch call needs reverse_direction=True. The default
extrudes INTO the body (toward the inward normal — the cut/pocket
case). See extrude_sketch's reverse_direction arg.
Gotcha — sketch axis mapping is NOT intuitive on Y-normal faces:
For a face with normal +Y or -Y, sketch +Y maps to world ∓Z
(opposite sign of the face normal's Y component). Always read
sketch_axis_mapping from the response BEFORE drawing geometry
whose world position matters — don't assume sketch +Y = world +Z.
Failure modes: - centroid doesn't match any face within 0.01 mm → raises with hint to re-run list_faces. - centroid matches multiple faces → raises listing candidates; tighten the coordinate. - face is hidden / view occluded → IFace2.Select4 returns False; reorient the SW view and retry.
Example — Ø10 hole through the top face of a block: sk = create_sketch_on_face(selector=<top planar face — see above>) # read sk["sketch_axis_mapping"] before placing geometry create_circle(25, 25, 5) extrude_cut(end_condition="through_all")
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| selector | No | ||
| face_centroid_mm | No |