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, fourteen leaves — the group
Cutting (12) over the touched steps holding the ten 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, holdingLanes, undecidedLanes, 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,projectorsession;standsInFor— the project's inspecting key the tree answers for,MachiningStatewhile 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, valueScale, valueLabels, valueHidden, sameStepsAs }:nameas authored (null or empty for none),shortNamethe lane's label (empty shows the name, cut to fit; a built-in tree's is in the request's language),huein degrees,colorthe leaf's own#RRGGBB, the value fields null for a leaf showing none (valueUnitLabelempty for a unitless key or one the registry lacks,%for a ratio and for the breakage probability;valueScalethe factor the chart multiplies the leaf's values by before it prints them in that unit, 100 for a ratio, 1 for any other key and for one the registry lacks;valueLabelsthe names of a value key whose values are named, a cutter zone's, in the request's language and in the shape of an item'svalueLabels(PresentCatalogService.ResolveValueLabels), null for any other key),valueHiddenfor a physics value key the interface hides,sameStepsAsthe id of the first leaf before this one in its own list on its very condition, the sameJoinand the sameTermsin order, with no node without a condition between the two (CompiledStepColorTree.Leaf.SameStepsAsId; a leaf with no condition never matches, and none pairs across one: of[A, otherwise, A2]A2 names none; of three leaves on one condition the second and the third both name the first), null for any other: such a leaf takes no step, each being the leaf it names, as leaf 16, High breakage probability, is leaf 4's, and holds wherever that leaf holds.holdingLanes— an array a bucket, highest lane first: the bucket'smax, the lane of its most important leaf, then the lanes of the leaves that hold on the steps that leaf takes (CompiledStepColorTree.FindHoldingAfter: a leaf whose own condition holds, and every group's above it, whatever took the step; an otherwise leaf only on its own steps; nothing after a node without a condition); a raw answer's point gives its own step's;[]for a bucket without a step in a leaf. The steps of the bucket's lower lanes add nothing: a union over every step of a bucket would put together states that never held on one step. The walk starts at the step's stored leaf and reads a key only when a term needs it, oneStepColorTreeHoldingReaderan answer (LocalProjectService.NewStepColorTreeHoldingReader), on the request's thread, never from the step cache: a key whose read reached the step cache decides nothing on that step and is read off its resident read alone for the rest of the answer, and a read that throws decides nothing on its step.undecidedLanes— ascending, the lanes of the leaves whose holding or whose value the walk could not read on a step of the answer, which have no bar or no value there;[]for the built-in trees, whose keys are resident or in memory.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 }a bucket over the same steps asholdingLanes, the steps the bucket'smaxleaf takes, on which the leaf holds: the slot's float32 for the leaf that takes them, the walk's read as a float32 for a leaf that holds beside it, a leaf withsameStepsAsamong them (the value key's own values, a ratio's as the ratio; NaN for a bucket without one, among them a bucket whosemaxleaf's steps the leaf neither takes nor holds on, though it may take steps of its own there); found bylane.leafTotals{ lane, id, steps, seconds }per leaf andnoValueTotals{ 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 areStepDuration, provisional whilepending. A leaf withsameStepsAscounts the steps the leaf it names takes on which it holds with a value that is not NaN, read by the walk, so those steps count in both leaves; the Colors dropdown leaves it out of the time it divides by (BaseStripChart.vue,treeTotals).notes— a built-in tree's{ code, message, args }, what its leaves cannot show about the steps since the last reset (Notes); for a project's or a session's tree, the oneSpecializedTreenote of a play without a spindle capability whose absent keys changed the tree as compiled (A play without a spindle capability); empty else.
Beside it:
GET api/execution/step-properties— each row'sgroup,engineeringfor a color tree's key (built-in, the project's or a session's) andsciencefor any other, andbuiltInTree. The order stays the localized names', and acurrentKeystanding in for a hidden physics key, or for a key the play has no value under, is never a tree's but the stand-in's below: the picker makes the groups (Strip Charts).absentKeyssays which keys the list left out for want of a spindle capability, and why (A play without a spindle capability).- The color guide's
tree—{ key, name, origin, editTreeId, leaves, notes }, the leaves incolorTree.leaves' shape, while the selected guide is a tree's. - The
Individualaspect asked for a built-in tree's key while the slots hold another key answerspending, 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,
SubstituteForWithheldKey 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, and walks the leaves that hold
beside each step's (ColorTreeTrack.ReadAlso) as the slot path does; 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.
SubstituteForWithheldKey withholds a second kind of key: one the play has no value under on any
step (LocalProjectService.StepKeyAbsence.Keys, the spindle's without a spindle capability). While
the project's inspecting key is such a key, it answers the first key of the list step-properties
serves — by localized name, no tree's, neither a hidden physics key nor an absent one, and not read
off the time mapping unless every key is — and currentKey names it. The Individual aspect asked
for the absent key answers the empty payload, not pending: the client reads step-properties again
and asks for its currentKey. The project's key is left as it is, and comes back as the color index
drawn once the capability does. No tree's key is ever absent: a tree is compiled for the absent keys
instead.
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 but SpecializedTree, nor for an empty strip but the
full tree's SpindleCapability of a play without a spindle capability, which is said whatever the
strip holds (A play without a spindle capability). Under
review, one note alone, but for that one again:
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 and spindle power overload step ordinals read 0, as its overload
revolutions do: Spindle torque sustained overload and Spindle power sustained overload are never judged, and their steps
fall into Spindle torque overload, or into Spindle power overload where the spindle torque ratio is not above 100% (both
leaves compare the recorded cut with the spindle capability loaded now); Stress overload, High breakage probability and
Thermal stress overload read the recorded stress ratio and thermal stress ratio themselves and are judged.
In a play without a spindle capability the full tree's is RecordedPlayLoadWithoutSpindle instead,
which leaves the spindle's runs and leaves out — they are not in the tree as compiled — and
SpindleCapability follows it.
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 takes one of two forms. In a
play without a spindle capability (LocalProjectService.StepKeyAbsence not empty) it is the absence's
note, said from the configuration, not from the steps — whatever the strip holds and whether or not
the physics ran, before the first step and under review as well: source none when the runtime
equipment holds no capability (file names the referenced file that could not be read, null when
none is set and no file referenced), noContinuousCondition for one without a continuous torque
or power contour, cacheNotBuilt for one whose speed cache throws at every probed speed (fault the
message), name the capability's for the last two and null for none, absentKeys the keys in
ordinal order, and the text says that the spindle leaves are left out of the tree, the spindle's keys
out of the lists, and that Load not evaluated takes a cut only when its stress ratio has no value.
Otherwise it 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. A project that never set a capability holds none — a new setup starts
null, and a setup file that embeds every value of the class default (TMV-720A-STD-8000RPM) with no
file reference and no Set="true" on its element, as an earlier version saved it, is read as none
(SetupEquipment.SpindleCapability) — and is a play without a spindle
capability, source none with a null file. 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.
A play without a spindle capability
A play without a spindle capability to read against has no value under the spindle's keys on any
step, which the service knows from the configuration before a step is read, and which the trees and
the lists take in once rather than reading no value on each step (the owner, 2026-11-16: only the
spindle capability has this fallback; a missing cutting parameter, workpiece material or coolant
condition stays a ConfigurationWarning).
- The keys.
[NeedsSpindleCapability]marks the[Present]properties ofMachiningStepworked out from the capability, with what they need of it:Capability(the input power, the meter power and the two accumulated energies, which read the energy efficiency and the dry-run power) orSpeedCache(the fifteen that read the limits at the step's speed: the four ratios, the temperature and its ratio, the speed under load with its deviation and its endpoint ratio, the two overload runs' revolutions, peak ratios and step ordinals).StepPresentCatalog.KeysNeedingSpindleCapabilitycollects them. - The absence.
StepKeyAbsence.Of(spindleCapability, spindleCapabilityFile)reads the runtime equipment's capability and the file the setup references: no capability isNotSetwithout a file andFileUnreadablewith one, both every marked key; a capability whose speed cache (SpindleSpeedCache.Createat a speed) comes back null withContinuousConditionNotSetisNoContinuousCondition, and one whose build throws at every probed speed — the gear shift speed and twice it when a positive one is set, 1000 rpm else — isCacheNotBuilt,Faultthe first message, both theSpeedCachekeys alone. A shortest-duration torque or power contour without points is that case:Createinterpolates theMinBycontour at every speed and throws. A capability that builds a cache at one probed speed isNone, as is one that throws on one side of the gear shift speed alone. Without a capability the accumulated energies stay at 0 and the spindle temperature at its starting temperature on every step (HiNc.IntegrationTests/SpindleCapabilityAbsencePlayTests.cs). - When it is read.
LocalProjectService.StepKeyAbsenceis read again wherever the inspecting slots go stale — the setup forwarded to the run, a session's begin, the registry rebuilt, a recompute's end —; an absence of the same case keeps the same key set. When the keys change, the registry's generation moves (BumpStepPropertiesGenerationOnly) and the inspected key is bound anew (UpdateInspectingQuantityFunc): a scan, the guide over the tree compiled again, a redraw. - The trees. Every registered tree — the built-in ones, the project's, a session's — is compiled
by
StepColorTree.Compile(IReadOnlySet<string> absentKeys), andStepColorTreeHolder.Compiledcompiles it again from its source when the absent keys differ from the ones it was compiled for; a preview's tree goes throughLocalProjectService.CompileStepColorTree. The rule (CompiledStepColorTree.Specialize): a term on an absent key that needs a value holds on no step, so anAllwith one never holds and its node goes with its subtree, and anAnydrops it; aNoValueterm on an absent key is dropped from anAll, and from anAnythat keeps a term on another key; a condition left with no term of the ones it had holds always (anAllwithout terms, still a node with a condition), the otherwise after it in its list goes and the nodes with a condition after it stay; anAnyof absent keys' terms without aNoValuegoes; a group kept keeps its specialized condition though no leaf under it is left; a leaf whose value key is absent shows none. Taken out nodes have no lane; the ids of the others do not change.CompiledStepColorTree.Specializationlists the nodesOmitted,NarrowedandValueless,AbsentKeysthe keys,Authoredthe tree as written;HasSameLogicAscompares the trees as written and their absent keys. With a spindle capability nothing is absent and every tree compiles as written. - The lists.
GET step-propertiesleaves the keys out and carriesabsentKeys(BuiltInTreeNotes.AbsentKeysView:reasonnotSet,fileUnreadable,noContinuousConditionorcacheNotBuilt,file,fault,keys; null for none); theAvailabilityaspect leaves their series out; theIndividualaspect asked for one answers empty (The stand-in);StepInfoPresentKeysskips them in Step Properties. The tree editor'skeyOptions, the Step Present preference and the step file keep them; a step's values and a script's read are unchanged. - The notes.
BuiltInTreeNotes.Ofgives the full built-in tree the absence'sSpindleCapabilitynote (Notes), and a project's or a session's tree whoseSpecializationis not empty oneSpecializedTreenote:source(none,noContinuousCondition,cacheNotBuilt),name,file,fault, andomitted,narrowedandvalueless, each{ id, name, isLeaf, holdsAlways }with the node's name as authored. The SPA writes it fromcharts.coloring.note.specializedTree.*(colorTreeNotes.ts,specializedTreeText), each list only when it is not empty.
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, the409and the copy.Execution/BuiltInTreeNotes.cs— a built-in tree's notes, the absence'sSpindleCapabilitynote,SpecializedTreeandAbsentKeysView.Execution/ExecutionChartsController.cs—groupandbuiltInTree,origin,editTreeId, the names resolved and thenoteson both answers; the stand-in (SubstituteForWithheldKey,currentKey,standsInFor,IdColorsPayload);absentKeys, and the absent keys left out of the list, theAvailabilityaspect and theIndividualone;holdingLanes,undecidedLanesandleafValuesthroughColorTreeTrack.ReadAlsoandUndecidedLanes.Execution/StepColorTreeController.csPreview— a sent tree compiled for the absent keys;Common/StepInfoPresentKeys.cs— the absent keys skipped in Step Properties.Common/StepPhysicsKeys.cs—PhysicsColorTrees;Environments/PreferenceController.cs— the Step Present categoryengineeringView;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,readOnlyandcopyStepColorTree;wwwroot-src/src/api/executionCharts.ts—group,builtInTree,originand 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/CompiledStepColorTree.cs—Leaf.SameStepsAsId, the first earlier leaf of a list on a leaf's very condition;FindHolding,CanHoldAfterandFindHoldingAfter, the leaves that hold beside a step's own.HiNc/MachiningProcs/StepColorTreeHoldingReader.cs— the chart's read of those leaves and their values, a step at a time, without a step-cache read a step;LocalProjectService.NewStepColorTreeHoldingReadermakes one an answer.HiNc/MachiningProcs/LocalProjectService.BuiltInStepColorTrees.cs— the registry entry and its registration,IsBuiltInStepColorTreeKeyandReadPlayedUnder.HiNc/MachiningProcs/CompiledStepColorTree.csSpecialize,Specialization,AbsentKeys;HiNc/MachiningProcs/StepColorTree.csCompile(IReadOnlySet<string>);HiNc/MachiningProcs/LocalProjectService.StepKeyAbsence.cs— the absence read, refreshed and compiled for;StepColorTreeHolderinLocalProjectService.ProjectStepColorTrees.cs— the compile again when the absent keys change.HiMech/MachiningSteps/StepPresentCatalog.cs— the reserved keys, andKeysNeedingSpindleCapability;HiMech/MachiningSteps/NeedsSpindleCapabilityAttribute.cs— the mark;HiMech/MachiningSteps/StepKeyAbsence.cs— the four cases and their 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.
See Also
- Step Colors Branch — the branch that calls these routes, its root panel listing the built-in trees first
- Strip Charts — the charts whose answers carry a tree's
originandnotes, and the picker that groups the rows ofstep-properties - Step Color Trees over HTTP — the same routes from a caller's side: bodies, answers and refusal codes
- Engineering View Coloring — the built-in trees from the user's side