Debugging¶

llmcad includes built-in visual debugging tools designed for LLM feedback loops. The primary tool is snapshot(), which renders multi-view PNG images that LLMs can inspect.

snapshot¶

snapshot(
    body: Body,
    name: str,
    views: list[str] = None,
    output_dir: str = ".",
) -> str

Renders a multi-view snapshot and saves it as a PNG.

Parameter	Description
`body`	The Body to render
`name`	Filename (without `.png` extension)
`views`	List of views to render (default: `["front", "right", "top", "iso"]`)
`output_dir`	Directory to save the image (default: current directory)

Returns: Path to the saved image.

from llmcad import Box, snapshot

plate = Box(100, 60, 10, color="steel")
path = snapshot(plate, "my_plate")
# Saves: ./my_plate.png

Available views¶

View	Camera direction
`front`	Looking along +Y (seeing the -Y face)
`back`	Looking along -Y
`right`	Looking along -X (seeing the +X face)
`left`	Looking along +X
`top`	Looking along -Z (seeing the +Z face)
`bottom`	Looking along +Z
`iso`	Isometric view (from top-right-front)

Custom views¶

# Just front and iso
snapshot(plate, "two_views", views=["front", "iso"])

# All six orthographic views
snapshot(plate, "all_views", views=["front", "back", "right", "left", "top", "bottom"])

How rendering works¶

The body is tessellated using OpenCASCADE's BRepMesh_IncrementalMesh
Mesh faces are rendered with Phong shading using VTK
Edges are rendered as dark lines on top of the mesh
Views are arranged in a 2x2 grid (or single view if only one specified)
Each view has a gradient background with axis labels

show¶

show(body: Body, name: str = None)

Opens the body in the OCP CAD Viewer VSCode extension for interactive 3D viewing.

from llmcad import Box, show

plate = Box(100, 60, 10)
show(plate, "my plate")

Note

Requires the ocp_vscode package: pip install ocp_vscode

show_faces¶

show_faces(body: Body, name: str = "faces", output_dir: str = ".") -> str

Renders an isometric view and prints named face information.

from llmcad import Box, show_faces

plate = Box(100, 60, 10)
show_faces(plate)
# Prints:
# Named faces:
#   top: center=(0.0, 0.0, 5.0)
#   bottom: center=(0.0, 0.0, -5.0)
#   front: center=(0.0, -30.0, 0.0)
#   ...

show_edges¶

show_edges(body: Body, name: str = "edges", output_dir: str = ".") -> str

Renders an isometric view with edge information.

from llmcad import Box, show_edges

plate = Box(100, 60, 10)
show_edges(plate)
# Prints: Total edges: 12

measure¶

measure(a: Position, b: Position) -> float

Prints and returns the distance between two positions.

from llmcad import Box, measure

plate = Box(100, 60, 10)
measure(plate.top.center, plate.bottom.center)
# Prints: Distance: 10.000 mm

Debugging workflow for LLMs¶

A typical LLM debugging loop:

# 1. Build the model
plate = Box(100, 60, 10)
boss = extrude(Rect(30, 30).place_on(plate.top), amount=20)
plate = plate + boss

# 2. Take a snapshot to verify
snapshot(plate, "step1")
# LLM inspects step1.png

# 3. Check face names
print(plate)  # Body('plate', faces=['top', 'bottom', 'front', 'back', 'left', 'right', '_end'])

# 4. Continue building
hole = extrude(Circle(10).place_on(plate.top), through=True)
plate = plate - hole
snapshot(plate, "step2")
# LLM inspects step2.png

# 5. Measure to verify
measure(plate.top.center, plate.bottom.center)