Shapes3D Module

Methods for creating geometric shapes in 3D.

This module provides a collection of functions for generating and manipulating various 3D geometric shapes within NumPy arrays. The implemented shapes range from basic primitives such as spheres, cubes, and cylinders to more complex structures like toroids, Möbius strips, and fractal-based geometries.

Each function operates on a 3D NumPy array, modifying it by filling the specified shape with a given value. The methods utilize vectorized operations for efficiency and support both solid and hollow versions of certain shapes where applicable.

These functions are useful for synthetic data generation, volumetric modeling, scientific simulations, and 3D image processing tasks.

@author: Antony Vamvakeros

nDTomo.sim.shapes3D.create_cone(arr, tip, height, outer_radius, thickness=1, fill_value=1, caps=False)[source]

Creates a solid or hollow cone in a 3D NumPy array, oriented along the Z-axis.

The function supports both solid and hollow cones. If thickness=0, a solid cone is created. If thickness > 0, a hollow cone with a specified wall thickness is created. Optional base caps can be included to close the bottom of the cone.

Parameters:

arr (np.ndarray) – 3D NumPy array where the cone will be drawn.
tip (tuple of int) – (x0, y0, z0) coordinates of the cone’s tip.
height (int) – The height of the cone along the Z-axis.
outer_radius (float) – The radius of the cone at the base.
thickness (float, optional (default=1)) – Radial thickness of the conical shell. If set to 0, a solid cone is created.
fill_value (int or float, optional) – The value used to fill the cone or its walls.
caps (bool, optional (default=False)) – If True, the cone is closed off at the base with a filled annular disk. If False, the cone remains open at the base.

Returns:

arr – The modified 3D array with the cone drawn.

Return type:

np.ndarray

nDTomo.sim.shapes3D.create_cube(arr, center, size, thickness=0, fill_value=1)[source]

Creates a solid or hollow cube in a 3D NumPy array.

This function generates either a solid cube or a hollow cube shell in the given 3D array arr. If thickness is 0, a solid cube is created. Otherwise, a hollow cube with specified wall thickness is formed.

Parameters:

arr (np.ndarray) – 3D NumPy array where the cube will be drawn.
center (tuple of int) – (x, y, z) coordinates of the cube’s center.
size (int) – The edge length of the cube.
thickness (int, optional) – The thickness of the cube walls (default is 0, which creates a solid cube).
fill_value (int or float, optional) – The value to fill inside the cube or its walls (default is 1).

Returns:

Updated 3D array with the cube or hollow cube drawn.

Return type:

np.ndarray

nDTomo.sim.shapes3D.create_cuboid(arr, center, size_x, size_y, size_z, thickness=0, fill_value=1)[source]

Creates a solid or hollow cuboid in a 3D NumPy array.

This function generates either a solid cuboid or a hollow cuboid shell in the given 3D array arr. If thickness is 0, a solid cuboid is created. Otherwise, a hollow cuboid with specified wall thickness is formed.

Parameters:

arr (np.ndarray) – 3D NumPy array where the cuboid will be drawn.
center (tuple of int) – (x, y, z) coordinates of the cuboid’s center.
size_x (int) – The length of the cuboid along the x-axis.
size_y (int) – The length of the cuboid along the y-axis.
size_z (int) – The length of the cuboid along the z-axis.
thickness (int, optional) – The thickness of the cuboid walls (default is 0, which creates a solid cuboid).
fill_value (int or float, optional) – The value to fill inside the cuboid or its walls (default is 1).

Returns:

Updated 3D array with the cuboid or hollow cuboid drawn.

Return type:

np.ndarray

nDTomo.sim.shapes3D.create_cylinder(arr, center_xy, z_range, outer_radius, thickness=1, fill_value=1, caps=True)[source]

Creates a solid or hollow cylinder in a 3D NumPy array, oriented along the Z-axis.

The function supports both solid and hollow cylinders. If thickness=0, a solid cylinder is created. If thickness > 0, a hollow cylinder with a specified wall thickness is created. Optional top and bottom caps can be included.

Parameters:

arr (np.ndarray) – 3D NumPy array where the cylinder will be drawn.
center_xy (tuple of int) – (cx, cy) coordinates of the cylinder’s center in the X-Y plane.
z_range (tuple of int) – (z_start, z_end) indices defining the height of the cylinder along the Z-axis.
outer_radius (int) – Outer radius of the cylinder’s base.
thickness (int, optional) – Radial thickness of the cylinder walls. If set to 0 (default), a solid cylinder is created.
fill_value (int or float, optional) – The value used to fill the cylinder or its walls.
caps (bool, optional) – If True, the cylinder is closed off with top and bottom caps. If False, the cylinder remains open.

Returns:

Updated 3D array with the cylinder drawn.

Return type:

np.ndarray

nDTomo.sim.shapes3D.create_ellipsoid(arr, center, radii, fill_value=1, hollow_thickness=0)[source]

Creates a 3D ellipsoid in arr, centered at center, with radii (a, b, c).

Parameters:

arr (np.ndarray) – 3D array where the ellipsoid is drawn.
center (tuple (x0, y0, z0)) – Center of the ellipsoid.
radii (tuple (a, b, c)) – Semi-axes lengths along X, Y, Z.
fill_value (int or float, optional) – The value to fill the ellipsoid.
hollow_thickness (float, optional (default=0)) – If > 0, makes the ellipsoid hollow with wall thickness hollow_thickness.

Returns:

arr – The modified array.

Return type:

np.ndarray

nDTomo.sim.shapes3D.create_hexagonal_prism(arr, center_xy, z_range, outer_radius, fill_value=1)[source]

Creates a hexagonal prism in arr.

Parameters:

arr (np.ndarray) – 3D array where the hexagonal prism is drawn.
center_xy (tuple (cx, cy)) – Center of the hexagonal cross-section.
z_range (tuple (z_min, z_max)) – Z-range for the prism.
outer_radius (float) – Outer radius of the hexagon.
fill_value (int or float, optional) – The value to fill the hexagonal prism.

Returns:

arr – The modified array.

Return type:

np.ndarray

nDTomo.sim.shapes3D.create_menger_sponge(arr, center, size, depth, fill_value=1)[source]

Recursively creates a 3D Menger sponge inside arr.

Parameters:

arr (np.ndarray) – 3D array where the Menger sponge is drawn.
center (tuple (cx, cy, cz)) – Center of the sponge.
size (int) – Side length of the current cube.
depth (int) – Recursion depth of the sponge.
fill_value (int or float, optional) – The value to fill the sponge.

Returns:

arr – The modified array.

Return type:

np.ndarray

nDTomo.sim.shapes3D.create_mobius_strip(arr, center, major_radius, width, num_points=100, fill_value=1)[source]

Creates a Möbius strip in arr using parametric equations.

Parameters:

arr (np.ndarray) – 3D array where the Möbius strip is drawn.
center (tuple (x0, y0, z0)) – Center of the Möbius strip.
major_radius (float) – Main radius of the strip.
width (float) – Width of the Möbius band.
num_points (int, optional) – Resolution of the generated Möbius strip.
fill_value (int or float, optional) – The value to fill the Möbius strip.

Returns:

arr – The modified array.

Return type:

np.ndarray

nDTomo.sim.shapes3D.create_pyramid(arr, tip, height, base_size, thickness=1, fill_value=1)[source]

Creates a solid or hollow pyramid in a 3D NumPy array, oriented along the Z-axis.

The pyramid has a square base centered at (x0, y0, z0 + height), tapering to a tip at (x0, y0, z0). If thickness=0, a solid pyramid is created. If thickness > 0, a hollow pyramid with a uniform wall thickness is created. Optional base and tip caps can be included to fully enclose the pyramid.

Parameters:

arr (np.ndarray) – 3D NumPy array where the pyramid will be drawn.
tip (tuple of int) – (x0, y0, z0) coordinates of the pyramid’s tip.
height (int) – The height of the pyramid along the Z-axis.
base_size (int) – The width of the pyramid’s square base at z0 + height.
thickness (int, optional (default=1)) – The thickness of the pyramid’s walls. If set to 0, a solid pyramid is created.
fill_value (int or float, optional) – The value used to fill the pyramid or its walls.
caps (bool, optional (default=False)) – If True, adds a solid base to the pyramid.

Returns:

arr – The modified 3D array with the pyramid drawn.

Return type:

np.ndarray

nDTomo.sim.shapes3D.create_sphere(arr, center, outer_radius, thickness=0, fill_value=1)[source]

Creates a solid or hollow sphere in a 3D array.

This function generates either a solid sphere or a hollow spherical shell (hollow sphere) in the given 3D array arr. If thickness is 0, a solid sphere is created. Otherwise, a shell is formed where voxels within the specified thickness are filled.

Parameters:

arr (np.ndarray) – 3D array where the sphere is drawn.
center (tuple of int) – (x0, y0, z0) coordinates specifying the center of the sphere.
outer_radius (int or float) – The outer radius of the sphere.
thickness (int or float, optional) – Thickness of the shell (default is 0, which creates a solid sphere).
fill_value (int or float, optional) – The value to fill inside the sphere or shell (default is 1).

Returns:

arr – The modified array with the sphere or shell.

Return type:

np.ndarray

nDTomo.sim.shapes3D.create_torus(arr, center, major_radius, minor_radius, fill_value=1, hollow_thickness=0)[source]

Creates a torus (3D ring) in arr, centered at center, with major and minor radii.

Parameters:

arr (np.ndarray) – 3D array where the torus is drawn.
center (tuple (x0, y0, z0)) – Center of the torus.
major_radius (float) – Distance from the torus center to the middle of the ring.
minor_radius (float) – Thickness of the torus tube.
fill_value (int or float, optional) – The value to fill the torus.
hollow_thickness (float, optional (default=0)) – If > 0, makes the torus hollow with tube thickness hollow_thickness.

Returns:

arr – The modified array.

Return type:

np.ndarray

nDTomo.sim.shapes3D.create_voronoi_3d(arr, seed_points, fill_values=None)[source]

Creates a Voronoi diagram in a 3D NumPy array.

Parameters:

arr (np.ndarray) – 3D array where the Voronoi diagram is drawn.
seed_points (list of tuples [(x1, y1, z1), (x2, y2, z2), ...]) – List of seed points for the Voronoi cells.
fill_values (list, optional) – List of values corresponding to each seed point. If None, assigns unique integer values to each region.

Returns:

arr – The modified array with Voronoi regions.

Return type:

np.ndarray