voxels
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.
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.
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:555 =# 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.
