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

> Learn to use build123d selectors for topology in text-to-cad. This guide explains how to embed CAD topology data in GLB files for precise edge-level picking and highlighting in your viewer.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-07-22

---

**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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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.

```python
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.

```python
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.

```python
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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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.