feat: utility modules, preprocessing improvements, galvo correction

[FIrgolitsch]

Stacked PR 2/18 — review order: #115 → #97 → #98 → #99 → #100 → #101 → #108 → #106 → #107 → #87 → #116 → #110 → #111 → #40 → #112 → #113 → #117 → #118

Base: pr-a-build-tooling (#115). Retargets to main as upstream PRs merge.

---

PR #97 — Utility Modules, Preprocessing & Core Library Improvements

General-purpose library and script improvements that the feature PRs (#98–#101) build on. Two commits: the initial addition and a follow-up that refines registration, mosaic-grid generation, and adds rehoming detection.

New library modules

• linumpy/preproc/normalization.py — intensity normalization (percentile / rolling-ball / per-slice) used by both CPU and GPU paths
• linumpy/preproc/resampling.py — resampling utilities shared by linum_resample_mosaic_grid.py and the GPU equivalents
• linumpy/utils/image_quality.py — image-quality metrics (variance, sharpness, edge score)
• linumpy/utils/orientation.py — orientation utilities (axis swaps, flips, orientation-code parsing)
• linumpy/utils/visualization.py — preview / annotation helpers used by AIP and screenshot scripts

New scripts

• linum_fix_galvo_shift_zarr.py — galvo-shift correction for OME-Zarr volumes
• linum_clean_raw_data.py — raw-data cleaning / curation
• linum_compare_stitching.py — A/B comparison of two stitching runs
• linum_extract_pyramid_levels.py — extract specific levels from an OME-Zarr pyramid
• linum_normalize_z_intensity.py — per-slice z-axis intensity normalization
• linum_aip_png.py — average-intensity projection with PNG output + annotations
• linum_screenshot_omezarr_annotated.py — annotated OME-Zarr screenshots for reports
• linum_generate_mosaic_aips.py — batch mosaic-AIP generation
• linum_detect_rehoming.py — detect motor rehoming events from stage logs (used by feat: updated Nextflow workflows with profiles, auto-assess, rehoming #108's auto-rehoming workflow)

Library refactors

• linumpy/stitching/registration.py — refactored for shared use by CPU and GPU registration paths; adds affine helpers and a unified SimpleITK wrapper
• linumpy/stitching/mosaic_grid.py, topology.py, FileUtils.py, manual_registration.py — API cleanups and type-hinting
• linumpy/preproc/icorr.py, xyzcorr.py — functional rewrite for vectorisation / thread-safety
• linumpy/io/zarr.py, data_io.py, thorlabs.py — improved error handling and dtype handling
• linumpy/utils/metrics.py, io.py — misc. cleanup
• _thread_config imported first in all touched scripts so thread caps apply before numpy/jax/cupy

Script refactors (significant)

• linum_create_mosaic_grid_3d.py — rewrite for streaming and _thread_config compatibility
• linum_estimate_transform.py — unified CPU entry point used by feat: GPU acceleration module and scripts #99's GPU path
• linum_fix_illumination_3d.py — refactored into reusable functions
• linum_resample_mosaic_grid.py, linum_normalize_intensities_per_slice.py — align APIs with the new preproc modules
• linum_register_pairwise.py — uses the refactored registration.py
• linum_aip_png.py, linum_generate_mosaic_aips.py — preview integration

Tests added

• test_preproc_normalization.py, test_preproc_resampling.py, test_preproc_xyzcorr.py
• test_utils_orientation.py, test_utils_visualization.py
• scripts/tests/test_crop_3d_mosaic_below_interface.py, scripts/tests/test_resample_mosaic_grid.py

Notes

• linumpy/stitching/__init__.py imports interpolation, motor, stacking submodules, which are added by feat: slice interpolation for missing sections (z-morph) #87 and feat: motor stacking, auto-exclude, refined stitching #98 respectively — those imports resolve once the upstream PRs land