Scale & Resolution

Example: Voxel Size Changes

A smaller voxel can be useful when more detail is desired, but it also makes the simulation more demanding. CFL, surface tension, and viscosity constraints may require more substeps.

Relative Grid Resolution

This is the legacy/default resolution behavior where voxel_size = domain_max_extent / grid_resolution.

If the domain becomes smaller, the voxel size becomes smaller too, giving you more detail but higher cost.

Use Relative Grid Resolution when:

• You want the same number of grid cells regardless of domain size
• Reducing the domain should increase physical detail
• You are intentionally increasing simulation resolution by scaling the domain down
• You are working with legacy scenes that already rely on this behavior

Fixed Voxels Per Meter (VPM)

This mode keeps the physical voxel size constant: voxel_size = 1 / voxels_per_meter.

If the domain becomes smaller, the grid has fewer cells, making small domains cheaper instead of accidentally more expensive.

Use Fixed Voxels Per Meter when:

• You want stable physical resolution
• You want a specific voxel size (1 cm, 4 mm, 2 mm, 1 mm) regardless of domain size
• You are simulating real-world sized objects
• You want predictable scaling from glass-sized scenes to larger domains

Recommended VPM Values

These values are starting points. Production scenes may require higher or lower values depending on camera distance, particle count, meshing settings, and desired surface detail.

Auto

Auto is the recommended starting point. Undine chooses the scale policy needed for the current pipeline stage while preserving a world-space scale contract between the domain, solver cache, and Meshify output.

Use Auto when:

• You want Undine to keep interactive preview responsive without changing the final scale interpretation
• You want final bakes and Meshify output to stay tied to world-space units
• You do not need to force a fully physical or fully cinematic scale policy manually

Physical Scale

Physical Scale is the explicit real-world mode. In this mode, physical values remain real-world values — water remains water, surface tension remains physical, gravity remains physical.

Use Physical Scale when:

• A glass is actually glass-sized
• A tear is actually tear-sized
• The simulation should respond according to real-world dimensions
• Physical interpretation is more important than visual scale matching

A 0.3 m glass domain with water should behave differently from a 30 m waterfall domain. This is correct: small-scale water is more affected by surface tension, while large-scale water is dominated by gravity and inertia.

Cinematic Scale Lock

Cinematic Scale Lock is used when the artist wants the simulation to preserve the same visual behavior after scaling the domain. This is useful when the domain is scaled for composition, camera framing, preview speed, or production convenience, but the desired motion should remain visually similar.

Use Cinematic Scale Lock when:

• The scene is artistically scaled rather than physically scaled
• The fluid should keep the same look after changing the domain size
• A simulation is authored at one scale and reused at another
• Shots require visual continuity rather than strict physical interpretation

Reference Scale

Cinematic Scale Lock uses a captured reference extent. Press Capture Reference Scale to store the current domain size as the reference.

The solver then applies scale-aware parameter mapping so that the visual character of the fluid remains closer to the reference simulation.

Parameter Scaling

When Cinematic Scale Lock is active, Undine computes effective solver values from the artist-authored values. For s = scale_factor = current_extent / reference_extent:

Glass or Cup of Water

Recommended starting point:

• Resolution Mode: Fixed Voxels Per Meter
• Scale Behavior: Physical Scale
• VPM: 250–500

For close-up glass simulations, increase VPM. For preview, use lower VPM and increase later.

Tears or Drops on a Face

Recommended starting point:

• Resolution Mode: Fixed Voxels Per Meter
• Scale Behavior: Physical Scale
• VPM: 500–1000

Surface tension becomes visually important at this scale. For drops to remain attached to skin, use a collider wetting/contact material.

Character Splash

Recommended starting point:

• Resolution Mode: Fixed Voxels Per Meter
• Scale Behavior: Physical Scale
• VPM: 100–250

This keeps resolution stable while the domain is adjusted around the character.

River or Waterfall

Recommended starting point:

• Resolution Mode: Fixed Voxels Per Meter
• Scale Behavior: Physical Scale
• VPM: 10–100

For large water, use whitewater, foam, bubbles, and meshing detail rather than extreme grid resolution. Surface tension is usually negligible at large scale.

Reusing a Simulation at a Different Size

Recommended starting point:

• Resolution Mode: Fixed Voxels Per Meter or Relative Grid Resolution
• Scale Behavior: Cinematic Scale Lock

Workflow:

1. Set the domain to the original/reference size
2. Tune the simulation look
3. Press Capture Reference Scale
4. Scale the domain for the shot
5. Keep Cinematic Scale Lock enabled
6. Review diagnostics and adjust VPM if needed

Relative Grid Resolution + Cinematic Scale Lock

This combination preserves numerical invariants perfectly when scaling the domain. As the scale factor s changes, both the voxel size and the physical parameters scale proportionally:

• h → s·h (voxel size scales with domain)
• v → s·v (velocity scales)
• gravity → s·gravity (gravity scales)
• ν → s²·ν (kinematic viscosity scales)
• σ → s³·σ (surface tension scales)

This scaling preserves the key numerical constraints:

• CFL ≈ constant — The Courant number stays stable because velocity and voxel size scale together
• viscosity alpha ≈ constant — Viscous diffusion timescale remains proportional
• capillary constraint ≈ constant — Surface tension timestep restriction stays stable

Use this combination when:

• You want perfect numerical invariance across domain sizes
• The simulation must behave identically at different scales
• You're debugging numerical stability issues
• Legacy compatibility is required

The grid cell count remains approximately constant, so cost stays similar regardless of domain size.

Fixed Voxels Per Meter + Cinematic Scale Lock

This combination keeps voxel size h constant while scaling velocity, gravity, surface tension, and viscosity. The numerical behavior is different:

• h → constant (voxel size stays fixed)
• v → s·v (velocity scales)
• gravity → s·gravity (gravity scales)
• ν → s²·ν (kinematic viscosity scales)
• σ → s³·σ (surface tension scales)

This results in:

• Smaller physical domain at smaller scales
• Constant voxel size in world units
• Fewer grid cells for smaller domains
• Proportional visual motion preserved
• Relaxed CFL typically, since h doesn't shrink with the domain
• Lower computational cost for smaller domains

Use this combination when:

• You want smaller domains to be computationally cheaper
• Production cost matters more than perfect numerical invariance
• You need to scale a simulation down for preview and up for final
• You're working with multiple shots at different scales from the same simulation asset

Choosing the Right Combination

Recommended Default for Most Scenes

Use Fixed Voxels Per Meter + Physical Scale for most real-world scenes.

• Voxel size stays tied to physical units (1 cm, 4 mm, 2 mm, etc.)
• Gravity, viscosity, surface tension remain unchanged
• Scaling the domain changes grid dimensions and cell count instead of silently shrinking the voxel
• Small domains become cheaper, not accidentally expensive

Legacy Compatibility

Use Relative Grid Resolution + Physical Scale to preserve legacy behavior from earlier Undine versions.

• Grid dimensions stay close to the selected grid resolution
• Shrinking the domain also shrinks voxel size
• Small domains can require more CFL, viscosity, or capillary substeps

Cinematic Modes

Relative Grid Resolution + Cinematic Scale Lock — Use when the goal is a matched visual retime/rescale around a captured reference.

• Voxel size and physical parameters scale together
• Perfect numerical invariance (CFL, viscosity alpha, capillary constraint all constant)
• Same computational cost regardless of domain size

Fixed Voxels Per Meter + Cinematic Scale Lock — Use as a low-cost artistic mode.

• Makes small domains cheaper while preserving visual motion proportionally
• Does not guarantee CFL, viscosity, or capillary invariance
• Best for production preview/final scaling workflows

VPM Quick Guide

Manual Validation for Scale-Sensitive Shots

When working with scale-sensitive shots, always validate before running:

1. Scale the domain to the intended size
2. Check Voxel Size in the Scale & Resolution panel
3. Review Estimated Grid Dims (avoid very low axis resolution)
4. Verify Estimated Cell Count is manageable
5. Run a short test and monitor runtime CFL and substep metrics in the Debug panel
6. Adjust VPM or mode combination if warnings appear