{"name":"napari-fast4dreg","display_name":"Fast4DReg","visibility":"public","icon":"","categories":["Annotation","Segmentation","Acquisition"],"schema_version":"0.2.1","on_activate":null,"on_deactivate":null,"contributions":{"commands":[{"id":"napari-fast4dreg.get_reader","title":"Open data with Fast4DReg","python_name":"napari_fast4dreg._reader:napari_get_reader","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"napari-fast4dreg.write_multiple","title":"Save multi-layer data with Fast4DReg","python_name":"napari_fast4dreg._writer:write_multiple","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"napari-fast4dreg.write_single_image","title":"Save image data with Fast4DReg","python_name":"napari_fast4dreg._writer:write_single_image","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"napari-fast4dreg.make_sample_data","title":"Load sample data from Fast4DReg","python_name":"napari_fast4dreg._sample_data:make_sample_data","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"napari-fast4dreg.make_function_widget","title":"Fast4DReg Registration","python_name":"napari_fast4dreg:Fast4DReg_widget","short_title":null,"category":null,"icon":null,"enablement":null}],"readers":[{"command":"napari-fast4dreg.get_reader","filename_patterns":["*.npy"],"accepts_directories":false}],"writers":[{"command":"napari-fast4dreg.write_multiple","layer_types":["image*","labels*"],"filename_extensions":[],"display_name":""},{"command":"napari-fast4dreg.write_single_image","layer_types":["image"],"filename_extensions":[".npy"],"display_name":""}],"widgets":[{"command":"napari-fast4dreg.make_function_widget","display_name":"Fast4DReg","autogenerate":false}],"sample_data":[{"command":"napari-fast4dreg.make_sample_data","key":"unique_id.1","display_name":"Fast4DReg"}],"themes":null,"menus":{},"submenus":null,"keybindings":null,"configuration":[]},"package_metadata":{"metadata_version":"2.4","name":"napari-fast4dreg","version":"0.2.7","dynamic":["license-file"],"platform":null,"supported_platform":null,"summary":"Dask empowered multidim, rigid registration for volumetric measurements","description":"# napari-fast4dreg\n\n[![License BSD-3](https://img.shields.io/pypi/l/napari-fast4dreg.svg?color=green)](https://github.com/Macl-I/napari-fast4dreg/raw/main/LICENSE)\n[![PyPI](https://img.shields.io/pypi/v/napari-fast4dreg.svg?color=green)](https://pypi.org/project/napari-fast4dreg)\n[![Python Version](https://img.shields.io/pypi/pyversions/napari-fast4dreg.svg?color=green)](https://python.org)\n[![tests](https://github.com/Macl-I/napari-fast4dreg/workflows/tests/badge.svg)](https://github.com/Macl-I/napari-fast4dreg/actions)\n[![codecov](https://codecov.io/gh/Macl-I/napari-fast4dreg/branch/main/graph/badge.svg)](https://codecov.io/gh/Macl-I/napari-fast4dreg)\n[![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/napari-fast4dreg)](https://napari-hub.org/plugins/napari-fast4dreg)\n\nDask-empowered multi-dimensional registration for volumetric measurements with enhanced features and real-time progress tracking.\n\nThis is a Python port of the original Fast4DReg Fiji Plugin, with added rotation correction, support for out-of-memory processing, and advanced registration options.\n\n**Original paper:** [Fast4DReg: fast registration of 4D microscopy](https://journals.biologists.com/jcs/article/136/4/jcs260728/287682/Fast4DReg-fast-registration-of-4D-microscopy)\n\n----------------------------------\n\n## ⚠️ Disclaimer\n\n**For versions > 0.1.0:** AI was used to implement features and improvements in this package. While all changes have been tested, not all features may perform exactly as expected. If you encounter any issues or unexpected behavior, please **immediately raise a GitHub PR** so problems can be fixed as soon as possible. Your feedback helps improve the reliability and quality of this package.\n\n----------------------------------\n\n## ✨ Features\n\n- **Multi-dimensional registration**: XY, Z, and 3D rotation correction\n- **Out-of-memory processing**: Handle large datasets that don't fit in RAM using Zarr-based storage\n- **Efficient multi-channel handling**: Zarr storage with optimized chunking (1×1×Z×Y×X) for fast per-channel access\n- **Flexible projection methods**: Average, Max, Median, or Min projection\n- **Reference modes**: Relative (frame-to-frame) or First Frame correction\n- **Multi-channel support**: Use multiple reference channels with optional normalization\n- **Real-time progress tracking**: Detailed progress updates with ETA and completion time\n- **Thread-based execution**: Non-blocking UI during processing\n- **Flexible axis ordering**: Support for ImageJ and Python axis conventions\n- **Auto-detection**: Automatic single-channel mode detection\n- **GPU acceleration (optional)**: Automatic OpenCL GPU detection with NVIDIA preference and CPU fallback\n- **2D+t support**: Process time-lapse images with various dimensionalities\n- **Compressed storage**: Built-in Blosc compression reduces temporary storage by 2-3×\n\n## Example Results\n\n![3D_plane_registration](./media/3D_plane_registration_scalebar_time_stamped.gif)\n![3D_MIP_registration](./media/3D_mip_registration_scalebar_time_stamped.gif)\n![drift_results](./media/drift_analysis.png)\n\n\n## Installation\n\n### Quick Install (with pip)\n\nYou can install `napari-fast4dreg` via [pip]:\n\n```bash\n# full install\npip install napari-fast4dreg\n\n# api-only access (i.e. HPC) \npip install napari-fast4dreg[api-only]\n```\n\n### Recommended: Using Conda/Mamba\n\nFor the best experience and easier dependency management, we recommend using [Anaconda](https://www.anaconda.com/download) or [Miniforge/Mambaforge](https://github.com/conda-forge/miniforge):\n\n1. **Install Conda/Mamba** (if not already installed):\n   - Download and install [Miniforge](https://github.com/conda-forge/miniforge) (recommended, includes mamba)\n   - Or download [Anaconda](https://www.anaconda.com/download) / [Miniconda](https://docs.conda.io/en/latest/miniconda.html)\n\n2. **Create a new environment**:\n   ```bash\n   conda create -n napari-env python=3.10\n   conda activate napari-env\n   ```\n   \n   Or with mamba (faster):\n   ```bash\n   mamba create -n napari-env python=3.10\n   mamba activate napari-env\n   ```\n\n3. **Install napari and the plugin**:\n   ```bash\n   pip install napari[all] napari-fast4dreg\n   ```\n\n4. **Launch napari**:\n   ```bash\n   napari\n   ```\n\n### From Source (for development)\n\n```bash\ngit clone https://github.com/COSC-Lab/napari-fast4dreg.git\ncd napari-fast4dreg\npip install -e .\n```\n\n### Optional GPU Acceleration (pyclesperanto)\n\nFast4DReg can use [pyclesperanto](https://github.com/clEsperanto/pyclesperanto_prototype) to accelerate all transformations (translations and rotations) on OpenCL GPUs. This is **automatic** when available.\n\n```bash\npip install pyclesperanto-prototype\n```\n\nBehavior summary:\n- **Auto-detects** OpenCL devices on import\n- **Prefers NVIDIA** GPUs over Intel GPUs when multiple are available\n- **Gracefully falls back to CPU** if GPU is not available or runs out of VRAM\n\nCheck the current backend in Python:\n\n```python\nfrom napari_fast4dreg import get_gpu_info\nprint(get_gpu_info())  # e.g., \"GPU (NVIDIA RTX 1000)\" or \"CPU (scipy)\"\n```\n\n## Usage \n\n### Quick Start\n\n1. **Load your image**: Drag and drop your image (or use the test image from this repository) into napari. Don't worry about file size—napari uses dask internally to handle even the largest images.\n\n2. **Open the plugin**: Navigate to `Plugins → napari-fast4dreg → Fast4DReg` in the napari menu.\n\n3. **Configure settings**:\n\n   - **Image Layer**: Select your image from the dropdown menu\n   \n   - **Axis Order**: Choose your data structure:\n     - `TZCYX_ImageJ` - Standard ImageJ orientation (default)\n     - `CTZYX` - Python/NumPy orientation\n     - `TZYX`, `ZCYX`, `CZYX`, `ZYX` - Other supported formats\n   \n   - **Reference Channel(s)**: Specify which channel(s) to use for drift detection\n     - Single channel: `0` (first channel), `1` (second channel), etc.\n     - Multiple channels: `0,3,5` or `0 3 5` (comma or space-separated, sums channels)\n     - Example: For a nuclear signal in channel 1, enter `1`\n   \n   - **Normalize Channels**: Enable this when using multiple reference channels with different intensity ranges\n   \n   - **Projection Type**: Choose how Z-stacks are projected for drift detection:\n     - `Average` - Mean intensity projection (default)\n     - `Max` - Maximum intensity projection\n     - `Median` - Median intensity projection\n     - `Min` - Minimum intensity projection\n   \n   - **Axis Order**: Specify your image's axis order as a string:\n     - `CTZYX` - Channels, Time, Z, Y, X (default, 5D)\n     - `TZYX` - Time, Z, Y, X (4D, single channel)\n     - `ZYX` - Z, Y, X (3D, single timepoint + channel)\n     - `ZCYX` - Z, Channels, Y, X\n     - `CYX` - Channels, Y, X (2D, single timepoint)\n     - Any other combination works! Missing dimensions (C, T, Z) are automatically added as singletons\n   \n   - **Reference Mode**: Choose drift correction strategy:\n     - `Relative` - Frame-to-frame comparison (cumulative drift, default)\n     - `First Frame` - Compare all frames to the first frame (absolute drift)\n   \n   - **Output Directory**: Specify where to save results and temporary files\n   \n   - **Multichannel Registration Mode**: Enable for channel-specific registration\n   \n   - **Corrections**: Select which corrections to apply:\n     - ☑ **XY Drift Correction** - Lateral drift\n     - ☑ **Z Drift Correction** - Axial drift  \n     - ☑ **Rotation Correction** - 3D rotation in XY, ZX, and ZY planes\n     - ☑ **Crop Output** - Remove invalid regions after correction\n     - ☑ **Export CSV & Plots** - Save drift data and generate visualizations\n\n4. **Run**: Click the \"Run Registration\" button and monitor progress with real-time ETA\n\n5. **Results**: The registered image will be automatically added to the napari viewer and saved to your output directory\n\n### Advanced Features\n\n#### Multi-Channel Reference\n\nUse multiple channels for more robust drift detection:\n- Enter channels as comma-separated values: `0,2,4`\n- Enable \"Normalize Channels\" if channels have greatly different brightness ranges.\n- The plugin will sum (or normalize+sum) the specified channels before drift detection\n\n#### Progress Tracking\n\nThe plugin provides detailed progress updates:\n- **Fine-grained steps**: See exactly what operation is running (up to 23 steps when running all corrections)\n- **Real-time ETA**: Estimated time remaining based on average step duration\n- **Completion report**: Total processing time displayed when finished\n- **Non-blocking UI**: Continue using napari while processing runs in the background\n\n#### Projection Methods\n\nDifferent projection types are optimized for different data:\n- **Average**: Best for uniform samples, reduces noise\n- **Max**: Highlights bright features, good for sparse structures\n- **Median**: Robust to outliers, good for noisy data\n- **Min**: Highlights dark features, i.e. brightfield\n\n#### Reference Modes\n\n- **Relative** (default): Compares consecutive frames (t → t+1 → t+2...). Best for continuous drift.\n- **First Frame**: Compares all frames to t=0. Best for periodic or intermittent drift.\n\n### Programmatic API (No GUI)\n\nFast4DReg can be integrated into your workflows without the napari GUI using the programmatic API:\n\n```python\nfrom napari_fast4dreg import register_image\n\n# Load your image (CTZYX format)\nimport numpy as np\nimage = np.load(\"my_timelapse.npy\")  # Shape: (C, T, Z, Y, X)\n\n# Run registration\nresult = register_image(\n    image,\n    ref_channel=0,\n    correct_xy=True,\n    correct_z=True,\n    correct_rotation=True,\n    output_dir=\"./results\"\n)\n\n# Access results\nregistered = result['registered_image']\nxy_drift = result['xy_drift']\nz_drift = result['z_drift']\n```\n\n**Or load directly from file:**\n\n```python\nfrom napari_fast4dreg import register_image_from_file\n\nresult = register_image_from_file(\n    \"my_image.tif\",\n    axis_order=\"TZCYX\",  # ImageJ format\n    ref_channel=1,\n    output_dir=\"./results\"\n)\n```\n\n**With progress tracking:**\n\n```python\ndef show_progress(message):\n    print(f\"Progress: {message}\")\n\nresult = register_image(\n    image,\n    ref_channel=0,\n    progress_callback=show_progress,\n    output_dir=\"./results\"\n)\n```\n\n**Advanced options:**\n\n```python\nresult = register_image(\n    image,\n    ref_channel=\"0,3,5\",  # Multi-channel reference\n    normalize_channels=True,\n    projection_type='max',\n    reference_mode='first_frame',\n    correct_rotation=False,  # Skip rotation for speed\n    keep_temp_files=True,  # Keep temporary files\n    return_drifts=True  # Include drift data in result\n)\n```\n\nSee `examples_api_usage.py` for more examples of programmatic usage.\n\n\n## Output Files\n\nThe plugin generates the following outputs (when corresponding options are selected):\n\n- **`registered.zarr/`**: The final registered image stack in Zarr format\n  - Uses efficient (1, 1, Z, Y, X) chunking for fast channel/timepoint access\n  - Includes built-in Blosc compression (typically 2-3× smaller than raw data)\n  - Can be opened directly in napari by dragging the .zarr folder\n  - Compatible with dask, zarr, and other array processing libraries\n- **`tmp_data_1.zarr/` and `tmp_data_2.zarr/`**: Temporary Zarr stores with compressed data\n  - Uses efficient (1, 1, Z, Y, X) chunking for fast channel/timepoint access\n  - Includes built-in Blosc compression (typically 2-3× smaller than raw data)\n  - Can be opened directly in napari by dragging the .zarr folder\n  - Safe to delete after registration completes\n- **`drifts.csv`**: Complete drift table with columns:\n  - `x-drift`, `y-drift` - Lateral drift in pixels\n  - `z-drift` - Axial drift in pixels\n  - `rotation-xy`, `rotation-zx`, `rotation-zy` - Rotation angles in degrees\n- **`drift_analysis.png`**: Combined visualization of all drift components (4-panel figure)\n- **Legacy plots** (if generated):\n  - `XY-Drift.svg` - Lateral drift visualization\n  - `Z-Drift.svg` - Axial drift visualization\n  - `Rotation-Drift.svg` - 3D rotation visualization\n\nAll plots are saved as high-quality vector graphics (SVG) or PNG, suitable for publications and presentations.\n\n## Performance Tips\n- **Speed**: The design of this pipeline relies on many read and writes to disk. For optimal performance try writing to a SSD or NVMe SSD.\n\n- **Multi-channel reference**: Enable normalization when channels have vastly different intensities\n- **Projection method**: Try Max projection for sparse/bright features, Median for noisy data\n- **Reference mode**: Use \"First Frame\" if drift is periodic or intermittent\n- **Temporary files**: Ensure sufficient disk space in your output directory (approximately 2-3× your image size)\n\n## Recent Updates\n\n### Enhanced Features (2024-2026)\n\n- ✨ **Programmatic API**: Complete API for workflow integration without napari GUI\n  - `register_image()` function for direct Python access\n  - `register_image_from_file()` for loading and registering in one step\n  - Progress callbacks, drift data export, and full parameter control\n  - See `API_REFERENCE.md` and `examples_api_usage.py` for details\n- ✨ **Zarr-based storage**: Replaced NPY stacks and TIFF output with Zarr for better performance\n  - Optimized chunking (1, 1, Z, Y, X) for multi-channel images\n  - Built-in compression reduces storage by 2-3×\n  - Faster random access for individual channels/timepoints\n  - Final output saved as `registered.zarr` instead of TIFF\n- ✨ **Multi-channel reference support**: Use multiple channels (e.g., `0,3,5`) with optional normalization\n- ✨ **Flexible projection methods**: Choose between Average, Max, Median, or Min projection\n- ✨ **Reference mode options**: Select Relative (frame-to-frame) or First Frame correction\n- ✨ **Fine-grained progress tracking**: 23 detailed steps with real-time ETA and completion time\n- ✨ **Thread-based execution**: Non-blocking UI allows continued napari interaction during processing\n- ✨ **Enhanced UI**: Single unified widget with all controls in one place\n- ✨ **Improved compatibility**: npe2-compatible plugin architecture\n\n## Roadmap / Future Enhancements\n\n- [x] ~~Implement Zarr storage as alternative to NPY stacks~~ ✅ (Completed 2026)\n- [ ] ~~Test alternative affine transform functions (SimpleITK, OpenCV)~~ (Postponed: bottleneck is read-write speed, not transform functions)\n- [ ] ~~Add CUDA support for GPU acceleration (NVIDIA GPUs)~~ (Postponed: bottleneck is read-write speed)\n- [ ] Add drift prediction/interpolation for missing frames\n\n## Contributing\n\nContributions are very welcome! Please feel free to:\n- Submit bug reports and feature requests via [GitHub Issues](https://github.com/COSC-Lab/napari-fast4dreg/issues)\n- Submit pull requests with enhancements\n- Contact: marcel.issler@kuleuven.be\n\n## Credit \nThis [napari] plugin was generated with [Cookiecutter] using [@napari]'s [cookiecutter-napari-plugin] template.\n\n## License\n\nDistributed under the terms of the [BSD-3] license,\n\"napari-fast4dreg\" is free and open source software\n\n## Issues\n\nIf you encounter any problems, please [file an issue] along with a detailed description.\n\n[napari]: https://github.com/napari/napari\n[Cookiecutter]: https://github.com/audreyr/cookiecutter\n[@napari]: https://github.com/napari\n[MIT]: http://opensource.org/licenses/MIT\n[BSD-3]: http://opensource.org/licenses/BSD-3-Clause\n[GNU GPL v3.0]: http://www.gnu.org/licenses/gpl-3.0.txt\n[GNU LGPL v3.0]: http://www.gnu.org/licenses/lgpl-3.0.txt\n[Apache Software License 2.0]: http://www.apache.org/licenses/LICENSE-2.0\n[Mozilla Public License 2.0]: https://www.mozilla.org/media/MPL/2.0/index.txt\n[cookiecutter-napari-plugin]: https://github.com/napari/cookiecutter-napari-plugin\n\n[napari]: https://github.com/napari/napari\n[tox]: https://tox.readthedocs.io/en/latest/\n[pip]: https://pypi.org/project/pip/\n[PyPI]: https://pypi.org/\n","description_content_type":"text/markdown","keywords":null,"home_page":null,"download_url":null,"author":"Marcel Issler","author_email":"marcel.issler@kuleuven.be, marcel.issler@vib.be","maintainer":null,"maintainer_email":null,"license":"BSD-3-Clause","classifier":["Development Status :: 2 - Pre-Alpha","Framework :: napari","Intended Audience :: Developers","License :: OSI Approved :: BSD License","Operating System :: OS Independent","Programming Language :: Python","Programming Language :: Python :: 3","Programming Language :: Python :: 3 :: Only","Programming Language :: Python :: 3.8","Programming Language :: Python :: 3.9","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Programming Language :: Python :: 3.14","Topic :: Scientific/Engineering :: Image Processing"],"requires_dist":["numpy","scikit-image","matplotlib","zarr","tqdm","scipy","pandas","dask","napari; extra == \"napari\"","magicgui; extra == \"napari\"","qtpy; extra == \"napari\"","pyqt5; extra == \"napari\"","tox; extra == \"testing\"","pytest; extra == \"testing\"","pytest-cov; extra == \"testing\"","pytest-qt; extra == \"testing\"","napari; extra == \"testing\"","pyqt5; extra == \"testing\""],"requires_python":">=3.8","requires_external":null,"project_url":null,"provides_extra":["api-only","napari","testing"],"provides_dist":null,"obsoletes_dist":null},"npe1_shim":false}