Procedural 3D Modeling

The Geometry of Possibility

Create 3D models with mathematics, not meshes.

Write a script. Get infinite variations. Soyuz transforms mathematical expressions into real-time 3D previews and production-ready meshes.

Signed Distance Fields: The Mathematical Heart

The Simple Idea

An SDF (Signed Distance Function) answers a simple question: "How far is this point from the surface?"

+ Positive distance = point is outside

- Negative distance = point is inside

0 Zero = point is on the surface

Why It Matters

SDFs unlock incredibly simple boolean operations. Combining shapes becomes basic math:

min(a, b)

Union

Combine two shapes

max(a, -b)

Subtract

Carve one from another

max(a, b)

Intersect

Keep only overlap

No polygon meshes. No vertex counts. Just pure mathematical expressions that scale to any resolution.

Technical Deep-Dive: The SDF Formula

Here's the actual WGSL code for a sphere SDF. The elegance is in its simplicity:

sphere.wgsl

fn sd_sphere(p: vec3<f32>, radius: f32) -> f32 {
    return length(p) - radius;
}

p - The 3D point we're testing

length(p) - Distance from origin to point

radius - The sphere's radius

The result: positive outside, negative inside, zero on surface. That's it.

Everything You Need to Build

Soyuz provides a complete toolkit for procedural 3D modeling. Here's what's available:

13 Primitives

sphere, box, cylinder, torus, capsule, cone, ellipsoid, plane, octahedron

6 Boolean Operations

union, subtract, intersect, smooth_union, smooth_subtract, smooth_intersect

4 Modifiers

shell, round, onion, elongate

9 Transforms

translate, rotate_x/y/z, scale, mirror_x/y/z, symmetry_x/y/z

2 Deformations

twist, bend

3 Repetition

repeat, repeat_limited, repeat_polar

Total: 37 operations that can be combined infinitely through method chaining.

Built for Modularity

Soyuz is organized into focused, reusable crates. Each has a single responsibility, making the system easy to understand and extend.

Hover over a crate to see its description and dependencies

From Script to Screen

The 30-Second Version

1. Write Script

Rhai code describing your shape

→

↓

2. Generate GPU Code

Soyuz compiles to WGSL shaders

→

↓

3. See Your Shape

Real-time 3D preview appears

How Raymarching Works

Soyuz uses sphere tracing, a raymarching technique where the SDF value tells us the maximum safe distance to step:

For each pixel, we cast a ray into the scene. At each step, we evaluate the SDF to get the distance to the nearest surface.

Key insight: The SDF value is a guaranteed safe step size. If we're 2 units from any surface, we can safely step 2 units forward without missing anything.

This makes raymarching incredibly efficient: large steps far from surfaces, tiny steps near them.

Technical Deep-Dive: Raymarching Implementation

Here are the key constants and techniques used in Soyuz's raymarcher:

MAX_STEPS

128 iterations per ray

MAX_DIST

100.0 units maximum travel

MIN_SURF_DIST

0.0001 surface threshold

Shadow Steps

32 samples for soft shadows

raymarch.wgsl

fn raymarch(ro: vec3<f32>, rd: vec3<f32>) -> RayResult {
    var dist = 0.0;
    for (var i = 0; i < MAX_STEPS; i++) {
        let p = ro + rd * dist;
        let d = scene_sdf(p);

        // Adaptive threshold: relaxes with distance
        if (d < MIN_SURF_DIST + 0.0002 * dist) {
            return RayResult(true, dist, p);
        }

        dist += d;
        if (dist > MAX_DIST) { break; }
    }
    return RayResult(false, dist, vec3(0.0));
}

Optimizations: Distance-adaptive surface threshold, unrolled AO loops (3 samples), adaptive shadow stepping, and pre-computed sin/cos at shader generation time.

Why Soyuz?

Platform Parity

The same SDF definition runs identically everywhere:

Desktop GPU (WGPU)
Browser (WebAssembly)
CPU (headless mesh export)

Single Source of Truth

Mathematical formulas are defined once in soyuz-math and automatically generate:

Verified Rust code
Matching WGSL shaders
No formula drift between platforms

Script-First Workflow

Everything is a text file:

Version control friendly (git diff works!)
Reproducible builds
No binary blob assets

Tight Integration

Geometry and rendering are unified:

Lighting, materials, environment in scripts
Sun direction, fog, shadows configurable
No separate config files

Soyuz vs. The World

A fair comparison. Every tool has strengths; here's where Soyuz fits.

Feature	Soyuz	OpenSCAD	SDF Libraries	Houdini
Paradigm	SDF + Script	CSG + Script	SDF only	Node graph
Real-time Preview	Yes (GPU)	No (CPU)	Varies	Yes
Price	Free / Open Source	Free / Open Source	Free	$$$
Learning Curve	Medium	Medium	High	Very High
Export Formats	glTF, GLB, OBJ, STL	STL, OFF, AMF	Usually none	Everything
GPU Acceleration	Yes (WGPU)	No	Rarely	Yes
Scripting	Rhai	OpenSCAD lang	Host language	VEX / Python

Note: Houdini is industry-standard for complex VFX work. OpenSCAD pioneered script-based CAD. Soyuz aims to bring SDF-based modeling to a wider audience with modern tooling.

Performance Characteristics

SDF operations

12 primitives, 6 booleans, 9 transforms, more

Export formats

OBJ, GLTF, GLB, STL

~600KB

WASM module size

Gzipped

Optimization Techniques & Honest Limitations

Optimizations Used

Unrolled AO loops (3 samples)
Adaptive shadow stepping
Distance-adaptive surface threshold
Pre-computed sin/cos at code generation
Full-screen triangle (1 draw call)

Known Limitations

Very complex scenes (deep nesting) can slow down
Raymarching has 128 step limit per ray
Maximum ray distance of 100 units
WASM runs in browser sandbox (no filesystem)