// undine docs
Scale & Resolution
Undine includes a scale-aware resolution and simulation system designed to make fluid behavior predictable across very different scene sizes: small containers, facial droplets, character splashes, waterfalls, rivers, and large exterior bodies of water.
The system separates resolution (how large each voxel is) from scale behavior (whether physical parameters adapt when you resize the domain), making small domains cheaper and large domains more manageable.
Resolution Mode
Undine supports two resolution modes that control how voxel size is determined when the domain changes size.
Relative Grid Resolution
Legacy/default mode where voxel_size = domain_max_extent / grid_resolution. Scaling down the domain increases detail but also cost.
Relative Grid Resolution changes simulation behavior with scale. Use Fixed Voxels Per Meter for physically consistent results.
Use when you want the same grid cell count regardless of domain size, or when reducing the domain should intentionally increase physical detail.
Fixed Voxels Per Meter (VPM)
Keeps physical voxel size constant: voxel_size = 1 / voxels_per_meter. Smaller domains get fewer cells, making them cheaper instead of accidentally expensive.
Use when you want stable physical resolution across different domain sizes, or when simulating real-world sized objects (glasses, tears, splashes, waterfalls).
| Use Case | Suggested VPM | Voxel Size | Notes |
|---|---|---|---|
| Rivers, oceans, distant waterfalls | 10–50 | 10–2 cm | Use foam/whitewater for detail |
| Medium waterfalls, character-scale | 50–150 | 2–0.67 cm | Good for previews |
| Buckets, splashes, props | 100–250 | 1 cm–4 mm | Balanced production range |
| Glasses, cups, small containers | 250–500 | 4–2 mm | Better surface definition |
| Drops, skin droplets, close-ups | 500–1000 | 2–1 mm | Higher cost; use when needed |
| Macro liquid detail | 1000+ | <1 mm | Expensive; careful substeps required |
Auto Scale Mode
Auto Scale Mode keeps preview and final output aligned without forcing the artist to micromanage resolution strategy. During interactive preview in Streamflow, Undine uses Relative Grid Resolution so cell count stays stable and iteration remains responsive.
During final baking and Meshify, the pipeline switches internally to Fixed Voxels Per Meter so voxel size stays tied to world-space units and fluid behavior remains physically coherent across scale. This transition happens inside the pipeline and does not alter the user workflow.
The solver operates in world-space units, and Meshify consumes a validated scale contract that prevents double transforms, drift, or mismatches between particle data and generated surfaces.
Uniform domain scaling therefore produces a proportional simulation instead of silently changing the apparent fluid type. Non-uniform scaling is constrained to avoid undefined behavior.
Scale Behavior
Controls how physical parameters are interpreted when the domain is scaled. Independent from Resolution Mode.
Physical Scale
Default mode. Physical values remain real-world values — water remains water, surface tension remains physical, gravity remains physical.
Use when simulating real-world sized objects where a glass should behave differently from a waterfall. Small-scale water is more affected by surface tension; large-scale water is dominated by gravity and inertia.
Cinematic Scale Lock
Preserves the same visual behavior after scaling the domain. Useful when the domain is scaled for composition, camera framing, or production convenience.
Press 'Capture Reference Scale' to store the current domain size. The solver then applies scale-aware parameter mapping: velocities scale by s, viscosity by s², surface tension by s³, where s = current_extent / reference_extent.
Use when the scene is artistically scaled rather than physically scaled, or when a simulation authored at one scale must be reused at another size with the same visual look.
| Parameter Type | Scaling | Reason |
|---|---|---|
| Lengths, radii, distances | × s | Preserves geometric proportions |
| Emitter velocities | × s | Keeps motion visually proportional |
| Gravity / accelerations | × s | Preserves visual trajectory timing |
| Kinematic viscosity | × s² | Preserves diffusion behavior |
| Surface tension | × s³ | Keeps capillary behavior consistent |
| Density | unchanged | Mass density remains material-like |
Warnings and Diagnostics
Undine displays scale-related diagnostics to prevent unstable or inefficient setups.
- Low Axis Resolution — when one domain axis has too few cells (<16), causing poor pressure solve behavior
- High Cell Count — when estimated cell count becomes expensive
- CFL Warning — when fluid moves too fast for current voxel size
- Capillary Warning — when surface tension requires many substeps
- Viscosity Stiffness Warning — when viscosity becomes numerically stiff
- Extreme Scale Factor Warning — when Cinematic Scale Lock has scale factor <0.1 or >10.0
Artistic Workflows
Glass or Cup of Water
Resolution Mode: Fixed Voxels Per Meter · Scale Behavior: Physical Scale · VPM: 250–500
For close-up shots, increase VPM. For preview, use lower VPM and increase later.
Tears or Drops on a Face
Resolution Mode: Fixed Voxels Per Meter · Scale Behavior: Physical Scale · VPM: 500–1000
Surface tension becomes visually important at this scale. For drops to stick to skin, use collider wetting/contact material — Scale & Resolution controls voxel scale, not adhesion.
Character Splash
Resolution Mode: Fixed Voxels Per Meter · Scale Behavior: Physical Scale · VPM: 100–250
Keeps resolution stable while the domain is adjusted around the character.
River or Waterfall
Resolution Mode: Fixed Voxels Per Meter · Scale Behavior: Physical Scale · VPM: 10–100
For large water, use whitewater and meshing detail rather than extreme grid resolution. Surface tension is usually negligible at large scale.
Reusing a Simulation at Different Size
Resolution Mode: Fixed Voxels Per Meter or Relative Grid Resolution · Scale Behavior: Cinematic Scale Lock
Workflow: tune simulation at reference size → press 'Capture Reference Scale' → scale domain for the shot → keep Cinematic Scale Lock enabled → review diagnostics.
Mode Combinations: Numerical Behavior
The interaction between Resolution Mode and Scale Behavior determines the numerical properties of the simulation when the domain is scaled. Understanding these combinations helps choose the right mode for your workflow.
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 · ν → s²·ν (kinematic viscosity) · σ → s³·σ (surface tension)
This scaling preserves the key numerical constraints: CFL ≈ constant (Courant number stays stable), viscosity alpha ≈ constant (diffusion timescale proportional), capillary constraint ≈ constant (surface tension timestep stable).
Use when you want perfect numerical invariance across domain sizes, the simulation must behave identically at different scales, you're debugging numerical stability issues, or 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 · ν → s²·ν · σ → s³·σ
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), and lower computational cost for smaller domains.
Use 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, or you're working with multiple shots at different scales from the same simulation asset.
This mode can be thought of as 'cinematic low-cost scale lock' — it preserves visual motion proportionally but intentionally breaks perfect numerical invariance to make smaller domains cheaper. This is not a limitation; it's a production feature.
| Combination | Numerical Invariance | Cost Scaling | Primary Use Case |
|---|---|---|---|
| Relative Grid + Cinematic Lock | Perfect (CFL, visc, capillary constant) | Constant (same cell count) | Exact numerical matching, debugging |
| VPM + Cinematic Lock | Visual motion preserved, CFL relaxed | Scales down with domain | Production preview/final scaling |
| VPM + Physical Scale | Real-world physical behavior | Scales down with domain | Physical accuracy (glasses, tears, rivers) |
| Relative Grid + Physical Scale | Legacy behavior | Constant (same cell count) | Legacy scenes, intentional detail increase |
Quick Reference Guide
This section provides quick recommendations for common scenarios. These are starting points based on beta testing; adjust based on your scene requirements.
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, and scaling the domain changes grid dimensions 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, but 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, giving perfect numerical invariance (CFL, viscosity alpha, capillary constraint all constant) with 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.
Manual Validation for Scale-Sensitive Shots
When working with scale-sensitive shots, always validate before running: scale the domain to the intended size, check Voxel Size in the panel, review Estimated Grid Dims (avoid very low axis resolution), verify Estimated Cell Count is manageable, run a short test and monitor runtime CFL and substep metrics in the Debug panel, then adjust VPM or mode combination if warnings appear.
| VPM Range | Purpose | Notes |
|---|---|---|
| 32–64 | Preview | Fast iteration, broad motion only |
| 64–120 | General use | Balanced quality and performance |
| 120–240 | Detail | Good surface definition |
| 240+ | High detail | Check Estimated Cell Count before running |
Best Practices
- Use Fixed Voxels Per Meter for physically sized scenes
- Use Relative Grid Resolution for legacy scenes or intentional resolution scaling
- Use Physical Scale for real-world behavior
- Use Cinematic Scale Lock for visual scale matching
- Choose VPM based on desired physical detail, not just domain size
- Watch estimated grid dimensions and cell count before running
- Avoid very low cell counts on any axis (minimum 16–32 cells)
- Treat surface tension carefully in small-scale scenes
- Use wetting/contact controls for droplets sticking to colliders
- Increase VPM for final close-ups; lower it for preview