dymokomi/luce-render
Source of release 0.1.0
0.1.0 / src / render / environment.lucb
#==============================================================================================
#
# render/environment - A dome light's image, sampled by importance
#
# DESCRIPTION:
# A dome light (UsdLuxDomeLight) wraps a lat-long image around the scene: the
# image's center looks down the light's -Z, its top is +Y. Pixels are read from
# OpenEXR (luce-exr) as linear Rec.709, the convention of HDR environments, and
# turned into ACEScg. Texels are constant (no filtering), so sampling a texel in
# proportion to its luminance times sin θ (its solid angle) makes the light's
# pdf follow its radiance exactly: the kernels (shaders/lights.glsl) search the
# rows' cumulative weights, then the chosen row's.
#
# The spectral build turns a texel's ACEScg into a spectrum linearly: three
# smooth spectra that sum to the flat one (blue below ~490 nm, red above ~595,
# green between), weighted by a 3 × 3 matrix of ACEScg (basis_weights). Every
# texel then costs one matrix product, white stays flat, and colors are exact.
#
#==============================================================================================
## Linear Rec.709 (sRGB primaries, D65) to ACEScg, Bradford-adapted.
func rec709_to_acescg() -> Matrix3:
return Matrix3([0.613097, 0.339523, 0.047379,
0.070194, 0.916354, 0.013452,
0.020616, 0.109570, 0.869815])
func logistic(x: f64) -> f64:
return 1.0 / (1.0 + math.exp(-x))
## The basis spectra at `lambda` nm, as shaders/spectrum.glsl evaluates them:
## blue, green, red.
pub func basis_spectra(lambda: f64) -> Vector3:
let blue = 1.0 - logistic((lambda - 490.0) / 12.0)
let red = logistic((lambda - 595.0) / 12.0)
return Vector3(blue, 1.0 - blue - red, red)
## The matrix from ACEScg to the basis spectra's weights: the inverse of
## their colors through the film.
pub func basis_weights() -> Matrix3:
let integrals = cmf_integrals()
var columns: Vector3[3] = [Vector3(), Vector3(), Vector3()]
var lambda = lambda_min
while lambda <= lambda_max:
let b = basis_spectra(lambda)
let matching = cmf(lambda)
columns[0] = columns[0].add(matching.multiply_scalar(b.x))
columns[1] = columns[1].add(matching.multiply_scalar(b.y))
columns[2] = columns[2].add(matching.multiply_scalar(b.z))
lambda += 1.0
let film = film_matrix()
var rgb: Vector3[3] = [Vector3(), Vector3(), Vector3()]
for k in 0..<(usize)3:
let xyz = Vector3(columns[k].x / integrals.x, columns[k].y / integrals.y, columns[k].z / integrals.z)
rgb[k] = film.apply(xyz)
# Columns: blue, green, red's ACEScg.
let colors = Matrix3([rgb[0].x, rgb[1].x, rgb[2].x, rgb[0].y, rgb[1].y, rgb[2].y, rgb[0].z, rgb[1].z, rgb[2].z])
return colors.inverse()
pub struct Environment:
pub var width: usize
pub var height: usize
## Four floats a texel, rows from the top: ACEScg radiance, and its weight
## (luminance × sin θ).
pub var texels: Growing[f32]
## Each row's cumulative weights (`width` a row, ending at 1), then the
## rows' (`height`, ending at 1).
pub var cdf: Growing[f32]
## The weights' sum, and the texels' mean luminance over the sphere.
pub var total: f64
pub var average: f64
pub func init():
self.width = 0
self.height = 0
self.texels = Growing[f32]()
self.cdf = Growing[f32]()
self.total = 0.0
self.average = 0.0
pub func close():
self.texels.close()
self.cdf.close()
## The environment in image file `path` (OpenEXR, RGB or Y).
pub func load_environment(path: str) -> Environment!:
var name: str
with memory.heap:
name = try strings.copy(path)
defer:
with memory.heap: strings.release(name)
let bytes = try files.read((c.str)name)
var raster = Raster(max_pixels = 67108864)
defer raster.close()
raster.encoded = try new u8[bytes.value.length] --- in memory.heap
memory.copy(raster.encoded, bytes.value, bytes.value.length)
bytes.release()
try exr.probe(&raster)
try raster.allocate()
for chunk in 0..<raster.chunks.length: try exr.decode_chunk(&raster, chunk)
var channel: i64[3] = [-1, -1, -1]
var grey: i64 = -1
for at in 0..<raster.channels.length:
let n = raster.channels[at].name
if n == "R": channel[0] = (i64)at
elif n == "G": channel[1] = (i64)at
elif n == "B": channel[2] = (i64)at
elif n == "Y": grey = (i64)at
if channel[0] < 0 or channel[1] < 0 or channel[2] < 0:
if grey < 0: error(invalid, "an environment image needs R, G and B channels, or Y")
channel = [grey, grey, grey]
return try environment_of(raster.width, raster.height, raster.pixels, raster.channels.length, channel)
## An environment from `width` × `height` pixels of `stride` samples each,
## its linear Rec.709 R, G and B at `channel`.
pub func environment_of(width: usize, height: usize, pixels: const f64[], stride: usize, channel: const i64[]) -> Environment!:
var environment = Environment()
errdefer environment.close()
environment.width = width
environment.height = height
let to_acescg = rec709_to_acescg()
try environment.texels.reserve(width * height * 4)
try environment.cdf.reserve(width * height + height)
var rows = Growing[f64]()
defer rows.close()
var luminance_sum: f64 = 0.0
var solid_angle: f64 = 0.0
for y in 0..<height:
let sin_theta = math.sin(math.pi * ((f64)y + 0.5) / (f64)height)
var row: f64 = 0.0
let start = environment.cdf.count
for x in 0..<width:
let at = (y * width + x) * stride
let source = Vector3(pixels[at + (usize)channel[0]], pixels[at + (usize)channel[1]], pixels[at + (usize)channel[2]])
let raw = to_acescg.apply(source)
let rgb = Vector3(math.max(0.0, raw.x), math.max(0.0, raw.y), math.max(0.0, raw.z))
let lum = luminance(rgb)
let weight = lum * sin_theta
for value in [rgb.x, rgb.y, rgb.z, weight]: try environment.texels.push((f32)value)
row += weight
try environment.cdf.push((f32)row)
luminance_sum += lum * sin_theta
solid_angle += sin_theta
# The row's cumulative weights end at 1 (uniform across an empty row).
for x in 0..<width:
let at = start + x
environment.cdf.items[at] = (f32)((f64)environment.cdf.items[at] / row if row > 0.0 else ((f64)(x + 1) / (f64)width))
try rows.push(row)
var total: f64 = 0.0
for row in rows.view(): total += row
var running: f64 = 0.0
for y in 0..<height:
running += rows.items[y]
try environment.cdf.push((f32)(running / total if total > 0.0 else ((f64)(y + 1) / (f64)height)))
environment.total = total
environment.average = luminance_sum / solid_angle if solid_angle > 0.0 else 0.0
return environment