Render

Render a layer using the specified backend.

Parameters:

Name	Type	Description	Default
root	Layer	Root layer to render.	required
config	Config | None	Rendering configuration. If None, uses default.	None
filename	Path | str | None	Output filename.	None
backend	BackendName | None	Backend name — "webgl" (ships with the base install), "mitsuba", or "blender". If None, uses the configured default, which is "webgl" unless changed via :func:set_default_backend. The heavier Mitsuba and Blender backends must be requested explicitly.	None
**kwargs	Any	Backend-specific keyword arguments forwarded verbatim to the chosen backend (e.g. background / title for WebGL, yaml_file for Mitsuba, blender_engine / blend_file for Blender). Unknown keys raise TypeError.	{}

Returns:

Name	Type	Description
A	RenderResult	class:RenderResult bundling the in-memory image (Mitsuba), the
	RenderResult	main output path, and the outputs manifest (per-pass sidecar
	RenderResult	files, or "interactive" for the WebGL viewer).

Examples:

>>> import hakowan as hkw
>>> layer = hkw.layer(mesh)
>>> result = hkw.render(layer, filename="output.png")
>>> result.path            # PosixPath('output.png')
>>> result.outputs         # {'main': PosixPath('output.png'), ...}
>>> # Mitsuba: display the rendered image in a notebook
>>> result.image

Source code in hakowan/render/__init__.py

def render(
    root: layer.Layer,
    config: Config | None = None,
    filename: Path | str | None = None,
    backend: BackendName | None = None,
    **kwargs: Any,
) -> RenderResult:
    """Render a layer using the specified backend.

    Args:
        root: Root layer to render.
        config: Rendering configuration. If None, uses default.
        filename: Output filename.
        backend: Backend name — ``"webgl"`` (ships with the base install),
            ``"mitsuba"``, or ``"blender"``. If ``None``, uses the configured
            default, which is ``"webgl"`` unless changed via
            :func:`set_default_backend`. The heavier Mitsuba and Blender
            backends must be requested explicitly.
        **kwargs: Backend-specific keyword arguments forwarded verbatim to the
            chosen backend (e.g. ``background`` / ``title`` for WebGL,
            ``yaml_file`` for Mitsuba, ``blender_engine`` / ``blend_file`` for
            Blender). Unknown keys raise ``TypeError``.

    Returns:
        A :class:`RenderResult` bundling the in-memory ``image`` (Mitsuba), the
        main output ``path``, and the ``outputs`` manifest (per-pass sidecar
        files, or ``"interactive"`` for the WebGL viewer).

    Examples:
        >>> import hakowan as hkw
        >>> layer = hkw.layer(mesh)
        >>> result = hkw.render(layer, filename="output.png")
        >>> result.path            # PosixPath('output.png')
        >>> result.outputs         # {'main': PosixPath('output.png'), ...}
        >>> # Mitsuba: display the rendered image in a notebook
        >>> result.image
    """
    # Compile the layer tree into a scene
    scene = compile(root)
    logger.info("Compilation done")

    # Get config
    if config is None:
        config = Config()

    # Get backend and render
    backend_name = resolve_backend_name(backend)
    logger.info(f"Using backend: {backend_name}")
    backend_impl = get_backend(backend_name)

    # Warn about any requested render pass the chosen backend cannot honor,
    # rather than silently dropping it. Capability is declared per backend via
    # RenderBackend.SUPPORTED_PASSES.
    supported = {p.name for p in backend_impl.SUPPORTED_PASSES}
    unsupported = config.render_passes - supported
    if unsupported:
        logger.warning(
            f"The '{backend_name}' backend does not support render pass(es) "
            f"{sorted(unsupported)}; they will be ignored. "
            f"Supported passes: {sorted(supported)}."
        )

    raw = backend_impl.render(scene, config, filename, **kwargs)

    # Normalize the backend's primary return into a RenderResult. Mitsuba
    # returns an in-memory image; file backends (Blender/WebGL) return the path
    # they actually wrote, or None. Prefer the backend-reported path — the
    # WebGL backend rewrites the suffix to ``.html``, so its returned path is
    # the truthful main output, not the user's *filename*.
    image = raw if not isinstance(raw, (str, Path)) else None
    if isinstance(raw, (str, Path)):
        path: Path | None = Path(raw)
    elif filename is not None:
        path = Path(filename)
    else:
        path = None

    # Surface the produced artifacts so the user does not have to guess which
    # sidecar files appear (or that passes are live in the viewer instead).
    manifest = _manifest_for(backend_impl, config, path)
    if manifest:
        logger.info(
            "Render outputs: " + ", ".join(f"{k}={v}" for k, v in manifest.items())
        )

    return RenderResult(backend=backend_name, outputs=manifest, image=image, path=path)

RenderResult

hkw.render() returns a RenderResult bundling the in-memory image (Mitsuba), the main output path, and the manifest of all files produced (including per-pass sidecars).

The outcome of a :func:render call.

Attributes:

Name	Type	Description
backend	BackendName	Name of the backend that produced this result.
outputs	dict[str, Path | str]	Manifest mapping "main" and each honored render pass to its artifact — a :class:~pathlib.Path for file backends, or the string "interactive" for viewer backends (WebGL). Empty when nothing was written to disk (filename was None).
image	Any	The in-memory rendered image when the backend produces one (Mitsuba); None otherwise. Use this for notebook display.
path	Path | None	The main output path when written to disk; None otherwise.

The object is also a :pep:519 path-like (__fspath__), so it can be passed straight to open(), :class:~pathlib.Path, etc. when a main output file was written.

Source code in hakowan/render/__init__.py

@dataclass
class RenderResult:
    """The outcome of a :func:`render` call.

    Attributes:
        backend: Name of the backend that produced this result.
        outputs: Manifest mapping ``"main"`` and each *honored* render pass to
            its artifact — a :class:`~pathlib.Path` for file backends, or the
            string ``"interactive"`` for viewer backends (WebGL). Empty when
            nothing was written to disk (``filename`` was ``None``).
        image: The in-memory rendered image when the backend produces one
            (Mitsuba); ``None`` otherwise. Use this for notebook display.
        path: The main output path when written to disk; ``None`` otherwise.

    The object is also a :pep:`519` path-like (``__fspath__``), so it can be
    passed straight to ``open()``, :class:`~pathlib.Path`, etc. when a main
    output file was written.
    """

    backend: BackendName
    outputs: dict[str, Path | str] = field(default_factory=dict)
    image: Any = field(default=None, repr=False)
    path: Path | None = None

    def __fspath__(self) -> str:
        if self.path is None:
            raise TypeError(
                "RenderResult has no output path "
                "(render() was called without a filename)."
            )
        return str(self.path)

Related Functions

set_default_backend

Set the default rendering backend for subsequent render calls.

import hakowan as hkw

# Set Blender as default
hkw.set_default_backend("blender")

# All subsequent renders will use Blender unless overridden
hkw.render(layer, filename="output.png")

Set the default rendering backend.

Parameters:

Name	Type	Description	Default
name	BackendName	Backend name.	required

Raises:

Type	Description
ValueError	If backend is not registered.

Source code in hakowan/backends/__init__.py

def set_default_backend(name: BackendName):
    """Set the default rendering backend.

    Args:
        name: Backend name.

    Raises:
        ValueError: If backend is not registered.
    """
    global _default_backend
    if name not in _backends and name not in _backend_loaders:
        raise ValueError(f"Unknown backend: {name}. Available: {list_backends()}")
    _default_backend = name

list_backends

List all available rendering backends.

import hakowan as hkw

backends = hkw.list_backends()
print(backends)
# Output: ['blender', 'mitsuba', 'webgl']

List the rendering backends whose dependencies are installed.

Availability is probed without importing the heavy backend modules.

Source code in hakowan/backends/__init__.py

def list_backends() -> list[str]:
    """List the rendering backends whose dependencies are installed.

    Availability is probed without importing the heavy backend modules.
    """
    names = set(_backends) | set(_backend_loaders)
    return sorted(n for n in names if _is_available(n))