Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

How a colour is found

RESQML 2.0.1 has no colour at all; from 2.2 on, colour is carried by graphical information objects that apply to an object, to a collection of objects, or to a whole model. An object that carries nothing itself can therefore still be drawn in a colour that was chosen for something it belongs to. This page states the order in which the library looks, and what it answers.

The walk lives in energyml-domain (inherit for the order, which knows nothing about colours; color_inherit for the colour question). It reads relations from the package index, so no object is opened to follow a link. The rule that there is one colour decision for every face is in ADR 0009.

The order

The first rank that has an answer wins.

RankWhere the colour is looked for
1on the object itself
2on the collections that reference it, then on the collections of those collections
3on its parents
4on the collections that reference those parents, nested
5on the parents of the parents, with the same rules, one stage up at a time
6on the model that references the object or one of its parents

A parent is reached through the three fields a representation, an interpretation and a feature climb by: RepresentedObject, RepresentedInterpretation and InterpretedFeature (the feature / interpretation / representation chain, “FIRP”). A collection is a membership written by a CollectionsToDataobjectsAssociationSet: a member is in the collection of the association with the same index.

Within one rank the shortest path wins; at equal length the first in document order wins, and the other candidates are kept and shown as ties, not hidden. Rank 5 is read stage by stage, so a collection of a grandparent does not race a great-grandparent. Some things are noted but not followed: the collections of the model, and any collection that is a project.

A property has a shorter path: the property, its property kind, the kind’s parents, a collection at each step, and nothing beyond. A property never takes the colour of the representation it hangs on, nor of a model.

What the answer carries

An answer is not just a colour. It carries:

  • the level it was found at (the object, a collection, a parent, the model), read from the last step of the path;
  • the path from the object to the one that carries the colour: each step says where it leaves, where it arrives, by what kind of link (parent, collection, model) and through which field;
  • the ties that lost, and the notes about what was skipped and why (a cycle, a duplicate association, a colour on a collection that is not followed).

A face that shows a colour can therefore also show why it is that colour.

Nothing found is no colour

When no rank answers, the answer is none. The library does not invent a default: choosing what to draw then is the decision of the view, which is the one that knows whether to derive a hue from the identifier, draw grey, or hide the object. This follows refuse rather than draw.

Placing a value on the map

Finding the colour map is one question; placing a value on it is another. ColorMap::sample takes the value and a Scaling (the ColorInformation of the object) and does this, in order:

  1. A missing value or a NaN has the map’s null colour, whatever the scaling.
  2. MinMax, when given, is the range of values that spans the map; a value outside it takes the extreme colour. Without MinMax, the map’s own range stands for the range of the values.
  3. Under UseLogarithmicMapping, the log of the value is what is placed between the logs of that range (RESQML TRG 2.2 section 4.5, p. 56).
  4. InterpolationMethod (linear or logarithmic, section 4.7 p. 58) is a different thing: the spacing between two stops of a continuous map. The two may be combined, and neither stands for the other.

A range that reaches zero or less has no logarithm. ColorMap::check_scaling refuses it by name, try_sample returns that refusal, and sample answers None (call check_scaling once to say why). The null colour is still given to a missing value. See ADR 0025.

Cycles and duplicates

A collection that holds itself, near or far, is a cycle: it is named, and the walk does not follow the edge that closes it. The same collection named in two associations of one set counts once, as does an object listed twice in an association, as the common schema’s rules on collections require; both cases are counted in the notes.

Reading a colour map once

A colour map shared by thousands of properties is read and validated once by a Cascade, then kept for the life of that cascade (and for the one source it was read from). Nothing invalidates it: a caller whose package changed builds a new cascade, as it already does for the set. The stops of a map are sorted by index, and sampling a value bisects them instead of walking them from the first.