Sketch from Image

Convert an image (drawing, sketch, reference photo, technical drawing) into a FreeCAD sketch by identifying its geometric shapes and creating a sketch with equivalent geometry.

When to use

• User has attached an image and says "create a sketch from this", "trace this shape", "make a sketch of this", or similar.
• User wants a starting point for CAD work from a visual reference.

Required user inputs (ask if missing)

1. Bounding size in mm — the real-world size the sketch should occupy. Ask as: "What size (in mm) should this sketch be? Provide either the overall width or height." Example: "width 40mm" or "height 25mm".
2. Plane — default XY if not specified. Accept XY, XZ, YZ.
3. Body name — if the user wants the sketch on an existing body. Default: no body (standalone sketch).

Do NOT guess the size. Without a real dimension, the sketch is useless for CAD.

Extraction procedure

Look at the attached image (or the textual description if no image is present) and identify the 2D shapes. For each shape, record:

• Shape type: rect, circle, polygon, or line
• Position and size, scaled so that the overall bounding box matches the user-provided dimension (width OR height; preserve aspect ratio)

Scaling rule

1. Measure the image's apparent bounding box in pixels (or relative units).
2. Compute scale = user_dimension_mm / measured_dimension_pixels.
3. Multiply every coordinate and radius by scale.
4. Flip Y-axis if the source uses Y-down (SVG, screen pixels, most image formats). FreeCAD sketches use Y-up. Negate all Y coordinates after scaling.
5. Translate so the sketch is centered around origin (or anchored at 0,0 — state which).

Shape JSON schema (internal — use this shape before calling the tool)

{
  "shapes": [
    {"type": "rect",    "x": 0, "y": 0, "width": 40, "height": 25},
    {"type": "circle",  "cx": 20, "cy": 12.5, "r": 3},
    {"type": "polygon", "points": [[0,0], [10,0], [5,8]]},
    {"type": "line",    "x1": 0, "y1": 0, "x2": 10, "y2": 10}
  ],
  "dimensions": [],
  "notes": "brief description of what was recognized"
}

The dimensions array is reserved for future use (auto-constraint from measured values in technical drawings). Leave it [] for now.

Output

After deriving the JSON, call create_sketch with the shapes. Do NOT add constraints — rectangles and circles are auto-constrained. Example:

create_sketch(
  plane="XY",
  geometries=[
    {"type": "rectangle", "x": 0, "y": 0, "width": 40, "height": 25},
    {"type": "circle", "cx": 20, "cy": 12.5, "radius": 3}
  ]
)

For line shapes, emit them as polygons with two points, since create_sketch groups connected line segments into a polygon.

After creating the sketch

Briefly report:

• Shapes created (count per type)
• Final bounding size
• Any shapes you couldn't confidently identify — list them so the user can clarify or re-attach a clearer image.

Do NOT pad, pocket, or otherwise extrude the sketch unless the user explicitly asks — this skill only produces the 2D profile.

Iterating on the sketch

If the user wants to adjust the sketch after initial creation, use edit_sketch.

For resizing, moving, or replacing geometry (most common), use clear_all=true and provide the complete updated geometry:

edit_sketch(sketch_name="MySketch", clear_all=true, add_geometries=[
    {"type": "rectangle", "x": 0, "y": 0, "width": 50, "height": 30},
    {"type": "circle", "cx": 6, "cy": 6, "radius": 3}
])

This clears all old geometry and constraints, then adds fresh geometry — no over-constraint issues. The sketch object, plane attachment, and body membership are preserved.

For adding new geometry to existing (e.g. "add a second hole"): edit_sketch(sketch_name, add_geometries=[...])

For changing dimensions (e.g. "make it 50mm wide"): use clear_all=true with updated geometry coordinates — dimensions are auto-constrained from the geometry. Do NOT manually add DistanceX/DistanceY/Radius constraints.

Limitations (mention if relevant)

• Curves and splines are approximated as polygons; for complex curves the user should trace manually or use a dedicated tracing tool.
• Dimension lines and annotations in the image are ignored in v1 (will be supported in a future version via the dimensions array).
• Hidden lines, section lines, and construction lines are treated as regular geometry. If the image uses drafting conventions, warn the user.