rayrender (version 0.42.0)

homogeneous_medium: Homogeneous Participating Medium

Description

Describe a medium independently of the surface that contains it. Attach it to closed objects with [set_medium()]. Rendering automatically selects integrator_type = "nee" for scenes containing attached media.

Usage

homogeneous_medium(
  sigma_a = 0,
  sigma_s = 1,
  density_scale = 1,
  g = 0,
  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

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.

emission

Default `0`. Nonnegative scalar or RGB emitted radiance `Le`. Color names are also accepted. The volume source is `sigma_a * Le`.

temperature

Default `NULL`. Blackbody temperature in kelvin. 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 (FALSE) { # interactive() || identical(Sys.getenv("IN_PKGDOWN"), "true")
fog = homogeneous_medium(sigma_s = 5, g = 0.65)
scene = set_medium(cube(width=1.2), fog) |>
add_object(sphere(y=1,x=1,radius=0.3,material=light(intensity=20))) |>
add_object(generate_studio(material=diffuse(color="dodgerblue")	))
render_scene(scene, integrator_type = "nee", sample_method="sobol")

# Foggy cornell box
fog = homogeneous_medium(sigma_s = 0.1, sigma_a = 0.1, g = 0, density_scale = 0.01, temperature = 0)
 scene = generate_cornell(
 lightwidth = 10,
 lightdepth = 10,
 lightintensity = 3000
) |>
 add_object(set_medium(
   cube(x = 555 / 2, y = 555 / 2, z = 555 / 2, width = 554),
   fog
 ))
render_scene(
 scene,
 integrator_type = "nee",
 fov = 40,
 samples = 256
)
}