trimesh.exchange.binvox

Parsing functions for Binvox files.

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

Exporting meshes as binvox files requires binvox CL tool to be on your path.

Classes:

Binvox(rle_data, shape, translate, scale)

Binvoxer([dimension, file_type, …])

Interface for binvox CL tool.

Trimesh([vertices, faces, face_normals, …])

Functions:

binvox_bytes(rle_data, shape[, translate, scale])

Get a binary representation of binvox data.

binvox_header(shape, translate, scale)

Get a binvox header string.

export_binvox(voxel[, axis_order])

Export trimesh.voxel.VoxelGrid instance to bytes

find_executable(executable[, path])

Tries to find ‘executable’ in the directories listed in ‘path’.

load_binvox(file_obj[, resolver, …])

Load trimesh VoxelGrid instance from file.

parse_binvox(fp[, writeable])

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

parse_binvox_header(fp)

Read the header from a binvox file.

voxel_from_binvox(rle_data, shape[, …])

Factory for building from data associated with binvox files.

voxelize_mesh(mesh[, binvoxer, export_type])

Interface for voxelizing Trimesh object via the binvox tool.

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

Bases: tuple

Attributes:

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

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=False, 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=True, 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}

}

Attributes:

SUPPORTED_INPUT_TYPES

SUPPORTED_OUTPUT_TYPES

file_type

SUPPORTED_INPUT_TYPES = ('ug', 'obj', 'off', 'dfx', 'xgl', 'pov', 'brep', 'ply', 'jot')
SUPPORTED_OUTPUT_TYPES = ('binvox', 'hips', 'mira', 'vtk', 'raw', 'schematic', 'msh')
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.

Returns

Return type

VoxelGrid object resulting.