Leaf table manipulations#

This section focusses on working with existing scenes rather than generating new ones.

In deadleaves, each scene is represented by a leaf table: a pandas DataFrame where each row contains a single leaf’s geometry parameters (and optionally appearance). The LeafTopology class treats this table as a mutable scene description, allowing you ti rebuild or modify segmentation maps directly from the stored parameters - without resampling leaves.

LeafTopology is designed for advanced workflows where scenes need to be edited, combined, or reinterpreted after generation, Typical use cases include merging independently generated scenes, changing occlusion order by reassigning leaf_idx, applying transformations or motion to existing leaves, and editing or relabeling individual leaves.

(Re)Construct a segmentation map#

A segmentation map can always be reconstructed from a leaf table.

Rebuilding the segmentation is useful whenever the table changes or is reused in a new context. For example, you might load a previously saved table from disk, edit leaf parameters such as position or size, merge multiple scenes into a composite structure, or generate a sequence of frames where leaves move over time. In all of these cases, the geometry does not need to be resampled — the segmentation is simply recomputed from the updated table.

This separation lets you treat the leaf table as an editable scene graph and the segmentation as an implementation of that graph.

topology = LeafTopology(image_shape=(512,512))
segmentation_map = topology.segmentation_map_from_table(leaf_table)

This feature is in particular used if a leaf table is passed to the ImageRenderer without a segmentation map.

Example: Circular motion

Show code cell source

Hide code cell source

import pandas as pd
import torch

import matplotlib.pyplot as plt
from matplotlib import animation
from IPython.display import HTML

from deadleaves import (
    LeafGeometryGenerator,
    LeafAppearanceSampler,
    ImageRenderer,
    LeafTopology,
)

image_shape = (512, 512)
area = image_shape[0] * image_shape[1]

geometry = LeafGeometryGenerator(
    leaf_shape="circular",
    shape_param_distributions={
        "area": {"uniform": {"low": area * 0.005, "high": area * 0.01}},
    },
    image_shape=image_shape,
    n_sample=250,
    position_mask={
        "shape": "circular",
        "params": {
            "area": area * 0.35,
        },
    },
)

leaf_table, segmentation_map = geometry.generate_segmentation()

color_params = {
    "H": {"uniform": {"low": 0.0, "high": 0.2}},
    "S": {"uniform": {"low": 0.0, "high": 1.0}},
    "V": {"uniform": {"low": 0.0, "high": 1.0}},
}

appearance = LeafAppearanceSampler(
    leaf_table=leaf_table,
)

table = appearance.sample_color(color_param_distributions=color_params)

def apply_circular_motion(
    leaf_table: pd.DataFrame,
    image_size: tuple[int, int] | torch.Size,
    angle_step: float,
    angular_jitter: float = 0.0,
    radial_jitter: float = 0.0,
) -> pd.DataFrame:

    table = leaf_table.copy()

    cy = image_size[0] / 2
    cx = image_size[1] / 2

    x = torch.tensor(table["x_pos"]) - cx
    y = torch.tensor(table["y_pos"]) - cy

    # convert to Polar coordinates
    r = torch.sqrt(x**2 + y**2)
    theta = torch.arctan2(y, x)

    # update angle
    theta += angle_step
    if angular_jitter > 0:
        theta += torch.distributions.normal.Normal(0.0, angular_jitter).sample((len(theta),))

    # update radius
    if radial_jitter > 0:
        r += torch.distributions.normal.Normal(0.0, radial_jitter).sample((len(r),))
        r = torch.clip(r, 0.0, None)

    # back to Cartesian coordinates
    table["x_pos"] = cx + r * torch.cos(theta)
    table["y_pos"] = cy + r * torch.sin(theta)

    return table


frames = []
for t in range(10):
    table = apply_circular_motion(
        leaf_table=table,
        image_size=segmentation_map.shape,
        angle_step=torch.pi / 10,
        angular_jitter=0.1,
    )

    renderer = ImageRenderer(
        leaf_table=table,
        image_shape=image_shape,
        background_color=torch.tensor(1.0),
    )
    image = renderer.render_image()
    frames.append(image.cpu())


fig, ax = plt.subplots(figsize=(3, 3))
im = ax.imshow(frames[0])
ax.axis("off")
ax.set_position((0.0, 0.0, 1.0, 1.0))


def update(i):
    im.set_data(frames[i])
    return [im]


ani = animation.FuncAnimation(
    fig,
    update,
    frames=len(frames),
    interval=100,
    blit=True,
)

plt.close(fig)
HTML(ani.to_jshtml())

Merge leaf tables#

Merging leaf tables allows you to combine multiple independently generated dead leaves scenes into a single composite scene. The operation concatenates all rows, preserves every geometric and appearance attribute, and assigns a consistent leaf_idx so that the combined scene has a valid global occlusion order.

This is useful when different parts of a scene should follow different statistics or roles. For example, you might generate one table describing a structured proto-object and another describing background clutter, then merge them to create a scene where both regimes coexist. Because all attributes are preserved, the merged table still contains the full parametric description of every leaf and can immediately be turned back into a segmentation map.

Example: Merging images with different appearances

../_images/2bdce58107c6316af9a3b2d04c317f186bbdfff7f19f84f254c15988d11c155f.png

Reassign leaf indices#

Leaf indices (leaf_idx) determine occlusion order and therefore control which leaves appear in front of others. Reassigning indices lets you modify depth structure without changing any geometric or appearance parameters. This is useful for generating control conditions, testing robustness to layering, or reorganizing scenes while preserving semantic grouping.

Several index operations are available depending on how much structure you want to keep.

Global randomization#

The method ignores all prior structure and shuffles depth across the entire scene. All attributes are preserved, but layering becomes fully random.

randomized_table = LeafTopology.randomize_index(leaf_table, seed=42)

Example: Shuffle leaf depth

---------------------------------------------------------------------------
RuntimeError                              Traceback (most recent call last)
Cell In[3], line 25
     21 colormodel = LeafAppearanceSampler(leaf_table)
     22 colormodel.sample_color(color_params)
     23 
     24 renderer = ImageRenderer(colormodel.leaf_table, segmentation_map)
---> 25 renderer.render_image()
     26 
     27 randomized_table = LeafTopology.randomize_index(colormodel.leaf_table)
     28 renderer_randomized = ImageRenderer(randomized_table, image_shape=image_shape)

File ~/checkouts/readthedocs.org/user_builds/deadleaves/checkouts/latest/deadleaves/deadleaves.py:967, in ImageRenderer.render_image(self)
    963 lut = torch.zeros(max_idx + 1, 3, device=self.device)
    965 # Map each leaf's colour into its leaf_idx row.
    966 # leaf_table row i has leaf_idx = leaf_indices[i], colour = colors[i].
--> 967 lut[leaf_indices] = colors
    969 # Single gather: paint the entire image at once
    970 seg = self.segmentation_map.to(dtype=torch.long, device=self.device)

File ~/checkouts/readthedocs.org/user_builds/deadleaves/envs/latest/lib/python3.12/site-packages/torch/utils/_device.py:122, in DeviceContext.__torch_function__(self, func, types, args, kwargs)
    120 if func in _device_constructors() and kwargs.get("device") is None:
    121     kwargs["device"] = self.device
--> 122 return func(*args, **kwargs)

RuntimeError: Index put requires the source and destination dtypes match, got Float for the destination and Double for the source.

Reindex by group#

This method reindexes or shuffles depth locally within semantic groups, defined in one of the table columns. This preserves object-level structure but varies internal layering. Useful if you want a certain set of leaves in the foreground.

shuffled = LeafTopology.reindex_by_group(
    leaf_table, 
    groupby="type", 
    shuffle=True, 
    group_order="ascending", 
    seed=42
    )

Example: Order leaves by shape