State Objects

The Delta State and Key State objects transmit information about the identity, position, and role of all geometric elements at a particular moment in time during a material removal simulation. Each geometric element described by a Geometry Reference Object.

Delta State Object

The delta state object is sent by the server with a nc:state event, and can be requested by the client through the /state/delta endpoint.

  'project': string,
  'workingstep': string,
  'time_in_workingstep': 0,
  'prev': string,
  'geom': GeomRefObj[]
Property Unit Description
Project string The name of the project this keystate applies to.
workingstep string The ID of the workingstep that this state applies to.
time_in_workingstep N/A Not currently used. Always zero.
prev string Not currently used. Always an empty string. This field will eventually identify be the key state that this delta is based on.
geom GeomRefObj[] An array of geometry reference objects that identify shape, role, and position information.

An example of a delta update from an nc:state websocket event pushed to the client.

   { Many more geometry references for other parts of the machine
     tool, as-is, to-be, cutter, and inprocess shapes. }

Key State Object

The key state object is identical to the delta state, but does not have a "prev" property. It represents the most current full scene. The Keystate object is as follows

  'project': string,
  'workingstep': string,
  'time_in_workingstep': 0,
  'geom': GeomRefObj[]

Geometry Reference Object

  'id': 	string,
  <'shape': 	string>,
  <'dynamicshape': 	string>,
  'xform': 	double[16],
  'bbox': 	double[6],
  'usage': 	string
  <'version': 	uint>,
Property Type Description
id string The UUID of the referenced shape. The client can request the shape with GET /nc/geometry/{id} if it does not already have a cached version.
shape string The ID string with a ".json" extension. The value is not important, but the "shape" and "dynamicshape" properties are mutually exclusive. A geometry reference with a "shape" property identifies CAD shape like a cutter or fixture may change position in space but will not change shape.
dynamicshape string As above, a geometry reference with a "dynamicshape" property identifies material removal volume that will change shape as well as position over time. The client does not request this shape by ID, instead it typically calls GET nc/geometry/delta/-1 to get the most recent removal shape.
xform double[16] The 4x4 transform matrix for the associated geometry. The transform follows the GL usage shown below.
  • m[0-2] is the x axis direction, m[3] is zero
  • m[4-6] is the y axis direction, m[7] is zero
  • m[8-10] is the z axis direction, m[11] is zero
  • m[12-14] is the origin, m[15] is one
double m[16] = [
       xi, xj, xk, 0.0,	 yi, yj, yk, 0.0,
       zi, zj, zk, 0.0,	 wx, wy, wz, 1.0
bbox double[6] The bounding box of the associated geometry as the low X,Y,Z values and and the high X,Y,Z values .
usage string A string keyword describing what the shape element represents. Values are:
  • asis A CAD workpiece for the starting material. This "rawpiece" or "stock" model may be from the start of the entire machining program, or from the start of the operation. STEP-NC process can specify as-is models at any point in the process.
  • cutter A CAD workpiece for the cutting tool.
  • fixture A CAD workpiece for fixturing.
  • inprocess The workpiece with ongoing material removal. Only with dynamicshapes.
  • machine Part of the machine tool. A machine is likely to be an assembly with many components, each of which will be continually changing position according to the machine kinematics. There will be a machine shape ref for each piece in the assembly.
  • removal Not currently used.
  • tobe CAD workpiece that is being produced. Represents the final form after machining either the operation or the entire program. Like the "asis" model, a STEP-NC process can specify to-be models at any point in the process.
  • toolpath Toolpath curves, the shape will be a polyline.
version uint The version of the dynamicshape geometry. Only used with dynamicshape references.