Step Colors REST

The REST behind the Step Colors Branch and behind what the charts answer for a color tree: api/execution/step-color-trees (Execution/StepColorTreeController.cs), which edits the project's trees and answers for HiNC's built-in ones, and the trees' fields on the charts' answers (Execution/ExecutionChartsController.cs). The same routes from a caller's side — bodies, answers, refusal codes — are Step Color Trees over HTTP, and how a tree sorts the steps is Color Trees.

The Routes

api/execution/step-color-trees edits the project's list in memory, one edit at a time under the project's step-definition lock (StepDefinitionEditLock(API)); POST api/project/save writes it. The trees and the step variables share one key space: each controller refuses with 409 a key the other defines, and a rename of either moves the color index, the color guide, the chart's Y-axis setting and the other trees' references along when nothing else keeps the old key. Set as color index is POST api/execution/inspecting-key.

Request	What it does
`GET ?lang=`	the project's trees with their state, occurrence and leaves, HiNC's built-in trees (`builtInTrees`), the trees registered at run, the key options, whether the physics keys are offered, the color index, the generation
`GET {key}?occurrence=`	one tree, as the list describes it; a built-in tree's when the project's list holds none under the key and `occurrence` is 0 or left out
`PUT {key}?occurrence=`	adds, changes or renames (a body `key` other than the route's) a whole tree, numbering the nodes without an id; names, short names and hues alone are taken in place; `If-None-Match: *` makes it an add only; `409` `StepColorTreeBuiltIn` under a built-in tree's key
`DELETE {key}?occurrence=`	removes the tree the occurrence names, or every tree under the key; keeps the color index; `409` `StepColorTreeBuiltIn` under a built-in tree's key
`POST {key}/copy`	copies a built-in tree to the end of the project's list, `201` with the copy's `GET` as `Location`
`POST check`	what a tree would be refused for and warned about, nothing changed
`POST preview`	the played steps classified under a tree — the body's or a registered key's — over the display range or all steps, one step explained; one preview at a time, nothing changed

Built-in Trees

LocalProjectService registers HiNC's own trees whenever a project is loaded, in every registry it builds, after the built-in properties and the MC. coordinates and before the project's definitions, in the order of BuiltInStepColorTrees.KeysInOrder: MachiningState, thirteen leaves — the group Cutting (12) over the touched steps holding the nine load leaves — read off the play and the physics, then MachiningStateGeometry, five leaves read off the play alone, whose ids are the full tree's for the same leaves. The two keys are among the keys StepPresentCatalog.IsBuiltInKey names, so every check that keeps a built-in property's key from a project's step variable or tree, a script's registration or a CSV or mapped column keeps them as well. The registry entry is of a kind of its own, neither the project's nor a session's, which LocalProjectService.IsBuiltInStepColorTreeKey tells apart; each service compiles a tree once, so a registry rebuilt keeps the tree's color guide and its hues.

MachiningState is a physics key: StepPhysicsKeys.PhysicsColorTrees, a set IsPhysics alone reads, holds it, so step-properties, the Step Present dialog and Step Properties leave it out while the interface hides the physics, and the chart stands its no-physics tree in for it (The stand-in). MachiningStateGeometry is no physics key. The Step Present dialog files every color tree's key — built-in, the project's, a session's — under its category engineeringView (PreferenceController), and StepInfoPresentKeys offers the built-in trees' keys without recording them as step variables.

The engine's instance carries the English names, and the answers put them in the request's language. GET's item and the preview's node names are built from a fresh instance in the request's culture (DescribeBuiltIn; Preview‘s source): origin builtIn, readOnly true, occurrence 0, state registered, inspected while the color index is the key. Every other answer that prints the tree's name or a leaf's — the step properties’ name and shortName, the Individual item's label, the color guide's names and leaves, the Step Properties row, the Step Present dialog's candidates — resolves the English by the tree's key (PresentCatalogService.ResolveBuiltInTreeText): a copy, under a key of its own, keeps the names it was copied with.

PUT and DELETE under a built-in tree's key answer 409 StepColorTreeBuiltIn, before any key check, unless the project's list holds a tree under that key — a project file edited by hand. That tree is listed keyTaken, never inspected (the color index reads the built-in entry), and GET {key} answers it, the built-in tree then being in builtInTrees alone; it can be renamed away, which moves no references, or deleted; and a PUT under the key itself falls to the key check, 400 StepColorTreeKeyTaken. registeredAtRun and keyOptions leave the built-in trees out, and the charts' editTreeId is null for them.

POST {key}/copy takes a body that may be left out (EmptyBodyBehavior.Allow; none reads as {}). Under the step-definition lock it takes newKey, or else the first of {key}Copy, {key}Copy2, … that no project tree or step variable, no registry key and not the color index holds; passes it through PUT's key refusals; refuses with 409 a key a project tree or step variable has; adds a fresh instance in the request's culture under that key, with name when one is given, numbered as a PUT numbers; registers the project's definitions again; and checks the tree for the answer's messages. A key that holds no built-in tree answers 404 StepColorTreeNotFound.

What the Charts Carry for a Tree

The Individual item of GET api/execution/strip-chart carries colorTree for a tree's key alone, { key, name, origin, standsInFor, editTreeId, leaves, leafMask, leafStepIndex, leafValues, leafTotals, noValueTotals, notes }, each per-bucket array aligned with xs (the answer around it is on Strip Charts):

name — the tree's name, its key when it has none (a built-in tree's in the request's language); origin — builtIn, project or session; standsInFor — the project's inspecting key the tree answers for, MachiningState while its no-physics tree stands in (The stand-in), null for a tree drawn as itself; editTreeId — the Control-Tree id of the project's tree under the key on the Step Colors Branch, null for a built-in or a script's tree.
leaves — tree order, { id, lane, name, shortName, hue, color, valueKey, valueLabel, valueUnitLabel, valueHidden }: name as authored (null or empty for none), shortName the lane's label (empty shows the name, cut to fit; a built-in tree's is in the request's language), hue in degrees, color the leaf's own #RRGGBB, the value fields null for a leaf showing none (valueUnitLabel empty for a unitless key or one the registry lacks), valueHidden for a physics value key the interface hides.
leafMask — a uint a bucket, bit lane per leaf a step fell into (test with (mask >>> lane) & 1: lane 31 is 2147483648); null over 32 leaves.
leafStepIndex — a bucket's first step in its highest lane, −1 for none.
leafValues — per leaf that shows a value and is not hidden, { lane, min, max } over that leaf's steps (the slot's float32, NaN for none); found by lane.
leafTotals { lane, id, steps, seconds } per leaf and noValueTotals { steps, seconds } — over the drawn steps (the window's positions with a step and a finite x); no leaf, a read that threw and a stale slot count as no value, the seconds are StepDuration, provisional while pending.
notes — a built-in tree's { code, message, args }, what its leaves cannot show about the steps since the last reset (Notes); empty for any other tree.

Beside it:

GET api/execution/step-properties — each row's group, engineering for a color tree's key (built-in, the project's or a session's) and science for any other, and builtInTree. The order stays the localized names', and a currentKey standing in for a hidden physics key is never a tree's but the stand-in's below: the picker makes the groups (Strip Charts).
The color guide's tree — { key, name, origin, editTreeId, leaves, notes }, the leaves in colorTree.leaves' shape, while the selected guide is a tree's.
The Individual aspect asked for a built-in tree's key while the slots hold another key answers pending, as for any tree: a built-in key is walked by its registry getter only when it is no tree's, or is the stand-in's.

The stand-in

While the interface hides the physics and the project's inspecting key is MachiningState, SubstituteKeyWhilePhysicsOff answers MachiningStateGeometry when that tree is registered — the one tree that is ever a substitute — and currentKey names it. The Individual aspect asked for it walks it by its registry getter, which classifies each step anew off four keys the step holds in memory (CollisionText, IsRapidCut, IsTouched, IsRapid) and reads no store, into a ColorTreeTrack of its own whose StandsInFor is the inspecting key; its lanes are its own, its notes its own, and IdColorsPayload compares the selected guide's key with StandsInFor, so idColors comes from the full tree's guide by the leaf ids the two trees share. The 3D view and the color guide's tree stay the full tree's. Asked for MachiningState itself, the Individual aspect answers the empty payload with pending: true every time, so a client reads step-properties again and asks for its currentKey; POST inspecting-key answers the key stored, MachiningState, as for any hidden physics key, while step-properties answers the key shown. With the physics shown again, currentKey is MachiningState once more.

Notes

Execution/BuiltInTreeNotes.cs writes a built-in tree's notes from LocalProjectService.ReadPlayedUnder(): the strip's count, the act runner's PlayedUnderTable read against it, whether a recorded play is under review, the spindle capability — the runtime equipment's, by name, and the file the setup references for it, by its file name alone (none when the capability is embedded) — and the tools whose stress ratio was never evaluated on a touched step with a physics result (PhysicsNoneMonitor.ToolsWhoseStressRatioWasNeverEvaluated, the tools Play-StressRatio--None names), and whether any touched step on a tool the physics runs on got a physics result (PhysicsNoneMonitor.AnyTouchedStepWithResult). The table has four tracks of change points by strip index: whether collision detection was on for the step — the value the step procedure detected by, read once a step —, whether the session's pipeline was built by the host's CSV runner, whether the physics was on (Config.EnablePhysics as the step procedure read it), and whether the detection, switched on, answered no result (MachiningEquipment.Detect returned null: no collision licence, or no machining chain), recorded after the detection and before the step yields a collision. A track keeps its first point and then a point only where its value changes, at most 4,096 changes and no byte a step; the change past them truncates that track alone, which keeps only whether each value occurred: the scope often. The act runner clears the table with the strip (ResetStateAndClStrip) — a reset, another project, a review opened or closed — so a Start, which does not reset, adds to it, and a switch after the last step changes nothing.

No note for a key that is no built-in tree's, nor for an empty strip. Under review, one note alone: RecordedPlay for MachiningStateGeometry, RecordedPlayLoad for MachiningState — the review's steps were not played here, and nothing was recorded for them; the full tree's sorts a touched rapid as a cut by the load the recording holds (the physics ran on rapid steps too), and says that the recording's spindle torque overload, spindle power overload and stress overload runs are not folded again, so its spindle torque, spindle power and stress overload revolutions read 0: Spindle torque sustained overload and Spindle power sustained overload are never judged; Stress overload and Thermal stress overload read the recorded stress ratio and thermal stress ratio themselves and are judged. Otherwise, in this order, CollisionDetectionOff, CollisionDetectionUnlicensed and NoRapidSemantics for both trees, then for MachiningState alone PhysicsOff, SpindleCapability and StressRatioNotEvaluated. A track's note is all when one range covers the strip, part with the first eight ranges and moreRanges, often when its track ran past the limit while the value occurred, and absent when the value never occurred. SpindleCapability comes once the physics track saw a step with the physics on and some touched step got a physics result — with the switch on but no physics licence, no tool with a flute envelope or a standing spindle nothing was read against the capability: source file when the setup references a file, embedded when the capability is the setup's own, none when the runtime equipment holds none (a referenced file that could not be read). A project that never set a capability holds the class default, TMV-720A-STD-8000RPM, embedded, which nothing tells from a chosen one. StressRatioNotEvaluated comes when its list is not empty. message is the server's English. The SPA writes the note in the app language from args and the bundle's charts.coloring.note.*, naming the leaves by id from the same answer's leaves, and shows message for a code or a scope it does not know.

Source Code Path

See HiNC App Anatomy for git repository links.

Web Application

HiNC-2025-webservice:

Execution/StepColorTreeController.cs — the routes, the built-in trees' items, the 409 and the copy.
Execution/BuiltInTreeNotes.cs — a built-in tree's notes.
Execution/ExecutionChartsController.cs — group and builtInTree, origin, editTreeId, the names resolved and the notes on both answers; the stand-in (SubstituteKeyWhilePhysicsOff, currentKey, standsInFor, IdColorsPayload).
Common/StepPhysicsKeys.cs — PhysicsColorTrees; Environments/PreferenceController.cs — the Step Present category engineeringView; Common/StepInfoPresentKeys.cs — the built-in trees' keys offered, not recorded as step variables.
Environments/PresentCatalogService.cs — ResolveBuiltInTreeText; Execution/SelectedStepInfoService.cs — the Step Properties row of a built-in tree.
wwwroot-src/src/api/stepColorTrees.ts — builtInTrees, origin, readOnly and copyStepColorTree; wwwroot-src/src/api/executionCharts.ts — group, builtInTree, origin and the notes' parse.
wwwroot-src/src/components/execution/charts/colorTreeNotes.ts — a note's text in the app language.

HiAPI Engine

HiNc/MachiningProcs/BuiltInStepColorTrees.cs — the trees as data: keys, leaves, the group, ids, hues, the thresholds and the names in five languages.
HiNc/MachiningProcs/LocalProjectService.BuiltInStepColorTrees.cs — the registry entry and its registration, IsBuiltInStepColorTreeKey and ReadPlayedUnder.
HiMech/MachiningSteps/StepPresentCatalog.cs — the reserved keys.
HiMech/MachiningProcs/PlayedUnderTable.cs — the four tracks; HiMech/MachiningProcs/MachiningActRunner.cs — the record in the step procedure, and its reset; HiMech/MachiningProcs/PhysicsNoneMonitor.cs — the tools whose stress ratio was never evaluated.

Table of Contents