Rendering And Analysis

This guide covers the rendering-side modules: what drives image generation, how terrain quality is configured, and where the lower-level helpers fit.

Viewer-First Rendering

For most users, forge3d rendering begins with the viewer:

  • open_viewer_async() launches the scene runtime

  • ViewerHandle applies terrain, camera, sun, overlay, and point-cloud changes

  • terrain_params and presets define reproducible scene settings

  • animation and camera_rigs automate camera motion

  • terrain_scatter adds deterministic terrain population and related helpers

This is the path behind most of the terrain, overlay, point-cloud, and camera examples in the repo.

Terrain Configuration

forge3d.terrain_params is the central configuration module for advanced terrain rendering. It groups settings into focused dataclasses such as:

  • lighting, shadows, fog, reflections, bloom, height AO, and sun visibility

  • material noise, POM, triplanar, and other terrain surface controls

  • LOD, sampling, clamp, denoise, and offline quality settings

  • terrain virtual-texture settings and overlay-related settings

Use it directly when you are building repeatable terrain render presets or feeding TerrainRenderer.

Native And Offscreen Rendering

forge3d exposes two lower-level rendering layers.

Scene

Use Scene when you want a compact native offscreen surface. It is suitable for image generation, quick experiments, and targeted feature testing.

Session + TerrainRenderer

Use this stack when you need the full terrain-native pipeline:

  • Session owns the native runtime context

  • MaterialSet defines terrain materials

  • IBL provides environment maps

  • TerrainRenderParams configures the terrain renderer

  • TerrainRenderer renders frames, AOVs, and offline accumulation passes

terrain_atmosphere_path_demo.py is the clearest example of this lower-level terrain path in the repo today.

Offline Accumulation And Denoise

forge3d.offline.render_offline() wraps the multi-batch accumulation flow around TerrainRenderer. Use it when you want progressive offline quality instead of a single interactive snapshot.

For the exact accumulation sequence, output contract, and denoise handoff, see terrain/offline-render-quality.md.

forge3d.denoise_oidn.oidn_denoise() applies CPU denoise to beauty buffers, optionally with albedo and normal guidance.

This pair is the main route for high-quality terrain output without building your own accumulation loop from scratch.

Geometry, Mesh, And Vector Helpers

These modules support scene construction before rendering:

  • forge3d.geometry: mesh generation, extrusion, subdivision, displacement, tangents, transforms, and validation

  • forge3d.mesh: TBN generation and mesh-side utilities

  • forge3d.io: DEM and mesh IO helpers

  • forge3d.vector: 2D vector scene primitives and rendering helpers

They are not just internal plumbing. They are the intended building blocks when you need to generate or preprocess geometry in Python before passing it into a viewer or export pipeline.

Path Tracing, SDF, And Lighting

forge3d also exposes lower-level rendering utilities outside the terrain viewer:

  • forge3d.path_tracing: path-tracing helpers and camera creation

  • forge3d.sdf: SDF primitives, builders, and scene helpers

  • forge3d.lighting: lower-level lighting and ReSTIR-oriented helpers

  • forge3d.materials and forge3d.textures: material containers and supporting wrappers

These modules are more specialized than the viewer workflow, but they are part of the public package surface and documented in the API reference.

Diagnostics And Device Utilities

Use the top-level helpers and forge3d.mem when you need environment or memory information:

  • has_gpu(), enumerate_adapters(), device_probe(), get_device()

  • memory_metrics(), budget_remaining(), utilization_ratio()

These are useful when a script needs to decide between a viewer path, a native offscreen path, or a pure-Python fallback.

device_probe() never raises. It always returns a dict whose status field is one of:

  • "ok" — an adapter was found; the dict carries name, backend, device_type, and software_fallback (True when the adapter is a software rasterizer such as WARP or lavapipe).

  • "no_adapter" — the native module works but no hardware or software adapter is exposed for the requested backends.

  • "probe_error" — the probe itself failed; reason carries the exception.

  • "native_missing" — the compiled forge3d._forge3d extension did not import; reason preserves the original import error.

Every non-"ok" result includes reason and remediation fields, so scripts can branch or report without string-matching exception text.

If the native module fails to import

When forge3d._forge3d cannot be imported (missing DLL, ABI mismatch, wheel built for another interpreter), native-only names such as Scene, TerrainRenderer, and Session are absent from the package. Accessing one raises an AttributeError that preserves the root cause instead of a bare name error:

forge3d.Scene requires the native extension, but the compiled extension
forge3d._forge3d failed to import: ImportError('DLL load failed ...').
Reinstall the wheel (pip install --force-reinstall forge3d) or rebuild from a
checkout with: maturin develop --release

Call forge3d.native_import_error() to retrieve the original import exception programmatically, and device_probe() to get the same information as a structured "native_missing" result.

If no GPU adapter is found

GPU acquisition never panics. forge3d first requests a hardware adapter and, when none exists, automatically retries with the platform’s software fallback adapter (WARP on Windows, Mesa’s lavapipe on Linux) so headless hosts keep working — engine_info()["software_fallback"] reports honestly when the software path is in use, and a warning is logged. Only when even the software fallback is unavailable do GPU-touching calls raise a catchable RuntimeError:

[Device] Device error: No suitable GPU adapter found (backends tried: DX12 |
VULKAN | ...; WGPU_BACKENDS/WGPU_BACKEND not set). A hardware adapter was not
found and the software fallback adapter is also unavailable. Verify GPU
drivers are installed, pin a backend via WGPU_BACKENDS (vulkan|dx12|metal|gl),
or install a software rasterizer for headless use (Windows ships WARP; on
Linux install Mesa's lavapipe).

Example Map

  • triangle_png.py: minimal native renderer sanity check

  • terrain_atmosphere_path_demo.py: full terrain-native rendering stack

  • camera_animation_demo.py: animation plus viewer-driven frame export

  • terrain_camera_rigs_demo.py: camera-rig automation on top of the viewer

  • pnoa_river_showcase_video.py: terrain composition plus cinematic output