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\).
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. 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 back to the file it was read from.
p	Export a sample: one particle per shape, laid out so that the library can be opened directly in see.

Warning

s overwrites the input file in place, without asking. Keep a copy of a library you care about before pressing it.

Typical workflow after a conversion

stl2shape -i mesh.stl -r 0.01 -c    # -> mesh.shp, preCompDone n
shapeSurvey mesh.shp

Then, in the window: browse with + to check the geometry, press C to compute the mass properties of every shape, and s to save. The library is then ready for a simulation, and no shape will be recomputed at start-up.