Physics-Based Image Generation

juspice.shape_based is the physics-based part of JuSPICE’s synthetic data toolkit. It builds synthetic microscopy images out of simple shapes — round, Gaussian-intensity particle blobs and wavy crack lines, plus configurable noise — with no trained model and no GPU required.

Overview

Since these images are built by drawing shapes directly, JuSPICE knows exactly where every shape is — so the mask (which pixels belong to which object) is always exact, never guessed. That makes this method well suited for:

  • checking how well a segmentation algorithm performs,

  • generating labeled training data for supervised learning,

  • checking that a feature-extraction pipeline works correctly.

Typical usage

All physics-based generation methods are accessed through the ShapeBasedAccessor via spice.shape_based. Start by loading a real image as the background, then chain drawing calls in-place:

from juspice.io import load_data, save_data

spice = load_data("background.png")

# Initialise a drawing session (sets canvas size from the background)
spice.shape_based.create(
    width=512, height=512,
    background_img_path="background.png",
)

# Add shapes — all calls mutate spice.data in place
spice.shape_based.generate_gaussian_circles(
    lighting_mode="dark", num_objects=50, radii=(5, 30),
)
spice.shape_based.generate_wiggly_cracks(
    crack_type="polynomial", num_cracks=5, length=150,
)

# Derive a multi-frame sequence (returns a new SPICEData)
frame_spice = spice.shape_based.generate_sequence(num_objects=10)

save_data(spice)

Every accessor call is automatically recorded into spice.history with its runtime argument values, making the pipeline fully reproducible via to_lines() or to_script().

Reproducibility

Physics-based generation calls inside a Tracker recording block are captured verbatim in the session-level _history.py. The <stem>.json sidecar records every spice.shape_based.* call and its parameters via DatasetHistory.

See also