volume

Makie.volume Function

volume(volume_data)
volume(x, y, z, volume_data)

Plots a volume with optional physical dimensions x, y, z.

All volume plots are derived from casting rays for each drawn pixel. These rays intersect with the volume data to derive some color, usually based on the given colormap. How exactly the color is derived depends on the algorithm used.

Plot type

The plot type alias for the volume function is Volume.

source

Examples

Value based Algorithms (:absorption, :mip, :iso, counter)

Value based algorithms samples sample the colormap using values from volume data.

using GLMakie
r = LinRange(-1, 1, 100)
cube = [(x.^2 + y.^2 + z.^2) for x = r, y = r, z = r]
contour(cube, alpha=0.5)

cube_with_holes = cube .* (cube .> 1.4)
volume(cube_with_holes, algorithm = :iso, isorange = 0.05, isovalue = 1.7)

using GLMakie
using NIfTI
brain = niread(Makie.assetpath("brain.nii.gz")).raw
mini, maxi = extrema(brain)
normed = Float32.((brain .- mini) ./ (maxi - mini))

fig = Figure(size=(1000, 450))
# Make a colormap, with the first value being transparent
colormap = to_colormap(:plasma)
colormap[1] = RGBAf(0,0,0,0)
volume(fig[1, 1], normed, algorithm = :absorption, absorption=4f0, colormap=colormap, axis=(type=Axis3, title = "Absorption"))
volume(fig[1, 2], normed, algorithm = :mip, colormap=colormap, axis=(type=Axis3, title="Maximum Intensity Projection"))
fig

RGB(A) Algorithms (:absorptionrgba, :additive)

RGBA algorithms sample colors directly from the given volume data. If the data contains less than 4 dimensions the remaining dimensions are filled with 0 for the green and blue channel and 1 for the alpha channel.

using GLMakie
using LinearAlgebra
# Signed distance field for a chain Link (generates distance values from the
# surface of the shape with negative values being inside)
# based on https://iquilezles.org/articles/distfunctions/ "Link"
# (x,y,z) sample position, length between ends, shape radius, tube radius
function sdf(x, y, z, le, r1, r2)
    x, y, z = Vec3f(x, max(abs(y) - le, 0.0), z);
    return norm(Vec2f(sqrt(x*x + y*y) - r1, z)) - r2;
end

r = range(-5, 5, length=31)
data = map([(x,y,z) for x in r, y in r, z in r]) do (x,y,z)
    r = max(-sdf(x,y,z, 1.5, 2, 1), 0)
    g = max(-sdf(y,z,x, 1.5, 2, 1), 0)
    b = max(-sdf(z,x,y, 1.5, 2, 1), 0)
    # RGBAf(1+r, 1+g, 1+b, max(r, g, b) - 0.1)
    RGBAf(r, g, b, max(r, g, b))
end

f = Figure(backgroundcolor = :black, size = (700, 400))
volume(f[1, 1], data, algorithm = :absorptionrgba, absorption = 10)
volume(f[1, 2], data, algorithm = :additive, absorption = 10)
f

Indexing Algorithms (:indexedabsorption)

Indexing Algorithms interpret the value read from volume data as an index into the colormap. So effectively it reads idx = round(Int, get(data, sample_pos)) and uses colormap[idx] as the color of the sample. Note that you can still use float data here, and without interpolate = false it will be interpolated.

using GLMakie
r = -5:5
data = map([(x,y,z) for x in r, y in r, z in r]) do (x,y,z)
    1 + min(abs(x), abs(y), abs(z))
end
colormap = [:red, :transparent, :transparent, RGBAf(0,1,0,0.5), :transparent, :blue]
volume(data, algorithm = :indexedabsorption, colormap = colormap,
    interpolate = false, absorption = 5)

Attributes

absorption

Defaults to 1.0

Absorption is a scaling multiplier for the density (alpha) values sampled by algorithm = :absorption, :absorptionrgba and :indexedabsorption. Increasing it will increase the light absorbed by each sample. It is also used with additive as scaling prefactor for samples.

algorithm

Defaults to :mip

Sets the volume algorithm that is used.

algorithm = :iso

Shows the surface where each volume data sample matches isovalue with a tolerance of ±isorange. This algorithm expects float data.

algorithm = :mip

Shows the maximum intensity projection of the given float volume data. This derives the color of each pixel from the largest value sampled along the respective ray.

algorithm = :absorption

:absorption may be thought of as a simple cloud or smoke rendering algorithm. This version uses float volume data to sample the colormap. The resulting RGBA color defines smoke/cloud color with the RGB component and the particle density with the alpha component. The absorption attribute can be used to globally scale the particle density.

More specifically, the algorithm does the following. For each pixel a light ray is generated from the viewer/camera, which samples the volume front to back. Each sample acquires a color (RGB) and particle density (alpha) as explained above. The particle density is weighted by the ray step size and absorption to define the fraction of light that is reflected. A proportional amount of the sampled color is then added to the pixels color and the light intensity is reduced accordingly.

Note that this is very simplified compared to reality. The algorithm does not consider the scene-set light source(s), changes in light color or any scattering beyond total reflection.

algorithm = :absorptionrgba

This algorithm skips the colormapping and instead directly samples colors (RGB) and particle densities (alpha) from RGBA volume data. Beyond that, the algorithm behaves the same as :absorption.

algorithm = :indexedabsorption

This algorithm replaces the float based colormapping of :absorption with direct indexing of the colormap.

algorithm = :additive

Accumulates colors along ray using accumulated_color = 1 - (1 - accumulated_color) * (1 - sampled_color) where sampled_color is a sample of volume data at the current ray step. absorption may be used to scale all sampled_color values. This algorithm expects RGBA volume data.

Note that this algorithm can compute colors beyond RGBA(1,1,1,1). These will then appear white. To fix this, try setting absorption to a value between 0 and 1 to scale down the intensity. If the intensity is too low the render will become dark or transparent. It might be helpful to do this on a dark background.

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 @inherit clip_planes 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[].

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, Makie.Symlog10, Makie.AsinhScale, Makie.SinhScale, Makie.LogScale, Makie.LuptonAsinhScale, and Makie.PowerScale.

depth_shift

Defaults to 0.0

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

diffuse

Defaults to 1.0

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

enable_depth

Defaults to true

Enables more accurate but slower depth handling. When turned off depth is based on the back vertices of the bounding box of the volume. When turned on it is based on the ray start point in front of the camera. For algorithm = :iso (and contours) it is based on the front most surface rendered.

fxaa

Defaults to true

Adjusts whether the plot is rendered with fxaa (fast approximate anti-aliasing, GLMakie only). Note that some plots implement a better native anti-aliasing solution (scatter, text, lines). For them fxaa = true generally lowers quality. Plots that show smoothly interpolated data (e.g. image, surface) may also degrade in quality as fxaa = true can cause blurring.

highclip

Defaults to automatic

The color for any value above the colorrange.

inspectable

Defaults to @inherit inspectable

Sets whether this plot should be seen by DataInspector. The default depends on the theme of the parent scene.

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 true

Sets whether the volume data should be sampled with interpolation.

isorange

Defaults to 0.05

Sets the maximum accepted distance from the isovalue for the :iso algorithm. accepted = isovalue - isorange < value < isovalue + isorange

isovalue

Defaults to 0.5

Sets the target value for the :iso algorithm. accepted = isovalue - isorange < value < isovalue + isorange

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

samples

Defaults to 200

Sets how many samples are taken along each ray through the volume.

shading

Defaults to true

Controls if the plot object is shaded by the parent scenes lights or not. The lighting algorithm used is controlled by the scenes shading attribute.

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

Controls the inheritance or directly sets the transformations of a plot. Transformations include the transform function and model matrix as generated by translate!(...), scale!(...) and rotate!(...). They can be set directly by passing a Transformation() object or inherited from the parent plot or scene. Inheritance options include:

• :automatic: Inherit transformations if the parent and child space is compatible

• :inherit: Inherit transformations

• :inherit_model: Inherit only model transformations

• :inherit_transform_func: Inherit only the transform function

• :nothing: Inherit neither, fully disconnecting the child's transformations from the parent

Another option is to pass arguments to the transform!() function which then get applied to the plot. For example transformation = (:xz, 1.0) which rotates the xy plane to the xz plane and translates by 1.0. For this inheritance defaults to :automatic but can also be set through e.g. (:nothing, (:xz, 1.0)).

transparency

Defaults to false

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

visible

Defaults to true

Controls whether the plot gets rendered or not.