Skip to content
API Reference
spatial
bar3d
voxels

voxels

Mojo function 🡭

voxels

fn def voxels(filled: List[List[List[Bool]]], elev: Float64 = 30, azim: Float64 = -60, theme: Theme = Theme(WHITE, Color(UInt8(30), UInt8(100), UInt8(180), UInt8(255)), Color(UInt8(80), UInt8(80), UInt8(80), UInt8(255)), Color(UInt8(225), UInt8(225), UInt8(225), UInt8(255)), Color(UInt8(40), UInt8(40), UInt8(40), UInt8(255)), SIMD(12), SIMD(3.5), SIMD(2), Int(60), Int(20), Int(20), Int(50), True, False, False, Color(UInt8(240), UInt8(240), UInt8(240), UInt8(255)), Int(3), Color(UInt8(60), UInt8(110), UInt8(200), UInt8(255)), Color(UInt8(235), UInt8(235), UInt8(235), UInt8(255)), Color(UInt8(220), UInt8(90), UInt8(40), UInt8(255)), ColorRamp(), ColorPalette(), SIMD(3), SIMD(15), True, SIMD(1), Int(0), False, Color(UInt8(200), UInt8(60), UInt8(60), UInt8(255)), Color(UInt8(224), UInt8(224), UInt8(224), UInt8(255)), Color(UInt8(120), UInt8(120), UInt8(120), UInt8(255)), Color(UInt8(100), UInt8(100), UInt8(100), UInt8(255)), Color(UInt8(230), UInt8(230), UInt8(230), UInt8(255)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), UInt8(90), UInt8(160), False, False, SIMD(0), SIMD(18), SIMD(14), Color(UInt8(110), UInt8(110), UInt8(110), UInt8(255)), SIMD(14), Color(UInt8(150), UInt8(150), UInt8(150), UInt8(255)), Color(UInt8(224), UInt8(236), UInt8(246), UInt8(200)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), True, False, False, True, AxisPosition.EDGE, AxisPosition.EDGE, String("sans-serif"), True, UInt8(90), Int(5), Int(4), Int(130), Int(14), Int(8), Int(14), Int(100), Int(8), SIMD(4), OutputFormat.SVG, Tooltips.AUTO, Missing.DRAW, String("(missing)"), Int(1000), False, LineStyle.SOLID, SIMD(1.5), LineStyle.SOLID, LegendPosition.RIGHT, XAxisLabelRotation.AUTO, TickFormat.AUTO, TickFormat.AUTO), width: Int = Int(640), height: Int = Int(480), title: String = "", subtitle: String = "") -> Chart[Voxels]

A solid built out of unit cubes: which cells of a 3D grid are filled.

Mark.VOXELS. One cube per filled cell, with the faces between two filled cells left out – they are inside the solid and cannot be seen. What is drawn is the surface of the shape, so a hollow shell and the same shell packed solid look identical, which is the point: only the outside is ever visible.

Use it for a shape that is genuinely three-dimensional and blocky – an occupancy grid, a segmentation, a lattice of on/off states. Cells buried inside the solid are invisible by construction, so a grid whose interesting structure is interior needs slices, not this.

Example:

from dataviz import save, voxels

def main() raises:
    # Illustrative occupancy: a staircase climbing through the
    # grid, so every layer differs from the one below it.
    var grid = List[List[List[Bool]]]()
    for layer in range(6):
        var rows = List[List[Bool]]()
        for row in range(6):
            var cols = List[Bool]()
            for col in range(6):
                cols.append(col >= layer and row >= layer)
            rows.append(cols^)
        grid.append(rows^)

    var c = voxels(grid, title="Illustrative Occupancy Grid")
    save(c, "docs/src/examples/out_voxels.svg")

Args:

  • filled (List[List[List[Bool]]]): filled[layer][row][col], True where the cell is solid. Layers run up z, rows along y, columns along x, and every layer and row must be the same size.
  • elev (Float64): Degrees to look down on the scene from, above the x-y plane.
  • azim (Float64): Degrees to turn the scene through, about the z axis.
  • theme (Theme): Full styling knobs beyond this function’s own parameters – see Theme’s docstring.
  • width (Int): Pixel width of the returned Plot (.size()).
  • height (Int): Pixel height of the returned Plot (.size()).
  • title (String): The chart’s title, shown above the plot.
  • subtitle (String): A secondary line shown under the title.

Returns:

Chart[Voxels]: The finished chart – unrendered. Call save(plot, path) to write it (any of .svg/.png/.pdf/.bmp), or render(plot)/render_svg(plot) for the explicit two-step.

Raises:

Error: The grid is empty, or a layer or row is the wrong size.

fn def voxels(df: DataFrame, x: String, y: String, z: String, elev: Float64 = 30, azim: Float64 = -60, theme: Theme = Theme(WHITE, Color(UInt8(30), UInt8(100), UInt8(180), UInt8(255)), Color(UInt8(80), UInt8(80), UInt8(80), UInt8(255)), Color(UInt8(225), UInt8(225), UInt8(225), UInt8(255)), Color(UInt8(40), UInt8(40), UInt8(40), UInt8(255)), SIMD(12), SIMD(3.5), SIMD(2), Int(60), Int(20), Int(20), Int(50), True, False, False, Color(UInt8(240), UInt8(240), UInt8(240), UInt8(255)), Int(3), Color(UInt8(60), UInt8(110), UInt8(200), UInt8(255)), Color(UInt8(235), UInt8(235), UInt8(235), UInt8(255)), Color(UInt8(220), UInt8(90), UInt8(40), UInt8(255)), ColorRamp(), ColorPalette(), SIMD(3), SIMD(15), True, SIMD(1), Int(0), False, Color(UInt8(200), UInt8(60), UInt8(60), UInt8(255)), Color(UInt8(224), UInt8(224), UInt8(224), UInt8(255)), Color(UInt8(120), UInt8(120), UInt8(120), UInt8(255)), Color(UInt8(100), UInt8(100), UInt8(100), UInt8(255)), Color(UInt8(230), UInt8(230), UInt8(230), UInt8(255)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), UInt8(90), UInt8(160), False, False, SIMD(0), SIMD(18), SIMD(14), Color(UInt8(110), UInt8(110), UInt8(110), UInt8(255)), SIMD(14), Color(UInt8(150), UInt8(150), UInt8(150), UInt8(255)), Color(UInt8(224), UInt8(236), UInt8(246), UInt8(200)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), True, False, False, True, AxisPosition.EDGE, AxisPosition.EDGE, String("sans-serif"), True, UInt8(90), Int(5), Int(4), Int(130), Int(14), Int(8), Int(14), Int(100), Int(8), SIMD(4), OutputFormat.SVG, Tooltips.AUTO, Missing.DRAW, String("(missing)"), Int(1000), False, LineStyle.SOLID, SIMD(1.5), LineStyle.SOLID, LegendPosition.RIGHT, XAxisLabelRotation.AUTO, TickFormat.AUTO, TickFormat.AUTO), width: Int = Int(640), height: Int = Int(480), title: String = "", subtitle: String = "") -> Chart[Voxels]

Draw occupied voxels from a sparse DataFrame of coordinates.

Each row marks one filled unit cube. x, y, and z must be zero-based integer coordinates; unlisted cells are empty. The highest coordinate on each axis sets the grid’s extent.

Args:

  • df (DataFrame): The frame listing occupied cells.
  • x (String): Numeric column of voxel column indices.
  • y (String): Numeric column of voxel row indices.
  • z (String): Numeric column of voxel layer indices.
  • elev (Float64): See the grid overload.
  • azim (Float64): See the grid overload.
  • theme (Theme): See the grid overload.
  • width (Int): See the grid overload.
  • height (Int): See the grid overload.
  • title (String): See the grid overload.
  • subtitle (String): See the grid overload.

Returns:

Chart[Voxels]: The finished chart – unrendered.

Raises:

Error: There are no occupied cells, a column is invalid, a coordinate is not a nonnegative integer, or a cell repeats.

bar3d