Application shapeSurvey

shapeSurvey is an OpenGL browser for a shape library. It answers the two questions that come up whenever a shape file has been written by hand or produced by a converter: does this shape look like what I meant? and are its mass properties right?

shapeSurvey shapes.txt

It is also the tool that pre-computes a library. A shape whose preCompDone is n has its volume, inertia and bounding box recomputed every time a simulation starts; running the computation once here and saving the result removes that cost, and lets you check the values before they are used.

Browsing the library

Key	Action
+ / -	Next / previous shape. A shape whose preCompDone is n gets its bounding box fitted on the fly when it is displayed.
h	Show the help.
e	Print the extents of the bounding box in the terminal.
a / A	Decrease / increase the transparency.
b	Background colours on/off.
w / W	Roll the camera about the viewing axis.
q	Quit.

The mouse rotates, pans and zooms as in see.

Computing the mass properties

Key	Action
c	Compute the mass properties of the current shape, and set its preCompDone to y.
C	The same for every shape of the library that is still marked n.
*	Reset preCompDone of the current shape to n, to force a recomputation.
N / n	Multiply / divide by ten the number of Monte-Carlo samples (MCnstep), between \(10^3\) and \(10^8\). Note that a value above \(10^7\) saved in the file is brought back to \(10^7\) when the file is read again.
d	Clean every shape, removing the duplicated entities.

The volume and the inertia of a sphero-polyhedron have no closed form in the general case, so they are estimated by Monte-Carlo sampling. The accuracy therefore depends on MCnstep, and the estimated relative error on the volume is printed with the result.

Tip

Increase MCnstep with N until the printed error is small enough for your purpose, then press C and s (or use -P). For a shape used as a driven wall the default is plenty; for a grain whose mass drives the dynamics, it is worth a few more samples.

Note

A shape marked preCompDone y is trusted: Rockable uses the volume and the inertia written in the file without checking them. This is efficient, and it is also how a wrong value gets used silently, so it is worth looking at the numbers once.

Fitting the bounding box

Key	Action
o	Cycle through the fitting strategies: covariance, minimum volume, axis-aligned, imposed axis. The chosen one is stored as fibObbOption.
t	Build the OBB-tree of the current shape.
k / K	Show one level less / one level more of the tree.

The oriented bounding box is what the neighbour detection uses first, so a poorly fitted box costs time on every step. The four strategies differ in what they optimise: the covariance fit is fast and usually good, the minimum-volume fit is tighter on elongated shapes, and the axis-aligned one is only relevant for shapes already aligned with the axes.

Warning

The OBB-tree, and the OBBtreeLevel keyword of the shape files, are deprecated. The tree can still be built and displayed here, but the contact detection is driven by AddOrRemoveInteractions, whose OBBtree option builds what it needs on its own.

Saving

Key	Action
s	Save the library in mod_<file>, next to the file it was read from (mod_shapes.shp for shapes.shp). The file that was read is not modified.
p	Export a sample: one particle per shape, laid out so that the library can be opened directly in see.

Note

An existing mod_<file> is overwritten without asking. Rename it before using it: mv mod_shapes.shp shapes.shp.

Typical workflow after a conversion

stl2shape -r 0.01 -c mesh.stl       # -> mesh.shp, preCompDone n
shapeSurvey mesh.shp                # look at it
shapeSurvey mesh.shp -P mesh.shp    # pre-compute, in place, without window

The library is then ready for a simulation, and no shape will be recomputed at start-up. In the window, the keys C then s do the same as -P, but write mod_mesh.shp.

Command line

shapeSurvey <shapeFile> [options] opens the window, except with one of the two options below, which do their work and exit.

Option	Description
-P, --precompute out.shp	Compute the mass properties of every shape marked preCompDone n (with the MCnstep of each shape), and write the whole library to out.shp, which can be the input file itself. No window is opened: it can be used in a script, or on a machine without display.
-o, --output file.png	Render one shape to an image (-i n or -N name to choose it, -W, -H, --elev, --azim, --skin file.rmsh, --wire, --color, --transparent). See shapeSurvey -h.