Selection & remap

These tools let an LLM pick faces, edges, or vertices on scene bodies and carry those picks forward across mutations, transforms, and pattern instances. All six tools are Swift only — the Node server does not expose them.

Tools

• select_topology · remap_selection · find_correspondences · select_by_feature · list_selections · clear_selections

select_topology

Pick faces, edges, or vertices on a scene body matching optional filter criteria. Mints and registers server-tracked selectionIds in the format sel:<bodyId>#<kind>[<idx>].

Server: Swift only

Parameters

Returns — Array of selectionId strings plus an anchor snapshot (centroid, kind, index) for each matched entity. The registry retains these until clear_selections is called or the session ends.

Example

// tool call arguments
{ "bodyId": "part", "kind": "face", "filter": { "surfaceType": "plane", "normalDirection": [0, 0, 1], "normalTolerance": 5.0 }, "limit": 1 }

// example result
{
  "selections": [
    {
      "selectionId": "sel:part#face[2]",
      "kind": "face",
      "index": 2,
      "centroid": [0.0, 0.0, 10.0],
      "surfaceType": "plane"
    }
  ]
}

Notes — selectionIds produced here can be passed directly to add_dimension, remap_selection, and find_correspondences. Use list_selections to review all live picks.

remap_selection

Remap one or more selectionIds to their post-mutation equivalents on the same body. Uses history-backed resolution (exact, zero-distance) for tools that record topology history (transform_body, heal_shape, boolean_op, apply_feature); falls back to a closest-centroid heuristic for all other mutations.

Server: Swift only

Parameters

Returns — For each input selectionId: zero or more new selectionIds plus a fate string ("preserved" | "approximate" | "lost"). Fate is "preserved" when history confirms an exact match, "approximate" for centroid-heuristic matches, "lost" when no post-mutation entity falls within the tolerance.

Example

// tool call arguments
{ "selectionIds": ["sel:part#face[2]"] }

// example result
{
  "remapped": [
    {
      "input": "sel:part#face[2]",
      "outputs": ["sel:part#face[2]"],
      "fate": "preserved",
      "confidenceMm": 0.0
    }
  ]
}

Notes — This tool handles the within-body case only. To carry a pick from a source body onto a mirrored or patterned copy, use find_correspondences.

find_correspondences

Map selectionIds from a source body onto a target body that is a known transform of the source (typically a mirror_or_pattern output). Applies an optional explicit transform to each source anchor centroid, then nearest-neighbour searches among the target’s topology.

Server: Swift only

Parameters

transform sub-fields

Returns — For each source selectionId: one target selectionId (or null) plus confidenceMm and fate ("matched" | "lost").

When transform is omitted, resolution falls back to provenance metadata recorded by mirror_or_pattern (stored in provenance.json), then to bbox-translation inference, and finally to an identity fallback. The response includes a transformSource field indicating which path resolved ("explicit" | "provenance" | "bbox-inference" | "identity-fallback").

Example

// tool call arguments
{
  "sourceSelectionIds": ["sel:part#face[2]"],
  "targetBodyId": "part_mirror",
  "transform": {
    "kind": "mirror",
    "planeOrigin": [0, 0, 0],
    "planeNormal": [1, 0, 0]
  }
}

// example result
{
  "transformSource": "explicit",
  "correspondences": [
    {
      "source": "sel:part#face[2]",
      "target": "sel:part_mirror#face[5]",
      "confidenceMm": 0.0,
      "fate": "matched"
    }
  ]
}

Notes — For within-body remapping after a mutation, use remap_selection instead. Linear and circular pattern outputs produce N copies; provenance is not written for them, so supply an explicit transform or rely on bbox-translation inference.

select_by_feature

Run AAG feature recognition on a body and register a selectionId for each detected hole or pocket, without requiring a prior query_topology call.

Server: Swift only

Parameters

Returns — Array of selectionIds (one per detected feature instance) plus metadata (kind, representative face indices). The picks are registered in the SelectionRegistry and can be forwarded directly to add_dimension.

Example

// tool call arguments
{ "bodyId": "bracket", "kinds": ["hole"] }

// example result
{
  "selections": [
    { "selectionId": "sel:bracket#face[4]", "featureKind": "hole" },
    { "selectionId": "sel:bracket#face[7]", "featureKind": "hole" }
  ]
}

Drives — AAG feature recognition (same engine as recognize_features).

list_selections

Return every active selectionId held in the SelectionRegistry together with its anchor metadata. A cheap introspection call — useful when the session context no longer holds the original pick results.

Server: Swift only

No parameters.

Returns — Array of entries, each with selectionId, bodyId, kind, index, and centroid. Returns an empty array when the registry is clear.

Example

// tool call arguments
{}

// example result
{
  "selections": [
    {
      "selectionId": "sel:part#face[2]",
      "bodyId": "part",
      "kind": "face",
      "index": 2,
      "centroid": [0.0, 0.0, 10.0]
    }
  ]
}

clear_selections

Drop every selectionId from the SelectionRegistry. Any existing selectionId strings become invalid after this call.

Server: Swift only

No parameters.

Returns — { "cleared": <count> } — the number of entries removed.

Example

// tool call arguments
{}

// example result
{ "cleared": 3 }