Table of Contents

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, 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, valueScale, valueLabels, valueHidden, sameStepsAs }: 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, % for a ratio and for the breakage probability; valueScale the 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; valueLabels the 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's valueLabels (PresentCatalogService.ResolveValueLabels), null for any other key), valueHidden for a physics value key the interface hides, sameStepsAs the id of the first leaf before this one in its own list on its very condition, the same Join and the same Terms in 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's max, 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, one StepColorTreeHoldingReader an 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 as holdingLanes, the steps the bucket's max leaf 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 with sameStepsAs among them (the value key's own values, a ratio's as the ratio; NaN for a bucket without one, among them a bucket whose max leaf's steps the leaf neither takes nor holds on, though it may take steps of its own there); 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. A leaf with sameStepsAs counts 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 one SpecializedTree note 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'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, 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). absentKeys says 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 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, 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 of MachiningStep worked 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) or SpeedCache (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.KeysNeedingSpindleCapability collects them.
  • The absence. StepKeyAbsence.Of(spindleCapability, spindleCapabilityFile) reads the runtime equipment's capability and the file the setup references: no capability is NotSet without a file and FileUnreadable with one, both every marked key; a capability whose speed cache (SpindleSpeedCache.Create at a speed) comes back null with ContinuousConditionNotSet is NoContinuousCondition, 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 — is CacheNotBuilt, Fault the first message, both the SpeedCache keys alone. A shortest-duration torque or power contour without points is that case: Create interpolates the MinBy contour at every speed and throws. A capability that builds a cache at one probed speed is None, 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.StepKeyAbsence is 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), and StepColorTreeHolder.Compiled compiles it again from its source when the absent keys differ from the ones it was compiled for; a preview's tree goes through LocalProjectService.CompileStepColorTree. The rule (CompiledStepColorTree.Specialize): a term on an absent key that needs a value holds on no step, so an All with one never holds and its node goes with its subtree, and an Any drops it; a NoValue term on an absent key is dropped from an All, and from an Any that keeps a term on another key; a condition left with no term of the ones it had holds always (an All without terms, still a node with a condition), the otherwise after it in its list goes and the nodes with a condition after it stay; an Any of absent keys' terms without a NoValue goes; 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.Specialization lists the nodes Omitted, Narrowed and Valueless, AbsentKeys the keys, Authored the tree as written; HasSameLogicAs compares 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-properties leaves the keys out and carries absentKeys (BuiltInTreeNotes.AbsentKeysView: reason notSet, fileUnreadable, noContinuousCondition or cacheNotBuilt, file, fault, keys; null for none); the Availability aspect leaves their series out; the Individual aspect asked for one answers empty (The stand-in); StepInfoPresentKeys skips them in Step Properties. The tree editor's keyOptions, the Step Present preference and the step file keep them; a step's values and a script's read are unchanged.
  • The notes. BuiltInTreeNotes.Of gives the full built-in tree the absence's SpindleCapability note (Notes), and a project's or a session's tree whose Specialization is not empty one SpecializedTree note: source (none, noContinuousCondition, cacheNotBuilt), name, file, fault, and omitted, narrowed and valueless, each { id, name, isLeaf, holdsAlways } with the node's name as authored. The SPA writes it from charts.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, the 409 and the copy.
  • Execution/BuiltInTreeNotes.cs — a built-in tree's notes, the absence's SpindleCapability note, SpecializedTree and AbsentKeysView.
  • Execution/ExecutionChartsController.cs — group and builtInTree, origin, editTreeId, the names resolved and the notes on both answers; the stand-in (SubstituteForWithheldKey, currentKey, standsInFor, IdColorsPayload); absentKeys, and the absent keys left out of the list, the Availability aspect and the Individual one; holdingLanes, undecidedLanes and leafValues through ColorTreeTrack.ReadAlso and UndecidedLanes.
  • Execution/StepColorTreeController.cs Preview — 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 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/CompiledStepColorTree.cs — Leaf.SameStepsAsId, the first earlier leaf of a list on a leaf's very condition; FindHolding, CanHoldAfter and FindHoldingAfter, 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.NewStepColorTreeHoldingReader makes one an answer.
  • HiNc/MachiningProcs/LocalProjectService.BuiltInStepColorTrees.cs — the registry entry and its registration, IsBuiltInStepColorTreeKey and ReadPlayedUnder.
  • HiNc/MachiningProcs/CompiledStepColorTree.cs Specialize, Specialization, AbsentKeys; HiNc/MachiningProcs/StepColorTree.cs Compile(IReadOnlySet<string>); HiNc/MachiningProcs/LocalProjectService.StepKeyAbsence.cs — the absence read, refreshed and compiled for; StepColorTreeHolder in LocalProjectService.ProjectStepColorTrees.cs — the compile again when the absent keys change.
  • HiMech/MachiningSteps/StepPresentCatalog.cs — the reserved keys, and KeysNeedingSpindleCapability; 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 origin and notes, and the picker that groups the rows of step-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