Rescaling

This guide provides practical examples and detailed usage patterns for rescaling transformations in Crater. For the mathematical theory, see Rescaling Transformations.

Available Rescaling Functions

Hyperbolic Tangent Family

Standard Tanh: $h (x) = tanh (k x)$

Domain: $R$
Range: $(- 1, 1)$
Properties: Smooth $C^{\infty}$ function, preserves sign, symmetric about origin
Parameters: $k$ controls transition steepness

Scaled Tanh: $h (x) = a + b \cdot tanh (k x)$

Domain: $R$
Range: $(a - ∣ b ∣, a + ∣ b ∣)$
Properties: Configurable center point $a$ and half-range $∣ b ∣$

#![allow(unused)]
fn main() {
use crater::csg::prelude::*;
use crater::csg::rescale::RescaleScheme;
use burn::backend::wgpu::WgpuDevice;
use burn::backend::wgpu::Wgpu;

fn example_tanh_rescaling() {
    // Standard tanh: maps to (-1, 1)
    let device = WgpuDevice::default();
    let field = Field3D::<Wgpu>::sphere(2.0, device).into_isosurface(0.0);
    let tanh_field = field.clone().rescale(RescaleScheme::Tanh { k: 2.0 });
    
    // Scaled tanh: maps to (3, 7) with center at 5
    let scaled_field = field.rescale(RescaleScheme::ScaledTanh {
        center: 5.0,
        scale: 2.0,
        k: 1.0,
    });
}
}

Logistic (Sigmoid) Family

Standard Sigmoid: $h (x) = \frac{1}{1 + e ^{- k x}}$

Domain: $R$
Range: $(0, 1)$
Properties: Smooth $C^{\infty}$ function, monotonically increasing, asymptotic bounds
Numerical Stability: Implementation uses different formulas for positive/negative inputs

Scaled Sigmoid: $h (x) = a + b \cdot sigmoid (k x)$

Domain: $R$
Range: $(a, a + b)$
Properties: Configurable minimum $a$ and range $b$

Arctangent Family

Standard Arctan: $h (x) = arctan (k x)$

Domain: $R$
Range: $(- \frac{π}{2}, \frac{π}{2})$
Properties: Smooth $C^{\infty}$ function, preserves sign, linear near origin for small $k$

Scaled Arctan: $h (x) = a + \frac{b}{π} arctan (k x)$

Domain: $R$
Range: $(a - \frac{b}{2}, a + \frac{b}{2})$

Error Function

Error Function: $h (x) = erf (k x)$

Domain: $R$
Range: $(- 1, 1)$
Properties: Smooth $C^{\infty}$ function, Gaussian-like transition, preserves sign
Implementation: High-quality approximation using $erf (x) \approx tanh (\frac{2}{π} x)$

Soft Clipping

Soft Clip: $h (x) = \frac{x}{1 + k ∣ x ∣}$

Domain: $R$
Range: $(- \frac{1}{k}, \frac{1}{k})$
Properties: Preserves sign, linear for small inputs, asymptotic bounds
Continuity: Continuous everywhere but not differentiable at $x = 0$ when $k \neq = 1$

Practical Examples

Example 1: Normalizing Distance Fields

use crater::csg::prelude::*;
use crater::csg::rescale::RescaleScheme;
use burn::backend::wgpu::WgpuDevice;
use burn::backend::wgpu::Wgpu;

fn main() {
    let device = WgpuDevice::default();
    // Create a sphere distance field
    let sphere = Field3D::<Wgpu>::sphere(2.0, device);
    // Normalize to (-1, 1) range with tanh
    let normalized = sphere.rescale(RescaleScheme::Tanh { k: 0.5 });
}

Example 2: Creating Probability-Like Fields

use crater::csg::prelude::*;
use crater::csg::rescale::RescaleScheme;
use burn::backend::wgpu::WgpuDevice;
use burn::backend::wgpu::Wgpu;

fn main() {
    let device = WgpuDevice::default();
    // Create a sphere distance field
    let sphere = Field3D::<Wgpu>::sphere(2.0, device);
    // Convert distance field to probability-like values in (0, 1)
    let probability_field = sphere.rescale(RescaleScheme::Sigmoid { k: 2.0 });
    
    // Values near the surface (distance ≈ 0) map to ≈ 0.5
    // Negative distances (inside) map to values < 0.5
    // Positive distances (outside) map to values > 0.5
}

Example 3: Custom Range Mapping

use crater::csg::prelude::*;
use crater::csg::rescale::RescaleScheme;
use burn::backend::wgpu::WgpuDevice;
use burn::backend::wgpu::Wgpu;

fn main() {
    let device = WgpuDevice::default();
    // Map field values to engineering units [0, 100] 
    let field = Field3D::<Wgpu>::sphere(2.0, device).into_isosurface(0.0);
    let engineering_field = field.rescale(RescaleScheme::ScaledSigmoid {
        min: 0.0,
        range: 100.0,
        k: 1.0,
    });
}

Example 4: Large-Scale Numerical Stability

This example demonstrates how rescaling prevents numerical failures with large geometric features:

use crater::csg::prelude::*;
use crater::analysis::prelude::*;
use burn::backend::wgpu::WgpuDevice;
use burn::backend::wgpu::Wgpu;
use burn::backend::Autodiff;
use burn::prelude::*;

fn main() {
    let device = WgpuDevice::default();
    // Create a very large sphere (radius = 100 units)
    // Without rescaling, distance values would range from -∞ to +∞
    let large_sphere = Field3D::<Autodiff<Wgpu>>::sphere(100.0, device.clone()).into_isosurface(0.0);
    
    // Apply tanh rescaling to bound values to (-1, 1)
    // k = 0.01 provides smooth transition around the surface
    let rescaled_sphere = large_sphere.rescale(RescaleScheme::Tanh { k: 0.01 });
    
    // Test points at various distances from center
    let test_points = [
        [0.0, 0.0, 0.0],     // Center: distance = -100 → tanh(-1) ≈ -0.76
        [50.0, 0.0, 0.0],    // Halfway: distance = -50 → tanh(-0.5) ≈ -0.46  
        [100.0, 0.0, 0.0],   // Surface: distance = 0 → tanh(0) = 0
        [150.0, 0.0, 0.0],   // Outside: distance = 50 → tanh(0.5) ≈ 0.46
        [200.0, 0.0, 0.0],   // Far outside: distance = 100 → tanh(1) ≈ 0.76
    ];
    
    let results = rescaled_sphere.evaluate(Tensor::<Autodiff<Wgpu>, 2, Float>::from_data(test_points, &device));
    
    // All values are guaranteed to be in (-1, 1)
    // Ray casting and other algorithms converge reliably
    // No overflow or underflow issues with extreme distances
    
    // Ray casting that would fail with unbounded fields now works
    let rays = Rays::new_from_slices(
        &[[110.0, 0.0, 0.0], [90.0, 0.0, 0.0]], 
        &[[-1.0, 0.0, 0.0], [1.0, 0.0, 0.0]],   
        device
    );
    
    let intersections = rescaled_sphere.region().ray_cast(
        rays,
        &Algebra::default(),
        RayCastAlgorithm::Analytical
    );
    // ✓ Successful intersection finding with bounded field values
}

Why This Example Matters: Large distance values (±100 units) would cause floating-point precision issues in iterative algorithms

Parameter Selection Guidelines

Steepness Parameter $k$

Small $k$ (< 1): Gradual transition, nearly linear near origin
Large $k$ (> 5): Sharp transition, step-function-like behavior
$k = 1$ : Balanced transition suitable for most applications

Range Parameters

Choose based on downstream requirements
Consider numerical precision of target system
Ensure compatibility with other field operations

crater.rs