Table of Contents

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:

  1. 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 (geometryKey on the workpiece's create routes, key on the per-kind New and NewWithValue, …); 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.
  2. 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.
  3. Read back through the key — GET /api/StaticTranslation/Get?staticTranslationKey=…, GET /api/StlFile/GetInfo?stlFileKey=…, or GET /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:

  1. GET /api/mech/equipment-topology/graph lists 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 whose arrowAnchorGuid is the workpiece anchor whose roles include ProgramZeroAnchor is the one that places program zero; the one arriving at FixtureMount places the workpiece on the fixture; the fixture branch arriving at TableMount places the fixture on the table. Skip the attachments (isAttachment: true, owner equipment) — the equipment builds those itself from the roles.
  2. Build a transformer under a key of the caller's own — POST /api/StaticTranslation/NewWithValue?key=K&x=…&y=…&z=… — and install it with POST /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, which index-transformer on the same branch also answers; editing through that key is the nested-edit case of the next section.
  3. A role is bound with POST /api/mech/equipment-topology/roles/{owner}/{role} and the body { "guid": "…" } — an anchor guid for TableMount, ToolMount, WorkpieceMount, GeomAnchor, FixtureMount and ProgramZeroAnchor, a branch guid for AxisX … AxisC and Spindle; 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 belongs ErrorTermRole, ErrorTermDynamic, ErrorTermOnToolAxis, ErrorTermNotOnRole), and gives each axis and the spindle the guid of its error term, errorTermBranchGuid, empty when it has none.
  4. 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} being AxisX … AxisC or Spindle, 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 the role, the new anchor, the errorTerm and the role's branch. DELETE on 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 with index-transformer and update-transformer like any branch's, static kinds only. The mark by itself is set and cleared with POST /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 is GET / PUT /api/mech/equipment-topology/error-terms, a bare JSON true or false as the whole body. Where an error term stands is in Error-Term Branches; a request the editor does not accept answers 409 with a code naming 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-topology route table, the role checks and the error codes