Mesh and tet volume items

Status: Complete Last Updated: 2026-10-15

This page tells how the viewport colors and lights a tri mesh item and a tet volume item. It also tells what the viewport does where two items cover the same surface.

The two tones

Each item type has its own tone. A tone comes from the primary color of the palette, which is the highlight color of the edition you run.

The turn happens in CIE LCh, so the lightness that you see does not change with the hue. Each tone also gets its own lightness, between L* 35 and 80. The palette chooses the two lightness values that keep the primary and the two tones far apart. The test is a CIE76 difference of at least 25 between each pair, in normal vision and under protanopia, deuteranopia and tritanopia. Each edition's seed passes it.

The tones are not stored. When the palette changes, the tones change with it, in the viewport and in the scene tree.

What colors an item

The first rule that applies wins:

1. A field. The item shows a scalar field of its asset through a colormap. See Fields.
2. A material. If you give the item a material that differs from the default, its albedo colors the item.
3. The tone of the item type. The default gray material never shows on a mesh or a tet volume.

Edges and light

Both types draw the edges of their triangles. A tet volume draws the triangles of its boundary and of the caps of its cut planes. The edge color is the surface color, lighter by 15 in CIELAB L*. Both types use one shading function, so a tet volume and a mesh baked from it look the same.

The edge is less diffuse and smoother than the surface, so it looks shinier. A tri mesh shades smooth across edges under 45 degrees. A tet volume shades flat. A mesh item can store its own angle as creaseAngle in its type data. A boundary bake of a tet volume stores 0, so it shades flat and looks the same as the volume.

A highlight does not change these colors. A hovered or selected mesh or tet volume shows its outline only.

Fields

A field is a named value for each element or each vertex of an item's asset. An element field colors each triangle flat. A vertex field blends the color across each triangle. A vector field shows as its length.

The other fields come from the asset file, for example the result of a simulation. A field with one value only shows the middle of its colormap.

The fields of a file are a field set. Each field has a descriptor: its name, its arity (scalar, vector or symmetric tensor), its location (node or element), its unit, its frame and its axis. A derived field is a field kernel over the stored fields, for example the kernel von_mises over the stress tensor. The viewport runs the kernel on the GPU, and the hover and OPAL run it on the CPU, from one text, so they give the same value.

To color an item, use the Field row of its box, or Mesh ▸ Field or Tet ▸ Field in its menu. To color an item from OPAL, use the task construct.presentation.add or construct.presentation.set. A new field keeps the colormap and resets a manual range.

Presentation

What an item shows of its fields is its presentation: an ordered list of presenters, in the item's type data as presentation. Each entry is a map {kind, id, enabled, params}. params holds only the parameters that differ from the default. An item with no presenter stores no key.

An item has at most one color presenter. The model refuses a kind that the item type does not take, and gives the reason. construct.presentation.kinds lists each kind with its parameters. Every kind draws.

A presenter that draws nothing stays in the list, and says why. The reasons, in the order they are checked:

1. The presenter is hidden.
2. Its field is not in the item's field set, for example after a solve that did not write it.
3. Its field has an arity that the kind does not take. deform takes a vector field, threshold a scalar field, and glyphs a vector or a tensor field. The other kinds take any field, and a vector shows as its length.
4. A ghost has no deform with a scale that is not 0.
5. The kind has nothing to show: a deform whose scale is off, a probes presenter with no probe, a cut with every plane off or with planes that keep nothing, a threshold that no element passes, a setup with no solve setup, or glyphs on the section with no plane that cuts.

construct.presentation.add and construct.presentation.set refuse a field of an arity that the kind does not take, and change nothing.

The color presenter has these parameters:

The deform presenter of a tet volume moves each node by a vector field times a scale. The vertex shader moves the node, so a change of the scale or of the animation phase uploads nothing. The cut planes test the rest shape, and the box of the item, which frames the camera and places the gizmo, stays the rest shape's.

phase and axisStep can hold an expression, as an item's parameters can. The item keeps them as the parameters presentation.<presenter>.phase and presentation.<presenter>.axisStep, so they evaluate on every frame of the timeline and of a render, they save with the scene, and an edit is one undo step. A phase sets the phase whatever animate says. A value past 0 or 1 holds at that end, so = anim.frame / 120 deforms over 120 frames and holds. A render that steps an axis gets the fields of each value it reaches before it starts, and one render steps one axis.

The scale shows as a multiplier, for example "×280 (auto)", in the presenter's row and on the legend. A field in world axes turns into the item's axes first, so an item's own scale does not scale the motion twice. The normals of a moved face come from the moved triangle.

The ghost presenter draws the rest shape over the moved one, translucent (style translucent) or as its edges (style wire). It draws only while a deform presenter moves the item, and it takes no click.

The markers presenter puts an anchored label at the extremes of a field: a dot at the place, a leader line and the value, in the unit of the item's legend.

A marker on a deformed volume moves with its place. A marker whose place a surface hides draws at 40 % opacity with a dashed leader. When the legend of the item ends at a percentile, a label marks the true maximum too.

The cut presenter of a tet volume cuts it with up to six planes. Each plane is perpendicular to one axis of the item. A part shows when it is on the kept side of every plane that is on. The cap of each plane is the face of the cut. It shows the field with the surface's colormap, range and kernel, and the other planes clip it. The caps move with a deformed part.

The threshold presenter of a tet volume shows only the elements where a scalar field passes a test. The elements that stay make a closed surface.

For a field at the nodes, an element passes below when its smallest node value does, and above when its largest node value does. A threshold and the cut planes work together: an element shows when it passes the threshold and is on the kept side of every plane.

The probes presenter holds the pinned points of an item, in the item's own axes. Each probe shows as a label with its name and the value of the shown field, and the Probes tab lists every field at each probe. A probe of a mesh lies on its surface.

To change the probes, use the Probes tab or the construct.probe.* tasks. Each change is one undo step. See Probe values.

Values at a point

The value of a field at a point comes from the sampler. It finds the tetrahedron that holds the point and the weights of its four corners. A derived field (a kernel such as von Mises) is computed at the corners first, and then the value is weighted. So the value is the color that the viewport shows at that point. A field of the elements gives the element's value. A point outside the volume has no value.

The hover readout of a tet volume that shows a field adds one line, for example "von Mises 182.4 MPa (interpolated)", and the legend marks the value with a tick. The first hover on a large volume says "Locating…" while the search tree builds. On a deformed volume, the hover reads the value of the material point under the cursor: the point of the part as modeled that moved there.

Axis values

The fields of an item can vary over an axis: a load case, a mode, a time step or an iteration. Every presenter of the item shows one value of each axis. The item stores the values in typeData.presentationAxes, a map of axis id to value index. An axis with no entry shows its first value.

The view clock can play an axis. It shows ten values a second and then starts again from the first value. A play changes no document. While an axis plays, the range of full and robust is the range of all the axis's values, so the legend does not change between values. The scale of a deformation is the largest motion over every value, in a play and out of one. A play holds a value until the fields of the next value are built.

construct.view.clock reads and sets the view clock: running pauses or starts it, phase fixes the phase of a deformation's cycle, speed scales its time (1 is real time, from 1/16 to 16), and axisStep shows an axis value in the view only. A resume goes on from the time of the pause. Its answer names the axes that play in playing. It makes no undo step.

While the clock runs, only the tet volumes and the meshes move. The SDF items keep the image of their last ray march, and each frame copies it in under the moving items: a frame of an animation marches no SDF again. A camera move or a change of an SDF item marches again. The clock ticks about 30 times a second, on a whole number of the display's refreshes. It stops while its window is in the background, hidden or minimized.

Each task that changes the presentation is one undo step.

Field information

An item can describe each field of its asset in its fieldInfo map: a label, a unit and a frame. A solve writes the information of its four fields (see Solve a tet volume). The computed fields of the table above carry theirs from the code.

The range and the colormap are not field information. They are parameters of the color presenter.

construct.scene.get_item reports fieldInfo for a mesh or a tet volume. It also reports presentation, and for an item with a field set, fieldSet: the descriptors of the fields, the axes, the producer and the located extremes.

One display rule

The tet layer, the mesh layer, the legend and OPAL use one rule to choose what a field shows. The rule reads the color presenter. For each part, the first that applies wins:

Then the cap limits the high end of a full or a robust range, and symmetric makes the range plus and minus its largest absolute value.

construct.presentation.set reports the result as display, and construct.view.legends lists the legends that the viewport shows, with the same values. Each legend also has its rangeMode, its percentile or its targets, symmetric and displayUnit.

Colormaps

Each colormap is a file that ships with the application. The file name is the colormap's id. Each file names where its table comes from and its license. "Original" in the table means a table made for this application.

Add :reversed to an id to read the map the other way. The factor of safety of a solve shows in fos-bands, with a targets range.

Color vision

viridis, cividis, batlow, cool-warm and vik stay readable for a reader with a color vision deficiency. The tests check each map under a simulation of protan, deutan and tritan vision: a sequential map gets lighter from end to end, and two entries 1/16 of the map apart differ by a CIE76 ΔE of at least 3. The rainbow maps fail that check, and the menu says so.

Values outside the range

The color presenter chooses what a value outside the range shows, with the key outOfRange:

The legend shows a swatch for each gray that the data reaches, and a no-data swatch when the field holds a NaN.

A surface that shows a field is lit with a limited light: the shading changes its color by at most ΔE 12 from the legend's color. Set lighting to flat in the color presenter for the legend's exact color.

Bands and the log scale

Set bands in the color presenter to a number from 2 to 24 for flat steps of color. Each band is the map's color at the band's center, and the legend puts its ticks on the band edges. Set scale to log for a log scale. A range that holds 0 or a negative value refuses it, and the legend says why.

The legend's ticks

The two ends of the legend show the exact range. The ticks between them are round numbers: 1, 2 or 5 times a power of ten. Each tick has the unit.

Add a colormap

A colormap is data, so a new one needs no code. Add a colormap tells how.

Two items in one place

Where two items cover the same surface, each pass moves its depth toward the camera by a small amount from a key. The key comes from the item. This gives three modes:

The move is under a pixel, and a pick takes it back out, so a pick returns the true surface point. For how this looks in the viewport, see Two items in one place.