dymokomi/luce-geocore
Source of release 0.7.5
0.7.5 / src / splats / lighting.lucb
## Splat lighting: Delight GSplats and Relight GSplats' kernels, after
## Houdini 22's Labs Delight GSplats and Labs Relight GSplats.
##
## A captured splat's color is its material lit by the capture's light.
## Delight estimates that light per splat and divides it out, writing
## `albedo`; Relight lights `albedo` again with a scene's lights and bakes
## the result into `Cd` and the `sh` bands, so every renderer (the viewport
## and luce-render, which treat splats as emitters of their captured color)
## shows the new light.
##
## Delight, per splat:
## 1. Illumination: its luminance blurred over its nearest neighbors (at
## most 16 within the radius) by a bilateral filter: a Gaussian of the
## distance (the spatial falloff, as a fraction of the radius) times a
## Gaussian of the chromaticity difference (edge preservation, scaled by
## the chroma influence), so light is averaged within a material and not
## across its edges. Opacity weighs each neighbor; the splat counts too.
## 2. Ambient occlusion (with `N`): the share of neighbors within the AO
## radius in front of the splat's surface, weighted by how far in front;
## it darkens the illumination estimate by the AO amount, so occluded
## splats are brightened when the light is divided out, and the crevice
## lift brightens them further.
## 3. Albedo: Cd times (the median illumination over its own)^amount, so the
## mean brightness stays, then white balance (each channel's mean pulled
## toward their gray), exposure (stops), gamma and saturation.
##
## Relight, per splat, the outgoing radiance toward each of 128 directions on
## the sphere (a Fibonacci set), projected on the SH bands of the chosen
## degree in the cloud's color encoding (as the splat stores them), with `Cd`
## from the mean (the DC term) and `restorient` set to `orient` so the bands
## are in world directions. The radiance is, over the lights:
## - diffuse: albedo (1 - metalness) / π · E · the wrapped cosine;
## - specular: the specular weight · GGX (Trowbridge-Reitz with Smith's
## shadowing) · Schlick's Fresnel from F0 = 0.04 (glass, plastic), toward
## the albedo by metalness;
## - plus `emission` (times `emission_color` when present).
## E is the light's irradiance perpendicular to it, times its visibility (the
## caller's, e.g. shadows through the splats' density); a dome adds its
## radiance as unoccluded ambient light. A splat's normal is `N`, else its
## shortest axis, lit from either side. `roughness`, `metalness` and
## `specular` point attributes override the options.
## What Delight GSplats does.
pub struct DelightOptions:
## 0 keeps Cd, 1 divides the estimated light out entirely.
pub let amount: f64
## How far neighbors are looked for (0: four times the median largest σ).
pub let radius: f64
## Neighbors per splat (1..16).
pub let points: usize
## The spatial Gaussian's σ as a fraction of the radius.
pub let spatial: f64
## The chromaticity Gaussian's σ.
pub let edge: f64
## How much chromaticity differences count (0: a plain spatial blur).
pub let chroma: f64
pub let ao_amount: f64
## 0: the radius.
pub let ao_radius: f64
pub let crevice_lift: f64
## 0..1: how far each channel's mean moves to their gray.
pub let white_balance: f64
pub let exposure: f64
pub let gamma: f64
pub let saturation: f64
## Most neighbors a search keeps (PointHash.nearest's).
let lighting_neighbors: usize = 16
struct DelightWork:
var points: const Float3[]
var color: Floats
var alpha: Floats
var normal: Floats
var options: const DelightOptions*?
var radius: f64
var ao_radius: f64
var hash: const PointHash*?
## Per splat: luminance, chromaticity, the illumination estimate, occlusion.
var luminance: f64[]
var chroma: Vector3[]
var light: f64[]
var occlusion: f64[]
## Rec.709 luminance of linear RGB.
func rec709_luminance(c: Vector3) -> f64:
return 0.2126 * c.x + 0.7152 * c.y + 0.0722 * c.z
## Each splat's albedo (linear RGB, three f32 a point) into `out`, from a
## splat cloud's `points` and point attributes `store`.
pub func delit_albedo(points: const Float3[], store: const AttributeStore*, options: const DelightOptions*, out: f32[]) -> !:
let count = points.length
if count == 0: return
var work: DelightWork
work.points = points
let color = float_attribute(store, color_name, 3)
work.color = Floats.of(store.entry((usize)color)) if color >= 0 else Floats.empty()
let alpha = float_attribute(store, opacity_name, 1)
work.alpha = Floats.of(store.entry((usize)alpha)) if alpha >= 0 else Floats.empty()
let normal = float_attribute(store, "N", 3)
work.normal = Floats.of(store.entry((usize)normal)) if normal >= 0 else Floats.empty()
work.options = options
var radius = options.radius
if not (radius > 0.0):
var sizes = Floats.of(store.entry((usize)float_attribute(store, scale_name, 3)))
radius = 4.0 * (try median_largest(&sizes, count))
if not (radius > 0.0): radius = 3.0 * mean_spacing(points)
work.radius = radius
work.ao_radius = options.ao_radius if options.ao_radius > 0.0 else radius
work.luminance = try new f64[count] --- in memory.heap
defer free(work.luminance) in memory.heap
work.chroma = try new Vector3[count] --- in memory.heap
defer free(work.chroma) in memory.heap
work.light = try new f64[count] --- in memory.heap
defer free(work.light) in memory.heap
work.occlusion = try new f64[count] --- in memory.heap
defer free(work.occlusion) in memory.heap
work.hash = none
var hash = try PointHash.for_radius(points, math.max(radius, work.ao_radius) if radius > 0.0 else 1.0)
defer hash.close()
if radius > 0.0: work.hash = &hash
ranges.each_range(count, 8192, (void*)&work, delight_color_range)
ranges.each_range(count, 2048, (void*)&work, delight_light_range)
# The median illumination is what the albedo keeps of the brightness.
let sorted = try new f64[count] --- in memory.heap
defer free(sorted) in memory.heap
for at in 0..<count: sorted[at] = work.light[at]
let middle = selected(sorted, count // 2)
let amount = math.clamp(options.amount, 0.0, 1.0)
let ao = math.clamp(options.ao_amount, 0.0, 1.0)
var sum = Vector3()
for at in 0..<count:
let lit = math.max(work.light[at] * (1.0 - ao * work.occlusion[at]), 1.0e-6)
let gain = math.pow(math.max(middle, 1.0e-6) / lit, amount) * (1.0 + math.max(options.crevice_lift, 0.0) * work.occlusion[at])
let c = color_at(&work.color, at).multiply_scalar(gain)
for k in 0..<(usize)3:
let channel = c.x if k == 0 else (c.y if k == 1 else c.z)
out[at * 3 + k] = (f32)channel
sum = sum.add(c)
# White balance: each channel's mean toward the means' gray.
let mean = sum.multiply_scalar(1.0 / (f64)count)
let gray = (mean.x + mean.y + mean.z) / 3.0
let balance = math.clamp(options.white_balance, 0.0, 1.0)
var gains: f64[3] = [1.0, 1.0, 1.0]
let means: f64[3] = [mean.x, mean.y, mean.z]
for k in 0..<(usize)3:
if means[k] > 0.0: gains[k] = 1.0 + balance * (gray / means[k] - 1.0)
let exposure = math.exp2(options.exposure)
let gamma = options.gamma if options.gamma > 0.0 else 1.0
for at in 0..<count:
var c = Vector3((f64)out[at * 3] * gains[0], (f64)out[at * 3 + 1] * gains[1], (f64)out[at * 3 + 2] * gains[2]).multiply_scalar(exposure)
c = Vector3(math.pow(math.max(c.x, 0.0), 1.0 / gamma), math.pow(math.max(c.y, 0.0), 1.0 / gamma), math.pow(math.max(c.z, 0.0), 1.0 / gamma))
let y = rec709_luminance(c)
let s = math.max(options.saturation, 0.0)
c = Vector3(y + s * (c.x - y), y + s * (c.y - y), y + s * (c.z - y))
out[at * 3] = (f32)math.max(c.x, 0.0)
out[at * 3 + 1] = (f32)math.max(c.y, 0.0)
out[at * 3 + 2] = (f32)math.max(c.z, 0.0)
func color_at(color: const Floats*, at: usize) -> Vector3:
if not color.present(): return Vector3(0.5, 0.5, 0.5)
return Vector3(math.max(color.at(at, 0), 0.0), math.max(color.at(at, 1), 0.0), math.max(color.at(at, 2), 0.0))
## Luminance and chromaticity.
func delight_color_range(context: void*, first: usize, end: usize, worker: usize):
_ = worker
let work = (DelightWork*)context
for at in first..<end:
let c = color_at(&work.color, at)
work.luminance[at] = rec709_luminance(c)
let total = c.x + c.y + c.z
work.chroma[at] = c.multiply_scalar(1.0 / total) if total > 1.0e-9 else Vector3(1.0 / 3.0, 1.0 / 3.0, 1.0 / 3.0)
## The bilateral illumination estimate and the occlusion.
func delight_light_range(context: void*, first: usize, end: usize, worker: usize):
_ = worker
let work = (DelightWork*)context
let options = work.options else return
let k = (usize)math.clamp((f64)options.points, 1.0, (f64)lighting_neighbors)
let spatial = math.max(options.spatial, 1.0e-3) * work.radius
let edge = math.max(options.edge, 1.0e-4)
let chroma = math.max(options.chroma, 0.0)
var list: u32[16]
for at in first..<end:
let p = work.points[at].vector()
var lit = work.luminance[at]
var weight: f64 = 1.0
var occluded: f64 = 0.0
var found: usize = 0
if let hash = work.hash:
found = hash.nearest(at, k, math.max(work.radius, work.ao_radius), list[..<k])
let n = Vector3(work.normal.at(at, 0), work.normal.at(at, 1), work.normal.at(at, 2)) if work.normal.present() else Vector3()
let has_normal = n.length() > 0.5
for index in 0..<found:
let other = (usize)list[index]
let d = work.points[other].vector().subtract(p)
let distance = d.length()
if distance <= work.radius:
let dc = work.chroma[other].subtract(work.chroma[at])
let w = math.exp(-0.5 * distance * distance / (spatial * spatial)) * math.exp(-0.5 * chroma * dc.dot(dc) / (edge * edge))
let a = math.clamp(work.alpha.at(other, 0), 0.0, 1.0) if work.alpha.present() else 1.0
lit += w * a * work.luminance[other]
weight += w * a
if has_normal and distance > 0.0 and distance <= work.ao_radius:
occluded += math.max(n.dot(d) / distance, 0.0) * (1.0 - distance / work.ao_radius)
work.light[at] = lit / weight
work.occlusion[at] = math.clamp(occluded / (f64)math.max((f64)found, 1.0) * 2.0, 0.0, 1.0) if found > 0 else 0.0
## A light as Relight GSplats sees it.
pub enum SplatLightKind as u8:
## A direction: `direction` toward the light, `radiance` its irradiance.
distant = 0
## A small source at `position`: rect, disk or sphere.
local = 1
## Uniform radiance from every direction.
dome = 2
pub struct SplatLight:
pub let kind: SplatLightKind
pub let position: Vector3
## Distant: toward the light. Local: the axis it emits along (one-sided
## when `one_sided`).
pub let direction: Vector3
## Linear RGB radiance (a distant light's: its irradiance).
pub let radiance: Vector3
## A local light's emitting area as seen head on (π r² for a sphere).
pub let area: f64
pub let one_sided: bool
## What Relight GSplats does.
pub struct RelightOptions:
## The SH degree written (0..3).
pub let degree: usize
pub let roughness: f64
pub let metalness: f64
## The specular lobe's weight (OpenPBR's specular_weight).
pub let specular: f64
## Light wraps past the terminator by this much (0..1).
pub let wrap: f64
## 0 lights by the normal, 1 as if from every side equally.
pub let softness: f64
## Directions each splat's radiance is sampled toward for the projection.
let relight_directions: usize = 128
struct RelightWork:
var points: const Float3[]
var origin: Vector3
var albedo: Floats
var normal: Floats
var orient: Floats
var scale: Floats
var roughness: Floats
var metalness: Floats
var specular: Floats
var emission: Floats
var emission_color: Floats
var lights: const SplatLight[]
var visibility: const f32[]
var options: const RelightOptions*?
var space: ColorSpace
var directions: Vector3[]
## The basis values at each direction (16 a direction).
var basis: f64[]
var items: usize
var colors: f32[]
var sh: f32[]
## `store` (a splat cloud's `count` point attributes; `points` relative to
## `origin`) relit by `lights`: Cd, `sh` of the options' degree and
## restorient = orient written, the rest kept. `visibility` holds each
## splat's visibility of each light (splat-major), or nothing (all visible).
pub func relit_store(points: const Float3[], origin: Vector3, store: const AttributeStore*, lights: const SplatLight[], visibility: const f32[],
options: const RelightOptions*, space: ColorSpace) -> AttributeStore!:
let count = points.length
var work: RelightWork
work.points = points
work.origin = origin
work.albedo = floats_or_empty(store, "albedo", 3)
if not work.albedo.present(): work.albedo = floats_or_empty(store, color_name, 3)
work.normal = floats_or_empty(store, "N", 3)
work.orient = floats_or_empty(store, orient_name, 4)
work.scale = floats_or_empty(store, scale_name, 3)
work.roughness = floats_or_empty(store, "roughness", 1)
work.metalness = floats_or_empty(store, "metalness", 1)
work.specular = floats_or_empty(store, "specular", 1)
work.emission = floats_or_empty(store, "emission", 1)
work.emission_color = floats_or_empty(store, "emission_color", 3)
work.lights = lights
work.visibility = visibility
work.options = options
work.space = space
let degree = options.degree if options.degree < 3 else 3
work.items = (degree + 1) * (degree + 1) - 1
work.directions = try new Vector3[relight_directions] --- in memory.heap
defer free(work.directions) in memory.heap
work.basis = try new f64[relight_directions * 16] --- in memory.heap
defer free(work.basis) in memory.heap
# A Fibonacci sphere: near-uniform directions of equal weight.
let golden = math.pi * (3.0 - math.sqrt(5.0))
for k in 0..<relight_directions:
let z = 1.0 - (2.0 * (f64)k + 1.0) / (f64)relight_directions
let r = math.sqrt(math.max(1.0 - z * z, 0.0))
let d = Vector3(r * math.cos(golden * (f64)k), r * math.sin(golden * (f64)k), z)
work.directions[k] = d
sh_basis(d, work.basis[k * 16..<(k + 1) * 16])
var color = try Attribute.create(color_name, Domain.point, DataType.float32, 3, count)
defer color.release()
work.colors = float32_values(&color)
var offsets = try Column[u8].allocate((count + 1) * 4)
defer offsets.release()
let bounds = u32[]((u32*)offsets.span().data, count + 1)
for at in 0..<count + 1: bounds[at] = (u32)(at * work.items)
var values = try Column[u8].allocate(count * work.items * 12)
defer values.release()
work.sh = f32[]((f32*)values.span().data, count * work.items * 3)
ranges.each_range(count, 1024, (void*)&work, relight_range)
var result = try store.shared()
errdefer result.close()
try result.put(color.share())
try result.put(try Attribute.ragged(sh_name, Domain.point, DataType.float32, 3, offsets.share(), values.share()))
let orient = float_attribute(store, orient_name, 4)
if orient >= 0:
var rest = try store.entry((usize)orient).renamed(restorient_name)
defer rest.release()
try result.put(rest.share())
return result
func floats_or_empty(store: const AttributeStore*, name: str, width: usize) -> Floats:
return point_floats(store, name, width) else Floats.empty()
## GGX's normal distribution at cos θh = `nh` for α = roughness².
func ggx(nh: f64, alpha: f64) -> f64:
let a2 = alpha * alpha
let d = nh * nh * (a2 - 1.0) + 1.0
return a2 / (math.pi * d * d)
## Smith's shadowing-masking for one direction at cos `c`.
func smith(c: f64, alpha: f64) -> f64:
let a2 = alpha * alpha
return 2.0 * c / (c + math.sqrt(a2 + (1.0 - a2) * c * c))
func relight_range(context: void*, first: usize, end: usize, worker: usize):
_ = worker
let work = (RelightWork*)context
let options = work.options else return
let lights = work.lights.length
for at in first..<end:
let p = work.points[at].vector().add(work.origin)
let albedo = color_at(&work.albedo, at)
# The normal: N, else the shortest axis lit from either side.
var n = Vector3(work.normal.at(at, 0), work.normal.at(at, 1), work.normal.at(at, 2)) if work.normal.present() else Vector3()
let two_sided = n.length() < 0.5
if two_sided:
let q = Quat(work.orient.at(at, 0), work.orient.at(at, 1), work.orient.at(at, 2), work.orient.at(at, 3)).normalized()
let sx = math.abs(work.scale.at(at, 0))
let sy = math.abs(work.scale.at(at, 1))
let sz = math.abs(work.scale.at(at, 2))
var column: usize = 2
if sx <= sy and sx <= sz: column = 0
elif sy <= sz: column = 1
n = q.matrix().column(column)
n = unit_or(n, Vector3(0.0, 1.0, 0.0))
let roughness = math.clamp(work.roughness.at(at, 0) if work.roughness.present() else options.roughness, 0.02, 1.0)
let alpha = roughness * roughness
let metal = math.clamp(work.metalness.at(at, 0) if work.metalness.present() else options.metalness, 0.0, 1.0)
let specular = math.max(work.specular.at(at, 0) if work.specular.present() else options.specular, 0.0)
let f0 = Vector3(0.04, 0.04, 0.04).multiply_scalar(1.0 - metal).add(albedo.multiply_scalar(metal))
var emitted = Vector3()
if work.emission.present():
let tint = Vector3(work.emission_color.at(at, 0), work.emission_color.at(at, 1), work.emission_color.at(at, 2)) if work.emission_color.present() else Vector3(1.0, 1.0, 1.0)
emitted = tint.multiply_scalar(work.emission.at(at, 0))
# Each light's direction (toward it), irradiance and diffuse term.
var toward: Vector3[8] = [Vector3(), Vector3(), Vector3(), Vector3(), Vector3(), Vector3(), Vector3(), Vector3()]
var irradiance: Vector3[8] = [Vector3(), Vector3(), Vector3(), Vector3(), Vector3(), Vector3(), Vector3(), Vector3()]
var diffuse = emitted
var ambient = Vector3()
let used = lights if lights < 8 else 8
for index in 0..<used:
let light = work.lights[index]
let seen = (f64)work.visibility[at * lights + index] if work.visibility.length > 0 else 1.0
var l = light.direction
var e = light.radiance.multiply_scalar(seen)
if light.kind == SplatLightKind.dome:
ambient = ambient.add(light.radiance)
toward[index] = Vector3()
irradiance[index] = Vector3()
continue
if light.kind == SplatLightKind.local:
let offset = light.position.subtract(p)
let d2 = math.max(offset.dot(offset), 1.0e-12)
l = offset.multiply_scalar(1.0 / math.sqrt(d2))
let facing = math.max(-light.direction.dot(l), 0.0) if light.one_sided else 1.0
e = e.multiply_scalar(light.area * facing / d2)
var cosine = n.dot(l)
if two_sided: cosine = math.abs(cosine)
let wrapped = math.max((cosine + options.wrap) / (1.0 + options.wrap), 0.0)
let term = wrapped * (1.0 - options.softness) + 0.5 * options.softness
toward[index] = l
irradiance[index] = e
diffuse = diffuse.add(Vector3(albedo.x * e.x, albedo.y * e.y, albedo.z * e.z).multiply_scalar((1.0 - metal) * term / math.pi))
diffuse = diffuse.add(Vector3(albedo.x * ambient.x, albedo.y * ambient.y, albedo.z * ambient.z).multiply_scalar(1.0 - metal))
# The radiance toward each direction, encoded, projected on the bands.
var dc = Vector3()
var coefficients: f64[45]
for k in 0..<(usize)45: coefficients[k] = 0.0
for k in 0..<relight_directions:
let v = work.directions[k]
var radiance = diffuse
let nv = math.abs(n.dot(v)) if two_sided else n.dot(v)
if nv > 0.0:
let side = n if not two_sided or n.dot(v) >= 0.0 else n.multiply_scalar(-1.0)
for index in 0..<used:
let l = toward[index]
let nl = side.dot(l)
if nl <= 0.0: continue
let h = unit_or(l.add(v), side)
let vh = math.max(v.dot(h), 0.0)
let schlick = math.pow(1.0 - vh, 5.0)
let f = f0.add(Vector3(1.0, 1.0, 1.0).subtract(f0).multiply_scalar(schlick))
let lobe = ggx(math.max(side.dot(h), 0.0), alpha) * smith(nl, alpha) * smith(nv, alpha) / (4.0 * nv)
let e = irradiance[index]
radiance = radiance.add(Vector3(f.x * e.x, f.y * e.y, f.z * e.z).multiply_scalar(lobe * specular))
radiance = radiance.add(Vector3(f0.x * ambient.x, f0.y * ambient.y, f0.z * ambient.z).multiply_scalar(specular))
let encoded = Vector3(from_linear(math.max(radiance.x, 0.0), work.space), from_linear(math.max(radiance.y, 0.0), work.space),
from_linear(math.max(radiance.z, 0.0), work.space))
dc = dc.add(encoded)
for item in 0..<work.items:
let b = work.basis[k * 16 + item + 1]
coefficients[item * 3] += b * encoded.x
coefficients[item * 3 + 1] += b * encoded.y
coefficients[item * 3 + 2] += b * encoded.z
let weight = 1.0 / (f64)relight_directions
dc = dc.multiply_scalar(weight)
work.colors[at * 3] = (f32)to_linear(dc.x, work.space)
work.colors[at * 3 + 1] = (f32)to_linear(dc.y, work.space)
work.colors[at * 3 + 2] = (f32)to_linear(dc.z, work.space)
# Orthonormal bands: c = ∫ e·Y dω ≈ 4π/N Σ e(ωₖ) Y(ωₖ).
let scale = 4.0 * math.pi * weight
for k in 0..<work.items * 3: work.sh[at * work.items * 3 + k] = (f32)(coefficients[k] * scale)