VoxelModel

class cubeforge.VoxelModel(voxel_dimensions=(1.0, 1.0, 1.0), coordinate_system='y_up')[source]

Bases: object

Represents a 3D model composed of voxels. Each voxel can have independent dimensions (width, height, depth).

Allows adding voxels based on coordinates and anchor points, and exporting the resulting shape using various mesh writers. Logging messages are emitted via the standard ‘logging’ module; configuration is up to the application.

__init__(voxel_dimensions=(1.0, 1.0, 1.0), coordinate_system='y_up')[source]

Initializes the VoxelModel.

Parameters:

  • voxel_dimensions (tuple) – A tuple of three positive numbers (x_size, y_size, z_size) representing the default size of each voxel along each axis. Always in (x, y, z) order regardless of coordinate system.

  • coordinate_system (str) – The coordinate system to use. Either ‘y_up’ (default) or ‘z_up’. Use ‘z_up’ for 3D printing to ensure correct orientation in most slicers. - ‘y_up’: Y axis is vertical (mathematical convention) - ‘z_up’: Z axis is vertical (3D printing convention)

__init__(voxel_dimensions=(1.0, 1.0, 1.0), coordinate_system='y_up')[source]

Initializes the VoxelModel.

Parameters:

  • voxel_dimensions (tuple) – A tuple of three positive numbers (x_size, y_size, z_size) representing the default size of each voxel along each axis. Always in (x, y, z) order regardless of coordinate system.

  • coordinate_system (str) – The coordinate system to use. Either ‘y_up’ (default) or ‘z_up’. Use ‘z_up’ for 3D printing to ensure correct orientation in most slicers. - ‘y_up’: Y axis is vertical (mathematical convention) - ‘z_up’: Z axis is vertical (3D printing convention)

add_cube(x, y, z, anchor=CubeAnchor.CORNER_NEG, dimensions=None)

Adds a voxel to the model. Replaces add_cube.

Parameters:

  • x (float) – X-coordinate of the voxel’s anchor point.

  • y (float) – Y-coordinate of the voxel’s anchor point (Y-up mode) or depth coordinate (Z-up mode).

  • z (float) – Z-coordinate of the voxel’s anchor point (Y-up mode) or vertical coordinate (Z-up mode).

  • anchor (CubeAnchor) – The reference point within the voxel that (x, y, z) corresponds to. Defaults to CubeAnchor.CORNER_NEG.

  • dimensions (tuple, optional) – Custom dimensions (x_size, y_size, z_size) for this voxel. Always in (x, y, z) order regardless of coordinate system. Dimensions are snapped to the model’s voxel grid spacing. If None, the model’s default dimensions are used.

add_cubes(coordinates, anchor=CubeAnchor.CORNER_NEG, dimensions=None)

Adds multiple voxels from an iterable. Replaces add_cubes.

Parameters:

  • coordinates (iterable) – An iterable of (x, y, z) tuples or lists.

  • anchor (CubeAnchor) – The anchor point to use for all voxels added in this call.

  • dimensions (tuple, optional) – The dimensions to apply to all voxels in this call. Dimensions are snapped to the model’s voxel grid spacing. If None, defaults are used.

add_voxel(x, y, z, anchor=CubeAnchor.CORNER_NEG, dimensions=None)[source]

Adds a voxel to the model. Replaces add_cube.

Parameters:

  • x (float) – X-coordinate of the voxel’s anchor point.

  • y (float) – Y-coordinate of the voxel’s anchor point (Y-up mode) or depth coordinate (Z-up mode).

  • z (float) – Z-coordinate of the voxel’s anchor point (Y-up mode) or vertical coordinate (Z-up mode).

  • anchor (CubeAnchor) – The reference point within the voxel that (x, y, z) corresponds to. Defaults to CubeAnchor.CORNER_NEG.

  • dimensions (tuple, optional) – Custom dimensions (x_size, y_size, z_size) for this voxel. Always in (x, y, z) order regardless of coordinate system. Dimensions are snapped to the model’s voxel grid spacing. If None, the model’s default dimensions are used.

add_voxels(coordinates, anchor=CubeAnchor.CORNER_NEG, dimensions=None)[source]

Adds multiple voxels from an iterable. Replaces add_cubes.

Parameters:

  • coordinates (iterable) – An iterable of (x, y, z) tuples or lists.

  • anchor (CubeAnchor) – The anchor point to use for all voxels added in this call.

  • dimensions (tuple, optional) – The dimensions to apply to all voxels in this call. Dimensions are snapped to the model’s voxel grid spacing. If None, defaults are used.

clear()[source]

Removes all voxels from the model.

generate_mesh(optimize=True)[source]

Generates a list of triangles representing the exposed faces of the voxels.

Ensures consistent counter-clockwise winding order (right-hand rule) for outward-facing normals.

Parameters:

optimize (bool) – If True, uses greedy meshing algorithm to merge adjacent coplanar faces, significantly reducing triangle count. Default: True (recommended for most use cases).

Returns:

A list of tuples, where each tuple is a triangle defined as

(normal, vertex1, vertex2, vertex3). Coordinates are in the model’s world space. Returns an empty list if no voxels have been added.

Return type:

list

remove_cube(x, y, z, anchor=CubeAnchor.CORNER_NEG)

Removes a voxel from the model based on its anchor coordinates. Replaces remove_cube.

Parameters:

  • x (float) – X-coordinate of the voxel’s anchor point.

  • y (float) – Y-coordinate of the voxel’s anchor point (Y-up mode) or depth coordinate (Z-up mode).

  • z (float) – Z-coordinate of the voxel’s anchor point (Y-up mode) or vertical coordinate (Z-up mode).

  • anchor (CubeAnchor) – The reference point within the voxel that (x, y, z) corresponds to.

remove_voxel(x, y, z, anchor=CubeAnchor.CORNER_NEG)[source]

Removes a voxel from the model based on its anchor coordinates. Replaces remove_cube.

Parameters:

  • x (float) – X-coordinate of the voxel’s anchor point.

  • y (float) – Y-coordinate of the voxel’s anchor point (Y-up mode) or depth coordinate (Z-up mode).

  • z (float) – Z-coordinate of the voxel’s anchor point (Y-up mode) or vertical coordinate (Z-up mode).

  • anchor (CubeAnchor) – The reference point within the voxel that (x, y, z) corresponds to.

save_mesh(filename, format='stl_binary', optimize=True, **kwargs)[source]

Generates the mesh and saves it to a file using the specified format.

Parameters:

  • filename (str) – The path to the output file.

  • format (str) – The desired output format identifier (e.g/, ‘stl_binary’, ‘stl_ascii’). Case-insensitive. Defaults to ‘stl_binary’.

  • optimize (bool) – If True, uses greedy meshing to reduce triangle count by merging adjacent coplanar faces. Can reduce file size by 10-100x for regular voxel structures. Default: True.

  • **kwargs – Additional arguments passed directly to the specific file writer (e.g., ‘solid_name’ for STL formats).

Class Overview

The VoxelModel class is the main interface for creating voxel-based 3D models in CubeForge.

Key Methods

Model Creation

VoxelModel.__init__

Initializes the VoxelModel.

Adding Voxels

VoxelModel.add_voxel

Adds a voxel to the model.

VoxelModel.add_voxels

Adds multiple voxels from an iterable.

Removing Voxels

VoxelModel.remove_voxel

Removes a voxel from the model based on its anchor coordinates.

VoxelModel.clear

Removes all voxels from the model.

Mesh Generation

VoxelModel.generate_mesh

Generates a list of triangles representing the exposed faces of the voxels.

VoxelModel.save_mesh

Generates the mesh and saves it to a file using the specified format.

Example Usage

Basic usage:

import cubeforge

# Create a model
model = cubeforge.VoxelModel(
    voxel_dimensions=(1.0, 1.0, 1.0),
    coordinate_system='z_up'
)

# Add voxels
model.add_voxel(0, 0, 0)
model.add_voxel(1, 0, 0)

# Generate and save mesh
model.save_mesh("output.stl")