voxels

MakieCore.voxels Function

voxels(x, y, z, chunk::Array{<:Real, 3})
voxels(chunk::Array{<:Real, 3})

Plots a chunk of voxels centered at 0. Optionally the placement and scaling of the chunk can be given as range-like x, y and z. (Only the extrema are considered here. Voxels are always uniformly sized.)

Internally voxels are represented as 8 bit unsigned integer, with 0x00 always being an invisible "air" voxel. Passing a chunk with matching type will directly set those values. Note that color handling is specialized for the internal representation and may behave a bit differently than usual.

Plot type

The plot type alias for the voxels function is Voxels.

source

Examples

Basic Example

using GLMakie
# Same as volume example
r = LinRange(-1, 1, 100)
cube = [(x.^2 + y.^2 + z.^2) for x = r, y = r, z = r]
cube_with_holes = cube .* (cube .> 1.4)

# To match the volume example with isovalue=1.7 and isorange=0.05 we map all
# values outside the range (1.65..1.75) to invisible air blocks with is_air
f, a, p = voxels(-1..1, -1..1, -1..1, cube_with_holes, is_air = x -> !(1.65 <= x <= 1.75))

Gap Attribute

The gap attribute allows you to specify a gap size between adjacent voxels. It is given in units of the voxel size (at gap = 0) so that gap = 0 creates no gaps and gap = 1 reduces the voxel size to 0. Note that this attribute only takes effect at values gap > 0.01.

using GLMakie
chunk = reshape(collect(1:27), 3, 3, 3)
voxels(chunk, gap = 0.33)

Color and the internal representation

Voxels are represented as an Array{UInt8, 3} of voxel ids internally. In this representation the voxel id 0x00 is defined as an invisible air block. All other ids (0x01 - 0xff or 1 - 255) are visible and derive their color from the various color attributes. For plot.color specifically the voxel id acts as an index into an array of colors:

using GLMakie
chunk = UInt8[
    1 0 2; 0 0 0; 3 0 4;;;
    0 0 0; 0 0 0; 0 0 0;;;
    5 0 6; 0 0 0; 7 0 8;;;
]
f, a, p = voxels(chunk, color = [:white, :red, :green, :blue, :black, :orange, :cyan, :magenta])

Colormaps

With non UInt8 inputs, colormap attributes (colormap, colorrange, highclip, lowclip and colorscale) work as usual, with the exception of nan_color which is not applicable:

using GLMakie
chunk = reshape(collect(1:512), 8, 8, 8)

f, a, p = voxels(chunk,
    colorrange = (65, 448), colorscale = log10,
    lowclip = :red, highclip = :orange,
    colormap = [:blue, :green]
)

When passing voxel ids directly (i.e. an Array{UInt8, 3}) they are used to index a vector [lowclip; sampled_colormap; highclip]. This means id 1 maps to lowclip, 2..254 to colors of the colormap and 255 to highclip. colorrange and colorscale are ignored in this case.

Texturemaps

You can also map a texture to voxels based on their id (and optionally the direction the face is facing). For this plot.color needs to be an image (matrix of colors) and plot.uvmap needs to be defined. The uvmap can take two forms here. The first is a Vector{Vec4f} which maps voxel ids (starting at 1) to normalized uv coordinates, formatted left-right-bottom-top.

using GLMakie
using FileIO

# load a sprite sheet with 10 x 9 textures
texture = FileIO.load(Makie.assetpath("voxel_spritesheet.png"))

# create a map idx -> LRBT coordinate of the textures, normalized to a 0..1 range
uv_map = [
    Vec4f(x, x+1/10, y, y+1/9)
    for x in range(0.0, 1.0, length = 11)[1:end-1]
    for y in range(0.0, 1.0, length = 10)[1:end-1]
]

# Define which textures/uvs apply to which voxels (0 is invisible/air)
chunk = UInt8[
    1 0 2; 0 0 0; 3 0 4;;;
    0 0 0; 0 0 0; 0 0 0;;;
    5 0 6; 0 0 0; 7 0 9;;;
]

# draw
f, a, p = voxels(chunk, uvmap = uv_map, color = texture)

The second format allows you define sides in the second dimension of the uvmap. The order of sides is: -x, -y, -z, +x, +y, +z.

using GLMakie
using FileIO

texture = FileIO.load(Makie.assetpath("voxel_spritesheet.png"))

# idx -> uv LRBT map for convenience. Note the change in order loop order
uvs = [
    Vec4f(x, x+1/10, y, y+1/9)
    for y in range(0.0, 1.0, length = 10)[1:end-1]
    for x in range(0.0, 1.0, length = 11)[1:end-1]
]

# Create uvmap with sides (-x -y -z x y z) in second dimension
uv_map = Matrix{Vec4f}(undef, 4, 6)
uv_map[1, :] = [uvs[9],  uvs[9],  uvs[8],  uvs[9],  uvs[9],  uvs[8]]  # 1 -> birch
uv_map[2, :] = [uvs[11], uvs[11], uvs[10], uvs[11], uvs[11], uvs[10]] # 2 -> oak
uv_map[3, :] = [uvs[2],  uvs[2],  uvs[2],  uvs[2],  uvs[2],  uvs[18]] # 3 -> crafting table
uv_map[4, :] = [uvs[1],  uvs[1],  uvs[1],  uvs[1],  uvs[1],  uvs[1]]  # 4 -> planks

chunk = UInt8[
    1 0 1; 0 0 0; 1 0 1;;;
    0 0 0; 0 0 0; 0 0 0;;;
    2 0 2; 0 0 0; 3 0 4;;;
]

f, a, p = voxels(chunk, uvmap = uv_map, color = texture)

The textures used in these examples are from Kenney's Voxel Pack.

Updating Voxels

The voxel plot is a bit different from other plot types which affects how you can and should update its data.

First you can pass your data as an Observable and update that observable as usual:

using GLMakie
chunk = Observable(ones(8,8,8))
f, a, p = voxels(chunk, colorrange = (0, 1))
chunk[] = rand(8,8,8)
f

You can also update the data contained in the plot object. For this you can't index into the plot though, since that will return the converted voxel id data. Instead you need to index into p.args.

using GLMakie
f, a, p = voxels(ones(8,8,8), colorrange = (0, 1))
p.args[end][] = rand(8,8,8)
f

Both of these solutions triggers a full replacement of the input array (i.e. chunk), the internal representation (plot.converted[4]) and the texture on gpu. This can be quite slow and wasteful if you only want to update a small section of a large chunk. In that case you should instead update your input data without triggering an update (using obs.val) and then call local_update(plot, is, js, ks) to process the update:

using GLMakie
chunk = Observable(rand(64, 64, 64))
f, a, p = voxels(chunk, colorrange = (0, 1))
chunk.val[30:34, :, :] .= NaN # or p.args[end].val
Makie.local_update(p, 30:34, :, :)
f

Picking Voxels

The pick function is able to pick individual voxels in a voxel plot. The returned index is a flat index into the array passed to voxels, i.e. plt.args[end][][idx] will return the relevant data. One important thing to note here is that the returned index is a UInt32 internally and thus has limited range. Very large voxel plots (~4.3 billion voxels or 2048 x 2048 x 1024) can reach this limit and trigger an integer overflow.

Attributes

alpha

Defaults to 1.0

The alpha value of the colormap or color attribute. Multiple alphas like in plot(alpha=0.2, color=(:red, 0.5), will get multiplied.

backlight

Defaults to 0.0

Sets a weight for secondary light calculation with inverted normals.

clip_planes

Defaults to automatic

Clip planes offer a way to do clipping in 3D space. You can set a Vector of up to 8 Plane3f planes here, behind which plots will be clipped (i.e. become invisible). By default clip planes are inherited from the parent plot or scene. You can remove parent clip_planes by passing Plane3f[].

color

Defaults to nothing

Sets colors per voxel id, skipping 0x00. This means that a voxel with id 1 will grab plot.colors[1] and so on up to id 255. This can also be set to a Matrix of colors, i.e. an image for texture mapping.

colormap

Defaults to @inherit colormap :viridis

Sets the colormap that is sampled for numeric colors. PlotUtils.cgrad(...), Makie.Reverse(any_colormap) can be used as well, or any symbol from ColorBrewer or PlotUtils. To see all available color gradients, you can call Makie.available_gradients().

colorrange

Defaults to automatic

The values representing the start and end points of colormap.

colorscale

Defaults to identity

The color transform function. Can be any function, but only works well together with Colorbar for identity, log, log2, log10, sqrt, logit, Makie.pseudolog10 and Makie.Symlog10.

depth_shift

Defaults to 0.0

adjusts the depth value of a plot after all other transformations, i.e. in clip space, where 0 <= depth <= 1. This only applies to GLMakie and WGLMakie and can be used to adjust render order (like a tunable overdraw).

depthsorting

Defaults to false

Controls the render order of voxels. If set to false voxels close to the viewer are rendered first which should reduce overdraw and yield better performance. If set to true voxels are rendered back to front enabling correct order for transparent voxels.

diffuse

Defaults to 1.0

Sets how strongly the red, green and blue channel react to diffuse (scattered) light.

fxaa

Defaults to true

adjusts whether the plot is rendered with fxaa (anti-aliasing, GLMakie only).

gap

Defaults to 0.0

Sets the gap between adjacent voxels in units of the voxel size. This needs to be larger than 0.01 to take effect.

highclip

Defaults to automatic

The color for any value above the colorrange.

inspectable

Defaults to true

sets whether this plot should be seen by DataInspector.

inspector_clear

Defaults to automatic

Sets a callback function (inspector, plot) -> ... for cleaning up custom indicators in DataInspector.

inspector_hover

Defaults to automatic

Sets a callback function (inspector, plot, index) -> ... which replaces the default show_data methods.

inspector_label

Defaults to automatic

Sets a callback function (plot, index, position) -> string which replaces the default label generated by DataInspector.

interpolate

Defaults to false

Controls whether the texture map is sampled with interpolation (i.e. smoothly) or not (i.e. pixelated).

is_air

Defaults to x->begin #= /home/runner/work/Makie.jl/Makie.jl/MakieCore/src/basic_plots.jl:607 =# isnothing(x) || (ismissing(x) || isnan(x)) end

A function that controls which values in the input data are mapped to invisible (air) voxels.

lowclip

Defaults to automatic

The color for any value below the colorrange.

material

Defaults to nothing

RPRMakie only attribute to set complex RadeonProRender materials. Warning, how to set an RPR material may change and other backends will ignore this attribute

model

Defaults to automatic

Sets a model matrix for the plot. This overrides adjustments made with translate!, rotate! and scale!.

nan_color

Defaults to :transparent

The color for NaN values.

overdraw

Defaults to false

Controls if the plot will draw over other plots. This specifically means ignoring depth checks in GL backends

shading

Defaults to automatic

Sets the lighting algorithm used. Options are NoShading (no lighting), FastShading (AmbientLight + PointLight) or MultiLightShading (Multiple lights, GLMakie only). Note that this does not affect RPRMakie.

shininess

Defaults to 32.0

Sets how sharp the reflection is.

space

Defaults to :data

sets the transformation space for box encompassing the plot. See Makie.spaces() for possible inputs.

specular

Defaults to 0.2

Sets how strongly the object reflects light in the red, green and blue channels.

ssao

Defaults to false

Adjusts whether the plot is rendered with ssao (screen space ambient occlusion). Note that this only makes sense in 3D plots and is only applicable with fxaa = true.

transformation

Defaults to automatic

No docs available.

transparency

Defaults to false

Adjusts how the plot deals with transparency. In GLMakie transparency = true results in using Order Independent Transparency.

uvmap

Defaults to nothing

Defines a map from voxel ids (and optionally sides) to uv coordinates. These uv coordinates are then used to sample a 2D texture passed through color for texture mapping.

visible

Defaults to true

Controls whether the plot will be rendered or not.