SBH Simulator

sbh-simulator is a toolkit for simulating serial blockface histology (SBH) acquisitions. It generates synthetic illumination inhomogeneity, splits images into overlapping mosaic grids, and includes a U-Net-based model to estimate vignettes from collections of affected images. It provides:

• Gaussian and Zernike-polynomial vignette generators
• Mosaic-grid assembly with configurable overlap and per-tile shading
• PyTorch Dataset classes for tiles, mosaic grids, and random tile pairs
• A U-Net-based illumination predictor with Lightning training modules
• Three CLI entry points: sbh-simulate, sbh-train, and sbh-vignette

Figure: Mosaic grid generated with 20 % overlap and Gaussian vignetting.

Requirements

• Python ≥ 3.14
• uv (recommended) or pip

GPU training is supported on Linux via CUDA 13.2. macOS and Windows use CPU-only PyTorch.

Getting Started

Installation

Clone the repository and install in editable mode with development dependencies:

git clone https://github.com/linum-uqam/sbh_simulator.git
cd sbh_simulator
uv sync --group dev

Optionally install the pre-commit hooks (ruff + ty checks on every commit):

uv run pre-commit install

Simulate vignetting on an image

sbh-simulate input.tif output_mosaic.tif --tile_size 512 --overlap_fraction 0.2 --sigma 1.0

Argument	Default	Description
input_image	—	Path to the input image
output_image	—	Path for the output mosaic-grid image
--tile_size	512	Tile size in pixels
--overlap_fraction	0.2	Fractional overlap between adjacent tiles (0–1)
--sigma	1.0	Gaussian vignette sigma in normalised coordinates

Train the illumination predictor

sbh-train data/train/ data/valid/ --n_epochs 100 --batch_size 8 --n_gpus 1

Argument	Default	Description
train_dir	—	Directory containing training tile images (*.jpg)
valid_dir	—	Directory containing validation tile images (*.jpg)
--n_epochs	250	Number of training epochs
--batch_size	8	Mini-batch size
--lr	0.1	Learning rate
--n_gpus	1	Number of GPUs (0 for CPU)
--n_tiles_per_sample	5	Tiles per training sample
--num_workers	6	DataLoader worker processes

Training is logged via Weights & Biases when available. Set WANDB_DISABLED=true to fall back to a CSV logger with no W&B account required.

Generate vignette test fixtures

sbh-vignette is designed for CI pipelines in downstream projects that need synthetic ground-truth illumination fields without importing sbh-simulator as a Python dependency.

# 4 reproducible Gaussian vignettes → fixtures/*.npy
sbh-vignette gaussian --n 4 --size 256 --seed 42 --output fixtures/

# 4 Zernike vignettes saved as float32 TIFF
sbh-vignette zernike --n 4 --size 256 --seed 42 --format tiff --output fixtures/

Argument	Default	Description
kind	—	gaussian or zernike
--n	1	Number of vignettes to generate
--size	128	Side length in pixels
--seed	None	Integer seed for reproducible output
--output	.	Output directory (created if absent)
--format	npy	npy (NumPy array) or tiff (float32 TIFF)
--order	5	Max Zernike radial order (zernike only)

Output files are named <kind>_<index>.<ext> (e.g. gaussian_0.npy). Each path is printed to stdout, one per line, for easy shell consumption.

Illumination model overview — flat-field $S(x)$, dark-field $D(x)$, clean image, and the combined corrupted output $I \cdot S + D$ for both generator families:

Python API

from sbh_simulator import simulator

# Generate a single random Gaussian vignette (512 × 512 by default)
vignette = simulator.generate_gaussian_vignette()

# Generate a Zernike-polynomial vignette
vignette = simulator.generate_zernike_vignette()

# Generate a Gaussian dark-field (additive background, peak amplitude 5 %)
darkfield = simulator.generate_gaussian_darkfield(max_offset=0.05)

# Generate a Zernike dark-field
darkfield = simulator.generate_zernike_darkfield(max_offset=0.05)

# Apply the full BaSiC image formation model
corrupted = clean_image * vignette + darkfield

Dark-field represents the additive background component in the image degradation model — camera read-out offset, auto-fluorescence, or stray light — independent of the multiplicative flat-field. Both Gaussian and Zernike families are supported, with amplitude controlled by max_offset (fraction of the normalised intensity range). See the illumination overview figure in the CLI section above for a side-by-side comparison of flat-field, dark-field, and their combined effect.

Development

uv run ruff check          # lint
uv run ruff format --check # format (use --fix to apply)
uv run ty check            # type-check
uv run pytest              # tests

GPU-only tests are skipped by default. Run them with:

uv run pytest -m gpu

Publications

• Lefebvre, J. (2023). Exploring CNN-Based Self-Supervised Illumination Inhomogeneity Compensation for Serial Optical Coherence Tomography. 2023 IEEE 20th International Symposium on Biomedical Imaging (ISBI), 1–5. https://doi.org/10.1109/isbi53787.2023.10230803