trimesh.exchange.binvox

Parsing functions for Binvox files.

https://www.patrickmin.com/binvox/binvox.html

Exporting meshes as binvox files requires the binvox executable to be in your path.

class trimesh.exchange.binvox.Binvox(rle_data, shape, translate, scale)

Bases: tuple

rle_data

Alias for field number 0

scale

Alias for field number 3

shape

Alias for field number 1

translate

Alias for field number 2

class trimesh.exchange.binvox.Binvoxer(dimension=32, file_type='binvox', z_buffer_carving=True, z_buffer_voting=True, dilated_carving=False, exact=True, bounding_box=None, remove_internal=False, center=False, rotate_x=0, rotate_z=0, wireframe=False, fit=False, block_id=None, use_material_block_id=False, use_offscreen_pbuffer=False, downsample_factor=None, downsample_threshold=None, verbose=False, binvox_path=None)

Bases: object

Interface for binvox CL tool.

This class is responsible purely for making calls to the CL tool. It makes no attempt to integrate with the rest of trimesh at all.

Constructor args configure command line options.

Binvoxer.__call__ operates on the path to a mode file.

If using this interface in published works, please cite the references below.

See CL tool website for further details.

https://www.patrickmin.com/binvox/

@article{nooruddin03,

author = {Fakir S. Nooruddin and Greg Turk}, title = {Simplification and Repair of Polygonal Models Using Volumetric

Techniques},

journal = {IEEE Transactions on Visualization and Computer Graphics}, volume = {9}, number = {2}, pages = {191–205}, year = {2003}

}

@Misc{binvox,

author = {Patrick Min}, title = {binvox}, howpublished = {{ t http://www.patrickmin.com/binvox} or

year = {2004 - 2019}, note = {Accessed: yyyy-mm-dd}

}

SUPPORTED_INPUT_TYPES = ('ug', 'obj', 'off', 'dfx', 'xgl', 'pov', 'brep', 'ply', 'jot')
SUPPORTED_OUTPUT_TYPES = ('binvox', 'hips', 'mira', 'vtk', 'raw', 'schematic', 'msh')
__init__(dimension=32, file_type='binvox', z_buffer_carving=True, z_buffer_voting=True, dilated_carving=False, exact=True, bounding_box=None, remove_internal=False, center=False, rotate_x=0, rotate_z=0, wireframe=False, fit=False, block_id=None, use_material_block_id=False, use_offscreen_pbuffer=False, downsample_factor=None, downsample_threshold=None, verbose=False, binvox_path=None)

Configure the voxelizer.

Parameters:

  • dimension (voxel grid size (max 1024 when not using exact))

  • file_type (str) –

    Output file type, supported types are:

    ’binvox’ ‘hips’ ‘mira’ ‘vtk’ ‘raw’ ‘schematic’ ‘msh’

  • z_buffer_carving (use z buffer based carving. At least one of) – z_buffer_carving and z_buffer_voting must be True.

  • z_buffer_voting (use z-buffer based parity voting method.)

  • dilated_carving (stop carving 1 voxel before intersection.)

  • exact (any voxel with part of a triangle gets set. Does not use) – graphics card.

  • bounding_box (6-element float list/tuple of min, max values,) – (minx, miny, minz, maxx, maxy, maxz)

  • remove_internal (remove internal voxels if True. Note there is some odd) – behaviour if boundary voxels are occupied.

  • center (center model inside unit cube.)

  • rotate_x (number of 90 degree ccw rotations around x-axis before) – voxelizing.

  • rotate_z (number of 90 degree cw rotations around z-axis before) – voxelizing.

  • wireframe (also render the model in wireframe (helps with thin parts).)

  • fit (only write voxels in the voxel bounding box.)

  • block_id (when converting to schematic, use this as the block ID.)

  • use_matrial_block_id (when converting from obj to schematic, parse) – block ID from material spec “usemtl blockid_<id>” (ids 1-255 only).

  • use_offscreen_pbuffer (use offscreen pbuffer instead of onscreen) – window.

  • downsample_factor (downsample voxels by this factor in each dimension.) – Must be a power of 2 or None. If not None/1 and core dumped errors occur, try slightly adjusting dimensions.

  • downsample_threshold (when downsampling, destination voxel is on if) – more than this number of voxels are on.

  • verbose (bool) – If False, silences stdout/stderr from subprocess call.

  • binvox_path (str) – Path to binvox executable. The default looks for an executable called binvox on your PATH.

property file_type
trimesh.exchange.binvox.binvox_bytes(rle_data, shape, translate=(0, 0, 0), scale=1)

Get a binary representation of binvox data.

Parameters:

  • rle_data (numpy array) – Run-length encoded numpy array.

  • shape ((3,) int) – Shape of voxel grid.

  • translate ((3,) float) – Translation of voxels

  • scale (float) – Length of entire voxel grid.

Returns:

data – Suitable for writing to binary file

Return type:

bytes

trimesh.exchange.binvox.binvox_header(shape, translate, scale)

Get a binvox header string.

shape: length 3 iterable of ints denoting shape of voxel grid. translate: length 3 iterable of floats denoting translation. scale: num length of entire voxel grid.

string including “data

“ line.

trimesh.exchange.binvox.export_binvox(voxel, axis_order='xzy')

Export trimesh.voxel.VoxelGrid instance to bytes

Parameters:

  • voxel (trimesh.voxel.VoxelGrid) – Assumes axis ordering of xyz and encodes in binvox default xzy ordering.

  • axis_order (str) – Eements in (‘x’, ‘y’, ‘z’, 0, 1, 2), the order of axes to encode data (standard is ‘xzy’ for binvox). voxel data is assumed to be in order ‘xyz’.

Returns:

result – Representation according to binvox spec

Return type:

bytes

trimesh.exchange.binvox.load_binvox(file_obj, resolver=None, axis_order='xzy', file_type=None)

Load trimesh VoxelGrid instance from file.

Parameters:

  • file_obj (file-like object) – Contains binvox data

  • resolver (unused)

  • axis_order (str) – Order of axes in encoded data. Binvox default is ‘xzy’, but ‘xyz’ may be faster where this is not relevant.

Returns:

result – Loaded voxel data

Return type:

trimesh.voxel.VoxelGrid

trimesh.exchange.binvox.parse_binvox(fp, writeable=False)

Read a binvox file, spec at https://www.patrickmin.com/binvox/binvox.html

Parameters:

fp (file-object) – File like object with binvox file

Returns:

  • binvox (namedtuple) – Containing data

  • rle (numpy array) – Run length encoded data

Raises:

IOError – If invalid binvox file

trimesh.exchange.binvox.parse_binvox_header(fp)

Read the header from a binvox file. Spec available: https://www.patrickmin.com/binvox/binvox.html

Parameters:

fp (file-object) – File like object with binvox file

Returns:

  • shape (tuple) – Shape of binvox according to binvox spec

  • translate (tuple) – Translation

  • scale (float) – Scale of voxels

Raises:

IOError – If invalid binvox file.

trimesh.exchange.binvox.voxel_from_binvox(rle_data, shape, translate=None, scale=1.0, axis_order='xzy')

Factory for building from data associated with binvox files.

Parameters:

  • rle_data (numpy) – Run-length-encoded of flat voxel values, or a trimesh.rle.RunLengthEncoding object. See trimesh.rle documentation for description of encoding

  • shape ((3,) int) – Shape of voxel grid.

  • translate ((3,) float) – Translation of voxels

  • scale (float) – Length of entire voxel grid.

  • encoded_axes (iterable) – With values in (‘x’, ‘y’, ‘z’, 0, 1, 2), where x => 0, y => 1, z => 2 denoting the order of axes in the encoded data. binvox by default saves in xzy order, but using xyz (or (0, 1, 2)) will be faster in some circumstances.

Returns:

result – Loaded voxels

Return type:

VoxelGrid

trimesh.exchange.binvox.voxelize_mesh(mesh, binvoxer=None, export_type='off', **binvoxer_kwargs)

Interface for voxelizing Trimesh object via the binvox tool.

Implementation simply saved the mesh in the specified export_type then runs the Binvoxer.__call__ (using either the supplied binvoxer or creating one via binvoxer_kwargs)

Parameters:

  • mesh (Trimesh object to voxelize.)

  • binvoxer (optional Binvoxer instance.)

  • export_type (file type to export mesh as temporarily for Binvoxer to) – operate on.

  • **binvoxer_kwargs (kwargs for creating a new Binvoxer instance. If binvoxer) – if provided, this must be empty.

Return type:

VoxelGrid object resulting.