TestVHACD - Man Page

TestVHACD – Test and utility command-line tool for the V-HACD library


TestVHACD <wavefront.obj> (options)


The V-HACD library decomposes a 3D surface into a set of “near” convex parts.


-h <n>

Maximum number of output convex hulls. Default is 32

-r <voxelresolution>

Total number of voxels to use. Default is 100,000

-e <volumeErrorPercent>

Volume error allowed as a percentage. Default is 1%. Valid range is 0.001 to 10

-d <maxRecursionDepth>

Maximum recursion depth. Default value is 10.

-s <true/false>

Whether or not to shrinkwrap output to source mesh. Default is true.

-f <fillMode>

Fill mode. Default is ‘flood’, also ‘surface’ and ‘raycast’ are valid.

-v <maxHullVertCount>

Maximum number of vertices in the output convex hull. Default value is 64

-a <true/false>

Whether or not to run asynchronously. Default is ‘true

-l <minEdgeLength>

Minimum size of a voxel edge. Default value is 2 voxels.

-p <true/false>

If false, splits hulls in the middle. If true, tries to find optimal split plane location. False by default.

-o <obj/stl/usda>

Export the convex hulls as a series of wavefront OBJ files, STL files, or a single USDA.

-g <true/false>

If set to false, no logging will be displayed.

Tuning Parameters

The default values are currently designed to give a fast and basic approximation of a shape.

If you want as accurate results as possible and don’t care if it takes quite a bit longer you can use a small error threshold (-e 0.01) and a high voxel resolution of ten million (-r 10000000) and a relatively high number of convex hulls say 128 (-h 128).

Finally you can set the maximum decomposition depth to much higher than the default value of 10. Setting it to say 15 (-d 15) will allow the algorithm to recurse much more deeply into the shape.

TestVHACD beshon.obj -e 0.01 -d 15 -r 10000000 -r 128

Usually this may be overkill for your use case but if you have say machined parts with sharp angles, these settings have a better chance of giving a good result.

Note that setting the maximum decomposition depth to 15 will make the tool run a very long time (possibly multiple minutes) but it will likely give the most precise results.

The default value for decomposition depth is currently ten and it goes in powers of two. So the default value considers a maximum of 1,024 hulls but with a depth of 15 it will consider 32,768 convex hull fragments.


February 2023