From 5589d907e6f508c8cef10aa94f5b03d1369cd14a Mon Sep 17 00:00:00 2001 From: Marvin Albert Date: Thu, 17 Oct 2024 16:15:33 +0200 Subject: [PATCH] Improved docs content and updated configuration --- .pre-commit-config.yaml | 3 +- docs/code_example.md | 8 ++- docs/data_formats.md | 62 ++++++++++++++++--- docs/docs_requirements.txt | 109 +++++++++++++++++++++++---------- docs/features.md | 96 ++++++++++++++++------------- docs/implementation_details.md | 2 +- docs/index.md | 12 ++-- mkdocs.yml | 46 +++++++++----- 8 files changed, 228 insertions(+), 110 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8164a32..4322a84 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,11 +1,12 @@ repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.4.0 + rev: v5.0.0 hooks: - id: check-docstring-first - id: end-of-file-fixer - id: trailing-whitespace - id: check-yaml # checks for correct yaml syntax for github actions ex. + args: ['--unsafe'] - repo: https://github.com/charliermarsh/ruff-pre-commit rev: v0.0.290 hooks: diff --git a/docs/code_example.md b/docs/code_example.md index 2525150..5a3165a 100644 --- a/docs/code_example.md +++ b/docs/code_example.md @@ -1,9 +1,11 @@ # Code example These code snippets walk you through a small stitching workflow consisting of -1) Preparing the input image data and metadata (tile positions, spacing, channels) -2) Registering the tiles -3) Stitching / fusing the tiles + + 1. Preparing the input image data and metadata (tile positions, spacing, channels) + 2. Registering the tiles + 3. Stitching / fusing the tiles + ### 1) Prepare data for stitching diff --git a/docs/data_formats.md b/docs/data_formats.md index 4e40d54..d36d8b3 100644 --- a/docs/data_formats.md +++ b/docs/data_formats.md @@ -1,21 +1,63 @@ # Data formats -For use with `multiview-stitcher`, data needs to be transformed into a [modified `multiscaleimage.MultiscaleImage`](./objects/#image). +!!! note + `multiview-stitcher` works with any numpy-like input arrays. Therefore, as long as the data can be read into a numpy array, it can be used with `multiview-stitcher`. -## TIFF +For attaching metadata to arrays, multiview-stitcher works with [SpatialImage](https://github.com/spatial-image/spatial-image) objects (with additional transform matrices attached). They can be constructed from Numpy, Dask or CuPy arrays as such: -Manual reading of tif files is supported with a convenience function. +```python +from multiview_stitcher import spatial_image_utils as si_utils +sim = si_utils.get_sim_from_array( + tile_array, + dims=["c", "y", "x"], + scale={'y': 0.5, 'x': 0.5}, + translation={"y": 30, "x": 50}, + transform_key="stage_metadata", + c_coords=['DAPI', 'GFP'], +) +``` -## CZI +A multiscale version of this object is represented by instances of [MultiscaleSpatialImage](https://github.com/spatial-image/multiscale-spatial-image), which can be created as such: -Mosaic czi file support thanks to [aicsimageio]. +```python +from multiview_stitcher import msi_utils +msim = msi_utils.get_msim_from_sim(sim, scale_factors=[2, 4]) +``` -## LIF +The following code can be used to extract a given scale from a multiscale image: -Mosaic lif file support thanks to [aicsimageio]. +```python +sim = msi_utils.get_sim_from_msim(msim, scale="scale0") +``` -## NGFF -Support provided by `multiscaleimage.MultiscaleImage`. +## OME-Zarr -The latest NGFF spec does not fully support the transformations required for stitching applications (yet). Therefore, `multiview-stitcher` currently defines its own data format, see [here](features/Coordinate systems). +!!! note + NGFF 0.4 (the latest OME-Zarr standard) currently only supports translation transformations. Therefore, affine transformations cannot yet be stored in OME-Zarr files. + +Some support for reading and writing OME-Zarrs is provided by [multiscaleimage.MultiscaleImage](https://github.com/spatial-image/multiscale-spatial-image). + +Further, `multiview_stitcher.ngff_utils` provides some convenience functions for reading and writing OME-Zarrs using [`ngff-zarr`](https://github.com/thewtex/ngff-zarr). + + +## Further file formats + +[`bioio`](https://github.com/bioio-devs/bioio) is a very convenient library for reading a large variety of image files and it includes support for lazy loading. Here's example code of how to use `bioio` to load an image file into a tile compatible with `multiview-stitcher`: + +```python +import bioio +from multiview_stitcher import spatial_image_utils as si_utils + +# use bioio to load the image as a xarray.DataArray +bioio_xr = BioImage("my_file.tiff").get_xarray_dask_stack().squeeze() + +sim = si_utils.get_sim_from_array( + bioio_xr.data, + dims=bioio_xr.dims, + scale=si_utils.get_spatial_dims_from_sim(bioio_xr), + translation=si_utils.get_origin_from_sim(bioio_xr), + c_coords=bioio_xr.coords["c"].values, + transform_key="stage_metadata", +) +``` diff --git a/docs/docs_requirements.txt b/docs/docs_requirements.txt index 9a5dec1..304fe78 100644 --- a/docs/docs_requirements.txt +++ b/docs/docs_requirements.txt @@ -1,39 +1,84 @@ -astor==0.8.1 -Babel==2.13.0 -certifi==2023.7.22 -charset-normalizer==3.3.0 +appnope==0.1.4 +asttokens==2.4.1 +attrs==24.2.0 +babel==2.16.0 +backcall==0.2.0 +beautifulsoup4==4.12.3 +bleach==6.1.0 +certifi==2024.8.30 +charset-normalizer==3.4.0 click==8.1.7 colorama==0.4.6 +decorator==5.1.1 +defusedxml==0.7.1 +docopt==0.6.2 +EditorConfig==0.12.4 +executing==2.1.0 +fastjsonschema==2.20.0 ghp-import==2.1.0 -griffe==0.36.5 -idna==3.4 -Jinja2==3.1.3 -Mako==1.2.4 -Markdown==3.5 -MarkupSafe==2.1.3 +griffe==1.4.1 +idna==3.10 +importlib_metadata==8.5.0 +importlib_resources==6.4.5 +ipython==8.12.3 +jedi==0.19.1 +Jinja2==3.1.4 +jsbeautifier==1.15.1 +jsonschema==4.23.0 +jsonschema-specifications==2024.10.1 +jupyter_client==8.6.3 +jupyter_core==5.7.2 +jupyterlab_pygments==0.3.0 +Markdown==3.7 +MarkupSafe==3.0.1 +matplotlib-inline==0.1.7 mergedeep==1.3.4 -mike==1.1.2 -mkdocs==1.5.3 -mkdocs-autorefs==0.5.0 -mkdocs-material==9.4.5 -mkdocs-material-extensions==1.2 -mkdocstrings==0.23.0 -mkdocstrings-python==1.7.3 -mkgendocs==0.9.2 -packaging==23.2 -paginate==0.5.6 -pathspec==0.11.2 -pip==23.3 -platformdirs==3.11.0 -Pygments==2.16.1 -pymdown-extensions==10.3 -python-dateutil==2.8.2 -PyYAML==6.0.1 +mike==2.1.3 +mistune==3.0.2 +mkdocs==1.6.1 +mkdocs-autorefs==1.2.0 +mkdocs-get-deps==0.2.0 +mkdocs-material==9.5.41 +mkdocs-material-extensions==1.3.1 +mkdocs-mermaid2-plugin==1.1.1 +mkdocstrings==0.26.2 +mkdocstrings-python==1.12.1 +nbclient==0.10.0 +nbconvert==7.16.4 +nbformat==5.10.4 +packaging==24.1 +paginate==0.5.7 +pandocfilters==1.5.1 +parso==0.8.4 +pathspec==0.12.1 +pexpect==4.9.0 +pickleshare==0.7.5 +pipreqs==0.5.0 +platformdirs==4.3.6 +prompt_toolkit==3.0.48 +ptyprocess==0.7.0 +pure_eval==0.2.3 +Pygments==2.18.0 +pymdown-extensions==10.11.2 +pyparsing==3.2.0 +python-dateutil==2.9.0.post0 +PyYAML==6.0.2 pyyaml_env_tag==0.1 -regex==2023.10.3 -requests==2.31.0 -setuptools==65.5.1 +pyzmq==26.2.0 +referencing==0.35.1 +regex==2024.9.11 +requests==2.32.3 +rpds-py==0.20.0 six==1.16.0 -urllib3==2.0.7 +soupsieve==2.6 +stack-data==0.6.3 +tinycss2==1.3.0 +tornado==6.4.1 +traitlets==5.14.3 +urllib3==2.2.3 verspec==0.1.0 -watchdog==3.0.0 \ No newline at end of file +watchdog==5.0.3 +wcwidth==0.2.13 +webencodings==0.5.1 +yarg==0.1.9 +zipp==3.20.2 diff --git a/docs/features.md b/docs/features.md index 651bc5f..1801f2a 100644 --- a/docs/features.md +++ b/docs/features.md @@ -2,66 +2,74 @@ Below is a list of features which are either already implemented or are on the roadmap. +## Dimensionality +- [x] 2D +- [x] 3D + ## Registration -### Pairwise registration -- [x] phase correlation +### Pairwise registration methods +- [x] Phase correlation - [x] ANTsPy -- [ ] elastix (`itk-elastix`) will be used for up to affine transformations -- [ ] bead alignment -- [ ] phase correlation for rotation + translation +- [ ] Elastix (`itk-elastix`) +- [ ] Bead alignment +- [ ] Phase correlation for rotation + translation -### Group registration +### Global paramater resolution -- [x] registration graph construction -- [x] automatic determination of suitable reference view -- [x] parameter concatenation along graph connectivity paths -- [ ] global optimization of registration parameters from (potentially overdetermined) pairwise transforms -- [ ] drift correction / temporal alignment +- [x] Graph construction +- [x] Automatic determination of reference view +- [x] Parameter concatenation along graph connectivity paths +- [x] Global optimization of registration parameters from (potentially overdetermined) pairwise transforms ## Transformations -- [x] chunked `dask_image.ndinterp.affine_transform` -- [ ] cupy-based transform -- [ ] chaining transformations instead of working with static coordinate systems +- [x] Chunked `dask_image.ndinterp.affine_transform` +- [ ] Cupy-based transform +- [ ] Chaining transformations instead of working with static coordinate systems ## Fusion -- [x] chunkwise -- [ ] modular API to plug in different fusion functions including: -- Supported weights: - - [x] blending - - [x] content-based -- Supported fusion methods: - - [x] weighted average - - [ ] multi-view deconvolution -- [ ] fusion of overlapping label maps -- [ ] GPU compatibility - -## Data formats -- [x] zarr based intermediate file format for reading and writing, compatible with parallel dask workflows: [multiscale-spatial-data](https://github.com/spatial-image/multiscale-spatial-image) -- [-] czi input - - [x] multi-positioning - - [ ] light-sheet -- [x] tif input -- [x] tif writing +### General + +- [x] Modular API to plug in different fusion and weight functions +- [ ] Support for fusion label maps +- [ ] Cupy-based fusion + +### Supported fusion methods: + + - [x] Weighted average + - [x] Maximum intensity projection + - [ ] Multi-view deconvolution + +### Supported weights: + + - [x] Linear blending + - [x] Content-based + +## Supported data formats + +- [x] OME-Zarr +- [x] Zarr based intermediate file format for reading and writing, compatible with parallel dask workflows: [multiscale-spatial-data](https://github.com/spatial-image/multiscale-spatial-image) +- CZI input + - [x] Multi-positioning + - [ ] Light-sheet +- [x] TIF input +- [x] TIF writing ## Visualization ### Napari -See [napari-stitcher](github.com/napari-stitcher). + +See [napari-stitcher](github.com/multiview-stitcher/napari-stitcher). + - [x] 2D slice view: multiscale rendering - 3D rendered view: - - [x] lowest scale - - [ ] chunked rendering -- [x] colormaps optimized for highlighting differences between overlapping views - -## Dimensionality -- [x] 2d -- [x] 3d + - [x] Lowest scale + - [ ] Chunked rendering +- [x] Colormaps optimized for highlighting differences between overlapping views ## Supported usage modes -- [x] as a library to build custom reconstruction workflows -- [ ] predefined workflows/pipelines adapted to specific setups -- [(x)] napari plugin -- [ ] processing on HPC +- [x] As a library to build custom reconstruction workflows +- [x] Napari plugin +- [ ] Convenience function for processing on HPC diff --git a/docs/implementation_details.md b/docs/implementation_details.md index f7e9d36..f41c35a 100644 --- a/docs/implementation_details.md +++ b/docs/implementation_details.md @@ -69,4 +69,4 @@ Further fusion weights can be obtained by the weight calculation function specif ### Content based fusion -To improve multi-view fusion in the context of strongly scattering samples, [content-based fusion](https://preibischlab.mdc-berlin.de/assets/spim_congeal_2008.pdf) turns out to be helpful. This fusion method is available in `multiview-stitcher` by using `multiview_stitcher.fusion.fuse(..., fusion_func=fusion.weighted_average_fusion, weights_method=weights.content_based)` (see [above](###Fusion-framework)). +To improve multi-view fusion in the context of strongly scattering samples, [content-based fusion](https://preibischlab.mdc-berlin.de/assets/spim_congeal_2008.pdf) turns out to be helpful. This fusion method is available in `multiview-stitcher` by using `multiview_stitcher.fusion.fuse(..., fusion_func=fusion.weighted_average_fusion, weights_method=weights.content_based)`. diff --git a/docs/index.md b/docs/index.md index f1776bc..df23c4d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,12 +11,14 @@ It leverages [`xarray`](https://github.com/xarray) in combination with [`spatial ### Napari plugin -There's an associated napari plugin: [napari-stitcher](https://github.com/napari-stitcher). +There's an associated napari plugin: [napari-stitcher](https://github.com/multiview-stitcher/napari-stitcher). -### Work in progress - -WARNING: THIS IS WORK IN PROGRESS, THE API IS NOT YET STABLE. ### Previous work -`multiview-stitcher` improves and replaces [MVRegFus](https://github.com/multiview-stitcher/MVRegFus). +`multiview-stitcher` improves and replaces [MVRegFus](https://github.com/m-albert/MVRegFus). + + +!!! note + + `multiview-stitcher` is a work in progress. The API is not yet stable. diff --git a/mkdocs.yml b/mkdocs.yml index fff12d0..d6e7567 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,7 +15,13 @@ plugins: handlers: python: paths: [src] + selection: + docstring_style: numpy - search + - mermaid2: + version: 11.3.0 + arguments: + securityLevel: 'loose' markdown_extensions: - pymdownx.highlight: @@ -24,22 +30,32 @@ markdown_extensions: pygments_lang_class: true - pymdownx.inlinehilite - pymdownx.snippets + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:mermaid2.fence_mermaid_custom + - pymdownx.tasklist: + custom_checkbox: true + # https://squidfunk.github.io/mkdocs-material/reference/admonitions + - admonition + - pymdownx.details - pymdownx.superfences nav: - - multiview-stitcher: - - index.md - - installation.md - - code_example.md - - notebooks.md - - features.md - - objects.md - - data_formats.md - - implementation_details.md - - napari_stitcher.md - - stitching_in_the_browser.md - - related_projects.md - - contributing.md + - index.md + - installation.md + - code_example.md + - chart.md + - notebooks.md + - features.md + - data_formats.md + - implementation_details.md + - objects.md + - napari_stitcher.md + - stitching_in_the_browser.md + - related_projects.md + - contributing.md - API: - api/registration.md - api/fusion.md @@ -50,8 +66,10 @@ theme: - content.tabs.link - content.code.annotate - content.code.copy - - navigation.tabs + # - navigation.tabs - navigation.footer # next/previous links in footer + - navigation.instant + - navigation.instant.progress icon: logo: fontawesome/solid/clone repo: fontawesome/brands/github