Editing Objects by Key
How a script edits geometry, transformers and the other setup objects the web service keeps in its object store, and how an edit reaches the runtime copy a run is built from. Signing in, reading a reply, file roots and the project lifecycle are on Driving the Web Service over HTTP. Replaying a mission is Running a Replay.
Geometry, transformers, cylindroid profiles and similar setup values are edited through an object store rather than through one route per field. A caller works in three moves:
- Create or index an object and get its key. A create route builds an object, installs it where
it belongs, stores it under a key and returns that key. The key is passed as a query argument
(
geometryKeyon the workpiece's create routes,keyon the per-kindNewandNewWithValue, …); when it is left out, a generated one is used and returned. An index route publishes an object that already exists — the geometry a workpiece already holds, the transformer inside a transformation geometry — and returns its key. - Edit through the key. Per-kind routes take the key as a query parameter and the new values as
query parameters too —
POST /api/StaticTranslation/UpdateTrans?staticTranslationKey=…&x=…&y=…&z=…— or a list as a JSON body. - Read back through the key —
GET /api/StaticTranslation/Get?staticTranslationKey=…,GET /api/StlFile/GetInfo?stlFileKey=…, orGET /api/Index/GetType?key=…for any key.
A vector is never an object of its own. The translation of a static translation, the axis and
pivot of a rotation and the two corners of a box are values of the object that owns them, and are
written through that owner's route with the owner's key and the three axes as query parameters:
StaticTranslation/UpdateTrans, StaticRotation/UpdateAxis and UpdatePivot,
DynamicRotation/UpdateAxis and UpdatePivot, DynamicTranslation/UpdateAxis, and Box3d/Update
with both corners. The owner's Get reads the value back, and the two rotations and the dynamic
translation also answer NormalizeAxis. No route hands out a key to a vector.
Container routes derive the keys of what they create from the container's own key, so a chain of calls can be scripted without parsing replies:
| Call | Key returned |
|---|---|
POST /api/Workpiece/CreateRawGeometry?geometryKey=K&geometryType=TransformationGeom |
K |
POST /api/TransformationGeom/CreateGeom?transformationGeomKey=K&geometryType=StlFile |
K-Geom |
POST /api/TransformationGeom/CreateTransformer?transformationGeomKey=K&transformerType=StaticTranslation |
K-Transformer |
POST /api/Workpiece/SetRawGeometryTransform?geometryKey=K&transformerType=StaticTranslation |
K — the geometry already in the slot, wrapped in place; K-Geom and K-Transformer are kept in step, and transformerType=None unwraps it again |
POST /api/Workpiece/Initialize?sessionKey=S |
a JSON object naming S-Workpiece, S-RawGeom and S-IdealGeom; a geometry key is indexed only when its slot holds something (hasRawGeom, hasIdealGeom) |
POST /api/Fixture/Initialize?sessionKey=S |
a JSON object naming S-Fixture |
POST /api/mech/equipment-topology/{owner}/branch/{guid}/index-transformer |
equipment-topology.<owner>.branch.<guid>.transformer — the transformer on that branch of the fixture, workpiece or machine tool; a branch carrying none is first given a pass-through one |
Placing a mesh as the stock, translated into position, therefore runs as below, here with the
caller's own prefix job7-stock and a mesh already uploaded to Geom/stock.stl:
POST /api/Workpiece/CreateRawGeometry?geometryKey=job7-stock&geometryType=TransformationGeom
POST /api/TransformationGeom/CreateGeom?transformationGeomKey=job7-stock&geometryType=StlFile
POST /api/StlFile/UpdateSource { "stlFileKey": "job7-stock-Geom", "rootName": "ProjectDirectory", "relFile": "Geom/stock.stl" }
GET /api/StlFile/GetInfo?stlFileKey=job7-stock-Geom -> loaded: true, triangleCount > 0
POST /api/TransformationGeom/CreateTransformer?transformationGeomKey=job7-stock&transformerType=StaticTranslation
POST /api/StaticTranslation/UpdateTrans?staticTranslationKey=job7-stock-Transformer&x=-45&y=-30&z=-12
POST /api/Workpiece/UpdateRawGeometry?geometryKey=job7-stock (re-install, next section)
POST /api/Workpiece/ClearRawGeomCache
A create route replaces whatever the slot held; nothing carries over from the object it
displaced. Wrapping what is already there is a separate family, the owners' Set…Transform routes —
Workpiece/SetRawGeometryTransform, Workpiece/SetIdealGeometryTransform,
mech/equipment-topology/{owner}/anchor/{id}/set-geom-transform,
FreeformHolder/SetGeometryTransform, GeomCombination/SetItemTransformAt,
TransformationGeom/SetGeomTransform and Cutter/{id}/upper-beam/set-transform — each taking
transformerType, a transformer kind or None: a bare geometry is wrapped in a TransformationGeom
around that very object, a wrapped one gets a fresh transformer of that kind, and None hands the
inner geometry back to the slot; the route answers the slot's key. These are what the web client's
Transform picker posts, and the client never names TransformationGeom as a kind; the sequence
above stays valid for a script and builds the same wrapper.
Anchors and branches of the equipment
The transformers that place the fixture on the table and the workpiece on the fixture are not slots
with routes of their own. Each is the transformer of a branch in the topology of the part that
owns it, and the routes under /api/mech/equipment-topology address a part's anchors and branches
by guid, with the owner — machine-tool, fixture or workpiece — in the path:
GET /api/mech/equipment-topology/graphlists every anchor (guid,owner,roles) and every branch (guid,owner,fletchAnchorGuid,arrowAnchorGuid,transformerType,isAttachment,isErrorTerm). Find a branch by the role of the anchor it arrives at, never by its name: the workpiece branch whosearrowAnchorGuidis the workpiece anchor whoserolesincludeProgramZeroAnchoris the one that places program zero; the one arriving atFixtureMountplaces the workpiece on the fixture; the fixture branch arriving atTableMountplaces the fixture on the table. Skip the attachments (isAttachment: true, ownerequipment) — the equipment builds those itself from the roles.- Build a transformer under a key of the caller's own —
POST /api/StaticTranslation/NewWithValue?key=K&x=…&y=…&z=…— and install it withPOST /api/mech/equipment-topology/{owner}/branch/{guid}/update-transformer?transformerKey=K. The answer is the canonical key the transformer is re-indexed under,equipment-topology.<owner>.branch.<guid>.transformer, whichindex-transformeron the same branch also answers; editing through that key is the nested-edit case of the next section. - A role is bound with
POST /api/mech/equipment-topology/roles/{owner}/{role}and the body{ "guid": "…" }— an anchor guid forTableMount,ToolMount,WorkpieceMount,GeomAnchor,FixtureMountandProgramZeroAnchor, a branch guid forAxisX…AxisCandSpindle; an empty guid unbinds.GET roles/{owner}lists each role with its candidates and the checks that fail (Unbound,NotOwn,Duplicate,NotReachable,AxisTransformerMismatch,AxisOffChain,SpindleOffToolAxis, and for marks where none belongsErrorTermRole,ErrorTermDynamic,ErrorTermOnToolAxis,ErrorTermNotOnRole), and gives each axis and the spindle the guid of its error term,errorTermBranchGuid, empty when it has none. - An error term belongs to an axis or the spindle of the machine tool. It is added with
POST /api/mech/equipment-topology/roles/machine-tool/{role}/error-term,{role}beingAxisX…AxisCorSpindle, with no body: in one edit a new anchor and the marked error term — a Static Rotation of 0° about (0, 0, 1) until a value is written — go in just before the role's branch, and that branch is rebuilt from the new anchor under a new guid. The answer carries therole, the newanchor, theerrorTermand the role'sbranch.DELETEon the same route takes the error term and its anchor out and answers the role's branch, under a new guid again; take the guid from the answer, or read the roles again, before addressing that branch. The error's value is the error term's transformer, set withindex-transformerandupdate-transformerlike any branch's, static kinds only. The mark by itself is set and cleared withPOST /api/mech/equipment-topology/{owner}/branch/{guid}/error-term: the body{ "value": false }clears it, and{ "value": true }sets it again only on a branch that stands where an error term stands, so a script can compare a play with the marks cleared, in which the controller knows the errors, against one with them set. Posting the value the branch already holds changes nothing. The project's error-term switch isGET/PUT /api/mech/equipment-topology/error-terms, a bare JSONtrueorfalseas the whole body. Where an error term stands is in Error-Term Branches; a request the editor does not accept answers 409 with acodenaming the reason, and the HTTP Surface table lists those codes with every other route of this controller.
Every topology edit under this controller, an error term added or removed and a mark set or cleared
included, rewires the equipment, and the attachment branches are given new guids each time, so read
the graph again before addressing one; writing the error-term switch rewires nothing. The worktable
attachment — from the machine's table end to the fixture's TableMount, or to the workpiece's
FixtureMount when there is no fixture — is the one attachment with an editable transformer,
addressed with the owner equipment (…/equipment/branch/{guid}/index-transformer and
update-transformer; its key is equipment-topology.equipment.table-to-comp); any other attachment
answers 409 AttachmentFixed.
The refusals carry a code: 400 UnknownOwner, 404 MechanismNotFound when the part is not
installed, 409 MechanismNotEditable for a cutter-location device, 409 RoleElementTaken when the
element already plays another role of the same part, 409 AxisTransformerMismatch when an axis is
given, or a bound axis branch is set to, a transformer of the wrong kind, 409 TransformerInUse
when the object under transformerKey already sits on another branch (build one transformer per
branch; re-posting the one a branch already carries is never refused), and 409 SolidsNotAllowed
for a geometry route on the workpiece — its geometry is the raw and target slots above, not an
anchor solid.
The store is shared by every caller of the service and its keys are plain strings. Writing a key that
already exists silently repoints it, so every caller needs a key prefix no other caller uses. Keys stay
until removed with POST /api/Index/Remove?key=…; removing a key only forgets the handle and never
takes the object out of the project.
Making an Edit Reach the Run
A project holds its equipment twice: the setup that is saved, and a runtime copy that the runner, the physics, collision checking and the stock mesh are built from. The runtime copy is not patched field by field — apart from the environment values (spindle capability, coolant condition, ambient temperature), which the spindle-capability routes forward at once. It is rebuilt from the setup at two moments:
- at the start of a fresh session — the first play after a project is loaded, or after a Reset;
- when an install route marks the setup edited — at once when no session is open, otherwise at the
next play or Reset. The install routes are the ones that put an object into a slot or edit the
equipment's topology: creating or replacing a workpiece geometry, installing a transformer on a
branch with
update-transformer, binding a role, adding or deleting an anchor or a branch, adding or removing an error term, setting or clearing a mark, writing the project's error-term switch, loading a machine chain, a material or cutting parameters, aligning the workpiece to a work offset.
The status says when an install is waiting. GET /api/Execution/status answers hasSession —
something has played since the last Reset — and setupEquipmentDirty — an install route has marked
the setup edited and the runtime copy has not been rebuilt from it yet — beside resetCount, which
each Reset raises by one, and instanceId, the identity of the service process the runId counts
in (instanceStartedUtc says when that process started). While both flags are true the web
client's Equipment page shows a banner with a Reset now button. In host code the flag is
IsSetupEquipmentDirty, and
SetupEquipmentDirtyChanged is raised on each change.
An edit made through a child key marks nothing. StaticTranslation/UpdateTrans,
StlFile/UpdateSource, Box3d/Update, a cylindroid's pair updates and every other per-kind route
change the setup object in place. The change reaches the runtime copy at the next fresh session and not before: a play started on
a session that is still open — a second start with no Reset in between — runs against the old
placement or the old shape, and nothing in its messages says so. The setup canvas draws the
workpiece's raw and target solids from the runtime copy, so a nested edit to either geometry goes on
showing the old shape there; the anchors, the fixture and the machine it draws from the setup
itself.
After the last nested edit inside a slot or a branch, re-install the slot's own object — posting the same key again is enough — and clear its cached solid where it has one:
| Edited inside | Re-install | Then |
|---|---|---|
| Workpiece raw geometry | POST /api/Workpiece/UpdateRawGeometry?geometryKey=<slot key> |
POST /api/Workpiece/ClearRawGeomCache |
| Workpiece target geometry | POST /api/Workpiece/UpdateIdealGeometry?geometryKey=<slot key> |
POST /api/Workpiece/ClearIdealGeomCache |
| The transformer of a fixture, workpiece or machine-tool branch | POST /api/mech/equipment-topology/{owner}/branch/{guid}/update-transformer?transformerKey=<its key> |
— |
| The worktable attachment's transformer | POST /api/mech/equipment-topology/equipment/branch/{guid}/update-transformer?transformerKey=<its key> |
— |
This is what the browser client does after every nested edit, and it makes the edit effective whatever state the session is in. Resetting before every start is the second guard, and saving and reloading rebuilds the runtime copy as well — one more reason every build ends with save, reload and a read-back.
See Also
- Driving the Web Service over HTTP — signing in, the reply envelope, named file roots and the project lifecycle these routes assume
- Running a Replay — reset, start and poll, which is when a waiting install reaches the run
- One Service, One Project — why a key needs a prefix of its own on a shared instance, and the edits refused while a run is live
- Object Store (IndexService) — the store behind the key-based routes, and its lifetime
- Workpiece — the re-install-then-clear chain the browser client runs after every nested edit, and the workpiece's three roles
- Fixture — the fixture's roles, topology and solid, and the topology routes behind its panel
- Equipment Topology Behavior — the whole
api/mech/equipment-topologyroute table, the role checks and the error codes