feat: add opt-in rasterization tiles

[stanbot8]

2 implementations exist. Both contain the same shared commit sequence. This implementation adds optional output tiles after the label dtype fix. The other implementation stops after the shared sequence and the label dtype fix with 1 output canvas. Compare the limitations.

Summary

Add optional output tiles to rasterization. tile_size=None keeps the current behavior. A positive tile_size limits each spatial output chunk. It also limits each Datashader canvas for points and shapes. This branch fixes the label-count failure. Closes #987.

Design

Images and labels pass bounded output chunks to the affine transform. Points use half-open internal tile bounds. Shapes use a 1-pixel halo and crop it. One spatial index selects the shapes for each tile. Sorted positions preserve Datashader first semantics.

The implementation changes src/spatialdata/_core/operations/rasterize.py.

Benchmark

The benchmark rasterized a 3 × 4096 × 4096 float32 image. The output size was 192 MiB. Each result was stored in a memory-mapped file with single-threaded Dask. The table shows medians from 7 runs on an Intel Core i7-8700K.

tile_size	Largest output chunk	Graph tasks	Median time	Time change	Peak RSS increase	RSS reduction
None	192 MiB	257	4.400 s	—	398.2 MiB	—
1024	12 MiB	756	4.009 s	-8.9%	221.2 MiB	44.5%
512	3 MiB	1220	3.682 s	-16.3%	216.2 MiB	45.7%
256	0.75 MiB	2628	4.500 s	+2.3%	218.5 MiB	45.1%

For this workload, tile_size=1024 reduced the peak RSS increase by 44.5%.

The image benchmark source and recorded results use candidate aab46d8ec96acb9213a51cd244397a12a2f0579f.

An indexed-shape benchmark used 4096 shapes and 64 tiles. The index reduced the Datashader input from 262145 to 5042 rows (98.1%). It reduced the largest tile input from 4096 to 81 shapes (98.0%). The median time fell from 1.443 s to 0.957 s (33.7%). Both outputs had the same checksum. See the shape benchmark source and recorded results.

Benchmark commands

uv run python benchmarks/benchmark_rasterize_tiling.py --size 4096 --repeats 7 --tile-size 0
uv run python benchmarks/benchmark_rasterize_tiling.py --size 4096 --repeats 7 --tile-size 1024
uv run python benchmarks/benchmark_rasterize_tiling.py --size 4096 --repeats 7 --tile-size 512
uv run python benchmarks/benchmark_rasterize_tiling.py --size 4096 --repeats 7 --tile-size 256

Limitations

Smaller tiles create more graph tasks. A shape that crosses tile boundaries is rendered in each intersecting tile.

Tests

Raster tests verify bounded chunks for 2D images, 2D labels, and 3D multiscale images. Point tests cover internal tile edges, global maximum bounds, and uneven tile sizes. Shape tests cover overlaps and categorical channels. Each tiled result is identical to the untiled result.

The rasterization test file passes with 14 tests. The complete suite passes with 1371 tests, 7 skips, and 1 expected failure.

The tests are in tests/core/operations/test_rasterize.py.

Commands

python -m pytest tests/core/operations/test_rasterize.py -q
python -m pytest --cov --color=no -n auto --dist worksteal -q
ruff check src/spatialdata/_core/operations/rasterize.py tests/core/operations/test_rasterize.py
ruff format --check src/spatialdata/_core/operations/rasterize.py tests/core/operations/test_rasterize.py

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.55%. Comparing base (eb4fb3d) to head (aab46d8).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1166      +/-   ##
==========================================
+ Coverage   92.44%   92.55%   +0.11%     
==========================================
  Files          51       51              
  Lines        7820     7900      +80     
==========================================
+ Hits         7229     7312      +83     
+ Misses        591      588       -3     

Files with missing lines	Coverage Δ
src/spatialdata/_core/operations/rasterize.py	92.85% <100.00%> (+2.25%)	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.