Color Trees
A color tree sorts steps by condition and colors each leaf. The color index, a range over an amount and one color per ID are on Color Guide System.
A color tree (StepColorTree(API)) is a step property whose value on a step is the id of the leaf the step falls into, with a color per leaf. Its key shares the key space of the step variables, and the property is categorical: as the color index it is colored one color per leaf, by the tree's own hues. The project keeps its trees in StepColorTreeList(API), saved with it and registered from the load on, in every session; a mission script registers one for its session (Defining a Tree).
HiNC defines two trees of its own, Machining State under the key MachiningState and Machining
State (No Physics) under MachiningStateGeometry
(BuiltInStepColorTrees(API)), whose leaves
Engineering View Coloring describes. They are registered
whenever a project is open, and are read-only: they are no part of the project's list, are never saved
with it and follow HiNC's version.
New(API) builds a new copy of one, its
names and short names in the culture given (English when none is), and null for a key without a
built-in tree; under a key of its own, a host adds the copy to the project's list and a script
registers it for its session, and from there it is a tree like any other.
How a Step Is Sorted
- The first node that holds takes the step. The nodes of a list are tried in order. A leaf (StepColorLeaf(API)) whose condition holds gives the step its id; a group (StepColorGroup(API)) whose condition holds hands the step to its own children, and only they are tried then. A node without a condition takes every step that reaches it: the list's “otherwise”. A step no leaf takes — no node of a list held, or a group took the step and none of its children did — has no value under the tree's key, and the 3D view draws it in the no-value green.
- The leaves that hold beside it. A leaf with a condition holds on a step when its own condition holds and so does the condition of every group above it, whichever node took the step. A leaf without a condition holds only on the steps it takes, a node after one without a condition in its list neither takes nor holds, and a step no leaf takes has no leaf that holds. Every leaf that holds beside the step's own therefore comes after it in tree order. Only the Color Index Time Chart reads them, as bars in their lanes (Where the leaves show): the tree's value on the step, its colour, Step Properties, the step file and a preview, its trace included, keep the one leaf the step falls into.
- A condition (StepColorCondition(API)) joins its terms by
AllorAny; without terms,Allholds for every step andAnyfor none. A term (StepColorTerm(API)) names a step property by its key and compares the step's value with a threshold —Gt,Ge,Lt,Le,Eq,Ne— or asks whether the step has a value under the key,HasValueorNoValue, with no threshold (StepColorOp(API)). - No value. A step without a value under the key — a number that is null or NaN, a text that is
null or empty — satisfies no comparison,
Neincluded;NoValueholds for it. A yes / no property reads as 1 or 0, soEqwith 1 asks for yes; a cutter zone (StressCriticalZone,StressOnsetZone) reads as the number of its CutterBeamZone(API), soEqwith 3 asks for the cylinder; and a text reads as a value when it is not empty. The physics values have none on a play without the physics, so a tree over them passes those steps on to the nodes below. - What a term can name. Any step property: the built-in ones, the machine coordinates, the
project's step variables, and the keys a script, a mapping or a training registers. The built-in ones
include the yes / no
IsRapid(commanded as a rapid traverse) andIsTouched, and eight that span steps:SpindleTorqueOverloadRevolutions,SpindlePowerOverloadRevolutionsandStressOverloadRevolutions, the spindle revolutions of the run of consecutive steps above 100 % the step is in — the spindle torque ratio, the spindle power ratio, the stress ratio —,SpindleTorqueOverloadPeakRatioandSpindlePowerOverloadPeakRatio, the peak of the spindle's torque run and of its power run,SpindleTorqueOverloadStepOrdinalandSpindlePowerOverloadStepOrdinal, the step's place in the spindle's torque run and in its power run, counted in steps from 1, andIsRapidCut, a rapid step that removed stock — with the deflection transformation on, not one that only rubbed the layer a deflected cut just left (Step Field Reference). A key that matches no step property reads as no value, and the session messages say so after the play. A tree's own key, or another tree's, reads as no value too: a tree is not read inside a tree.
Leaves: Hues, Ids and Values
- The hue. A leaf's Hue_deg(API) is the HSL hue of its color in degrees, drawn at full saturation and half lightness: a leaf's color is a hue alone. A hue picked by hand may be any, red included; a value outside 0 to 360 is taken modulo 360, with a warning, and NaN or an infinity counts as none. A leaf without one gets an automatic hue from its id, the one the id has under one color per ID, which keeps off 300° to 30° and 220° to 270°.
- The id. A node's Id(API) is from 1 to 1,048,575 (2²⁰ − 1). A node without one is numbered from the tree's NextId(API) when the tree is written, cloned or compiled — 1, 2, 3… in tree order for a tree built without ids, the same numbers every time — and a number is never given to a second node, so a deleted node's number stays free. The leaf's id is the tree's value on a step: what a step file writes under the tree's key, and what each step stores while the tree is the color index.
- The value key. A leaf may name a step property, ValueKey(API), whose values the Color Index Time Chart draws for the leaf's steps: a band inside the leaf's lane, from the least to the greatest value in each pixel column that bars the leaf — of its own steps where it is the most important leaf of the column's steps, and of that leaf's steps where it holds beside it —, scaled between the least and the greatest of the leaf's values the chart reads for the display range. The colors read the id alone, so a value key changes no color: the leaf's steps keep its one color in the 3D view. A value key that is a text shows 1 for a text and no value for none.
- Two leaves on one condition. A leaf whose condition is the very one of an earlier leaf of its
own list — the same
Join, the sameTermsin order; a leaf without a condition never matches; of three leaves on one condition the second and the third both name the first — takes no step, each being that earlier leaf's: Step Properties, the step file and the 3D view go by the earlier leaf, and a preview reads the later one 0 steps. It holds wherever the earlier leaf holds, so the Color Index Time Chart bars its lane and draws its value over the earlier leaf's steps, as for any leaf that holds (When a Tree Is Evaluated says which values it can read there). The built-in Machining State draws High breakage probability over Stress overload's steps this way, and a copy keeps it because the conditions are copied; changing one of the two conditions makes them ordinary leaves again. - The short name. A leaf's ShortName(API) is
the label of its lane on the Color Index Time Chart, where the room is about nine Latin letters or
five CJK characters; the legend, the lists and the tooltips keep the full name. It is saved as the
ShortNameattribute of<Leaf>, written only when it is not empty, and an empty one prints the name, cut to fit. Like the name, it changes no color. - Where the leaves show. While a tree is the color index, the 3D view draws each step in its leaf's
color, the Color Index Time Chart draws a lane per leaf — the first leaf at the top, named on the axis
by its short name, or by its name cut to fit when it has none, each lane kept whether or not a step
fell into it, and a pixel column that holds steps of several leaves drawn in the first of them, the
tree's order being the leaves' importance, with a grey bar in its lane and in the lane of each leaf
that holds on its steps — and the chart's Colors dropdown lists the leaves with their steps and time share
over the display range (Strip Charts). Step Properties prints a tree's
row as the leaf's id and name —
4 · Withinfor the tree below — and-for a step in no leaf.
Refusals and Warnings
A tree that cannot be evaluated as written is not registered; one that can, however odd, is registered as it is, with a warning. FindProblems(API) lists a tree's problems, each with its place in the tree, without reporting them.
- Refused — a tree without a key (a script's is reported; a project's is skipped silently, absent from the Step Colors root and the HTTP API's list), a term without a key, a comparison without a threshold, an id repeated or out of range, and a tree this version does not understand: an element, a comparison or a join it does not know, or a number it cannot read. A project's refused tree stays in the project and is saved back as written.
- Under a key that is taken, and not registered — a key named like a built-in step property or
one of HiNC's own trees,
MachiningStateandMachiningStateGeometry, or underMC., which the machine coordinates reserve; for a project's tree, a key a project step variable or an earlier tree has; for a script's, a key the project defines a step variable or a tree under. - Registered with a warning — a list without a node that takes every step, a node after one that
takes every step, which no step reaches,
a condition without terms, a group without children, a hue outside 0 to 360, a
NextIdoutside its range. - Checked against the step properties of the moment, on a tree as it is edited, by the Step Colors
root and the HTTP API's
check— a color tree's key, which reads as no value; a physics key the interface hides, which the tree reads all the same; a key no step property has yet, which reads as no value until a play or a script registers it; a value key not a quantity. - Put right on the load — a node without an id, or with one another node has or that is out of range, is numbered on the load, with a warning, and saved back with the number it got.
Each is reported but a project's tree without a key: a project's with the messages of its load, of each session's begin and of a refresh; a script's once per key in the session's messages. A key whose read throws on a step leaves that step in no leaf, said once a session.
Defining a Tree
A tree is defined in one of four places, each described on its own page:
- On the Execution page, under the Control Tree's Step Colors root, with a check and a preview before Apply: Step Colors.
- Over the web service's HTTP API, under
/api/execution/step-color-trees, with the same check and preview: Step Color Trees over HTTP, and from a question to a colored run in Workflow: Coloring Steps by Condition over the HTTP API. - In a mission script, for the session alone: RegisterStepColorTree(API) registers a tree that goes with the session and is never saved (Registering a Color Tree); a host does the same with RegisterStepColorTree(API).
- Over the SDK, in the project's list, below.
The check reports a tree's problems, and the preview sorts the played steps under it — the steps and the time each leaf takes, and the nodes one step went through; neither changes the project, the color index or the colors. A tree colors the run once it is the color index.
What is registered is a compiled copy of the tree, so a change to the tree object changes nothing until the tree is registered again. A threshold is in the key's own values: a ratio's is the ratio, in the SDK, the project file and the HTTP API alike, and only the Step Colors editor shows and takes it in percent (a threshold of 1 there reads 100). The tree the examples use, built as a script or a host builds it; its threshold, 1 for each ratio's 100 %, only illustrates the shape and is no limit HiNC sets:
StepColorTerm Above(string key) => new(key, StepColorOp.Gt, 1);
var tree = new StepColorTree
{
Key = "RatioCheck",
Name = "Ratio check",
Nodes =
[
new StepColorLeaf { Name = "Rapid",
When = StepColorCondition.All(new StepColorTerm("IsRapid", StepColorOp.Eq, 1)) },
new StepColorGroup { Name = "Ratios known",
When = StepColorCondition.All(StepColorTerm.HasValue("StressRatio")),
Children =
[
new StepColorLeaf { Name = "Above 100 %", Hue_deg = 0,
When = StepColorCondition.Any(Above("StressRatio"),
Above("MaxSpindleTorqueRatio"), Above("MaxSpindlePowerRatio")) },
new StepColorLeaf { Name = "Within", ValueKey = "MaxSpindlePowerRatio" },
] },
new StepColorLeaf { Name = "Other" }, // no When: every step that reaches it
],
};
In the project file the trees follow the step variables, under StepColorTreeList, written only when
the project has one; a group holds its condition, then its children. The same tree, as saved:
<StepColorTreeList>
<StepColorTree Key="RatioCheck" Name="Ratio check" NextId="6">
<Leaf Id="1" Name="Rapid">
<When Join="All">
<Term Key="IsRapid" Op="Eq" Threshold="1" />
</When>
</Leaf>
<Group Id="2" Name="Ratios known">
<When Join="All">
<Term Key="StressRatio" Op="HasValue" />
</When>
<Leaf Id="3" Name="Above 100 %" Hue_deg="0">
<When Join="Any">
<Term Key="StressRatio" Op="Gt" Threshold="1" />
<Term Key="MaxSpindleTorqueRatio" Op="Gt" Threshold="1" />
<Term Key="MaxSpindlePowerRatio" Op="Gt" Threshold="1" />
</When>
</Leaf>
<Leaf Id="4" Name="Within" ValueKey="MaxSpindlePowerRatio" />
</Group>
<Leaf Id="5" Name="Other" />
</StepColorTree>
</StepColorTreeList>
The rapid steps go to Rapid first. On a play without the physics the ratios have no value, so every
other step fails the group's condition and goes to Other; with the physics, Within draws the max
spindle power ratio of its steps as a band in its lane.
Editing the project's trees over the SDK. Replace StepColorTreeList(API) with a new list rather than changing it in place — it is enumerated while the project is saved — and call RefreshStepVariables(API) after it: the refresh compiles the project's step variables and color trees again, registers them in place of the ones registered before and reports what it does not register. A host that edits from more than one thread takes StepDefinitionEditLock(API) around the edit and the refresh that follows; the refresh takes the same lock itself, and readers of the step properties never take it.
// lps: the LocalProjectService the project is loaded in; tree: the StepColorTree above
lock (lps.StepDefinitionEditLock)
{
lps.MachiningProject.StepColorTreeList = [.. lps.MachiningProject.StepColorTreeList, tree];
lps.RefreshStepVariables();
}
When a Tree Is Evaluated
A tree is evaluated once per step, not once per frame. Each step keeps one stored value of the color index — for a tree, the leaf the step fell into and the leaf's value — computed as the step is built, after the step-built handlers have run. A background scan computes it again for every step whenever what it was computed from changes: another color index, a step variable or a tree registered or refreshed, a session's begin, a recompute of the step physics or a change to the environment the physics reads, values written onto the steps, a cutter or a material the steps read changed in the tool house. Until the scan has reached a step, the step's stored value reads as no value. A run of overload is known only when it closes, and a rapid line that removed stock only when the line ends, so the stored values of a tree that reads them are computed again for the steps of a run or a line as it closes; until then the steps of an open run hold the running total as it stood when each was computed.
The 3D recolor and the Color Index Time Chart read the stored values: neither evaluates the tree per redraw. Step Properties, a step file and a preview evaluate the tree for the steps they show, from the steps themselves.
The leaves that hold beside a step's own are read by the chart, each time it answers. They are
stored nowhere: for each step of the answer the chart starts at the leaf the stored value names and
tries the leaves after it, reading a key only when a term needs it. Where the leaf's own All
condition, or a group's above it, fixes a key's value — Machining State‘s Cutting fixes
IsTouched at yes — a later leaf that needs another value of it is passed over unread, so on the
steps most of a play is made of — a normal cut, a thermal stress overload, an air cut, a rapid — the built-in trees
read nothing. A key is read as the tree reads it, but never from
the step cache: a value the step keeps in memory or in the step physics channels is read, and a key
whose read reaches the step cache — a step variable a mission script writes onto the steps, for
example — decides nothing on that step and is read from then on only where the channels answer for
it. A read that throws decides nothing on its step either. A leaf whose condition or value could not
be read on some step of the answer is listed in the answer as undecided, without a bar or a value
there, and the chart marks its lane with ?; the built-in trees’ keys are all read from memory
or the channels, so they have none. The value a leaf shows beside another's is read the same way.
An edit that changes only the names, the short names and the hues of a project's tree — on the Step Colors root or over the HTTP API — keeps the stored values: the leaf ids are the same, so nothing is computed again, and the colors and the names follow at once. Any other edit, and every refresh over the SDK, registers the project's definitions again, and the scan follows.
A tree reads every key it names on every step it sorts, whichever node takes the step, and the scan reads what the steps keep in the step cache a segment of steps at a time.
Values written onto steps after they were built. A value a step-built handler — a script's
SessionStepBuilt(API), a host's
MachiningStepBuilt(API) — writes onto the
step being built is in the step's stored value as the step is published. A batch written with
WriteStepVariables(API) marks the stored values
stale once per batch, a single step["key"] = value after the play marks them itself, and so does a
mapping of measured data onto the steps; the scan follows. Host code that writes through the indexer
onto an earlier step while a play runs calls
NotifyStepValuesWritten(API) once its
writes are done: such a write can travel to the step cache with that step's own results, and then marks
nothing stale.
A cutter or a material changed after the play. The breakage probability and the thermal stress ratio read the cutter of the moment: a step keeps the tool it was played with and reads that tool's cutter as it is now. The web service's cutter routes — a cutter installed or cleared, its integral mode switched, a flute or shank material loaded or unset — mark the stored values stale, and the scan follows. Host code that edits a cutter's material in place calls NotifyToolHouseChanged(API) once the edit is done: a fracture strength or a Weibull modulus is no input of the stored step physics, so no recompute marks anything stale for it. A leaf drawn over another leaf's steps, as High breakage probability is over Stress overload's, stores no value: the chart reads its line each time it answers, so nothing has to be refilled for it, but a chart at rest reads again only when it is told to, which is what the scan after this call does.
See Also
- Color Guide System — the color index and the guides under it, of which a color tree is one
- Step Colors — the Execution page where a project's trees are defined, checked and previewed
- Step Colors Branch — how that root is built, and the routes it calls
- Step Color Trees over HTTP — the trees' HTTP routes
- Workflow: Coloring Steps by Condition over the HTTP API — a tree built, checked, previewed and shown over the HTTP API
- Strip Charts — the Color Index Time Chart, a lane per leaf