Mesh & visualization

Tools for converting B-rep bodies into triangle meshes, decimating those meshes, rendering headless PNG previews of the scene, ray-casting a pixel back to a world-space surface point, and producing multi-view ISO 128-30 DXF technical drawings. Reach for this family when you need a visual snapshot, a lightweight mesh export, or a production drawing.

Tools

generate_mesh · simplify_mesh · render_preview · signed_deviation_heatmap · overlay_render · pick_surface_point · generate_drawing

generate_mesh

Tessellate a scene body into triangles and return quality metrics; optionally write the mesh to .stl or .obj.

Server: Swift + Node

Parameters

Returns — Quality metrics (triangle count, min/max edge length, etc.). If outputPath is given, the mesh file is written. If returnGeometry is true, vertex + triangle data is included in the response.

Example

// tool call arguments
{ "bodyId": "part", "linearDeflection": 0.1, "outputPath": "/tmp/part.stl" }

// example result
{
  "triangleCount": 1248,
  "minEdgeLength": 0.08,
  "maxEdgeLength": 3.4,
  "outputPath": "/tmp/part.stl"
}

Drives — OCCTSwiftMesh tessellation pipeline; OCCTSwift BREP → mesh bridge.

simplify_mesh

QEM mesh decimation via OCCTSwiftMesh (vendored meshoptimizer). Outputs .stl or .obj.

Server: Swift + Node

Parameters

Returns — Triangle count before and after, achieved Hausdorff distance, and the written outputPath.

Example

// tool call arguments
{
  "bodyId": "housing",
  "outputPath": "/tmp/housing_lod.obj",
  "targetReduction": 0.7,
  "preserveBoundary": true
}

// example result
{
  "inputTriangles": 8400,
  "outputTriangles": 2520,
  "hausdorffDistance": 0.22,
  "outputPath": "/tmp/housing_lod.obj"
}

Drives — OCCTSwiftMesh QEM decimator (meshoptimizer).

render_preview

Headless Metal render of the current scene (or a named subset of bodies) to a PNG file. Overlays sidecar annotations (dimensions, primitives, bounding boxes, diff markers) and renders measurement labels.

Server: Swift + Node

Parameters

Returns — Path to the written PNG and image dimensions. Returns an error if the scene is empty or Metal is unavailable.

Notes — Mesh-scale bodies (imported STL/OBJ scans; more than 10k B-rep edges) take a linear tessellation path (#75): an STL lands as one face per facet, and the standard bridge’s per-edge extraction is quadratic in edge count — hours at scan scale. Edge overlays are kept up to 100k edges via OCCTSwift’s bulk allEdgePolylines (O(edges), OCCTSwift#275); beyond that, bodies render surface-only regardless of displayMode — at that facet density wireframe is visual noise anyway. pick_surface_point and overlay_render apply the same rule.

Example

// tool call arguments
{
  "outputPath": "/tmp/preview.png",
  "options": {
    "camera": "iso",
    "displayMode": "shadedWithEdges",
    "background": "light",
    "width": 1200,
    "height": 900
  }
}

// example result
{
  "outputPath": "/tmp/preview.png",
  "width": 1200,
  "height": 900
}

Notes — Pass the same options.camera / width / height values to pick_surface_point so pixel coordinates map to the same ray. Annotation overlays read from annotations.json in the output directory.

Drives — OCCTSwiftViewport OffscreenRenderer; OCCTSwiftTools Shape → ViewportBody bridge; AnnotationsRenderer for sidecar overlays.

signed_deviation_heatmap

Render fromBodyId’s surface coloured by signed distance to referenceBodyId — proud (over-build) red, on-target near-white, shy (under-build) blue — via a diverging colormap with a colorbar legend (#63). Shows exactly where a reconstruction departs, which a scalar deviation can’t. Swift-only.

Server: Swift

Parameters

Returns — { outputPath, bands, triangles, clamp, signMode, signedMin, signedMax, signedMean, ambiguousTriangles, ambiguousFraction }. The signed trio is null when every triangle rendered grey.

Notes — Colours track the signed distance to the surface each triangle corresponds to, which against an open, thin-walled reference is not always the nearest one — see Which way is out? for why, and why signMode defaults to robust (#72).

Triangles whose sign can’t be established render grey rather than a guessed red/blue, are excluded from signedMin / signedMax / signedMean, and are counted in ambiguousTriangles / ambiguousFraction. That happens where a comparably-close reference triangle disagrees on the side (a genuine tie), where robust finds no normal-compatible reference surface in reach, or where the triangle’s own normal is degenerate. A mostly-grey render means trust the magnitude (or cross_section_compare), not this tool’s sign; an ambiguousFraction of ~1.0 usually means the reference’s winding is inverted relative to the candidate.

overlay_render

Render the reference mesh (meshBodyId, semi-transparent amber) superimposed over the opaque candidate solid (solidBodyId, steel-grey) — see in 3D exactly where the reconstruction departs from the source mesh (#63). Swift-only.

Server: Swift

Parameters

Returns — { outputPath } (plus render metadata). Pairs naturally with import_file(format: "stl") to bring the reference mesh in first.

pick_surface_point

Cast a ray through pixel (screenX, screenY) of a render_preview-framed view and return the nearest world-space surface point on a body, plus the bodyId and a selectionId.

Server: Swift only

Parameters

Returns — World-space point [x, y, z], bodyId, and selectionId. The selectionId is a valid anchor for add_dimension, enabling you to measure to an arbitrary surface point rather than a topology centroid.

Example

// tool call arguments
{
  "screenX": 612,
  "screenY": 480,
  "options": { "camera": "iso", "width": 1200, "height": 900 }
}

// example result
{
  "point": [12.4, 0.0, 8.7],
  "bodyId": "part",
  "selectionId": "sel:part#surfacePoint[0]"
}

Notes — Always pass the same options that were used in the preceding render_preview call; mismatched framing will produce incorrect world coordinates. The returned selectionId can be passed directly to add_dimension as an anchor.

generate_drawing

Render a multi-view ISO 128-30 DXF technical drawing. Pass bodyId for a single-part drawing with sections and dimensions, or bodyIds (two or more bodies) for a general-arrangement assembly sheet with a parts list and numbered balloons.

Server: Swift + Node

Parameters

Returns — Path to the written .dxf file and a summary of views generated. Returns an error if neither bodyId nor bodyIds resolves to a loaded body.

Example

// tool call arguments
{
  "bodyId": "bracket",
  "outputPath": "/tmp/bracket.dxf",
  "spec": {
    "sheet": "A3",
    "title": "Bracket — Rev A",
    "views": ["front", "top", "right", "iso"]
  }
}

// example result
{
  "outputPath": "/tmp/bracket.dxf",
  "views": ["front", "top", "right", "iso"],
  "bodyCount": 1
}

Notes — For assembly sheets (bodyIds), per-view sections and dimensions in the spec are ignored; the sheet receives a shared multi-body view with an auto-generated parts list and one balloon per body. bodyIds takes precedence over bodyId when both are supplied.

Drives — DrawingComposer (from OCCTSwiftScripts); ISO 128-30 projection engine in OCCTSwift.