API Reference

Brickalize: Convert 3D models into LEGO-like brick structures.

class brickalize.Brick(d1: int, d2: int, is_support: bool = False)

Bases: object

__init__(d1: int, d2: int, is_support: bool = False)

Brick object

Parameters:

• d1 (int) – First dimension of the lego brick (length)

• d2 (int) – Second dimension of the lego brick (width)

• is_support (bool) – Whether the brick is a normal (model) or support brick (for lego printers)

Raises:

• TypeError – if the variable types are invalid

• ValueError – if the dimensions are negative

height = 1.2

property is_support: bool

Whether or not the brick type is a support or a building brick.

property length: int

Biggest dimension of the Lego Brick (excluding height).

property orientations: list[tuple[int, int]]

A list of all of the possible orientations that the brick can be in (1 or 2).

Returns:

The list of all possible orientations. These are tuples of x and y.

Return type:

list[tuple[int, int]]

oriented(x_long: bool) → tuple[tuple[int, int], bool]

Get an oriented, 2D version of the brick.

Parameters:

x_long (bool) – Whether the x-axis contains the length (largest dimension). The y-axis will contain the other value (width).

Returns:

A tuple containing:

• size (tuple[int, int]): The (x, y) size of the brick.

• type (bool): True if it is a support, otherwise False.

Return type:

tuple

property width: int

Smallest dimension of the Lego Brick (excluding height).

class brickalize.BrickModel(layer_height: float = 1.2)

Bases: object

__init__(layer_height: float = 1.2)

Initializes an empty brick model.

Parameters:

layer_height (float)

Raises:

• TypeError – if layer_height is not a float.

• ValueError – if the layer_height is not larger than 0

property is_empty: bool

True if the model contains no bricks, False otherwise.

Type:

bool

property layer_height: float

The height of each layer in the model.

property layers: dict[int, list[dict]]

A dictionary containing all layers and the bricks in each layer.

property max: tuple[int, int, int]

The maximum x, y, z coordinates of the model in bricks.

property min: tuple[int, int, int]

The minimum x, y, z coordinates of the model in bricks.

normalize() → None

Normalize the model to start from (0,0,0) in the bottom left corner. This will change the position of all bricks in the model.

place_brick(oriented_brick: tuple[tuple[int, int], bool], position: tuple[int, int, int]) → bool

Attempt to place a brick in the model at a specified position.

Parameters:

• oriented_brick (tuple[tuple[int, int], bool]) – tuple containing a tuple with the size in x and y direction and a bool that is True if the brick is support. ((x, y), is_support)

• position (tuple[int, int, int]) – The x, y and z coordinates, for the left, front, bottom corner, respectively

Returns:

Whether the placement was succesful or not

Return type:

bool

Raises:

TypeError – If the inputs are invalid

remove_brick(position: tuple[int, int, int]) → bool

Attempt to remove a brick in the model at a specified position.

Parameters:

position (tuple[int, int, int]) – The x, y and z coordinates, for the left, front, bottom corner, respectively

Returns:

Whether the placement was succesful or not

Return type:

bool

Raises:

TypeError – If the inputs are invalid

property size: tuple[int, int, int]

The size of the model in bricks (x, y, z).

class brickalize.BrickModelVisualizer

Bases: object

brick_mat = <open3d.cpu.pybind.visualization.rendering.MaterialRecord object>

static draw_brick(position: tuple, size: tuple)

Create a solid box in Open3D.

Parameters:

• position (tuple) – (x, y, z) coordinates representing the center of the box.

• size (tuple) – (l, w, h) dimensions of the box.

Returns:

Open3D mesh object representing the box.

Return type:

open3d.geometry.TriangleMesh

classmethod draw_model(voxel_array: ndarray, support_array: ndarray | None = None, voxel_height: float = 1.2) → list

Draw multiple bricks in Open3D with transparency.

Parameters:

• voxel_array (np.ndarray) – A 3D binary array [z,x,y] with the True values being occupied spaces with building bricks of the model.

• support_array (np.ndarray, optional) – A 3D binary array [z,x,y] with the True values being occupied spaces with support bricks of the model. (standard = None)

• voxel_height (float) – The relative height of the voxels (the width and depth are 1)

Returns:

A mesh list containing 1 or 2 meshes (dictionaries containing ‘name’, ‘geometry’ and ‘material’ as keys)

Return type:

list

classmethod draw_model_individual_bricks(brick_model: BrickModel) → list

Draw multiple bricks in Open3D with transparency.

Parameters:

brick_model (BrickModel) – A BrickModel instance from this module.

Returns:

A mesh list containing all the meshes (dictionaries containing ‘name’, ‘geometry’ and ‘material’ as keys)

Return type:

list

static generate_mesh_from_voxels(voxel_array: ndarray, voxel_height: float = 1.2) → TriangleMesh

Generates a mesh from a 3D binary array containing all exposed surfaces.

Parameters:

• voxel_array (np.ndarray) – A 3D binary array with the True values being occupied spaces of the model.

• voxel_height (float) – The relative height of the voxels (the width and depth are 1)

Returns:

Open3D mesh object representing the model.

Return type:

open3d.geometry.TriangleMesh

classmethod save_as_images(brick_model: BrickModel, dir_path: str, brick_color: tuple = (0, 255, 255), support_color: tuple = (200, 200, 255), add_lego_overlay: bool = True, show_ghost_layer: bool = False, pixels_per_stud: int = 20, line_thickness: float = 0.05)

Convert the model to images using Open3D.

Parameters:

• brick_model (BrickModel) – A BrickModel instance from this module.

• dir_path (str) – Path to the directory where images will be saved.

• brick_color (tuple, optional) – BGR color for normal bricks. Defaults to (0, 255, 255).

• support_color (tuple, optional) – BGR color for support bricks. Defaults to (200, 200, 255).

• add_lego_overlay (bool, optional) – Whether to add a shadow overlay to the images (requires a minimum pixels_per_stud of 10). Defaults to True.

• show_ghost_layer (bool, optional) – Whether to show a semi-transparent layer below the current layer, representing the lower layer. Defaults to False.

• pixels_per_stud (int, optional) – Number of pixels per stud. Defaults to 20.

• line_thickness (float, optional) – Thickness of the lines in the image relative to the size of a stud. Defaults to 0.05.

static save_model(mesh_list: list, file_path: str) → bool

Save the model to an STL file.

Parameters:

• mesh_list (list) – List of Open3D mesh objects to be saved.

• file_path (str) – Path to the output .stl file.

Returns:

True if the file was saved successfully, False otherwise.

Return type:

bool

static show_model(mesh_list: list)

Display a mesh list in an interactive 3D renderer using open3D

Parameters:

mesh_list (list) – A mesh list containing meshes (dictionaries containing ‘name’, ‘geometry’ and ‘material’ as keys)

support_mat = <open3d.cpu.pybind.visualization.rendering.MaterialRecord object>

class brickalize.BrickSet(bricks: list[Brick])

Bases: object

__init__(bricks: list[Brick])

Creates a set of unique bricks. This class is an iterable, which iterates over all bricks, in all orientations

Parameters:

bricks (list[Brick]) – A list of bricks

Raises:

• TypeError – if bricks is not a list of Brick objects.

• ValueError – if there are no (non-support) building bricks in the list

__iter__()

yield each brick. First yields all of the building bricks. Then yields all of the support bricks.

property bricks: list[Brick]

List of all the bricks in the set, including both building and support bricks.

property building_brick_orientations: list[tuple[int, int]]

A list of all of the possible orientations that all of the building bricks in the set can be in.

Returns:

The list of all possible orientations. These are tuples of x and y.

Return type:

list[tuple[int, int]]

property building_bricks: list[Brick]

List of all the building bricks.

get_building_brick_dimensions() → set

Get a set of all dimensions available with the bricks.

Returns:

A set containing all dimensions of the bricks, sorted from largest to smallest

Return type:

set[int]

get_building_bricks_by_dimension(dimension: int) → set

Get a set of all dimension by x bricks, where the set contains all complementary x

Parameters:

dimension (int) – the dimension the bricks must have

Returns:

A set containing the other dimension of the bricks that satisfy the dimension, sorted from largest to smallest

Return type:

set[int]

get_support_brick_dimensions() → set

Get a set of all dimensions available with the bricks.

Returns:

A set containing all dimensions of the bricks, sorted from largest to smallest

Return type:

set[int]

get_support_bricks_by_dimension(dimension: int) → set

Get a set of all dimension by x bricks, where the set contains all complementary x

Parameters:

dimension (int) – the dimension the bricks must have

Returns:

A set containing the other dimension of the bricks that satisfy the dimension, sorted from largest to smallest

Return type:

set[int]

property has_support: bool

Whether or not the brickset includes support bricks

property support_brick_orientations: list[tuple[int, int]]

A list of all of the possible orientations that all of the support bricks in the set can be in.

Returns:

The list of all possible orientations. These are tuples of x and y.

Return type:

list[tuple[int, int]]

property support_bricks: list[Brick]

List of all the support bricks.

class brickalize.Brickalizer

Bases: object

classmethod array_to_brick_model(voxel_array: ndarray, brick_set: BrickSet, brick_model: BrickModel | None = None, is_support=False) → BrickModel

Algorithm to place bricks in a brick model from a brick set, according to a 3D binary array specifying which voxels are occupied.

Parameters:

• voxel_array (np.ndarray) – A 3D binary numpy array

• brick_set (BrickSet) – A set of Bricks

• brick_model (BrickModel, optional) – A BrickModel to place the bricks in. Creates a new one if not provided (None).

• is_support (bool) – Whether the bricks in the array are support bricks or not

Returns:

A model containing bricks from brick_set in the shape of the voxel_array

Return type:

BrickModel

static brick_model_to_array(brick_model: BrickModel, include_support: bool = False) → ndarray

Converts a BrickModel to a 3D binary numpy array.

Parameters:

• brick_model (BrickModel) – A BrickModel instance.

• include_support (bool) – Whether to include support bricks in the output array.

Returns:

A 3D binary numpy array [z,x,y] where True indicates occupied space.

Return type:

np.ndarray

static extract_shell_from_3d_array(array: ndarray)

Extract the outermost shell from a 3D binary array and makes everything inside False.

Parameters:

array (np.ndarray) – A 3D binary array [z,x,y]

Returns:

A 3D binary array [z,x,y]

Return type:

np.ndarray

classmethod generate_support(brick_model: BrickModel, model_array: ndarray) → ndarray

Generates sparse pillar support based on a new ground definition. Checks if a building brick has at least one stud with a solid connection (all True in model_array) down to the lowest occupied layer in brick_model. If not, evaluates pillars from all studs of the floating brick, chooses the one requiring the fewest new support voxels, and generates that pillar downwards, skipping existing model parts and stopping at the lowest layer or other support.

The conceptual “ground” is considered to be just below the minimum Z index present in the brick_model.

Parameters:

• brick_model (BrickModel) – Used to identify building bricks, dimensions, and the lowest occupied layer.

• model_array (np.ndarray) – 3D boolean array [z, x, y] representing initial bricks.

Returns:

3D boolean array [z, x, y] where True indicates needed support.

Return type:

np.ndarray

Raises:

TypeError, ValueError – For invalid inputs or mismatched dimensions.

classmethod voxelize_stl(stl_file, grid_voxel_count=10, grid_direction='z', fast_mode=False, threshold=0.5, aspect_ratio=1.2)

Voxelizes an STL file into a grid of voxels, using a specified number of voxels in one direction and an aspect ratio for others.

Parameters:

• stl_file (str) – Path to the STL file.

• grid_voxel_count (int) – The number of voxels in the specified direction (X, Y, or Z).

• grid_direction (str) – The direction (‘x’, ‘y’, or ‘z’) in which to specify the number of voxels.

• fast_mode (bool) – If True, uses only the center point of each voxel for intersection checking instead of 8 points spaced inside the voxel, with the threshold.

• threshold (float) – Threshold for mesh intersection, determines the “solid” region inside the mesh. (0 to 1, where 1 means all 8 corners must be inside)

• aspect_ratio (float) – Size of the z axis compared to the x and y axis.

Returns:

A 3D binary numpy array [z,x,y]

Return type:

np.ndarray