Rendering Backends¶

Hakowan supports multiple rendering backends, allowing you to choose the renderer that best suits your needs. Three backends are available: WebGL (interactive browser viewer), Mitsuba (photorealistic), and Blender (Cycles/EEVEE). WebGL ships with the base install and is used by default; Mitsuba and Blender are optional extras (pip install hakowan[mitsuba] / pip install hakowan[blender]).

Available Backends¶

Mitsuba Backend¶

The Mitsuba backend is based on the Mitsuba 3 physically-based rendering system, which provides high-quality, photorealistic rendering with advanced lighting and material models. It is an optional extra — install it with pip install hakowan[mitsuba].

Advantages: - High-quality photorealistic rendering - Fast rendering with GPU acceleration - Support for advanced materials and lighting

Requirements: - Install the mitsuba extra (pip install hakowan[mitsuba])

Usage:

import hakowan as hkw

layer = hkw.layer("mesh.obj")
hkw.render(layer, filename="output.exr", backend="mitsuba")

Blender Backend¶

The Blender backend uses Blender's rendering engine through the bpy Python API. This backend is useful if you want to leverage Blender's rendering capabilities or integrate Hakowan into a Blender-based workflow.

Advantages: - Integration with Blender ecosystem - Access to Blender's Cycles and EEVEE rendering engines - Can save Blender scene files (.blend) for further editing - Supports render passes: albedo, depth, normal, facet ID

Requirements: - Install the blender extra (pip install hakowan[blender]); requires Python 3.13

Usage:

import hakowan as hkw

layer = hkw.layer("mesh.obj")
# Explicitly specify Blender backend
hkw.render(layer, filename="output.png", backend="blender")

# Optionally save the Blender scene file
hkw.render(
    layer,
    filename="output.png",
    backend="blender",
    blend_file="scene.blend"
)

WebGL Backend¶

The WebGL backend generates an interactive HTML viewer using three.js and glTF 2.0. The scene data is embedded in the HTML. By default, the viewer imports version-pinned Three.js modules from unpkg; offline=True writes those modules into a sibling asset directory instead. WebGL ships with the base install and is the default backend.

Advantages: - Default backend — ships with the base install - Immediate interactive browser output - Embedded glTF scene data - Optional offline module bundle - Live albedo, depth, and normal passes - Deterministic headless snapshots with hakowan[observe]

Requirements: - Interactive viewer: none beyond the base install and a modern browser - snapshot() / observe(): pip install "hakowan[observe]" followed by playwright install chromium

Usage:

import hakowan as hkw

layer = hkw.layer("mesh.obj")
hkw.render(layer, filename="output.html", backend="webgl")

Background:

The beauty view uses a soft "studio" radial gradient — a bright spot in the centre falling off towards the edges. Two presets are available via the background option:

hkw.render(layer, filename="output.html", backend="webgl", background="dark")   # default
hkw.render(layer, filename="output.html", backend="webgl", background="light")

The background option only sets the initial look. The interactive viewer includes a small ☀ / ☾ button (top-right) to toggle light/dark at any time. Transparent materials (e.g. ThinDielectric glass) refract whichever background is active.

Render result¶

Regardless of backend, hkw.render() returns a RenderResult:

result = hkw.render(layer, filename="output.png")

result.path       # main output path, or None if no filename was given
result.image      # in-memory image (Mitsuba only); None for Blender/WebGL
result.outputs    # manifest: {"main": ..., "<pass>": <path or "interactive">}
result.backend    # name of the backend that produced the result

result.outputs lists every artifact the render produced, including per-pass sidecars (see render passes). A RenderResult is also path-like, so it can be passed straight to open() or pathlib.Path when a main output file was written. For notebook display, use result.image (Mitsuba).

Backend Management¶

List Available Backends¶

You can query which backends are currently available:

import hakowan as hkw

backends = hkw.list_backends()
print(f"Available backends: {backends}")
# Output: Available backends: ['blender', 'mitsuba', 'webgl']

WebGL is always listed (it is part of the base install); Mitsuba and Blender appear only when their extras (hakowan[mitsuba] / hakowan[blender]) are installed.

Inspect Backend Capabilities¶

Capability declarations can be queried without importing heavyweight backend modules:

caps = hkw.backend_capabilities("webgl")
print(caps.marks)
print(caps.render_passes)
print(caps.features)
print(caps.limitations)

# JSON-safe form; includes declarations for unavailable optional backends too.
payload = caps.to_dict()
all_capabilities = hkw.list_backend_capabilities()

hkw.validate(layer, backend=..., strict=True) uses these declarations to reject requested behavior that the selected backend would approximate or ignore.

Set Default Backend¶

When backend= is not given, Hakowan defaults to WebGL — its dependency ships with the base install, so it is always available. The heavier Mitsuba and Blender backends are never auto-selected; request them explicitly per render with backend=, or change the process-wide default with set_default_backend().

You can change the default backend for all subsequent render calls:

import hakowan as hkw

# Make Mitsuba the default backend
hkw.set_default_backend("mitsuba")

# Now this will use Mitsuba
layer = hkw.layer("mesh.obj")
hkw.render(layer, filename="output.png")

# You can still override per render call
hkw.render(layer, filename="output.html", backend="webgl")

Backend-Specific Options¶

Different backends may support different options passed as keyword arguments to hkw.render().

Mitsuba Backend Options¶

# Save Mitsuba scene configuration to YAML
hkw.render(
    layer,
    filename="output.exr",
    backend="mitsuba",
    yaml_file="scene.yaml"
)

Blender Backend Options¶

# Use EEVEE instead of Cycles (faster)
hkw.render(
    layer,
    filename="output.png",
    backend="blender",
    engine="BLENDER_EEVEE"
)

# Save Blender scene file for further editing
hkw.render(
    layer,
    filename="output.png",
    backend="blender",
    blend_file="scene.blend"
)

WebGL Backend Options¶

# Default: compact HTML that imports Three.js from the pinned CDN URL.
hkw.render(layer, filename="output.html", backend="webgl")

# Portable offline folder: output.html + output_assets/.
hkw.render(
    layer,
    filename="output.html",
    backend="webgl",
    offline=True,
)

The first offline build downloads the pinned core, controls, geometry utilities, and environment-map loader dependencies into ~/.cache/hakowan/three/ and verifies their SHA-256 digests. Subsequent bundles are copied from that cache. See Snapshot and observation for deterministic PNG capture.

Choosing a Backend¶

Use Mitsuba when: - You want high-quality photorealistic rendering - You need fast rendering with GPU acceleration - You're creating publication-quality visualizations

Use Blender when: - You want Cycles or EEVEE rendering with Blender materials - You want to further edit the scene in Blender - You need render passes (albedo, depth, normal, facet ID)

Use WebGL when: - You want an interactive, shareable viewer in a browser - You need fast turnaround with no render time - You're embedding visualizations in web pages or notebooks

Troubleshooting¶

If a backend is not available, hkw.list_backends() will simply omit it. You can check which optional dependencies are missing:

pip install hakowan[mitsuba]  # enables the Mitsuba backend
pip install hakowan[blender]  # enables the Blender backend (Python 3.13)

The WebGL backend is part of the base install and is always available.