create_sketch_on_face

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")