Mesh and tet volume items

A tri mesh item and a tet volume item are finished geometry in the scene. A bake makes them from an SDF branch, and an import makes them from a file. This page tells how to import them, how to tell the two types apart, how to color them by a value and how to process them.

Import a mesh or a tet volume

1. Point at the gap in the scene tree where the item must go. A tag appears in the gap. Click its Mesh button. Or click Import… in the Things finder. Or choose Import mesh or tet volume… in a row's menu.
2. Choose the file. The dialog lists the formats that Construct reads: STL, OBJ, PLY and VTK.
3. The item appears at once with a progress mark, and fills in when the file is read.

The file decides what the item is:

The item lands where you opened the import: under the group of that gap, or at the root. The item keeps the path of its file, relative to the saved scene. When the file changes on disk, Construct offers to reload it.

The OPAL task construct.item.import_file does the same. OPAL uses it when you give it a model file as a reference, see Ask OPAL to look at your scene.

Tell a mesh from a tet volume

From the outside, a tet volume looks like a tri mesh: you see the triangles of its boundary. The viewport gives each type its own tone, so you can tell them apart.

• A tri mesh shows the primary color of the palette, turned by half a turn of hue.
• A tet volume shows the primary color, turned by three quarters of a turn.
• Both types draw the edges of their triangles, a little lighter than the surface.
• The scene tree row shows the same tone as the viewport.

If you give the item a material, the material colors the item instead of the tone. A hovered or selected item shows its outline only.

Color an item by a value

An item can show a scalar field of its asset through a colormap. To choose the field:

1. Right-click the mesh row or the tet volume row.
2. Choose Mesh ▸ Field or Tet ▸ Field.
3. Choose a field, or none to show the tone again.

The menu lists the fields that the item's asset stores under Stored, then the derived fields under Derived. A tri mesh always has dihedral, the largest angle between two faces at each vertex. A tet volume always has quality, volume, depth, skewness and radius ratio. A result of a simulation that is stored in the file shows as one more field. A derived field is a field kernel that fits the stored fields. The menu shows it by its label and its inputs, for example "von Mises stress (stress)".

The menu of an item has more entries for its fields. On a mesh, Mesh ▸ has Show min and max, Show peaks, Show glyphs, Show principal axes, Add probe, Line probe, Export probes as CSV… and Export field image…. A probe of a mesh lies on its surface. The Tet ▸ entries are in Work with a tet volume.

The presentation rows

What an item shows of its fields is its presentation: an ordered list of presenters. Each presenter shows the fields in one way:

Solve a tet volume shows each presenter on a solved part.

Click the arrow of the item's row to open its box. The box of a mesh or a tet volume has these rows:

Each change is one undo step, and one drag of a number is one step. Undo restores the field that the item showed before.

When a presenter draws nothing, its header tells you why, in the warning color. For example, the field is not in the item's field set, or a ghost has no deformation to show. The presenter stays in the list, so a new solve that writes the field shows it again. A field row offers only the fields that its presenter takes: a deformation takes a vector field, and a threshold takes a scalar field.

The color presenter has these parameter rows:

The Range row has these modes:

A new field keeps the colormap and resets a manual range.

The legend

When an item shows a field, a legend appears at the bottom right of the viewport. It gives the item, the field and its unit, the colormap and five values of the range. Its caption names the range mode, for example "Robust (95 %)", "Manual" or "Targets 2 and 4". For a robust range, a line over the bar gives the true maximum of the field. A mark ≥ at the top says that some values of the field are above the range, and ≤ at the bottom that some are below it. Items that show the same field with the same range and colormap share one legend. At most three legends show. A last line counts the others. The legend is part of the viewport, not of the scene. A rendered image shows it only with the option Field overlays of the render export. Tet ▸ Export field image… and Mesh ▸ Export field image… open the render export with that option on. See Read the result.

The legend takes the mouse:

A legend that several items share changes all of them, in one undo step. Its tooltip gives the count, for example "Range of 3 items".

Process a mesh

The Mesh ▸ submenu of a mesh row holds the operations that work on a finished mesh:

An operation changes the item. It does not add a new item.

1. The operation runs as a job, and the row shows that it is busy. You can work in the scene while it runs.
2. The job writes the result as a new file next to the old file.
3. The item then uses the new file, and the viewport draws it.

Each operation is one undo step. Undo goes back to the old file, which stays on disk while an undo or a redo step can use it. When you save the scene, the app deletes the files of operations that no item and no undo step uses. It looks only in the scene's own bake folders, and it keeps a file that another scene in the same folder uses. If you delete the item, or undo an earlier operation on it, while the job runs, the scene ignores the result of the job.

The item records each operation that it got. If you regenerate a baked mesh, the bake runs again from its SDF branch with the settings of the first bake, and then each recorded operation runs again, in the same order.

The operations that need an SDF field, for example the surface projection of the export dialog, are not in this menu. A finished mesh has no field.

Work with a tet volume

The Tet ▸ submenu of a tet volume row holds:

Remove degenerate tets and the improvement entries are operations, as the ones of the Mesh ▸ submenu: one job, one new file and one undo step. The cut plane is in the expanded row of the tet volume. See Cut a tet volume open.

A tet volume that you baked from an SDF item can also regenerate. Choose Bake ▸ Regenerate on its row. The bake runs again with the settings of the first bake, and then each recorded operation runs again.

Solve… runs a linear static analysis of the volume: you give a material, the regions that hold the part and the regions that load it, and the volume gets its displacement and its stress as fields that Tet ▸ Field shows. See Solve a tet volume.

The quality of a tetrahedron is its shortest edge divided by its longest edge. A regular tetrahedron has quality 1. A sliver, which has one very short edge, has a quality near 0. The solver gives a less accurate result in slivers, so a volume with many elements under 0.1 needs a finer bake, or the steps of Improve a tet volume.

Two more measures show how far a tetrahedron is from a regular one:

• Skewness goes from 0, a regular tetrahedron, to 1, a flat one. It is the measure that commercial meshers use for tetrahedra, with these bands:

  Skewness	Quality
  0 to 0.25	Excellent
  0.25 to 0.5	Good
  0.5 to 0.75	Fair
  0.75 to 0.9	Poor
  0.9 to under 1	Sliver
  1	Degenerate

• Radius ratio is 1 for a regular tetrahedron and grows without limit for a needle or a sliver.

Improve a tet volume

The improvement entries of Tet ▸ make the worst tetrahedra of a volume better without changing its surface:

• The surface does not move. Only the nodes inside the volume move, and only the tetrahedra inside it change.
• The highest skewness never gets worse. The mean skewness can rise a little while the highest falls, as in other meshers: the steps fix the worst tetrahedra first.

Use them in this order, or choose Improve to run the first three in rounds:

1. Sliver collapse removes the slivers (skewness over 0.985) by joining two inner nodes of each.
2. Face and edge swap replaces groups of two or three tetrahedra by a better group that fills the same space.
3. Skewness smooth moves the inner nodes of the tetrahedra over 0.75.
4. Quadratic elements (Tet10) comes last: the other steps refuse a Tet10 volume.

Laplace smooth improves the mean quality rather than the worst tetrahedra.

To see the gain, choose Tet ▸ Quality summary before and after, or color the volume by skewness.

Run it on another computer

Each operation runs as a construct.mesh_process job, which any computer of your farm that offers it can run. To send these jobs to the farm, set the placement of the type to farm, for example with the OPAL task batch.policy.set and perType construct.mesh_process=farm. The file goes to the other computer and the result comes back as one undo step.

Fill a mesh with tetrahedra

A closed tri mesh, for example an STL part that you imported, becomes a tet volume that the solver can use:

1. Right-click the mesh row.
2. Choose Bake ▸ Tet volume to add the volume to the scene, or Export ▸ Tet volume... to write it to a VTK file.
3. Set the options in the dialog, then click Bake or Export.... An export then asks for the file.

The dialog shows the name of the mesh and its triangle count, and its open edges when the mesh is loaded. When the mesh has a scale in the scene, the dialog says what the edge length is there.

The edge length is a mean, not a bound: the tetrahedra at the surface are smaller. The quality is measured, not guaranteed.

Keep the surface puts each outer node on the mesh's surface, but not each outer face. Between its three nodes a face is flat, so over a curved part it lies a little inside or outside the mesh. Sharp edges and corners come out rounded, and a part thinner than about one edge length can be lost. A node that would make a tetrahedron worse than the smallest angle stays where it is.

The job runs as a bake does, and the row shows its progress. When it ends, a message gives the count of tetrahedra and the range of their dihedral angles. It also tells you when:

• the mesh has open or over-shared edges. The fill closes each hole, and you get the volume.
• some tetrahedra have an angle under the floor. Choose Tet ▸ Field ▸ quality on the volume to see where they are.
• some outer nodes stayed off the surface to keep the tetrahedra valid.

A mesh that encloses no volume, for example a single sheet, gives no volume, and the message says why.

The figure shows a gear and the volume made from it with a target edge length of 2 mm. The volume is moved beside the mesh, cut open with a cut plane on the Y axis, and colored by quality.

The new volume sits where the mesh is, with the same parent and transform, and is named after the mesh. It keeps the options. Choose Bake ▸ Regenerate on the volume row to fill the mesh again with the same options: it uses the mesh as it is now, so after a Mesh ▸ operation on the mesh, Regenerate fills the changed mesh.

Cut a tet volume open

A cut plane shows the inside of a tet volume: the part on one side of the plane is not drawn, and the cut face, the cap, shows the inside. Each plane is perpendicular to one axis of the volume. The planes belong to the cut presenter of the volume. It holds up to six planes.

1. Click the arrow of the tet volume's row to open its box.
2. Click Cut plane so that it reads Enabled. If the volume has no cut presenter, this adds one.
3. Choose the Axis: X, Y or Z.
4. Drag the Offset box up or down, or double-click it and type a value in mm. The plane moves along the axis while you drag.
5. To keep the other half, click Flip so that it reads Enabled.
6. To cut with one more plane, click Add plane in the box of the cut presenter. Each new plane has its own Cut plane, Axis, Offset and Flip rows. Remove plane removes the last plane.

A part of the volume shows only when it is on the kept side of every plane that is on. Each cap shows the field of the volume in the colors of its legend, so a cap and the surface show the same value where they meet. To show the cuts without caps, turn off Caps in the box of the cut presenter.

Each change is one undo step, and one drag of the offset is one step. To show the whole volume again, click Cut plane so that it reads Disabled, or hide the cut presenter. The axis and the offset stay for the next cut.

The cut changes only what the viewport shows. A bake or an export uses the whole volume.

In OPAL, add the cut presenter with construct.presentation.add and change it with construct.presentation.set. The planes parameter is a JSON list of {axis, offset, flip, enabled}, with the axis 0 for X, 1 for Y and 2 for Z. Plane 0 is the plane of the Cut plane rows:

{"task": "construct.presentation.add", "args": {"item": "Body (tet)", "kind": "cut",
  "params": {"planes": "[{\"axis\":1,\"offset\":3}]"}}}
{"task": "construct.presentation.set", "args": {"item": "Body (tet)", "id": "cut-1",
  "params": {"planes": "[{\"axis\":1,\"offset\":3,\"flip\":true}]"}}}

construct.scene.get_item lists the planes as cutPlanes.

Turn a tet volume into a tri mesh

To get a tri mesh of a tet volume's outside, right-click the tet volume row and choose Bake ▸ Tri mesh (boundary). A new mesh item appears next to the volume, with the same parent and the same transform.

• The mesh has the exact positions of the volume's outer nodes. Nothing is welded, smoothed or simplified.
• The mesh shades flat, as the volume does, so the two look the same. Where both show, the viewport draws a fine checker of the two tones.
• A field of the volume, for example a simulation result, goes with each outer face to the mesh.
• The mesh is written as a VTK file next to the scene, so its fields stay with it. Save the scene before you bake.

To make the mesh lighter, use the Mesh ▸ submenu on the new row, for example Decimate ▸ 50 %. Undo removes the mesh. Regenerate on the mesh runs the bake again from the volume, then each operation that the mesh got.

The cut planes of the volume do not cut the bake. The bake is the whole outside.

Export a mesh or a volume to a file

A mesh or a tet volume writes to a file as it is, with no meshing options:

1. Right-click the row.
2. Choose Export ▸ Tri mesh to file... or Export ▸ Tet volume to file....
3. Choose the file in the save dialog.

A mesh writes to STL, OBJ, PLY or VTK. A tet volume writes to VTK only, because the other formats cannot hold tetrahedra.

To write the outside of a tet volume as a tri mesh, choose Export ▸ Tri mesh (boundary) to file... on the tet volume row. It writes the same surface as the boundary bake, to STL, OBJ, PLY or VTK, and adds nothing to the scene.

To fill a mesh with tetrahedra and write the volume to a file, choose Export ▸ Tet volume... on the mesh row. See Fill a mesh with tetrahedra. See Bake and Export for the SDF branch side.

Script it

Each menu entry on this page has an OPAL task that runs the same code:

This plan bakes a tet volume, bakes its boundary, decimates the mesh to half and exports it:

{
  "steps": [
    {"task": "construct.bake", "args": {"item": "Body", "kind": "tet", "cells": 64},
     "produces": {"tet": "itemId"}},
    {"task": "construct.bake", "args": {"item": "${tet}", "kind": "tri_boundary"},
     "produces": {"boundary": "itemId"}},
    {"task": "construct.passenger.process", "args": {"item": "${boundary}", "step": "qemDecimate(0.5)"}},
    {"task": "construct.item.export_file", "args": {"item": "${boundary}", "path": "body.ply"}}
  ]
}

Run it with construct opal plan.json scene.construct. Each step prints its time.

This plan fills an imported mesh named gear with a tet volume:

{
  "steps": [
    {"task": "construct.bake", "args": {"item": "gear", "kind": "tet_from_mesh", "edgeLength": 1.0}}
  ]
}

The quality of the volume is measured, not guaranteed. The result of the bake holds the numbers: tetQuality has the dihedral range and belowFloor, the count of tetrahedra under the quality floor. A script that needs a minimum reads tetQuality.minDihedralDeg or belowFloor and stops on its own.