grid_medium: Dense Grid Participating Medium

In rayrender: Build and Raytrace 3D Scenes

Dense Grid Participating Medium

Description

Density samples are cell centered and trilinearly interpolated. Array indices correspond to x, y, z, with x varying fastest. Outside 'bounds' the medium is vacuum. Inside the bounds, interpolation clamps to the outermost samples.

Usage

grid_medium(
  density,
  sigma_a = 0,
  sigma_s = 1,
  density_scale = 1,
  g = 0,
  bounds = rbind(c(-0.5, -0.5, -0.5), c(0.5, 0.5, 0.5)),
  emission = 0,
  temperature = NULL,
  emission_scale = 1,
  temperature_scale = 1,
  temperature_offset = 0,
  medium_transform = diag(4),
  haze = TRUE,
  haze_density_threshold = NULL
)

Arguments

density	A nonnegative numeric array with dimensions 'c(nx, ny, nz)'.
sigma_a	Default '0'. Absorption coefficient, a nonnegative number or RGB vector, per world-space distance unit.
sigma_s	Default '1'. Scattering coefficient, a nonnegative number or RGB vector, per world-space distance unit.
density_scale	Default '1'. Nonnegative multiplier for both coefficients.
g	Default '0'. Henyey-Greenstein asymmetry, strictly between -1 and 1. Positive values scatter forward along the incident light direction.
bounds	Default 'rbind(c(-0.5, -0.5, -0.5), c(0.5, 0.5, 0.5))'. Two rows giving minimum and maximum medium-space coordinates.
emission	Default '0'. Scalar/RGB radiance or an array with dimensions 'c(nx, ny, nz, 3)'. The volume source is 'sigma_a * Le'.
temperature	Default 'NULL'. Scalar kelvin temperature or an array with the same dimensions as 'density'. Mutually exclusive with nonzero emission.
emission_scale	Default '1'. Nonnegative multiplier for emitted radiance.
temperature_scale	Default '1'. Nonnegative multiplier applied after subtracting 'temperature_offset' from the temperature.
temperature_offset	Default '0'. Offset subtracted from temperatures.
medium_transform	Default 'diag(4)'. Invertible affine matrix mapping medium coordinates into the containing object's local coordinates.
haze	Default 'TRUE'. Include clear-air atmospheric haze inside this medium when enabled by [sky_light()], subject to 'haze_density_threshold'. Set 'FALSE' to skip its atmospheric in-scattering and extinction throughout the entire boundary, including empty cells, regardless of the threshold. The medium's own scattering, absorption, and emission remain active. In nested media the innermost medium's setting applies; 'sky_light(haze_in_volumes = FALSE)' overrides all media. This is an approximation and may affect thin clouds, edges, or low-altitude haze.
haze_density_threshold	Default 'NULL'. With 'haze = TRUE', omit haze only where interpolated density times 'density_scale' is at least this positive number. Lower-density regions and empty space retain haze. A homogeneous medium has density one before scaling. 'NULL' includes haze throughout the boundary. Ignored with 'haze = FALSE' or global haze exclusion. The threshold measures density, not optical depth or scattering strength; choose which media to tag accordingly. Crossings follow the trilinear field, including between scattering events, and transform with the medium.

Value

A reusable 'ray_medium' description.

Examples

if (requireNamespace("ambient", quietly = TRUE)) {
  noise_field = ambient::noise_perlin(
    dim = c(24, 24, 24), frequency = 0.02, octaves = 8, gain = 0.1
  )
  noise_field[noise_field < 0] = 0
  smoke = grid_medium(noise_field, g = 0.2, sigma_a = 10)
  scene = set_medium(cube(), smoke) |>
    add_object(sphere(x = 3, material = light(intensity = 10)))
  render_scene(
    scene, integrator_type = "nee", width = 64, height = 64,
    samples = 4, parallel = FALSE, plot_scene = FALSE
  )
}

rayrender documentation built on Sept. 16, 2026, 9:08 a.m.