Equipment Topology Column
The Topology column is the Equipment page's fourth column: the whole authored equipment — machine tool, fixture, workpiece and tool — drawn as one anchor / branch graph, with an editor card below it for whichever anchor, branch or assembly is picked. It is where a part's anchors, branches, transformers and solids are authored; the Control Tree's three mechanism items only bind roles — which of a part's own anchors and branches play its Table Mount, its Geometry Anchor, its Axis X — and a role armed there is bound by clicking its element in this graph. It has one surface:
- the rightmost column of the Equipment page (
/equipment), titled Topology. It carries no?tree=id of its own: the graph is not a Control-Tree branch, and a part's cluster in it is a shortcut to that part's tree item.
The column order is TREE | EDITOR | CANVAS | TOPOLOGY, one column-toggle button each in the menu
bar's column-button row — the fourth button, titled “Toggle the Topology column”. Its first-run
visibility follows the window — shown on one at least 1280 px wide, hidden on a narrower one — and
is stored with the rest of the device-local view preferences at their next write; a stored bit wins
whatever the window is afterwards. Its width is device-local (the topologyColPx view preference,
default 420 px) and it is pinned to 0 px rather than unmounted while hidden, so the graph keeps its
selection and scroll.
When the canvas is hidden and the Topology column shown, the column takes the canvas's width.
- Key Model:
- SetupEquipment — the authored equipment face (SetupEquipment), whose parts and attachments the graph draws and every edit lands on in place.
- GeneralXyzabcMachineTool, Fixture,
Workpiece — the three editable parts. Each owns an assembly
(
Asmb,Root,AnchorToSolid) and names its roles as settable anchor or branch properties: the machine's TableMount, ToolMount, AxisX …AxisCand Spindle; the fixture's TableMount, WorkpieceMount and GeomAnchor; the workpiece's FixtureMount, ProgramZeroAnchor and GeomAnchor. A transformer lives on a branch —Branch.Get(fixture.GeomAnchor, fixture.TableMount).Transformer— never on the part. - Asmb, Anchor, Branch — the topology primitives every cluster, node and edge of the graph stands for.
- IsErrorTerm — the error-term mark, which the Error term option
on the card of an axis's or the spindle's branch sets on the branch it inserts just before that
one, the role's error term: the controller solves on a copy of the machine in which every
marked branch is
NoTransform, and the machine runs with the marked branches while the project's error-term switch is on (see Error-Term Branches).
- Assistant Model:
- Rewire — rebuilds the attachment branches between the parts whole after every edit; the worktable attachment carries TableToComp.
- NotifySetupEquipmentEdited — lets the runtime face, its solver and axis configuration follow the authored edit.
- EnableErrorTerms — the project's error-term switch, set on the Machine Tool item and carried by the graph; a write is a setup edit the runtime face follows like any other.
Layout
Title Bar
- Refresh — an icon button (tooltip Refresh) at the right end of the column's title bar, spinning while a pull is in flight and disabled while an edit is; re-pulls the graph and every part's roles.
Armed-Role Strip
A strip between the title bar and the graph, shown only while a role is armed on a Roles panel: a chip reading "Pick {element} in the {owner} to bind {role}.", removable to disarm.
Graph
The graph is drawn by the graph view MechBuilderGraph.vue, whose name is historical. Every
assembly with an anchor somewhere below it is a cluster titled with the assembly's name, nested as
the assemblies nest: the equipment's own assembly (SetupEquipment) outermost and untagged, one
cluster per part inside it — the part's key assembly, its title tagged Machine Tool,
Fixture, Workpiece or Tool — and a part's sub-assemblies inside that. Above the graph
sits the graph view's own toolbar — the flow direction (top-down or left-to-right), zoom out, the
scale (a click returns to actual size), zoom in and fit to width — and the graph scrolls in its own
region, which a drag pans once the graph overflows it. A height divider under the graph sets its
height (the device-local topologyGraphPx view preference, default 320 px); the editor card below
it takes the rest.
- The tool is not edited here: its cluster holds only its assembly clusters and the anchor its attachment reaches, never its own anchors and branches.
- An anchor bound to a role carries a badge under its label naming the part and the role in the UI language — Fixture · Table Mount, Machine Tool · Tool Mount — and an outlined node style; a branch bound to an axis or the spindle carries its badge too (Machine Tool · Axis X). The badges are gathered from every part, not only from the part the element belongs to, so an element more than one part points at shows one badge per part.
- A part's own branch is a solid edge and an attachment between parts a dotted one. An edge is
labelled
name (transformer type), the transformer type alone when the branch has no name, and Attachment when it has neither. - A branch marked as an error term is a thick edge with an orange badge in its label reading
Error term. While the project's error-term switch is off, the badge is outlined and reads
Error term (not in effect), and the edge stays thick. The mark never colours the edge, so a
selected marked branch takes the selection's colours like any other. The graph carries the switch
(
errorTermsEnabled), so every pull draws the badges in its current state. - Clicking an anchor selects it and opens the anchor editor; clicking a branch selects it and opens the branch editor; clicking a cluster selects that assembly and — when it belongs to the machine tool, fixture or workpiece — moves the Control Tree to that part's mechanism item, so its Roles panel sits beside the graph. The three selections are mutually exclusive.
- With no project open the graph area reads “Open a project to see its equipment topology.”
Editor Card — Anchor
Header: the title Anchor, a Root badge on the part's root anchor, an owner chip (Machine Tool /
Fixture / Workpiece / Tool / Equipment); below it, one badge per role bound to the anchor — the same
text the graph draws, with the language-neutral form the REST graph carries (Fixture-TableMount) as its tooltip.
- On an editable owner (a machine tool that is a GeneralXyzabcMachineTool,
the fixture, the workpiece):
- Name — renamed on Enter or when the field is left, never while typing.
- Extend — a new anchor linked from this one by a
NoTransformbranch; the new anchor becomes the selection. - Delete — the trash button, on a double-click; not offered on the root anchor. A role bound to the anchor, or an axis or spindle role bound to a branch the deletion takes with it, is unbound first and named in a toast ("Unbound roles: …").
- Add Branch — a select over the part's other anchors not already joined to this one in either
direction; picking one creates a
NoTransformbranch from this anchor to it. - Geometry — a checkbox that hangs a solid on the anchor or removes it, and while enabled a type
badge (the kind, or Transformed {kind}), the display-colour swatch (an authored colour
beside a reset button, or the automatic one marked auto) and the
Geometry Editor over the solid's geometry. The editor's kind
picker offers
Box3d,Cylindroid,StlFileandGeomCombination, and no None entry; beneath it the Transform picker puts a transform on the picked geometry in place, and the transformer's editor follows the geometry's. A freshly enabled solid holds an empty wrapper, which the card reads as no kind picked yet. The section is not offered on the workpiece at all, whose anchors carry no solids. On the fixture's Geometry Anchor the checkbox cannot be cleared (the server refusesdisable-geomand the box snaps back with a toast), and with no None in the picker that solid's geometry can be switched to another kind here but emptied only over HTTP (create-geom?geometryType=None).
- On a non-editable owner (the tool, or a
ClMillingDevicemachine) the card shows only “{type} is shown here but not editable.”
Editor Card — Branch
Header: the title Branch, the owner chip, an Attachment chip on a branch between parts, an Error term chip on a marked branch, and the badge of an axis or spindle role bound to the branch, on its own row below.
- Name (editable on a part's own branch only; disabled on an attachment, which is named by its role
pair), the two endpoint chips (fletch → arrow anchor), the current transformer type, and, under
Transformer, the transformer editor: the shared
Transformer Select Panel switchboard, which swaps the branch's
transformer as soon as a kind is picked and re-posts an inner-value edit so the canvas follows.
On a marked branch it offers the static kinds only —
StaticTranslation,StaticRotation,StaticFreeform,GeneralTransformandNoTransform— the kinds the server takes there. - The Error term chip is orange, titled “The controller solves without this branch; the machine runs with it.” While the project's error-term switch is off it is grey, reads Error term (not in effect) and is titled “The project's error terms are switched off on the Machine Tool item: the machine runs without this branch's value as well.”
- Error term — a toggle below the Transformer section on the card of a machine-tool branch
bound to an axis (Axis X … Axis C) or the Spindle — the role card — and on no other card; a
branch a file binds to two of these roles carries it for the first. Its tooltip reads “Add an
error of the real machine to this role: a branch of its own, just before this one, carries it.
The controller solves machine coordinates without it, and the machine runs with it while the
project's error terms are on. Switched off, the error term is taken out again.” The toggle reads
the role's error term from the roles (
errorTermBranchGuid). Switched on, it postsroles/machine-tool/{role}/error-term, which inserts the error term and rebuilds the role's branch from the error term's anchor; switched off, it sendsDELETEto the same route, which takes the error term out and rebuilds the branch from its old start anchor (see Behavior). Either way the branch comes back under a new guid: the column re-pulls the graph and the roles and selects the rebuilt branch, so the card stays on the role. The option waits until the press on it has delivered its click before it queues, so a name typed into the card and left by that press is committed first, on the branch it was typed for; a name or transformer commit queued behind the rebuild follows the branch to its new guid, and a value commit for an error term taken out meanwhile is dropped. A refusal shows as a notification and leaves the toggle as the roles have it. - While the role has an error term, a chip beside the option reads Error term, titled "The
controller solves without the error term of {role}; the machine runs with it.", or, while the
project's error-term switch is off, Error term (not in effect), grey, titled “The project's
error terms are switched off on the Machine Tool item: the machine runs without the error term of
{role} as well.” Below the option sit the two anchors the error term joins (fletch → arrow) and
the error term's own Transformer Select Panel, which offers the static kinds only: a kind picked
there is put on the error term (
update-transformeron its guid), and a value edit re-posts the error term's key, so the error is edited without leaving the role card. The anchors and the editor show only while the graph agrees with the roles — the error term ends at the branch's fletch — since a bind on a Roles panel adopts its answer before the graph is re-pulled. - On the error term's own card — the marked branch that stands as an axis's or the spindle's error term — a line under the transformer type reads "This branch is the error term of {role}; it is added and removed on the card of {role}.", shown, like the role card's editor, while the graph agrees with the roles. That card has no option and no Clear mark; its Transformer section edits the same value as the role card.
- A mark no role owns — on a fixture's or a workpiece's branch, on a branch that plays an axis or
the spindle, or on a branch of the machine tool that stands in no error term's place (see
Behavior) — is one a hand-edited file brought in or a later edit left behind. Under
the transformer type, the card gives the part's Roles-panel finding about the branch, which the
chip's title repeats:
ErrorTermRoleon a branch that plays a role, otherwise the finding whose args name the branch by its guid (branchGuid), orErrorTermNotOnRolewhen none does. Below it, Clear mark — tooltip “Take the error-term mark off this branch; its transformer stays as it is.” — postsfalseto the branch'serror-termroute and re-pulls the graph. AClMillingDevicemachine's marked branch, which this column cannot clear, gets neither. - The worktable attachment — the machine's table end into the fixture's Table Mount, or into
the workpiece's Fixture Mount when the project has no fixture — is the one attachment with an
editable transformer: the equipment's
TableToComp, edited under ownerequipment. Every other attachment shows “Only the worktable attachment carries an editable transformer; the other attachments follow their roles.” - Delete (double-click) on a part's own branch; an axis or the spindle bound to it is unbound first and toasted.
- A branch of a non-editable part (a
ClMillingDevicemachine) shows only “{type} is shown here but not editable.”
Editor Card — Assembly
Clicking a cluster shows the card headed Mechanism, with the owner chip of the part the assembly belongs to.
- On an editable part (the machine tool, fixture or workpiece): a Name field that renames the assembly — on Enter or when the field is left; the server refuses a name carrying the path separator, one that opens like a GUID segment, and one a sibling assembly already carries — then the part's runtime type, “Roles are bound on this part's item in the Control Tree.” and an Open roles button that selects that item.
- On any other assembly (the tool's, the equipment's own, a
ClMillingDevicemachine's): the assembly's name as plain text, the type line and “{type} is shown here but not editable.”
Roles Panel (on the Control Tree)
Each of the three mechanism root panels — Machine Tool, Fixture,
Workpiece — ends with the Roles panel, titled Roles: one row per role, with
the role's label, a caption naming its kind (anchor or branch), “required” where the part needs
it, and “needs {transformer type}” on a branch role; a clearable select over the part's own
anchors or branches, leaving out the branches marked as error terms (a role bound outside the
part, or to a marked branch, is listed by name at the top so the select can show it); and the arm
button, a target icon whose tooltip reads “Pick on the graph” (lit while its role is armed). Below
the list, the server's checks — or “All checks pass.” A part the project has not mounted shows
“Not mounted.” instead of the rows, and a part whose type has no editable roles (a
ClMillingDevice machine) “{type} has no editable roles.”
| Part | Roles | Kind | Note |
|---|---|---|---|
| Machine tool | Table Mount, Tool Mount | anchor | required |
| Machine tool | Axis X, Axis Y, Axis Z | branch | optional; needs DynamicTranslation |
| Machine tool | Axis A, Axis B, Axis C | branch | optional; needs DynamicRotation |
| Machine tool | Spindle | branch | optional; needs DynamicRotation |
| Fixture | Table Mount, Workpiece Mount, Geometry Anchor | anchor | required |
| Workpiece | Fixture Mount, Program-Zero Anchor, Geometry Anchor | anchor | required |
| Check | Meaning |
|---|---|
Unbound |
Not bound; the mechanism needs this role. |
NotOwn |
Bound to an element outside this mechanism's own assembly. |
Duplicate |
The same element also plays {other}. |
NotReachable |
No branch chain leads from the root anchor to this anchor. |
AxisTransformerMismatch |
Needs a {expected} branch; the bound branch carries {actual}. |
AxisOffChain |
The branch is not on the chain between the table mount and the tool mount. |
SpindleOffToolAxis |
The spindle's rotation does not run along the tool mount's Z axis through its origin; turning it swings the tool around. |
ErrorTermRole |
The bound branch is marked as an error term; a role's branch cannot be one. Clear its mark in the Topology column, then add the error term on the branch's card. |
ErrorTermDynamic |
The error term {branch} carries {actual}; an error term carries a static transformer only. Change its transformer type to a static one, or clear its mark in the Topology column. |
ErrorTermOnToolAxis |
The error term {branch} lies between the spindle and the tool mount, which makes the spindle read as off the tool axis. Clear its mark, and add the spindle housing's error on the spindle branch's card. |
ErrorTermNotOnRole |
The branch {branch} is marked as an error term, but it is no axis's or spindle's: error terms are added on the cards of the machine tool's axis and spindle branches. Clear its mark in the Topology column. |
A finding is printed after the label of the role it is about ("Table Mount: Not bound; …").
A marked branch is reported by the first of the four error-term checks that fits, in the order of
the table, and by no other: ErrorTermRole under each role the branch plays; for any other marked
branch of the machine tool, ErrorTermDynamic when its kind is not static, wherever it lies, then
ErrorTermOnToolAxis, under Spindle, when it lies on the chain from the spindle branch to the
tool mount — the branch reaching the tool mount included, and even when it stands just before an
axis — and ErrorTermNotOnRole when it stands in no error term's place (see
Behavior); on a fixture or a workpiece, ErrorTermNotOnRole for every marked
branch. ErrorTermDynamic and ErrorTermNotOnRole are about no role, so the panel prints them
alone. {branch} is the marked branch's name, or its two anchors' names as fletch--->arrow when
it has none; the findings of the last three also carry the branch's guid as branchGuid in their
args, by which the branch card finds the finding about its branch. The chain from the spindle
branch to the tool mount is followed in either direction: with the Tool Mount bound to an anchor
on the table side, it runs back through the root, and a mark it passes is ErrorTermOnToolAxis's.
While any marked branch lies on that chain, SpindleOffToolAxis is not reported: the error would
skew that reading. An error term in its place off that chain is reported by none of the four; they
report a mark that a file or a script brought in, or one a later edit left where no role owns it
or moved onto that chain. ErrorTermRole also stops every run at its start with an
ErrorTermRoleException naming the role and the branch, until the mark is cleared or
another branch is bound.
Canvas Display Option
The shared Equipment canvas's Display Options dropdown carries a Role Anchors flag in its
Anchors group (show-role-anchors, off by default): it draws the axes of every bound role anchor —
the machine's two mounts, the fixture's three anchors, the workpiece's three — independently of the
per-anchor flags. An anchor the machine does not reach is not placed and draws nothing.
Behavior
How the column acts on the equipment is Equipment Topology Behavior:
arming a role and picking its element, adding and removing an error term and where one stands, the
refresh after every edit, what a live play refuses, the one chain every edit queues on — an edit
whose turn comes after the project was replaced is not sent — and when the column pulls the graph;
then the routes under api/mech/equipment-topology with their error codes
(HTTP Surface) and the graph a default part has
(Default Topology).
Source Code Path
The column, the Roles panels, the module singleton they share, the API module, and the controller,
services and engine types behind api/mech/equipment-topology are
Equipment Topology Source Code.
See Also
- Equipment Page — the page this column belongs to
- Equipment Topology Behavior — what the column does with an edit, a bind and a live play, and the routes and error codes behind it
- Equipment Topology Source Code — where the column, the Roles panels and the routes are implemented
- Machine Tool — the part whose mounts and axes are bound on its root panel and authored here
- Fixture — the part whose Geometry Anchor carries a solid and whose table branch the program-zero alignment writes
- Workpiece — the part whose anchors carry no solids, and whose Program-Zero Anchor a script addresses through this graph
- Transformer Select Panel — the switchboard the branch card mounts, and the parent-aware swap it performs
- Geometry Editor — the switchboard the anchor card mounts over the anchor solid's geometry
- Control Tree — the registry, which grows no slots for a mechanism's anchors and branches because they are edited in this column
- Building a Branch — an edit in this column rebuilds nothing; the host only re-pulls the graph (
reinitializeMechanism) - Selection and Layout — the Roles panels the mechanism roots end with, and a cluster click here selecting that part's root
- Tree Ids and Routes — why this column has no
?tree=id, and the hop that lands retired mechanism child ids on their item - Main Panel — the menu bar whose last column toggle on this page shows and hides the column
- Anchors and Roles — the end-user placement task done through this column and the Roles panels
- Object Store (IndexService) — the keyed store the branch transformers and anchor geometries are edited through