Table of Contents

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-term to add the role's error term, and sends DELETE to 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 with err appended (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 a StaticRotation of 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, then ErrorTermAbsent when no error term stands before the role's branch — a marked branch there out of its place is none — and ErrorTermBypass when 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 404 RoleNotFound.
  • 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-term clears 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; a ClMillingDevice machine is not editable here (409 MechanismNotEditable), 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 is update-transformer putting a kind that is not static on a marked branch (409 ErrorTermDynamic).
  • 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 / refreshTopology on 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's error-term only 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-transformer with 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 posts refresh-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-transformer refuses a transformer object that another branch of the equipment already carries (409 TransformerInUse), on the worktable attachment's route too.
  • While a play is live — the pace player locked (Running or Paused), or a play a host request drives directly on the session shell (POST /api/SessionShell/PlayNcFile and 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, …/update or …/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-cache and POST …/rgb answer 409 SolidEditRefusedWhileRunning before the action runs, so a refused request changes nothing; index-geom answers 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 reads Running or Paused, 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's IsRunningNcLines and leaves the player idle, so the status reads neither Running nor Paused and 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.notSaved by 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