Allow Custom Voxel Dimension

Author: Teddy-van-Jerry

README.md

@@ -8,7 +8,7 @@
 ## Features
 
 - [x] **Voxel-based Modeling:** Define 3D shapes by adding individual voxels (cubes).
-- [x] **Non-Uniform Voxel Dimensions:** Specify custom width, height, and depth for voxels.
+- [x] **Non-Uniform Voxel Dimensions:** Specify default non-uniform dimensions for a model, and override dimensions on a per-voxel basis.
 - [x] **Flexible Anchoring:** Position voxels using different anchor points ([`cubeforge.CubeAnchor`](cubeforge/constants.py)) like corners or centers.
 - [x] **STL Export:** Save the generated mesh to both ASCII and Binary STL file formats.
 - [x] **Simple API:** Easy-to-use interface with the core [`cubeforge.VoxelModel`](cubeforge/model.py) class.
@@ -23,7 +23,7 @@ pip install cubeforge
 ```
 
 **Install from source:**
-You can also clone the repository and install the package using pip:
+You can also clone the repository and install the package using `pip`:
 
 ```bash
 pip install .
@@ -48,10 +48,12 @@ model.add_voxel(1, 1, 0)
 # --- Or add multiple voxels at once ---
 # model.add_voxels([(0, 0, 0), (1, 0, 0), (1, 1, 0)])
 
-# --- Example with non-uniform dimensions and different anchor ---
-model_non_uniform = cubeforge.VoxelModel(voxel_dimensions=(2.0, 1.0, 3.0))
-# Add a voxel centered at (0, 0, 0)
-model_non_uniform.add_voxel(0, 0, 0, anchor=cubeforge.CubeAnchor.CENTER)
+# --- Example with custom dimensions per voxel ---
+tower_model = cubeforge.VoxelModel(voxel_dimensions=(1.0, 1.0, 1.0))
+# Add a 1x1x1 base cube centered at (0,0,0)
+tower_model.add_voxel(0, 0, 0, anchor=cubeforge.CubeAnchor.CENTER)
+# Stack a wide, flat 3x0.5x3 cube on top of it
+tower_model.add_voxel(0, 0.5, 0, anchor=cubeforge.CubeAnchor.BOTTOM_CENTER, dimensions=(3.0, 0.5, 3.0))
 
 # Define output path
 output_dir = "output"
@@ -68,7 +70,8 @@ print(f"Saved mesh to {output_filename}")
 
 The [`examples/create_shapes.py`](examples/create_shapes.py ) script demonstrates various features, including:
 *   Creating simple and complex shapes.
-*   Using different voxel dimensions.
+*   Using different default voxel dimensions.
+*   Overriding dimensions for individual voxels.
 *   Utilizing various [`CubeAnchor`](cubeforge/constants.py ) options.
 *   Saving in both ASCII and Binary STL formats.
 *   Generating a surface with random heights.
@@ -85,8 +88,8 @@ The output STL files will be saved in the [`examples`](examples ) directory.
 
 *   **[`cubeforge.VoxelModel`](cubeforge/model.py ):** The main class for creating and managing the voxel model.
     *   [`__init__(self, voxel_dimensions=(1.0, 1.0, 1.0))`](cubeforge/model.py ): Initializes the model, optionally setting default voxel dimensions.
-    *   [`add_voxel(self, x, y, z, anchor=CubeAnchor.CORNER_NEG)`](cubeforge/model.py ): Adds a single voxel.
-    *   [`add_voxels(self, coordinates, anchor=CubeAnchor.CORNER_NEG)`](cubeforge/model.py ): Adds multiple voxels.
+    *   [`add_voxel(self, x, y, z, anchor=CubeAnchor.CORNER_NEG, dimensions=None)`](cubeforge/model.py ): Adds a single voxel, optionally with custom dimensions.
+    *   [`add_voxels(self, coordinates, anchor=CubeAnchor.CORNER_NEG, dimensions=None)`](cubeforge/model.py ): Adds multiple voxels, optionally with custom dimensions.
     *   [`remove_voxel(self, x, y, z, anchor=CubeAnchor.CORNER_NEG)`](cubeforge/model.py ): Removes a voxel.
     *   [`clear(self)`](cubeforge/model.py ): Removes all voxels.
     *   [`generate_mesh(self)`](cubeforge/model.py ): Generates the triangle mesh data.

cubeforge/model.py

@@ -10,7 +10,7 @@
 
 class VoxelModel:
     """
-    Represents a 3D model composed of voxels aligned to a grid.
+    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
@@ -24,20 +24,20 @@ def __init__(self, voxel_dimensions=(1.0, 1.0, 1.0)):
         Args:
             voxel_dimensions (tuple): A tuple of three positive numbers
                                      (width, height, depth) representing the
-                                     size of each voxel in the X, Y, and Z
-                                     dimensions, respectively. Defaults to (1.0, 1.0, 1.0).
+                                     default size of each voxel.
         """
         if not (isinstance(voxel_dimensions, (tuple, list)) and
                 len(voxel_dimensions) == 3 and
                 all(isinstance(dim, (int, float)) and dim > 0 for dim in voxel_dimensions)):
             raise ValueError("voxel_dimensions must be a tuple or list of three positive numbers (width, height, depth).")
         self.voxel_dimensions = tuple(float(dim) for dim in voxel_dimensions)
-        # Stores the integer grid coordinates (ix, iy, iz) of each voxel.
-        # The actual position depends on the grid coordinates and voxel_dimensions.
-        self._voxels = set()
-        logger.info(f"VoxelModel initialized with voxel_dimensions={self.voxel_dimensions}")
+        # Stores voxel data as a dictionary:
+        # key: integer grid coordinate (ix, iy, iz)
+        # value: tuple of dimensions (width, height, depth) for that voxel
+        self._voxels = {}
+        logger.info(f"VoxelModel initialized with default voxel_dimensions={self.voxel_dimensions}")
 
-    def _calculate_min_corner(self, x, y, z, anchor):
+    def _calculate_min_corner(self, x, y, z, anchor, dimensions):
         """
         Calculates the minimum corner coordinates based on anchor point and voxel dimensions.
 
@@ -48,14 +48,15 @@ def _calculate_min_corner(self, x, y, z, anchor):
             y (float): Y-coordinate of the anchor point.
             z (float): Z-coordinate of the anchor point.
             anchor (CubeAnchor): The anchor type.
+            dimensions (tuple): The (width, height, depth) of the voxel.
 
         Returns:
             tuple: (min_x, min_y, min_z) coordinates of the voxel's minimum corner.
 
         Raises:
             ValueError: If an invalid anchor point is provided.
         """
-        size_x, size_y, size_z = self.voxel_dimensions
+        size_x, size_y, size_z = dimensions
         half_x, half_y, half_z = size_x / 2.0, size_y / 2.0, size_z / 2.0
 
         if anchor == CubeAnchor.CORNER_NEG:
@@ -73,7 +74,7 @@ def _calculate_min_corner(self, x, y, z, anchor):
 
         return min_x, min_y, min_z
 
-    def add_voxel(self, x, y, z, anchor=CubeAnchor.CORNER_NEG):
+    def add_voxel(self, x, y, z, anchor=CubeAnchor.CORNER_NEG, dimensions=None):
         """
         Adds a voxel to the model. Replaces add_cube.
 
@@ -84,33 +85,44 @@ def add_voxel(self, x, y, z, anchor=CubeAnchor.CORNER_NEG):
             anchor (CubeAnchor): The reference point within the voxel that
                                 (x, y, z) corresponds to. Defaults to
                                 CubeAnchor.CORNER_NEG.
+            dimensions (tuple, optional): The (width, height, depth) for this
+                                          specific voxel. If None, the model's
+                                          default dimensions are used.
         """
-        min_x, min_y, min_z = self._calculate_min_corner(x, y, z, anchor)
+        voxel_dims = self.voxel_dimensions if dimensions is None else tuple(float(d) for d in dimensions)
+        if dimensions is not None and not (isinstance(voxel_dims, (tuple, list)) and
+                                           len(voxel_dims) == 3 and
+                                           all(isinstance(d, (int, float)) and d > 0 for d in voxel_dims)):
+            raise ValueError("Custom dimensions must be a tuple or list of three positive numbers.")
 
-        # Calculate grid coordinates based on minimum corner and dimensions
-        # Using round to snap to the nearest grid point.
+        min_x, min_y, min_z = self._calculate_min_corner(x, y, z, anchor, voxel_dims)
+
+        # Calculate grid coordinates based on minimum corner and *default* dimensions
+        # This ensures voxels snap to a consistent grid.
         grid_x = round(min_x / self.voxel_dimensions[0])
         grid_y = round(min_y / self.voxel_dimensions[1])
         grid_z = round(min_z / self.voxel_dimensions[2])
 
         grid_coord = (grid_x, grid_y, grid_z)
-        self._voxels.add(grid_coord)
+        self._voxels[grid_coord] = voxel_dims
         # logger.debug(f"Added voxel at grid {grid_coord} (from anchor {anchor} at ({x},{y},{z}))")
 
     # Alias add_cube to add_voxel for backward compatibility (optional, but can be helpful)
     add_cube = add_voxel
 
-    def add_voxels(self, coordinates, anchor=CubeAnchor.CORNER_NEG):
+    def add_voxels(self, coordinates, anchor=CubeAnchor.CORNER_NEG, dimensions=None):
         """
         Adds multiple voxels from an iterable. Replaces add_cubes.
 
         Args:
             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. If None, defaults are used.
         """
         for x_coord, y_coord, z_coord in coordinates:
-            self.add_voxel(x_coord, y_coord, z_coord, anchor)
+            self.add_voxel(x_coord, y_coord, z_coord, anchor, dimensions)
 
     # Alias add_cubes to add_voxels
     add_cubes = add_voxels
@@ -126,14 +138,17 @@ def remove_voxel(self, x, y, z, anchor=CubeAnchor.CORNER_NEG):
             anchor (CubeAnchor): The reference point within the voxel that
                                 (x, y, z) corresponds to.
         """
-        min_x, min_y, min_z = self._calculate_min_corner(x, y, z, anchor)
+        # Note: Removal does not need custom dimensions, as it identifies the
+        # voxel by its position on the grid, which is calculated using default dimensions.
+        min_x, min_y, min_z = self._calculate_min_corner(x, y, z, anchor, self.voxel_dimensions)
 
         grid_x = round(min_x / self.voxel_dimensions[0])
         grid_y = round(min_y / self.voxel_dimensions[1])
         grid_z = round(min_z / self.voxel_dimensions[2])
 
         grid_coord = (grid_x, grid_y, grid_z)
-        self._voxels.discard(grid_coord)
+        if grid_coord in self._voxels:
+            del self._voxels[grid_coord]
         # logger.debug(f"Attempted removal at grid {grid_coord}")
 
     # Alias remove_cube to remove_voxel
@@ -162,7 +177,7 @@ def generate_mesh(self):
 
         logger.info(f"Generating mesh for {len(self._voxels)} voxels...")
         triangles = []
-        size_x, size_y, size_z = self.voxel_dimensions # Use specific dimensions
+        # Voxel dimensions are now fetched per-voxel, so size_x, etc. are defined inside the loop.
 
         # Define faces by normal, neighbor offset, and vertex indices (0-7)
         # Vertex indices correspond to relative positions scaled by dimensions:
@@ -180,22 +195,27 @@ def generate_mesh(self):
         ]
 
         processed_faces = 0
-        for gx, gy, gz in self._voxels:
-            # Calculate the minimum corner based on grid coordinates and dimensions
-            min_cx = gx * size_x
-            min_cy = gy * size_y
-            min_cz = gz * size_z
+        for (gx, gy, gz), (size_x, size_y, size_z) in self._voxels.items():
+            # Calculate the minimum corner based on grid coordinates and *default* dimensions
+            min_cx = gx * self.voxel_dimensions[0]
+            min_cy = gy * self.voxel_dimensions[1]
+            min_cz = gz * self.voxel_dimensions[2]
 
-            # Calculate the 8 absolute vertex coordinates for this voxel
+            # Calculate the 8 absolute vertex coordinates for this voxel using its specific dimensions
             verts = [
                 (min_cx + (i % 2) * size_x, min_cy + ((i // 2) % 2) * size_y, min_cz + (i // 4) * size_z)
                 for i in range(8)
             ]
 
             for normal, offset, indices in faces_data:
                 neighbor_coord = (gx + offset[0], gy + offset[1], gz + offset[2])
+                neighbor_dims = self._voxels.get(neighbor_coord)
 
-                if neighbor_coord not in self._voxels: # Exposed face
+                # A face is exposed if there is no neighbor, OR if the neighbor
+                # has different dimensions, which would create a complex partial
+                # surface. For simplicity and correctness of the outer shell,
+                # we will generate the face in the latter case.
+                if not neighbor_dims or neighbor_dims != (size_x, size_y, size_z): # Exposed face
                     processed_faces += 1
                     # Get the four vertices for this face using the indices
                     v0 = verts[indices[0]]
@@ -215,7 +235,7 @@ def save_mesh(self, filename, format='stl_binary', **kwargs):
 
         Args:
             filename (str): The path to the output file.
-            format (str): The desired output format identifier (e.g.,
+            format (str): The desired output format identifier (e.g/,
                         'stl_binary', 'stl_ascii'). Case-insensitive.
                         Defaults to 'stl_binary'.
             **kwargs: Additional arguments passed directly to the specific

cubeforge/writers.py

@@ -137,5 +137,5 @@ def get_writer(format_id):
     if writer_class:
         return writer_class()
     else:
-        supported_formats = ", ".join(_writer_map.keys())
+        supported_formats = ", ".join(sorted(_writer_map.keys()))
         raise ValueError(f"Unsupported format: '{format_id}'. Supported formats are: {supported_formats}")

examples/create_shapes.py

@@ -106,13 +106,13 @@
 
 for x in range(grid_size_x):
     for z in range(grid_size_z):
-        total_height = min_height + random.randint(0, max_additional_height)
-        for y in range(total_height):
-            # Add voxel using corner anchor. Coordinates are direct due to 1x1x1 dimension.
-            model6.add_voxel(x * voxel_dim[0],
-                             y * voxel_dim[1],
-                             z * voxel_dim[2],
-                             anchor=cubeforge.CubeAnchor.CORNER_NEG)
+        total_height = min_height + random.random() * max_additional_height
+        # Add voxel using corner anchor. Coordinates are direct due to 1x1x1 dimension.
+        model6.add_voxel(x * voxel_dim[0],
+                         0,
+                         z * voxel_dim[2],
+                         dimensions=(voxel_dim[0], total_height, voxel_dim[2]),
+                         anchor=cubeforge.CubeAnchor.CORNER_NEG)
 
 output_filename6 = os.path.join(output_dir, "random_height_surface.stl") # Use output_dir
 model6.save_mesh(output_filename6, format='stl_binary', solid_name="RandomHeightSurface")

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cubeforge"
-version = "0.1.0"
+version = "0.2.0"
 authors = [
   { name="Teddy van Jerry", email="me@teddy-van-jerry.org" },
 ]