use rayon::prelude::*;
use super::types::{
RayMarchResult, TransferFunction, VolumeGrid, VolumetricCamera, VolumetricIntegration,
VolumetricRay, VolumetricRenderConfig, VolumetricRenderError, VolumetricStats,
};
pub fn vr_gaussians_to_volume(
positions: &[f32],
scales: &[f32],
opacities: &[f32],
n_gaussians: usize,
grid: &mut VolumeGrid,
) -> Result<(), VolumetricRenderError> {
if positions.len() != n_gaussians * 3 {
return Err(VolumetricRenderError::BufferLengthMismatch {
field: "positions",
expected: n_gaussians * 3,
got: positions.len(),
});
}
if scales.len() != n_gaussians * 3 {
return Err(VolumetricRenderError::BufferLengthMismatch {
field: "scales",
expected: n_gaussians * 3,
got: scales.len(),
});
}
if opacities.len() != n_gaussians {
return Err(VolumetricRenderError::BufferLengthMismatch {
field: "opacities",
expected: n_gaussians,
got: opacities.len(),
});
}
if grid.is_empty() {
return Ok(());
}
let nx = grid.nx;
let ny = grid.ny;
let nz = grid.nz;
for g in 0..n_gaussians {
let gx = positions[g * 3];
let gy = positions[g * 3 + 1];
let gz = positions[g * 3 + 2];
let sigma = (scales[g * 3] + scales[g * 3 + 1] + scales[g * 3 + 2]) / 3.0;
let sigma = sigma.max(1e-6_f32);
let opacity = opacities[g].clamp(0.0, 1.0);
let r_world = 3.0 * sigma;
let x_lo = (gx - r_world - grid.origin[0]) / grid.voxel_size[0];
let x_hi = (gx + r_world - grid.origin[0]) / grid.voxel_size[0];
let y_lo = (gy - r_world - grid.origin[1]) / grid.voxel_size[1];
let y_hi = (gy + r_world - grid.origin[1]) / grid.voxel_size[1];
let z_lo = (gz - r_world - grid.origin[2]) / grid.voxel_size[2];
let z_hi = (gz + r_world - grid.origin[2]) / grid.voxel_size[2];
let ix0 = (x_lo.floor() as i64).clamp(0, nx as i64 - 1) as usize;
let ix1 = (x_hi.ceil() as i64).clamp(0, nx as i64 - 1) as usize;
let iy0 = (y_lo.floor() as i64).clamp(0, ny as i64 - 1) as usize;
let iy1 = (y_hi.ceil() as i64).clamp(0, ny as i64 - 1) as usize;
let iz0 = (z_lo.floor() as i64).clamp(0, nz as i64 - 1) as usize;
let iz1 = (z_hi.ceil() as i64).clamp(0, nz as i64 - 1) as usize;
let inv2s2 = 0.5 / (sigma * sigma);
for iz in iz0..=iz1 {
for iy in iy0..=iy1 {
for ix in ix0..=ix1 {
let wx = grid.origin[0] + (ix as f32 + 0.5) * grid.voxel_size[0];
let wy = grid.origin[1] + (iy as f32 + 0.5) * grid.voxel_size[1];
let wz = grid.origin[2] + (iz as f32 + 0.5) * grid.voxel_size[2];
let d2 = (wx - gx).powi(2) + (wy - gy).powi(2) + (wz - gz).powi(2);
let weight = opacity * (-d2 * inv2s2).exp();
grid.data[iz * ny * nx + iy * nx + ix] += weight;
}
}
}
}
Ok(())
}
pub fn vr_ray_aabb_intersect(ray: &VolumetricRay, grid: &VolumeGrid) -> Option<(f32, f32)> {
let min = grid.origin;
let max = [
grid.origin[0] + grid.nx as f32 * grid.voxel_size[0],
grid.origin[1] + grid.ny as f32 * grid.voxel_size[1],
grid.origin[2] + grid.nz as f32 * grid.voxel_size[2],
];
let mut t_near = f32::NEG_INFINITY;
let mut t_far = f32::INFINITY;
for i in 0..3 {
let d = ray.direction[i];
let o = ray.origin[i];
if d.abs() < f32::EPSILON {
if o < min[i] || o > max[i] {
return None;
}
} else {
let t1 = (min[i] - o) / d;
let t2 = (max[i] - o) / d;
let (tlo, thi) = if t1 < t2 { (t1, t2) } else { (t2, t1) };
t_near = t_near.max(tlo);
t_far = t_far.min(thi);
}
}
if t_near > t_far {
return None;
}
if t_far < 0.0 {
return None;
}
Some((t_near.max(0.0), t_far))
}
#[inline(always)]
fn xorshift64(state: &mut u64) -> u64 {
if *state == 0 {
*state = 1;
}
*state ^= *state << 13;
*state ^= *state >> 7;
*state ^= *state << 17;
if *state == 0 {
*state = 1;
}
*state
}
#[inline(always)]
fn xorshift64_f32(state: &mut u64) -> f32 {
let v = xorshift64(state);
(v as f32) / (u64::MAX as f32 + 1.0)
}
pub fn vr_march_ray(
ray: &VolumetricRay,
volume: &VolumeGrid,
tf: &TransferFunction,
config: &VolumetricRenderConfig,
) -> RayMarchResult {
vr_march_ray_impl(ray, volume, tf, config, None)
}
pub fn vr_march_ray_with_occupancy(
ray: &VolumetricRay,
volume: &VolumeGrid,
tf: &TransferFunction,
config: &VolumetricRenderConfig,
occupancy: &VolumeGrid,
) -> RayMarchResult {
vr_march_ray_impl(ray, volume, tf, config, Some(occupancy))
}
fn vr_march_ray_impl(
ray: &VolumetricRay,
volume: &VolumeGrid,
tf: &TransferFunction,
config: &VolumetricRenderConfig,
occupancy: Option<&VolumeGrid>,
) -> RayMarchResult {
let Some((t_entry, t_exit)) = vr_ray_aabb_intersect(ray, volume) else {
return RayMarchResult::default();
};
let step = config.step_size;
let mut prng = config.jitter_seed;
if prng == 0 {
prng = 1;
}
let jitter_offset = if config.jitter {
xorshift64_f32(&mut prng) * step
} else {
0.0
};
let span = MarchSpan {
t_start: t_entry + jitter_offset,
t_exit,
t_entry,
step,
};
let integration = config.integration;
match integration {
VolumetricIntegration::FrontToBack => {
vr_march_front_to_back(ray, volume, tf, config, span, occupancy)
}
VolumetricIntegration::BackToFront => {
vr_march_back_to_front(ray, volume, tf, config, span, occupancy)
}
VolumetricIntegration::Mip => vr_march_mip(ray, volume, tf, config, span, occupancy),
VolumetricIntegration::Avg => vr_march_avg(ray, volume, tf, config, span, occupancy),
}
}
#[derive(Debug, Clone, Copy)]
struct MarchSpan {
t_start: f32,
t_exit: f32,
t_entry: f32,
step: f32,
}
impl MarchSpan {
#[inline]
fn t_at(&self, k: usize) -> f32 {
self.t_start + (k as f32) * self.step
}
fn lattice_len(&self, max_steps: usize) -> usize {
let extent = self.t_exit - self.t_start;
if !extent.is_finite() || extent < 0.0 {
return 0;
}
let raw = (extent / self.step).floor();
let count = if raw.is_finite() {
(raw as usize).saturating_add(1)
} else {
usize::MAX
};
count.min(max_steps)
}
}
const OCCUPIED_THRESHOLD: f32 = 0.5;
fn occupancy_cell_exit_distance(occupancy: &VolumeGrid, ray: &VolumetricRay, p: [f32; 3]) -> f32 {
let dims = [occupancy.nx, occupancy.ny, occupancy.nz];
let mut best = f32::INFINITY;
for axis in 0..3 {
let vs = occupancy.voxel_size[axis];
if !vs.is_finite() || vs <= 0.0 || dims[axis] == 0 {
continue;
}
let dir = ray.direction[axis];
if dir.abs() < 1e-12 {
continue;
}
let u = (p[axis] - occupancy.origin[axis]) / vs;
let cell = (u.floor() as usize).min(dims[axis] - 1) as f32;
let bound = occupancy.origin[axis]
+ if dir > 0.0 {
(cell + 1.0) * vs
} else {
cell * vs
};
let t_axis = (bound - p[axis]) / dir;
if t_axis < best {
best = t_axis;
}
}
if best.is_finite() {
best.max(0.0)
} else {
0.0
}
}
fn occupancy_skip_target(
occupancy: &VolumeGrid,
ray: &VolumetricRay,
span: &MarchSpan,
k: usize,
) -> Option<usize> {
let t = span.t_at(k);
let p = ray.at(t);
if occupancy.sample_nearest(p[0], p[1], p[2]) >= OCCUPIED_THRESHOLD {
return None;
}
let delta = occupancy_cell_exit_distance(occupancy, ray, p);
let steps = (delta / span.step).ceil();
let steps = if steps.is_finite() && steps >= 1.0 {
steps as usize
} else {
1
};
Some(k.saturating_add(steps))
}
#[derive(Debug, Clone, Copy)]
struct EmptySample {
color: [f32; 3],
alpha_per_step: f32,
}
impl EmptySample {
fn new(tf: &TransferFunction, step: f32) -> Self {
let (color, alpha) = tf.evaluate(0.0);
let alpha = alpha.clamp(0.0, 1.0);
Self {
color,
alpha_per_step: 1.0 - (1.0 - alpha).powf(step),
}
}
#[inline]
fn is_transparent(&self) -> bool {
self.alpha_per_step <= 0.0
}
fn composite_run(
&self,
color: &mut [f32; 3],
alpha: &mut f32,
n: usize,
stop_alpha: Option<f32>,
) -> bool {
if self.is_transparent() || n == 0 {
return false;
}
let transmittance = 1.0 - *alpha;
let a = self.alpha_per_step;
let mut m = n;
let mut terminated = false;
if let Some(stop) = stop_alpha {
let remaining = (1.0 - stop).max(0.0);
if transmittance > remaining {
let base = 1.0 - a;
if base <= 0.0 {
m = 1;
terminated = true;
} else {
let needed = ((remaining / transmittance).ln() / base.ln()).ceil();
if needed.is_finite() && needed >= 0.0 && (needed as usize) <= n {
m = (needed as usize).max(1);
terminated = true;
}
}
} else {
return true;
}
}
let survive = (1.0 - a).powi(m.min(i32::MAX as usize) as i32);
let gained = transmittance * (1.0 - survive);
color[0] += gained * self.color[0];
color[1] += gained * self.color[1];
color[2] += gained * self.color[2];
*alpha += gained;
terminated
}
}
fn vr_march_front_to_back(
ray: &VolumetricRay,
volume: &VolumeGrid,
tf: &TransferFunction,
config: &VolumetricRenderConfig,
span: MarchSpan,
occupancy: Option<&VolumeGrid>,
) -> RayMarchResult {
let mut color = [0.0_f32; 3];
let mut alpha = 0.0_f32;
let mut n_steps = 0usize;
let lattice_len = span.lattice_len(config.max_steps);
let empty = EmptySample::new(tf, config.step_size);
let mut k = 0usize;
while k < lattice_len {
if let Some(occ) = occupancy {
if let Some(k_next) = occupancy_skip_target(occ, ray, &span, k) {
let skipped = k_next.min(lattice_len) - k;
let terminated = empty.composite_run(
&mut color,
&mut alpha,
skipped,
Some(config.early_termination_alpha),
);
k = k_next;
if terminated {
break;
}
continue;
}
}
let p = ray.at(span.t_at(k));
let density = volume.sample_trilinear(p[0], p[1], p[2]);
let (s_color, s_alpha) = tf.evaluate(density);
let s_alpha = s_alpha.clamp(0.0, 1.0);
let s_alpha = 1.0 - (1.0 - s_alpha).powf(config.step_size);
let contrib = (1.0 - alpha) * s_alpha;
color[0] += contrib * s_color[0];
color[1] += contrib * s_color[1];
color[2] += contrib * s_color[2];
alpha += contrib;
n_steps += 1;
if alpha >= config.early_termination_alpha {
break;
}
k += 1;
}
RayMarchResult {
color,
alpha,
n_steps,
t_entry: span.t_entry,
t_exit: span.t_exit,
}
}
fn vr_march_back_to_front(
ray: &VolumetricRay,
volume: &VolumeGrid,
tf: &TransferFunction,
config: &VolumetricRenderConfig,
span: MarchSpan,
occupancy: Option<&VolumeGrid>,
) -> RayMarchResult {
let mut color = [0.0_f32; 3];
let mut alpha = 0.0_f32;
let mut n_steps = 0usize;
let lattice_len = span.lattice_len(config.max_steps);
let empty = EmptySample::new(tf, config.step_size);
let mut k = 0usize;
while k < lattice_len {
if let Some(occ) = occupancy {
if let Some(k_next) = occupancy_skip_target(occ, ray, &span, k) {
let skipped = k_next.min(lattice_len) - k;
empty.composite_run(&mut color, &mut alpha, skipped, None);
k = k_next;
continue;
}
}
let p = ray.at(span.t_at(k));
let density = volume.sample_trilinear(p[0], p[1], p[2]);
let (s_color, s_alpha) = tf.evaluate(density);
let s_alpha = s_alpha.clamp(0.0, 1.0);
let s_alpha = 1.0 - (1.0 - s_alpha).powf(config.step_size);
let contrib = (1.0 - alpha) * s_alpha;
color[0] += contrib * s_color[0];
color[1] += contrib * s_color[1];
color[2] += contrib * s_color[2];
alpha += contrib;
n_steps += 1;
k += 1;
}
RayMarchResult {
color,
alpha,
n_steps,
t_entry: span.t_entry,
t_exit: span.t_exit,
}
}
fn vr_march_mip(
ray: &VolumetricRay,
volume: &VolumeGrid,
tf: &TransferFunction,
config: &VolumetricRenderConfig,
span: MarchSpan,
occupancy: Option<&VolumeGrid>,
) -> RayMarchResult {
let mut max_density = 0.0_f32;
let lattice_len = span.lattice_len(config.max_steps);
let mut n_steps = 0usize;
let mut k = 0usize;
while k < lattice_len {
if let Some(occ) = occupancy {
if let Some(k_next) = occupancy_skip_target(occ, ray, &span, k) {
k = k_next;
continue;
}
}
let p = ray.at(span.t_at(k));
let density = volume.sample_trilinear(p[0], p[1], p[2]);
if density > max_density {
max_density = density;
}
n_steps += 1;
k += 1;
}
let (color, alpha) = tf.evaluate(max_density);
RayMarchResult {
color,
alpha,
n_steps,
t_entry: span.t_entry,
t_exit: span.t_exit,
}
}
fn vr_march_avg(
ray: &VolumetricRay,
volume: &VolumeGrid,
tf: &TransferFunction,
config: &VolumetricRenderConfig,
span: MarchSpan,
occupancy: Option<&VolumeGrid>,
) -> RayMarchResult {
let mut sum_color = [0.0_f32; 3];
let mut sum_alpha = 0.0_f32;
let lattice_len = span.lattice_len(config.max_steps);
let (empty_color, empty_alpha) = tf.evaluate(0.0);
let mut n_steps = 0usize;
let mut n_lattice = 0usize;
let mut k = 0usize;
while k < lattice_len {
if let Some(occ) = occupancy {
if let Some(k_next) = occupancy_skip_target(occ, ray, &span, k) {
let skipped = k_next.min(lattice_len) - k;
let skipped_f = skipped as f32;
sum_color[0] += empty_color[0] * skipped_f;
sum_color[1] += empty_color[1] * skipped_f;
sum_color[2] += empty_color[2] * skipped_f;
sum_alpha += empty_alpha * skipped_f;
n_lattice += skipped;
k = k_next;
continue;
}
}
let p = ray.at(span.t_at(k));
let density = volume.sample_trilinear(p[0], p[1], p[2]);
let (s_color, s_alpha) = tf.evaluate(density);
sum_color[0] += s_color[0];
sum_color[1] += s_color[1];
sum_color[2] += s_color[2];
sum_alpha += s_alpha;
n_steps += 1;
n_lattice += 1;
k += 1;
}
if n_lattice == 0 {
return RayMarchResult::default();
}
let inv_n = 1.0 / n_lattice as f32;
RayMarchResult {
color: [
sum_color[0] * inv_n,
sum_color[1] * inv_n,
sum_color[2] * inv_n,
],
alpha: (sum_alpha * inv_n).clamp(0.0, 1.0),
n_steps,
t_entry: span.t_entry,
t_exit: span.t_exit,
}
}
pub fn vr_render_image(
volume: &VolumeGrid,
tf: &TransferFunction,
camera: &VolumetricCamera,
config: &VolumetricRenderConfig,
) -> Result<Vec<[f32; 4]>, VolumetricRenderError> {
vr_render_image_impl(volume, tf, camera, config, None)
}
pub fn vr_render_image_with_occupancy(
volume: &VolumeGrid,
tf: &TransferFunction,
camera: &VolumetricCamera,
config: &VolumetricRenderConfig,
occupancy: &VolumeGrid,
) -> Result<Vec<[f32; 4]>, VolumetricRenderError> {
vr_render_image_impl(volume, tf, camera, config, Some(occupancy))
}
fn vr_render_image_impl(
volume: &VolumeGrid,
tf: &TransferFunction,
camera: &VolumetricCamera,
config: &VolumetricRenderConfig,
occupancy: Option<&VolumeGrid>,
) -> Result<Vec<[f32; 4]>, VolumetricRenderError> {
if volume.nx == 0 || volume.ny == 0 || volume.nz == 0 {
return Err(VolumetricRenderError::ZeroSizeVolume {
nx: volume.nx,
ny: volume.ny,
nz: volume.nz,
});
}
if camera.width == 0 || camera.height == 0 {
return Err(VolumetricRenderError::InvalidCamera(
"width and height must be > 0".into(),
));
}
let w = camera.width as usize;
let h = camera.height as usize;
let mut out = vec![[0.0_f32; 4]; w * h];
let base_seed = config.jitter_seed;
out.par_chunks_mut(w).enumerate().for_each(|(py, row)| {
for (px, pixel) in row.iter_mut().enumerate() {
let mut pixel_config = config.clone();
if config.jitter {
let mut s = base_seed ^ ((py as u64).wrapping_mul(0x_9e37_79b9) ^ px as u64);
if s == 0 {
s = 1;
}
pixel_config.jitter_seed = s;
}
let ray = camera.generate_ray(px as f32, py as f32);
let result = vr_march_ray_impl(&ray, volume, tf, &pixel_config, occupancy);
*pixel = [
result.color[0],
result.color[1],
result.color[2],
result.alpha,
];
}
});
Ok(out)
}
pub fn vr_render_image_u8(
volume: &VolumeGrid,
tf: &TransferFunction,
camera: &VolumetricCamera,
config: &VolumetricRenderConfig,
) -> Result<Vec<u8>, VolumetricRenderError> {
let rgba_f32 = vr_render_image(volume, tf, camera, config)?;
let mut out = Vec::with_capacity(rgba_f32.len() * 4);
for [r, g, b, a] in rgba_f32 {
out.push((r.clamp(0.0, 1.0) * 255.0) as u8);
out.push((g.clamp(0.0, 1.0) * 255.0) as u8);
out.push((b.clamp(0.0, 1.0) * 255.0) as u8);
out.push((a.clamp(0.0, 1.0) * 255.0) as u8);
}
Ok(out)
}
pub fn vr_build_occupancy_grid(volume: &VolumeGrid, threshold: f32, factor: usize) -> VolumeGrid {
let factor = factor.max(1);
let onx = volume.nx.div_ceil(factor);
let ony = volume.ny.div_ceil(factor);
let onz = volume.nz.div_ceil(factor);
let vox_size = [
volume.voxel_size[0] * factor as f32,
volume.voxel_size[1] * factor as f32,
volume.voxel_size[2] * factor as f32,
];
let mut occ = VolumeGrid::new(onx, ony, onz, volume.origin, vox_size);
for oz in 0..onz {
let z_lo = (oz * factor).saturating_sub(1);
let z_hi = ((oz + 1) * factor + 1).min(volume.nz);
for oy in 0..ony {
let y_lo = (oy * factor).saturating_sub(1);
let y_hi = ((oy + 1) * factor + 1).min(volume.ny);
for ox in 0..onx {
let x_lo = (ox * factor).saturating_sub(1);
let x_hi = ((ox + 1) * factor + 1).min(volume.nx);
let mut occupied = 0.0_f32;
'outer: for iz in z_lo..z_hi {
for iy in y_lo..y_hi {
for ix in x_lo..x_hi {
if volume.density_at(ix, iy, iz) > threshold {
occupied = 1.0;
break 'outer;
}
}
}
}
occ.data[oz * ony * onx + oy * onx + ox] = occupied;
}
}
}
occ
}
pub fn vr_can_skip(occupancy: &VolumeGrid, ray: &VolumetricRay, t: f32, _step_size: f32) -> bool {
let p = ray.at(t);
occupancy.sample_nearest(p[0], p[1], p[2]) < OCCUPIED_THRESHOLD
}
pub fn vr_compute_stats(results: &[RayMarchResult]) -> VolumetricStats {
if results.is_empty() {
return VolumetricStats {
n_rays: 0,
mean_steps_per_ray: 0.0,
max_steps_per_ray: 0,
mean_alpha: 0.0,
fully_opaque_rays: 0,
empty_rays: 0,
};
}
let n = results.len();
let mut total_steps = 0usize;
let mut max_steps = 0usize;
let mut total_alpha = 0.0_f32;
let mut fully_opaque = 0usize;
let mut empty = 0usize;
for r in results {
total_steps += r.n_steps;
if r.n_steps > max_steps {
max_steps = r.n_steps;
}
total_alpha += r.alpha;
if r.alpha > 0.99 {
fully_opaque += 1;
}
if r.n_steps == 0 {
empty += 1;
}
}
VolumetricStats {
n_rays: n,
mean_steps_per_ray: total_steps as f32 / n as f32,
max_steps_per_ray: max_steps,
mean_alpha: total_alpha / n as f32,
fully_opaque_rays: fully_opaque,
empty_rays: empty,
}
}
pub fn vr_format_stats(stats: &VolumetricStats) -> String {
format!(
"VolumetricStats {{ n_rays: {}, mean_steps: {:.2}, max_steps: {}, \
mean_alpha: {:.4}, fully_opaque: {}, empty: {} }}",
stats.n_rays,
stats.mean_steps_per_ray,
stats.max_steps_per_ray,
stats.mean_alpha,
stats.fully_opaque_rays,
stats.empty_rays,
)
}
pub fn vr_format_config(config: &VolumetricRenderConfig) -> String {
format!(
"VolumetricRenderConfig {{ step_size: {}, max_steps: {}, \
early_term_alpha: {}, integration: {:?}, jitter: {} }}",
config.step_size,
config.max_steps,
config.early_termination_alpha,
config.integration,
config.jitter,
)
}
#[inline]
pub(super) fn vec3_sub(a: [f32; 3], b: [f32; 3]) -> [f32; 3] {
[a[0] - b[0], a[1] - b[1], a[2] - b[2]]
}
#[inline]
pub(super) fn vec3_add(a: [f32; 3], b: [f32; 3]) -> [f32; 3] {
[a[0] + b[0], a[1] + b[1], a[2] + b[2]]
}
#[inline]
pub(super) fn vec3_scale(a: [f32; 3], s: f32) -> [f32; 3] {
[a[0] * s, a[1] * s, a[2] * s]
}
#[inline]
pub(super) fn vec3_cross(a: [f32; 3], b: [f32; 3]) -> [f32; 3] {
[
a[1] * b[2] - a[2] * b[1],
a[2] * b[0] - a[0] * b[2],
a[0] * b[1] - a[1] * b[0],
]
}
#[inline]
pub(super) fn vec3_norm(a: [f32; 3]) -> [f32; 3] {
let len = (a[0] * a[0] + a[1] * a[1] + a[2] * a[2]).sqrt();
if len < f32::EPSILON {
a
} else {
[a[0] / len, a[1] / len, a[2] / len]
}
}
#[cfg(test)]
mod tests {
use super::*;
use super::super::types::TransferPoint;
fn cfg_with(integration: VolumetricIntegration, jitter: bool) -> VolumetricRenderConfig {
VolumetricRenderConfig {
step_size: 0.1,
integration,
jitter,
..VolumetricRenderConfig::default()
}
}
#[test]
fn test_vr_gaussians_to_volume_zero_size_no_panic() {
let mut grid = VolumeGrid::new(0, 4, 4, [0.0; 3], [1.0; 3]);
let positions = [0.0_f32, 0.0, 0.0];
let scales = [1.0_f32, 1.0, 1.0];
let opacities = [1.0_f32];
let result = vr_gaussians_to_volume(&positions, &scales, &opacities, 1, &mut grid);
assert!(result.is_ok());
}
#[test]
fn test_vr_march_ray_with_occupancy_matches_plain_march_when_fully_occupied() {
let volume = VolumeGrid::from_fn(8, 8, 8, [-1.0; 3], [0.25; 3], |_, _, _| 0.8);
let occupancy = vr_build_occupancy_grid(&volume, 0.1, 2);
let tf = TransferFunction::grayscale(1.0);
let cfg = cfg_with(VolumetricIntegration::FrontToBack, false);
let ray = VolumetricRay::new_normalized([0.0, 0.0, -2.0], [0.0, 0.0, 1.0]);
let plain = vr_march_ray(&ray, &volume, &tf, &cfg);
let with_occ = vr_march_ray_with_occupancy(&ray, &volume, &tf, &cfg, &occupancy);
assert!((plain.alpha - with_occ.alpha).abs() < 1e-4);
for c in 0..3 {
assert!((plain.color[c] - with_occ.color[c]).abs() < 1e-4);
}
}
#[test]
fn test_vr_march_ray_with_occupancy_skips_empty_space() {
let volume = VolumeGrid::from_fn(32, 32, 32, [-1.0; 3], [1.0 / 16.0; 3], |_, _, _| 0.0);
let occupancy = vr_build_occupancy_grid(&volume, 0.1, 4);
let tf = TransferFunction::grayscale(1.0);
let cfg = cfg_with(VolumetricIntegration::BackToFront, false);
let ray = VolumetricRay::new_normalized([0.0, 0.0, -2.0], [0.0, 0.0, 1.0]);
let plain = vr_march_ray(&ray, &volume, &tf, &cfg);
let with_occ = vr_march_ray_with_occupancy(&ray, &volume, &tf, &cfg, &occupancy);
assert!(
with_occ.n_steps < plain.n_steps,
"expected fewer steps with occupancy skipping: plain={} with_occ={}",
plain.n_steps,
with_occ.n_steps
);
assert!(with_occ.alpha < 1e-4, "empty volume should be transparent");
assert!(plain.alpha < 1e-4, "empty volume should be transparent");
}
fn sparse_ball_volume() -> VolumeGrid {
VolumeGrid::from_fn(16, 16, 16, [-1.0; 3], [0.125; 3], |x, y, z| {
if x * x + y * y + z * z < 0.25 * 0.25 {
1.0
} else {
0.0
}
})
}
#[test]
fn test_vr_render_image_with_occupancy_matches_plain() {
let volume = sparse_ball_volume();
let occupancy = vr_build_occupancy_grid(&volume, 0.1, 2);
let empty_cells = occupancy.data.iter().filter(|&&v| v < 0.5).count();
assert!(
empty_cells > occupancy.data.len() / 2,
"test setup must leave most coarse cells empty, got {empty_cells} of {}",
occupancy.data.len()
);
let tf = TransferFunction::grayscale(1.0);
let camera = VolumetricCamera::default_front(6, 6);
for integration in [
VolumetricIntegration::FrontToBack,
VolumetricIntegration::BackToFront,
VolumetricIntegration::Mip,
VolumetricIntegration::Avg,
] {
let cfg = cfg_with(integration, false);
let plain = vr_render_image(&volume, &tf, &camera, &cfg).expect("plain render");
let with_occ = vr_render_image_with_occupancy(&volume, &tf, &camera, &cfg, &occupancy)
.expect("occupancy render");
assert_eq!(plain.len(), with_occ.len());
for (a, b) in plain.iter().zip(with_occ.iter()) {
for c in 0..4 {
assert!(
(a[c] - b[c]).abs() < 1e-3,
"{integration:?} pixel mismatch: {a:?} vs {b:?}"
);
}
}
}
}
#[test]
fn test_vr_march_ray_with_occupancy_is_exact_on_sparse_volume() {
let volume = sparse_ball_volume();
let occupancy = vr_build_occupancy_grid(&volume, 0.1, 2);
let tf = TransferFunction::grayscale(1.0);
let ray = VolumetricRay::new_normalized([0.0, 0.0, -2.0], [0.0, 0.0, 1.0]);
for integration in [
VolumetricIntegration::FrontToBack,
VolumetricIntegration::BackToFront,
VolumetricIntegration::Mip,
VolumetricIntegration::Avg,
] {
let cfg = cfg_with(integration, false);
let plain = vr_march_ray(&ray, &volume, &tf, &cfg);
let with_occ = vr_march_ray_with_occupancy(&ray, &volume, &tf, &cfg, &occupancy);
assert!(
with_occ.n_steps < plain.n_steps,
"{integration:?}: skipping must save samples, plain={} with_occ={}",
plain.n_steps,
with_occ.n_steps
);
assert!(
plain.alpha > 0.1,
"{integration:?}: the probe ray must actually hit the ball, alpha={}",
plain.alpha
);
assert!(
(plain.alpha - with_occ.alpha).abs() < 1e-5,
"{integration:?}: alpha {} vs {}",
plain.alpha,
with_occ.alpha
);
for c in 0..3 {
assert!(
(plain.color[c] - with_occ.color[c]).abs() < 1e-5,
"{integration:?}: colour[{c}] {} vs {}",
plain.color[c],
with_occ.color[c]
);
}
}
}
#[test]
fn test_occupancy_grid_dilates_by_one_voxel_for_the_trilinear_stencil() {
let mut volume = VolumeGrid::new(4, 4, 4, [0.0; 3], [1.0; 3]);
volume.data[2] = 1.0; let occ = vr_build_occupancy_grid(&volume, 0.5, 2);
assert_eq!((occ.nx, occ.ny, occ.nz), (2, 2, 2));
let cell = |ox: usize, oy: usize, oz: usize| occ.data[oz * 4 + oy * 2 + ox];
assert!(cell(1, 0, 0) > 0.5, "the cell containing the voxel");
assert!(
cell(0, 0, 0) > 0.5,
"the adjacent cell whose trilinear stencil reaches the voxel"
);
assert!(
cell(0, 1, 0) < 0.5,
"cell (0,1,0)'s halo spans y = 1..3 and must not reach y = 0"
);
assert!(
cell(1, 1, 1) < 0.5,
"cell (1,1,1)'s halo spans y = z = 1..3 and must not reach y = z = 0"
);
}
#[test]
fn test_occupancy_skip_stops_at_the_empty_cell_boundary() {
let volume = VolumeGrid::from_fn(16, 16, 16, [-1.0; 3], [0.125; 3], |_, _, z| {
if (0.0..0.25).contains(&z) {
1.0
} else {
0.0
}
});
let occupancy = vr_build_occupancy_grid(&volume, 0.1, 2);
let tf = TransferFunction::grayscale(1.0);
let cfg = cfg_with(VolumetricIntegration::BackToFront, false);
let ray = VolumetricRay::new_normalized([0.0, 0.0, -2.0], [0.0, 0.0, 1.0]);
let plain = vr_march_ray(&ray, &volume, &tf, &cfg);
let with_occ = vr_march_ray_with_occupancy(&ray, &volume, &tf, &cfg, &occupancy);
assert!(
plain.alpha > 0.1,
"the slab must be visible: {}",
plain.alpha
);
assert!(
with_occ.n_steps < plain.n_steps,
"skipping should still save samples outside the slab"
);
assert!(
(plain.alpha - with_occ.alpha).abs() < 1e-5,
"the slab must not be skipped over: {} vs {}",
plain.alpha,
with_occ.alpha
);
}
#[test]
fn test_occupancy_skip_preserves_avg_divisor() {
let volume = sparse_ball_volume();
let occupancy = vr_build_occupancy_grid(&volume, 0.1, 2);
let tf = TransferFunction::grayscale(1.0);
let cfg = cfg_with(VolumetricIntegration::Avg, false);
let ray = VolumetricRay::new_normalized([0.0, 0.0, -2.0], [0.0, 0.0, 1.0]);
let plain = vr_march_ray(&ray, &volume, &tf, &cfg);
let with_occ = vr_march_ray_with_occupancy(&ray, &volume, &tf, &cfg, &occupancy);
assert!(plain.alpha > 0.0, "the probe ray must hit the ball");
assert!(
(plain.alpha - with_occ.alpha).abs() < 1e-5,
"average alpha must not depend on how many samples were skipped: \
{} vs {}",
plain.alpha,
with_occ.alpha
);
}
#[test]
fn test_occupancy_skip_folds_in_non_transparent_empty_space() {
let volume = sparse_ball_volume();
let occupancy = vr_build_occupancy_grid(&volume, 0.1, 2);
let fog = TransferFunction {
points: vec![
TransferPoint {
density: 0.0,
color: [0.2, 0.2, 0.6],
opacity: 0.25,
},
TransferPoint {
density: 1.0,
color: [1.0, 1.0, 1.0],
opacity: 1.0,
},
],
};
let ray = VolumetricRay::new_normalized([0.0, 0.0, -2.0], [0.0, 0.0, 1.0]);
for integration in [
VolumetricIntegration::FrontToBack,
VolumetricIntegration::BackToFront,
] {
let cfg = cfg_with(integration, false);
let plain = vr_march_ray(&ray, &volume, &fog, &cfg);
let with_occ = vr_march_ray_with_occupancy(&ray, &volume, &fog, &cfg, &occupancy);
assert!(
(plain.alpha - with_occ.alpha).abs() < 1e-3,
"{integration:?}: fog contribution of skipped samples must be \
folded in: {} vs {}",
plain.alpha,
with_occ.alpha
);
for c in 0..3 {
assert!(
(plain.color[c] - with_occ.color[c]).abs() < 1e-3,
"{integration:?}: colour[{c}] {} vs {}",
plain.color[c],
with_occ.color[c]
);
}
}
}
#[test]
fn test_march_front_to_back_clamps_out_of_range_opacity() {
let volume = VolumeGrid::from_fn(4, 4, 4, [-1.0; 3], [0.5; 3], |_, _, _| 0.5);
let tf = TransferFunction {
points: vec![
TransferPoint {
density: 0.0,
color: [1.0, 0.0, 0.0],
opacity: 0.0,
},
TransferPoint {
density: 1.0,
color: [1.0, 0.0, 0.0],
opacity: 2.5, },
],
};
let cfg = cfg_with(VolumetricIntegration::FrontToBack, false);
let ray = VolumetricRay::new_normalized([0.0, 0.0, -2.0], [0.0, 0.0, 1.0]);
let result = vr_march_ray(&ray, &volume, &tf, &cfg);
assert!(result.alpha.is_finite(), "alpha = {}", result.alpha);
for c in result.color {
assert!(c.is_finite(), "color component = {c}");
}
}
#[test]
fn test_march_back_to_front_clamps_out_of_range_opacity() {
let volume = VolumeGrid::from_fn(4, 4, 4, [-1.0; 3], [0.5; 3], |_, _, _| 0.5);
let tf = TransferFunction {
points: vec![
TransferPoint {
density: 0.0,
color: [0.0, 1.0, 0.0],
opacity: 0.0,
},
TransferPoint {
density: 1.0,
color: [0.0, 1.0, 0.0],
opacity: 3.0, },
],
};
let cfg = cfg_with(VolumetricIntegration::BackToFront, false);
let ray = VolumetricRay::new_normalized([0.0, 0.0, -2.0], [0.0, 0.0, 1.0]);
let result = vr_march_ray(&ray, &volume, &tf, &cfg);
assert!(result.alpha.is_finite(), "alpha = {}", result.alpha);
for c in result.color {
assert!(c.is_finite(), "color component = {c}");
}
}
}