Compile¶

The compile function is responsible for converting a layer specification into a renderable scene. This function is automatically called by hkw.render(), but can also be used directly for advanced workflows or debugging.

Overview¶

The compilation process transforms the high-level declarative layer specification into a low-level scene representation that can be rendered by a backend. During compilation, Hakowan:

Flattens the layer tree into individual views
Applies all transforms to the data
Processes channels and applies scales
Generates geometry and attributes for rendering
Computes the global scene transformation

Basic Usage¶

import hakowan as hkw

# Create a layer
layer = hkw.layer("mesh.obj").mark(hkw.mark.Surface)

# Compile the layer into a scene
scene = hkw.compile(layer)

# The scene can then be rendered
# (normally you would just call hkw.render() which does both)

When to Use Compile Directly¶

In most cases, you don't need to call compile() directly because hkw.render() does it automatically. However, there are scenarios where direct compilation is useful:

Debugging and Inspection¶

You can compile a layer to inspect the resulting scene without rendering:

import hakowan as hkw

layer = hkw.layer("mesh.obj")
scene = hkw.compile(layer)

# Inspect the compiled scene
print(f"Number of views: {len(scene.views)}")
for i, view in enumerate(scene):
    print(f"View {i}: {view.mark}, {view.data_frame.mesh.num_vertices} vertices")

Custom Rendering Workflows¶

If you're building a custom rendering pipeline or integrating Hakowan with other tools:

import hakowan as hkw

layer = hkw.layer("mesh.obj")
scene = hkw.compile(layer)

# Access the compiled mesh data
for view in scene:
    mesh = view.data_frame.mesh
    # Process mesh data with custom tools
    # ...

Testing and Validation¶

When writing tests or validating layer specifications:

import hakowan as hkw

def test_layer_compilation():
    layer = hkw.layer("mesh.obj").mark(hkw.mark.Surface)
    scene = hkw.compile(layer)

    assert len(scene.views) == 1
    assert scene.views[0].mark == hkw.mark.Surface

Compilation Process¶

The compilation process consists of several stages:

Layer Tree Condensation: The layer tree is flattened into individual views, where each path from root to leaf becomes a view.
Transform Application: All transforms specified in each view are applied to the data frame.
Channel Preprocessing: Channels are preprocessed and default values are assigned.
Channel Processing: Channels are processed, scales are applied, and attributes are computed.
Data Frame Finalization: The data frame is finalized and prepared for rendering.
Global Transform Computation: The global scene transformation is computed.

Scene Object¶

The result of compilation is a Scene object that contains:

views: A list of View objects, each representing a compiled layer
global_transform: The global transformation matrix applied to the entire scene

Each View object contains:

data_frame: The processed mesh data and attributes
mark: The mark type (Point, Curve, or Surface)
channels: The processed channels
material_channel: The material specification
transform: The transform chain applied to this view
global_transform: The global transformation for this view

Example: Multi-Layer Compilation¶

import hakowan as hkw

mesh = lagrange.io.load_mesh("shape.obj")
base = hkw.layer(mesh)

# Create multiple layers
surface = base.mark(hkw.mark.Surface)
wireframe = base.mark(hkw.mark.Curve).channel(size=0.01)
vertices = base.mark(hkw.mark.Point).channel(size=0.05)

# Combine layers
combined = surface + wireframe + vertices

# Compile - this creates 3 views
scene = hkw.compile(combined)

print(f"Total views: {len(scene.views)}")
# Output: Total views: 3