Voxelization documentation

[AzamatB]

There is no documentation on this package. In particular, I would like to voxelize a 3D mesh object.

Could you please tell how to do this?

[mikedh]

Hey, PR's are always welcome 😄 . I would recommend using an actual voxel package like openVDB if you need to do involved things. That being said, the easiest way to explore it is using an ipython terminal, one example of some noodling around:

In [1]: import trimesh

In [2]: m = trimesh.load('models/featuretype.STL')

In [3]: m.extents
Out[3]: array([ 5.   ,  2.5  ,  1.375])

In [4]: v = m.voxelized?
Signature: m.voxelized(pitch)
Docstring:
Return a Voxel object representing the current mesh
discretized into voxels at the specified pitch

Parameters
----------
pitch: float, the edge length of a single voxel

Returns
----------
voxelized: Voxel object representing the current mesh
File:      ~/errata/trimesh/trimesh/base.py
Type:      method

In [5]: v = m.voxelized(pitch=1.0)

In [6]: v?
Type:           VoxelMesh
String form:    <trimesh.voxel.VoxelMesh object at 0x7fb565565390>
File:           ~/errata/trimesh/trimesh/voxel.py
Docstring:      <no docstring>
Init docstring:
A voxel representation of a mesh that will track changes to 
the mesh.

At the moment the voxels are not filled in and only represent 
the surface.

Parameters
----------
mesh:      Trimesh object
pitch:     float, how long should each edge of the voxel be
size_max:  float, maximum size (in mb) of a data structure that
                  may be created before raising an exception

In [7]: dir(v)
Out[7]: 
['__class__',
 '__delattr__',
 '__dict__',
 '__dir__',
 '__doc__',
 '__eq__',
 '__format__',
 '__ge__',
 '__getattribute__',
 '__gt__',
 '__hash__',
 '__init__',
 '__init_subclass__',
 '__le__',
 '__lt__',
 '__module__',
 '__ne__',
 '__new__',
 '__reduce__',
 '__reduce_ex__',
 '__repr__',
 '__setattr__',
 '__sizeof__',
 '__str__',
 '__subclasshook__',
 '__weakref__',
 '_cache',
 '_data',
 'as_boxes',
 'filled_count',
 'is_filled',
 'marching_cubes',
 'matrix',
 'matrix_surface',
 'origin',
 'pitch',
 'point_to_index',
 'points',
 'shape',
 'show',
 'sparse_surface',
 'volume']

In [8]: v.matrix
Out[8]: 
array([[[ True,  True, False],
        [ True,  True, False],
        [ True,  True, False],
        [ True,  True, False],
        [False, False, False]],

       [[ True,  True, False],
        [ True,  True, False],
        [ True,  True, False],
        [ True,  True, False],
        [ True,  True, False]],

       [[ True,  True, False],
        [ True,  True, False],
        [ True,  True,  True],
        [ True,  True,  True],
        [ True,  True, False]],

       [[ True,  True, False],
        [ True,  True, False],
        [ True,  True,  True],
        [ True,  True,  True],
        [ True,  True, False]],

       [[ True,  True, False],
        [ True,  True, False],
        [ True,  True,  True],
        [ True,  True,  True],
        [ True,  True, False]],

       [[ True,  True, False],
        [ True,  True, False],
        [ True,  True, False],
        [ True,  True, False],
        [ True,  True, False]],

       [[False, False, False],
        [False,  True, False],
        [False,  True, False],
        [False,  True, False],
        [False,  True, False]]], dtype=bool)

[wplexhsu]

Hi, I also have a document question. Why were the "Module Reference" pages gone? Could it back? Thanks!

[mrlukeparry]

Hi Mike,

The new method using triangle subdivision and 'splatting' for voxelisation method seems pretty reliable. It's not blazingly quick like the original ray-tracing but it will do for now.

I suggest that you may need to change or add an optional parameter for the max_iter in the triangle subdivision section:

remesh.py: def subdivide_to_size(vertices, faces, max_edge, max_iter=10):

For small values for the pitch parameter, the method will fall over unless the max_iter is manually increased!

Thanks for your work! Luke

[mikedh]

RE: the module reference, it was gone because of a bug with an inherited networkx docstring and numpydoc. I fixed that issue and it builds on my computer (try make html in the docs folder) but still isn't building on readthedocs for unknown reasons

RE: subdivision max_iter parameter: sure, I made it passable in https://github.com/mikedh/trimesh/commit/05675e596338624c5e0874973f900f1d07ecd21b

[wplexhsu]

Hi, Mike, Excuse me for asking a question. How could I build the documents(html) on my computer? I build the index.html, but the "module reference" still not work. (Can't find the py-modindex.html file.) Thanks for your help! Lex

[mikedh]

Closing this as module references are building again (and deploying to https://trimsh.org/)

To build the docs, I thought the simplest way was a python build script:

cd docs
pip install -r requirements.txt
sudo apt-get install pandoc

python build.py