rayrender (version 0.42.0)

grid_medium: 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
)

Value

A reusable `ray_medium` description.

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.

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
  )
}