feat: Auto-detect parallel mode, fix overlap-based RAM estimation

[hongquanli]

Summary

• Auto-detect parallel mode based on file format (disabled for single-file OME-TIFF due to I/O contention)
• Fix RAM estimation to use actual overlap region size (was 5-10x over-conservative)
• Add hybrid batching: simple path when memory fits, batched when >30% RAM needed
• Use configurable max_workers instead of hardcoded values
• Add worker count logging for transparency

Benchmark Results

Test Datasets

Format	Tiles	Tile Size	Channels	Overlap	Pairs	Total Data
Zarr	70	2084×2084	4	~10%	120	~2.3 GB
Individual TIFFs	211	2040×2040	5	~61%	368	~8.4 GB
OME-TIFF	609	1080×1280	1	~3%	1168	~1.6 GB

Registration Performance (8 workers)

Format	Parallel	Sequential	Speedup
Zarr	6.5s	26s	4.0× ✅
Individual TIFFs	11.5s	37s	3.2× ✅
OME-TIFF	30s	22s	0.6× ❌

OME-TIFF is slower with parallel due to single-file I/O contention → auto-disabled

Test plan

• Run pytest tests/test_registration.py - all 13 tests pass
• Test with real datasets (Zarr, individual TIFFs, OME-TIFF)
• Verify auto-detection correctly enables/disables parallel mode

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR optimizes parallel tile registration by introducing smart RAM management and format-based auto-detection. The key improvement is fixing the RAM estimation to use actual overlap region sizes instead of full tile sizes, which reduces memory requirements by 5-10x. The PR adds a hybrid batching approach that switches to batched processing only when memory usage exceeds 30% of available RAM, and auto-detects whether to enable parallel processing based on file format to avoid I/O contention in single-file OME-TIFF.

• Auto-detect parallel mode based on file format (disabled for single-file OME-TIFF due to I/O contention)
• Fix RAM estimation to calculate actual overlap region size instead of full tile size
• Add hybrid batching that only activates when estimated memory exceeds 30% of RAM

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
tests/test_registration.py	Adds new test class TestOverlapBoundsSize to verify that overlap regions are correctly calculated and much smaller than full tiles
src/tilefusion/core.py	Implements auto-detection for parallel mode, fixes RAM estimation to use actual overlap bounds, adds hybrid batching logic, and uses configurable _max_workers throughout

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.