Table of Contents

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 … AxisC and 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 NoTransform branch; 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 NoTransform branch 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, StlFile and GeomCombination, 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 refuses disable-geom and 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 ClMillingDevice machine) 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, GeneralTransform and NoTransform — 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 posts roles/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 sends DELETE to 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-transformer on 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: ErrorTermRole on a branch that plays a role, otherwise the finding whose args name the branch by its guid (branchGuid), or ErrorTermNotOnRole when none does. Below it, Clear mark — tooltip “Take the error-term mark off this branch; its transformer stays as it is.” — posts false to the branch's error-term route and re-pulls the graph. A ClMillingDevice machine'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 owner equipment. 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 ClMillingDevice machine) 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 ClMillingDevice machine'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