Equipment Topology Behavior
What the Equipment page's Topology column (/equipment) does: a role armed and its element picked,
an error term added, marked or taken out, the refresh after every edit, what a live play leaves open
and what it refuses, the one chain every edit of the column and the Roles panels queues on, and when
the column pulls the graph; then the routes it calls under api/mech/equipment-topology, with their
error codes, and the graph a default part has. The column's layout — the graph, the editor cards and
the Roles panels — is Equipment Topology, and the files behind it are
Equipment Topology Source Code.
Behavior
- Arm and pick. The arm button on a Roles row arms that role (the chip appears in a strip above the graph), and a second click on it disarms. The next click on a graph element of the same kind that belongs to the same part binds it, toasts "{role} bound.", disarms and refreshes; an element of the wrong kind repeats the armed hint, and an element of another part toasts “That element belongs to another part; pick one from the part that owns the role.” and leaves the role armed. The select on the row binds without arming; clearing it unbinds. A refused bind leaves the select on the bound element.
- Adding and removing an error term. The role card's Error term option posts
roles/machine-tool/{role}/error-termto add the role's error term, and sendsDELETEto the same route to remove it. Adding is one edit, settled once. With F → A the role's branch, the server makes an anchor E in the assembly A sits in and the error term F → E, both named by the branch's name witherrappended (Xerr) — A's name when the branch has none, the role key when neither has one; a name that would not stay addressable is passed over, and a name an anchor of the machine carries already takes a three-digit counter (Xerr001). The error term carries aStaticRotationof 0° about Z, which leaves the machine as it was until a value is written, and is marked. A branch's ends are fixed, so the role's branch is rebuilt: a new branch E → A takes the old one's transformer object, its name, its mark and every role bound to it, under a new guid, and the old one is detached; a step that fails takes the others back. Removing is the way back: a new branch F → A takes E → A's transformer object, name, mark and roles, again under a new guid, and E → A, the error term and E go. Added and then removed, an error term leaves the machine file as it was but for that branch's guid when the branch is the only one out of its start anchor; when another branch leaves that anchor too, the rebuilt branch becomes the last one out of it, so the file's branch elements can also come in another order, the topology the same. - Adding is refused (409), checked in this order, on a role of the fixture or the workpiece
(
ErrorTermOutsideMachine), on a mount (ErrorTermRoleNotAxis), on an axis or the spindle bound to no branch of the machine (ErrorTermRoleUnbound), on a role whose own branch is marked, which only a file leaves (ErrorTermRoleMarked), on a role that has an error term already (ErrorTermExists) and on a role whose branch lies between the spindle branch and the tool mount, where the branch before it would lie too (ErrorTermOnToolAxis). Removing meets the first three, thenErrorTermAbsentwhen no error term stands before the role's branch — a marked branch there out of its place is none — andErrorTermBypasswhen a branch from the error term's start anchor to the role branch's end anchor stands beside it, so the role's branch could not go back there. A role key the part does not have is 404RoleNotFound. - Where an error term stands. One rule decides it, and the roles'
errorTermBranchGuid, the Roles panel's checks, both error-term routes of a role and the mark route all read it: a branch F → E stands in the place of the error term of the axis or the spindle whose branch E → A follows it when F → E is one of the machine's own branches, plays no role, carries a static kind and is the only branch into E, and E is an anchor of its own — not the root, playing no role, hanging no solid — from which nothing goes but that role's branch; marked, it is that role's error term. Why an error term goes there is in Where an Error Term Goes. A segment split into that shape by hand, its branch before the axis marked, reads as that axis's error term, and the axis's role card removes it like one it added. - The mark route. A branch's
error-termclears its mark (false), or sets one (true) only where the branch stands in an error term's place, so a script can compare a play with its error terms cleared against one with them marked. Clearing is never refused on the machine tool, the fixture or the workpiece; aClMillingDevicemachine is not editable here (409MechanismNotEditable), so a mark its file carries cannot be cleared in this column. Marking is refused (409), checked in this order, on a branch of the fixture or the workpiece (ErrorTermOutsideMachine: error terms belong to the machine tool), on a branch that plays an axis or the spindle (ErrorTermOnRole: the role would drop out of the controller's model), on a branch whose transformer is not a static kind (ErrorTermDynamic), on a branch between the spindle branch and the tool mount (ErrorTermOnToolAxis: the spindle would read as off the tool axis) and on a branch that stands in no error term's place (ErrorTermNotOnRole). Posting the value the branch already holds answers the branch and changes nothing: no rewire, nothing for the runtime face to follow. - The place is held only when an error term is added or a mark is set. A later edit — a role rebound or unbound, the role's branch deleted, the error term's anchor given a solid or bound as a mount, a branch added into or out of that anchor, the spindle or the Tool Mount rebound so that the chain between them passes a mark — is not refused, and the Roles panel reports the mark it leaves where no role owns it or on that chain. A mark no role owns shows on its branch's card with Clear mark.
- Two rules hold at every later edit. Binding an axis or the spindle to a marked branch is
refused (409
RoleOnErrorTerm), and so isupdate-transformerputting a kind that is not static on a marked branch (409ErrorTermDynamic). - After every edit — a bind, a rename, an anchor or branch created or deleted, a transformer
swapped, a solid hung, an error term added or removed, a mark set or cleared — the server
rewires the equipment's attachments
(Rewire), regenerates the
machine's collision pairs when the machine auto-generates them and both its mounts are bound,
and notifies the project so the runtime face follows; the canvas redraws on its next frame. The
attachment branches are re-minted by every rewire, so the column re-pulls the graph and the
roles (
reinitializeMechanism/refreshTopologyon the Control-Tree host) rather than patching them; a selected worktable attachment follows its new guid, and so does a role's branch that adding or removing its error term rebuilt. Calls that leave the topology unchanged — has-geom, geom-type, the rgb read and write, refresh-geom-cache, index-transformer — settle nothing; index-geom does so only when it hung a new solid, and a branch'serror-termonly when the mark changed. - An in-place value edit inside the branch card's transformer editor, or the role card's
error-term editor, re-posts
update-transformerwith the same key, so the object the switchboard produced is the one installed on the branch when the redraw happens; inside the anchor card's geometry editor it postsrefresh-geom-cache, so the runtime face — which shares the solid instance — re-triangulates. Either then refreshes the graph; a geometry kind switch is structural and goes through the host's re-pull instead. Re-posting the branch's own object is never refused;update-transformerrefuses a transformer object that another branch of the equipment already carries (409TransformerInUse), on the worktable attachment's route too. - While a play is live — the pace player locked (
RunningorPaused), or a play a host request drives directly on the session shell (POST /api/SessionShell/PlayNcFileand its siblings) in flight — the machine tool's and the fixture's solids are read-only. The runtime face does not copy them: it draws the very instances this column edits and checks collisions against them, so a run reads them as it plays. Those instances stay the run's until the next session boundary: a machine tool or a fixture swapped during a run (/api/mech/machine-tool/load,…/updateor…/create,/api/Fixture/UpdateFixture, none of them refused), or an anchor deleted with its solid, leaves the run on the old solids, and a write under them is refused too.enable-geom,disable-geom,create-geom,set-geom-transform,refresh-geom-cacheandPOST …/rgbanswer 409SolidEditRefusedWhileRunningbefore the action runs, so a refused request changes nothing;index-geomanswers the same on an anchor that has no solid yet, before it hangs one. The generic geometry and transformer editors (/api/Box3d,/api/TransformationGeom,/api/StaticTranslation, …) refuse a write the same way when its key names an object that is, or hangs under, one of those solids; every other object they serve — a workpiece's geometry, a tool's, a branch's transformer — passes. The Equipment page shows the refusal's own message in a banner while the execution status readsRunningorPaused, with a Stop and a Reset button, and covers or disables nothing: a write sent all the same is refused and shown as a notification. A direct play on the session shell raises the session'sIsRunningNcLinesand leaves the player idle, so the status reads neitherRunningnorPausedand no banner shows: a write during it is refused with the notification alone. The rest of the column — anchors, branches and their transformers, roles, error terms, renames, deletes — stays open during a run: it edits a face the runtime copies, and what it changes takes effect at the next session boundary. - Edits are serialised on one promise chain; while one is in flight — the column's own, or a bind
from a Roles panel's select — the graph ignores clicks; the title bar's Refresh and the card's
Extend, Delete, Add Branch select, Geometry checkbox, colour controls, Error term option and
Clear mark are disabled, and so are the Roles panels' selects and arm buttons. The
transformer and geometry editors in the card are not gated: a kind switch in either queues
behind the edit in flight. The name fields stay editable too: a rename committed meanwhile
queues behind the edit in flight. An edit whose turn on the chain comes after the project was
replaced — a New, Load, Reload or Close this tab has heard of — is not sent: it fails with
The project changed: nothing was done., which the column's notification, or the child editor
that drove the edit, reports after what was being done. A name commit checks earlier, once the press that left
its field has been delivered, and says
common.projectChange.notSavedby the name the element had (the name typed, for one that had none) instead of sending. The state — graph, roles, selection, armed role — is one module singleton shared by the column and the three Roles panels, so the Control-Tree host's own refresh after Load / Paste / New on a mechanism item updates the column too. - The column pulls the graph and the roles when it mounts, which it does even while hidden, since a hidden column is pinned to 0 px rather than unmounted. A pull the column wants while hidden — its state emptied under it — waits until it is shown on the active page; the host's re-pulls after a bind or a Load / Paste / New run either way. A no-project 404 is an empty state, not an error.
HTTP Surface
Everything is under api/mech/equipment-topology. Owners are machine-tool, fixture and
workpiece; equipment is accepted only by the two branch-transformer routes, and only for the
worktable attachment. A POST body is JSON.
| Route | Does |
|---|---|
GET graph?toolInternals= |
The whole equipment as one graph; toolInternals=true adds the tool's own anchors and branches (the page never asks for them); each branch carries isErrorTerm, and the graph the project's error-term switch as errorTermsEnabled |
GET error-terms, PUT error-terms body true / false |
The project's error-term switch as a bare JSON boolean; PUT answers the value written |
GET roles, GET roles/{owner} |
The roles of every part / one part, with candidates and checks; an axis's or the spindle's role names its error term as errorTermBranchGuid (empty when it has none, and on every other role) |
POST roles/{owner}/{role} body { "guid": "…" } |
Binds the role to the part's own element; an empty guid unbinds; answers the part's roles |
POST roles/{owner}/{role}/error-term |
Adds the error term of an axis or the spindle: a new anchor and a marked StaticRotation of 0° just before the role's branch, which is rebuilt from the new anchor under a new guid; answers { role, anchor, errorTerm, branch } — the new anchor, the error term and the rebuilt branch |
DELETE roles/{owner}/{role}/error-term |
Removes it: the role's branch is rebuilt from the error term's start anchor under a new guid, and the error term and its anchor go; answers the rebuilt branch |
POST {owner}/asmb/{id}/rename body { "name": "…" } |
Renames the part's key assembly or one below it; 400 for a name carrying the path separator, opening like a GUID segment, or worn by a sibling assembly |
POST {owner}/anchor/new?name= |
A stand-alone anchor in the part's key assembly |
POST {owner}/anchor/extend-from/{id} |
A new anchor downstream of {id} on a NoTransform branch |
POST {owner}/anchor/{id}/rename body { "name": "…" } |
Renames |
DELETE {owner}/anchor/{id} |
Deletes the anchor and its branches; answers { success, unboundRoles }; the root is refused |
POST {owner}/branch body { "fletchAnchorGuid", "arrowAnchorGuid" } |
A NoTransform branch between two anchors of the part |
POST {owner}/branch/{id}/rename |
Renames |
POST {owner}/branch/{id}/error-term body { "value": false } |
Clears the branch's error-term mark; true sets one, only where the branch stands in an error term's place; answers the branch with its isErrorTerm; the value the branch already holds answers it unchanged and settles nothing; 400 for a body without value |
DELETE {owner}/branch/{id} |
Deletes; answers unboundRoles |
POST {owner}/branch/{id}/index-transformer |
Indexes the branch's transformer; answers its key |
POST {owner}/branch/{id}/update-transformer?transformerKey= |
Swaps the branch's transformer to the indexed one; answers the canonical key |
GET {owner}/anchor/{id}/has-geom, GET …/geom-type, GET …/rgb |
The anchor solid's presence, geometry type name (or None), display colour |
POST {owner}/anchor/{id}/enable-geom, …/disable-geom |
Hangs a solid holding an empty TransformationGeom (an existing solid is kept), which the card presents as a slot with no kind yet / removes it |
POST {owner}/anchor/{id}/index-geom |
Indexes the solid's geometry for the editor, hanging a solid first when there is none; answers the key |
POST {owner}/anchor/{id}/create-geom?geometryType= |
A fresh geometry of that kind on the solid (None clears it) |
POST {owner}/anchor/{id}/set-geom-transform?transformerType= |
Wraps the solid's geometry in a TransformationGeom of that transformer kind, swaps the transformer, or with None unwraps it — in place, the authored geometry kept; what the card's Transform picker posts; 409 on an anchor without a solid or a solid holding nothing |
POST {owner}/anchor/{id}/refresh-geom-cache |
Clears the solid's cached triangulation after an in-place edit |
POST {owner}/anchor/{id}/rgb?rgb= |
Authors the display colour (#rrggbb; empty clears) |
While a play is live — the pace player locked (Running or Paused), or a play a host request
drives directly on the session shell in flight — enable-geom, disable-geom, create-geom,
set-geom-transform, refresh-geom-cache and POST …/rgb answer 409
SolidEditRefusedWhileRunning, and so does index-geom on an anchor that has no solid yet; every
other route of the table stays open (see Behavior).
IndexService keys: a branch transformer is equipment-topology.<owner>.branch.<guid>.transformer,
an anchor solid's geometry equipment-topology.<owner>.anchor.<guid>.geom (the guid written without
hyphens in both); the worktable attachment's is equipment-topology.equipment.table-to-comp.
| Status | code |
When |
|---|---|---|
| 404 | NoProjectLoaded |
No project, or no authored equipment |
| 400 | UnknownOwner |
An owner other than the three parts (tool included) |
| 404 | MechanismNotFound |
The owner names a part the project has not mounted |
| 409 | MechanismNotEditable |
The machine tool is a ClMillingDevice |
| 404 | RoleNotFound |
The part has no role of that key |
| 409 | RoleElementTaken |
The element already plays another role of the same part |
| 409 | AxisTransformerMismatch |
An axis or the spindle given a branch of the wrong kind, or its bound branch given the wrong transformer |
| 409 | MechanismRefused |
The part's own rule: a role takes only an element of its assembly |
| 400 | — | A branch's error-term with no body, or a body without value |
| 409 | ErrorTermOutsideMachine |
Adding or removing the error term of a fixture's or a workpiece's role, or marking a branch of the fixture or the workpiece |
| 409 | ErrorTermRoleNotAxis |
Adding or removing the error term of a mount |
| 409 | ErrorTermRoleUnbound |
Adding or removing the error term of an axis or the spindle bound to no branch of the machine tool |
| 409 | ErrorTermRoleMarked |
Adding the error term of a role whose own branch is marked as an error term |
| 409 | ErrorTermExists |
Adding the error term of a role that has one |
| 409 | ErrorTermAbsent |
Removing the error term of a role that has none |
| 409 | ErrorTermBypass |
Removing an error term while a branch from its start anchor to the role branch's end anchor stands beside it; args role, fletch and arrow, the two anchors by name |
| 409 | ErrorTermOnRole |
Marking a branch that plays an axis or the spindle |
| 409 | ErrorTermDynamic |
Marking a branch whose transformer is not a static kind, or update-transformer putting such a kind on a marked branch |
| 409 | ErrorTermOnToolAxis |
Adding the error term of a role whose branch lies between the spindle branch and the tool mount, or marking a branch there |
| 409 | ErrorTermNotOnRole |
Marking a branch that stands in no error term's place |
| 409 | RoleOnErrorTerm |
Binding an axis or the spindle to a branch marked as an error term |
| 409 | TransformerInUse |
update-transformer given a transformer object another branch of the equipment carries, the worktable attachment's route included; never the branch's own object re-posted |
| 409 | SolidsNotAllowed |
enable-geom, disable-geom, index-geom or create-geom on the workpiece (its read routes answer as for an anchor with no solid) |
| 409 | SolidEditRefusedWhileRunning |
enable-geom, disable-geom, create-geom, set-geom-transform, refresh-geom-cache or POST …/rgb while a play is live — the pace player locked (Running or Paused), or a play a host request drives directly on the session shell in flight — answered by a filter before any check of the route's own, so it then answers in place of UnknownOwner, MechanismNotFound, MechanismNotEditable, AnchorNotFound, SolidsNotAllowed or GeomAnchorKeepsItsSolid; and index-geom on an anchor without a solid then (it would hang one), answered in the action once the owner and the anchor resolve, so UnknownOwner, MechanismNotFound, MechanismNotEditable and AnchorNotFound come first and the workpiece still answers SolidsNotAllowed; at the same moments, a write of the generic geometry and transformer editors (/api/Box3d, /api/StaticTranslation, …) to an object that is, or hangs under, a solid of the machine tool or the fixture, on the authored face or on the runtime face, which keeps a swapped part's or a deleted anchor's solids until the next session boundary |
| 404 | AsmbNotFound |
An assembly guid outside the part's key assembly |
| 404 | AnchorNotFound |
An anchor guid outside the part's key assembly |
| 404 | BranchNotFound |
A branch guid outside the part's key assembly, or, under owner equipment, a guid that names no branch of the equipment |
| 409 | AttachmentFixed |
Owner equipment on any branch other than the worktable attachment (another attachment, or a part's own branch) |
| 409 | GeomAnchorKeepsItsSolid |
disable-geom on the fixture's Geometry Anchor |
Adding a role's error term meets ErrorTermOutsideMachine, ErrorTermRoleNotAxis,
ErrorTermRoleUnbound, ErrorTermRoleMarked, ErrorTermExists and ErrorTermOnToolAxis in that
order; removing it meets the first three, then ErrorTermAbsent and ErrorTermBypass. Marking a
branch meets ErrorTermOutsideMachine, ErrorTermOnRole, ErrorTermDynamic,
ErrorTermOnToolAxis and ErrorTermNotOnRole in that order; clearing a mark meets none of them.
Both error-term routes of a role rebuild the role's branch under a new guid, so a caller that kept
the old guid re-reads the roles or takes the answer's: the old one answers 404 BranchNotFound.
Where the English message names a role, it prints the raw role key
(AxisX, Spindle, TableMount); every other interface language shows the role's label in its
place.
The program-zero alignment stays on the Controller:
POST /api/Controller/iso-coordinate-table/{index}/align-workpiece-program-zero and
POST /api/Controller/iso-coordinate-table/revert-align-workpiece-program-zero rewrite the
transformer of the fixture branch that leads from its Geometry Anchor straight to its Table Mount.
Default Topology
A part built by CreateDefault — which is also the shape every legacy-form file loads onto — is what
the graph shows on a fresh project. Fixture: the root is the Geometry Anchor, carrying the fixture's
solid, with one NoTransform branch to the Table Mount and one to the Workpiece Mount, each
branch named after the mount it reaches. Workpiece: the root is the Fixture Mount; from the
Geometry Anchor one zero StaticTranslation branch leads to the Fixture Mount and one to the
Program-Zero Anchor, each named after the anchor it reaches. A mission script addresses the same
branches: once the fixture's table branch carries a StaticTranslation (the program-zero
alignment writes one; the default shape's is NoTransform),
(Branch.Get(Fixture.GeomAnchor, Fixture.TableMount).Transformer as StaticTranslation).Trans += new vec3d_t(0, 0, …);,
and Branch.Get(Workpiece.GeomAnchor, Workpiece.ProgramZeroAnchor).Transformer = transform;.
See Also
- Equipment Topology — the graph, the editor cards and the Roles panels these edits are made from
- Equipment Topology Source Code — the edit chain, the controller and the services behind these routes
- Editing Objects by Key — the same routes driven by a script
- Fixture — the fixture's anchors, branches, transformers and solids, edited through
these routes with owner
fixture - Anchors and Roles — the end-user placement task these routes serve