How to Use build123d Selectors for Topology in text-to-cad

text-to-cad embeds selectable topology information—including edges, faces, and custom selector meshes—inside GLB artifacts using the add_step_topology helper in cadpy/glb.py, enabling the CAD Viewer to perform edge-level picking and highlighting through the selectorView buffer.

The text-to-cad repository provides a sophisticated pipeline for converting STEP files into web-ready GLB models with interactive topology support. By leveraging build123d selectors for topology, developers can embed lightweight selector meshes that map specific geometric features—such as mounting holes or flange edges—to interactive UI elements. This capability is implemented through the cadpy package, which writes selector data directly into GLB extensions for consumption by the CAD Viewer. High-level integration patterns are documented in skills/cad/references/build123d-modeling.md, which details how the CAD skill invokes the GLB builder with topology flags enabled.

Understanding the Selector Topology Pipeline

The topology system centers on the add_step_topology function located in viewer/packages/cadpy/src/cadpy/glb.py. This utility writes a dedicated selector buffer—internally referred to as the I23d selector layer—into the GLB's STEP_topology extension. When you enable selector topology, the builder creates a selectorView manifest that maps selector IDs to specific mesh primitives, allowing the CAD Viewer to resolve user clicks to exact geometric entities like individual edges or named face groups.

The selector geometry remains physically separate from the main render mesh. According to the source code, this separation ensures that selector meshes (often rendered as lines or thin planes) do not penalize standard rendering performance while still providing barycentric-encoded edge IDs for precise hover detection.

Configuring StepArtifactSpec for Selector Output

To initiate the selector workflow, you must first define a StepArtifactSpec that declares your intent to generate topology data. This specification object, imported from cadpy.step_artifact, acts as the blueprint for the GLB generation process.

The critical flags for enabling build123d selectors are topology=True and selector=True. When both are set, the pipeline understands that the output GLB must contain the selectorView extension alongside the standard geometry buffers.

from cadpy.step_artifact import StepArtifactSpec
from pathlib import Path

spec = StepArtifactSpec(
    cad_ref="my_part",
    step_path=Path("models/my_part.stp"),
    output_format="glb",
    topology=True,
    selector=True,
)

Building GLB Files with Selector Topology

Once your specification is defined, you can generate the GLB using either the high-level API or the low-level builder functions. Both approaches require the include_selector_topology=True parameter to ensure the I23d selector buffer is written to the final artifact.

High-Level API: build_glb

The simplest approach uses the build_glb function from cadpy.glb. This method accepts your StepArtifactSpec and handles the entire conversion pipeline, including the injection of selector meshes.

from cadpy.glb import build_glb

glb_path = build_glb(
    spec,
    include_selector_topology=True,
)

When include_selector_topology is enabled, build_glb internally invokes add_step_topology to append the selectorView buffer to the GLB's STEP_topology extension.

Low-Level API: add_step_topology

For scenarios requiring manual control—such as adding selectors to existing GLB files or customizing the selector manifest—you can use the add_step_topology function directly. This approach requires constructing a SelectorBundle that encapsulates both the manifest metadata and the selector mesh geometry.

from cadpy.glb import add_step_topology, SelectorBundle

bundle = SelectorBundle(
    manifest={"selectorView": {"version": 1}},
    selector_meshes=my_selector_meshes,  # List of (name, trimesh) pairs

)

add_step_topology(
    glb_path,
    bundle,
    include_selector_topology=True,
)

Viewer Integration and Validation

The CAD Viewer automatically detects and consumes the selectorView extension when present in the GLB. As documented in packages/cadpy/docs/render-pipeline.md, the viewer's render pipeline reads the STEP_topology extension to map selector IDs to interactive UI elements, enabling features like edge-highlighting on hover and custom dropdown menus for named selectors (e.g., "mount_holes" or "flange_edges").

Validation of the selector topology occurs in viewer/packages/cadpy/src/cadpy/step_targets.py. This module raises a missing_selector_topology error if the selectorView extension is absent when selectors are requested, ensuring that downstream components receive the expected topological data.

Summary

• build123d selectors for topology are embedded via the add_step_topology helper in viewer/packages/cadpy/src/cadpy/glb.py.
• Enable selector generation by setting topology=True and selector=True in your StepArtifactSpec.
• Pass include_selector_topology=True to build_glb or add_step_topology to write the I23d selector layer.
• The viewer consumes selector data through the selectorView buffer inside the STEP_topology GLB extension.
• Validate selector presence using the logic in step_targets.py to prevent runtime errors in the CAD Viewer.

Frequently Asked Questions

What is the I23d selector layer?

The I23d selector layer is the internal name for the selector mesh buffer embedded within GLB artifacts. According to the text-to-cad source code, this layer contains lightweight geometry—often lines or thin planes encoded with barycentric edge IDs—that enables the CAD Viewer to perform precise edge-level picking without affecting the main model's rendering performance.

How does the selectorView extension work?

The selectorView extension is a JSON manifest stored within the GLB's STEP_topology extension block. It maps unique selector IDs to specific mesh primitives, allowing the CAD Viewer to translate user interactions (like mouse clicks) into selections of specific geometric entities such as individual edges or named face groups.

Can I add selectors to existing GLB files?

Yes. Using the low-level add_step_topology API, you can inject selector topology into pre-existing GLB binaries. Construct a SelectorBundle containing your selectorView manifest and selector mesh geometry, then call add_step_topology with include_selector_topology=True to append the data.

Where is selector topology validated?

Selector topology validation occurs in viewer/packages/cadpy/src/cadpy/step_targets.py. This module checks for the presence of the selectorView extension and raises a missing_selector_topology error if the selector data is absent when required by the viewer configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}