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/images/20230929_screenshot.png b/docs/images/20230929_screenshot.png deleted file mode 100644 index f3f37f1..0000000 Binary files a/docs/images/20230929_screenshot.png and /dev/null differ diff --git a/docs/images/logo.png b/docs/images/logo.png new file mode 100644 index 0000000..d0b446f Binary files /dev/null and b/docs/images/logo.png differ diff --git a/docs/images/naming_convention_example.png b/docs/images/naming_convention_example.png new file mode 100644 index 0000000..9f16440 Binary files /dev/null and b/docs/images/naming_convention_example.png differ diff --git a/docs/images/napari-stitcher-loaded-mosaic-annotated-inkscape.svg b/docs/images/napari-stitcher-loaded-mosaic-annotated-inkscape.svg new file mode 100644 index 0000000..ab3b72d --- /dev/null +++ b/docs/images/napari-stitcher-loaded-mosaic-annotated-inkscape.svg @@ -0,0 +1,169 @@ + + + +134562 diff --git a/docs/images/napari-stitcher-loaded-mosaic-annotated.png b/docs/images/napari-stitcher-loaded-mosaic-annotated.png new file mode 100644 index 0000000..c128724 Binary files /dev/null and b/docs/images/napari-stitcher-loaded-mosaic-annotated.png differ diff --git a/docs/images/napari-stitcher-loaded-mosaic.png b/docs/images/napari-stitcher-loaded-mosaic.png new file mode 100644 index 0000000..c16bea5 Binary files /dev/null and b/docs/images/napari-stitcher-loaded-mosaic.png differ diff --git a/docs/images/preposition.gif b/docs/images/preposition.gif new file mode 100644 index 0000000..03cdffb Binary files /dev/null and b/docs/images/preposition.gif differ diff --git a/docs/images/preposition3d.gif b/docs/images/preposition3d.gif new file mode 100644 index 0000000..fa84abb Binary files /dev/null and b/docs/images/preposition3d.gif differ diff --git a/docs/images/preposition_mosaic.gif b/docs/images/preposition_mosaic.gif new file mode 100644 index 0000000..db4476a Binary files /dev/null and b/docs/images/preposition_mosaic.gif differ diff --git a/docs/index.md b/docs/index.md index f2dd6f9..2e495aa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,4 +4,4 @@ A napari plugin for stitching large multi-positioning datasets in 2/3D+t using [`multiview-stitcher`](https://github.com/multiview-stitcher/multiview-stitcher). -![](images/20230929_screenshot.png) \ No newline at end of file +![](images/napari-stitcher-loaded-mosaic-annotated.png) \ No newline at end of file diff --git a/docs/installation.md b/docs/installation.md index 2a571fb..9133511 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -7,3 +7,105 @@ You can install `napari-stitcher` via pip: To install latest development version: pip install git+https://github.com/multiview-stitcher/napari-stitcher.git + +!!! note "Don't have conda installed?" + We recommend using python and `napari-stitcher` within a conda environment. Follow the instructions below to install `conda` on your computer. + +## Installing Python + +### Overview +This how-to teaches how to install Python on your computer using `conda`, which is both a + +- environment manager and a +- package manager. + + +### Instructions + +Select the installation instructions for your operating system and processor from the tabs below. + +=== "Linux" + + 1. In your web browser, navigate to this [download page](https://github.com/conda-forge/miniforge#miniforge). + 2. Scroll down to the "Miniforge" header of the "Downloads" section. Click the link to download link for `Miniforge-Linux-x86_64`. + 3. Open your terminal application + 4. Navigate to the folder you downloaded the installer to (usually this is in your Downloads folder). If the file was downloaded to your Downloads folder, you would enter: + + ```bash + cd ~/Downloads + ``` + + 5. Execute the installer with the command below. You can use your arrow keys to scroll up and down to read the license agreement and enter "yes" if you agree. + + ```bash + bash Miniforge-Linux-x86_64.sh + ``` + + 6. After installation, you will be asked if you would like to initialize your terminal with "conda init". Enter "yes" to initalize your terminal. + 7. To verify your installation worked, close your Terminal window and open a new one. You should see `(base)` to the left of your prompt. + + !!! note "Don't see (base)?" + You can manually initialize conda by entering the command below and re-opening your terminal application. + + + ```bash + conda init + ``` + +=== "Mac OS (Intel)" + + 1. In your web browser, navigate to this [download page](https://github.com/conda-forge/miniforge#miniforge). + 2. Scroll down to the "Miniforge" header of the "Downloads" section. Click the link to download link for `Miniforge-MacOSX-x86_64`. + 3. Open your Terminal (you can search for it in spotlight - `cmd` + `space`) + 4. Navigate to the folder you downloaded the installer to (usually this is in your Downloads folder). If the file was downloaded to your Downloads folder, you would enter: + + ```bash + cd ~/Downloads + ``` + + 5. Execute the installer with the command below. You can use your arrow keys to scroll up and down to read the license agreement and enter "yes" if you agree. + + ```bash + bash Miniforge-MacOSX-x86_64.sh + ``` + + 6. After installation, you will be asked if you would like to initialize your terminal with "conda init". Enter "yes" to initalize your terminal. + 7. To verify your installation worked, close your Terminal window and open a new one. You should see `(base)` to the left of your prompt. + + !!! note "Don't see (base)?" + You can manually initialize conda by entering the command below and re-opening your terminal application. + ```bash + conda init + ``` + + +=== "Mac OS (M1/M2)" + 1. In your web browser, navigate to this [download page](https://github.com/conda-forge/miniforge#miniforge). + 2. Scroll down to the "Miniforge" header of the "Downloads" section. Click the link to download link for `Miniforge-MacOSX-arm64`. + 3. Open your Terminal (you can search for it in spotlight - `cmd` + `space`) + 4. Navigate to the folder you downloaded the installer to (usually this is in your Downloads folder). If the file was downloaded to your Downloads folder, you would enter: + + ```bash + cd ~/Downloads + ``` + + 5. Execute the installer with the command below. You can use your arrow keys to scroll up and down to read it/agree to it. + + ```bash + bash Miniforge-MacOSX-arm64.sh + ``` + + 6. After installation, you will be asked if you would like to initialize your terminal with "conda init". Enter "yes" to initalize your terminal. + 7. To verify your installation worked, close your Terminal window and open a new one. You should see `(base)` to the left of your prompt. + + !!! note "Don't see (base)?" + You can manually initialize conda by entering the command below and re-opening your terminal application. + ```bash + conda init + ``` + +=== "Windows" + 1. In your web browser, navigate to this [download page](https://github.com/conda-forge/miniforge#miniforge). + 2. Scroll down to the "Miniforge" header of the "Downloads" section. Click the link to download link for `Miniforge-Windows-x86_64`. + 3. Find the file you downloaded (Miniforge-Windows-x86_64.exe) and double click to execute it. Follow the instructions to complete the installation. + 4. Once the installation has completed, you can verify it was correctly installed by searching for the "miniforge prompt" in your Start menu. \ No newline at end of file diff --git a/docs/naming_convention.md b/docs/naming_convention.md new file mode 100644 index 0000000..dcc8a0c --- /dev/null +++ b/docs/naming_convention.md @@ -0,0 +1,22 @@ +# Layer naming convention + +!!! note "Napari and multi-channel images" + In napari, different channels are represented as different layers. However `napari-stitcher` needs to know which layers correspond to the same tile. To do this, the layers need to be named in a specific way. + +For single channel datasets, layer names can be arbitrary. For multi-channel datasets, the layers need to be named in the following way for best compatibility with napari-stitcher: + +`{tile} :: {channel}`. + +Example: + +![](images/naming_convention_example.png){: style="width:40%"} + +This is the convention followed by [`bioio`](https://github.com/bioio-devs/bioio) when loading images into napari. + +!!! note "How to edit layer names?" + To rename a layer, double-click on the layer name in the layer list and type the new name. To programmatically rename layers, you can use e.g. something like the following code in the napari console: + + ```python + for il, l in enumerate(viewer.layers): + l.name = f'Tile {il // 2} :: {[GFP, RFP][il % 2]}' + ``` \ No newline at end of file diff --git a/docs/prearrangement.md b/docs/prearrangement.md new file mode 100644 index 0000000..2a1a427 --- /dev/null +++ b/docs/prearrangement.md @@ -0,0 +1,54 @@ +# Prepositioning tiles + +!!! note "Prepositioning tiles" + As a starting point for registration, `napari-stitcher` uses the positions of the layers as they are shown in napari. + +There are two ways to preoposition the layers in napari: + +### 1. Manual positioning + +You can manually position the tiles by dragging and dropping them in the viewer. This is useful when you have a small number of tiles and you want to freely position them. + +!!! note "Visualization tip" + To visualize tiles on top of each other in napari, you can set the "blending" property (in the layer controls) of all layers to "additive". Additionally, you can choose a different color for each layer to help you distinguish them. + +#### 2D case + +![](images/preposition.gif) + +#### 3D case + + + +!!! note "Pixel spacing" + Make sure to set the pixel spacing of the layers in Z, Y, X correctly. You can do this by opening the console and running something like the following code: + + ```python + for l in viewer.layers: + l.scale = [2, 0.3, 0.3] + ``` + +Install the awesome [`napari-threedee`](https://github.com/napari-threedee/napari-threedee) plugin to enable 3D positioning. + +![](images/preposition3d.gif) + + +### 2. Aligning on a grid + +The widget under Plugins->napari-stitcher->Mosaic arrangement allows you to align the layers on a grid. This is useful when you have a large number of tiles which should be placed on a regular grid. This works for 2D and 3D data. + +![](images/preposition_mosaic.gif) \ No newline at end of file diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..433f2b3 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,35 @@ + +# Quickstart + +![](images/napari-stitcher-loaded-mosaic-annotated.png) + +## Opening napari + +- Activate your conda environment by running `conda activate napari-stitcher` in the terminal (MacOS) or Miniconda Prompt (Windows) +- Start napari by running `napari` +- Start the plugin in the menu plugins > napari-stitcher > Stitcher + +## Load images into napari + +`napari-stitcher` can stitch any image layers that are loaded into napari. You can load images into napari by dragging and dropping files into the viewer, or by using the `File > Open Files` menu. + +Additionally, `napari-stitcher` supports reading mosaic files which contain multiple pre-positioned tiles. If more than one scene is present, you'll be prompted to select a scene to load. The following file formats are supported: +- `.czi` +- `.lif` + +Image files / napari layers to stitch can be 2D/3D(+time). + +## Some napari basics + +- The display settings (contrast, etc.) can be set using the panel at the top left (1) +- Tiles and channels can be displayed or hidden by clicking on the eye icon on the bottom left panel (2). Tiles are displayed with a color code to help the overlap inspection: an alternation of red and green is used so the overlapping structure appears yellow. +- The plugin panel is at the top right (3). + + +## Using the napari-stitcher plugin + +- The timepoints used to run the stitching can be adjusted with the “Timepoints” range slider. This is useful to quickly test the stitching in case of a large time series. +- Choose the channel used for calculating the registration with the “Reg channel” dropdown menu. +- Once the stitching or stabilization is performed, you can toggle between the “Original” image and the “Registered” image. Inspect the result by zooming on the overlap region. +- If you are satisfied with the result, click on “Fuse” to fuse all the tiles together in a single image. +- Export the output by slecting the output layer (4), and clicking on “File > Save selected layers” (you can also use “Cmd+S” or “Ctrl+S”). Use .tif format for the output. diff --git a/mkdocs.yml b/mkdocs.yml index a944899..977d5c8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,6 +15,13 @@ plugins: handlers: python: paths: [src] + selection: + docstring_style: numpy + - search + - mermaid2: + version: 11.3.0 + arguments: + securityLevel: 'loose' markdown_extensions: - pymdownx.highlight: @@ -23,13 +30,28 @@ 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 + - pymdownx.tabbed: + alternate_style: true + - attr_list nav: - - napari-stitcher: - - index.md - - installation.md - - contributing.md + - index.md + - installation.md + - quickstart.md + - prearrangement.md + - naming_convention.md + - contributing.md theme: name: material @@ -37,29 +59,29 @@ theme: - content.tabs.link - content.code.annotate - content.code.copy - - navigation.tabs + # - navigation.tabs - navigation.footer # next/previous links in footer + logo: images/logo.png icon: - logo: fontawesome/solid/clone repo: fontawesome/brands/github favicon: palette: + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: white + accent: teal + toggle: + icon: material/lightbulb + name: Switch to light mode # Palette toggle for light mode - media: "(prefers-color-scheme: light)" scheme: default - primary: dark blue + primary: white accent: dark blue toggle: icon: material/lightbulb-outline name: Switch to dark mode - # Palette toggle for dark mode - - media: "(prefers-color-scheme: dark)" - scheme: slate - primary: teal - accent: light green - toggle: - icon: material/lightbulb - name: Switch to light mode extra: version: