{
  "name": "napari-atlas-cci",
  "display_name": "Atlas CCI",
  "visibility": "public",
  "icon": null,
  "categories": [],
  "schema_version": "0.3.0",
  "on_activate": null,
  "on_deactivate": null,
  "contributions": {
    "commands": [
      {
        "id": "napari-atlas-cci.open_widget",
        "title": "AtlasCCI",
        "python_name": "napari_atlas_cci:AtlasCCIWidget",
        "short_title": null,
        "category": null,
        "icon": null,
        "enablement": null
      }
    ],
    "readers": null,
    "writers": null,
    "widgets": [
      {
        "command": "napari-atlas-cci.open_widget",
        "display_name": "AtlasCCI",
        "autogenerate": false,
        "default_dock_area": "right",
        "tabify": false
      }
    ],
    "sample_data": null,
    "themes": null,
    "menus": {},
    "submenus": null,
    "keybindings": null,
    "configurations": {}
  },
  "package_metadata": {
    "metadata_version": "2.4",
    "name": "napari-atlas-cci",
    "version": "1.1.14",
    "dynamic": [
      "license-file"
    ],
    "platform": null,
    "supported_platform": null,
    "summary": "A plugin that allows napari to run atlas stitching and alignement tool",
    "description": "# napari atlas cci\n\nA napari plugin for stitching and aligning array tomography data acquired with\nFIBICS ATLAS. It provides a graphical interface to the\n[CCI ATLAS backend](https://github.com/CCI-GU-Sweden/ATLAS).\n\nThe workflow has been tested primarily with data acquired on the Zeiss Gemini\nSEM 450 at the Centre for Cellular Imaging (CCI), University of Gothenburg.\nSee [CCI's correlative array tomography page](https://www.gu.se/index.php/en/core-facilities/core-facilities-research-infrastructures/centre-for-cellular-imaging-cci/our-services/correlative-array-tomography)\nfor details of the workflow and equipment.\n\n## Installation\n\nThe plugin requires Python **3.11 or 3.12**, napari, and a Qt backend. Its\n[ATLAS backend](https://github.com/CCI-GU-Sweden/ATLAS) is installed as a\nPython dependency; the master Zarr workflow requires `atlas-cci-align` 1.3.19\nor later.\n\n### Create an environment\n\nInstall [Miniforge](https://github.com/conda-forge/miniforge) or another Conda\ndistribution, then run the following in a terminal (on Windows, use a Conda\nterminal):\n\n```bash\nconda create -n atlas-napari -c conda-forge python=3.11 napari \"pyqt6>=6.7\" pip\nconda activate atlas-napari\npython -m pip install napari-atlas-cci\nnapari\n```\n\nIn napari, open **Plugins → Atlas CCI → AtlasCCI**. To start it again later,\nactivate the environment and run `napari`. For more ways to install napari, see\nthe [napari installation guide](https://napari.org/stable/tutorials/fundamentals/installation.html).\n\n### Qt backend troubleshooting\nThe plugin requires a compatible Qt backend. We recommend PyQt6 (Qt ≥6.7) for recent versions of napari.\n\nIf napari reports an incompatible Qt binding, explicitly select PyQt6 when launching the application.\n\nLinux / WSL / macOS:\n```bash\nQT_API=pyqt6 napari\n```\nWindows (Anaconda Prompt / Command Prompt):\n```bash\nset QT_API=pyqt6\nnapari\n```\nWindows (PowerShell):\n```bash\n$env:QT_API = \"pyqt6\"\nnapari\n```\n\n### Known dependency conflicts\nThe plugin uses webknossos to create and upload datasets to webKnossos.\nCurrently, webknossos 4.3.3 specifies dependency versions that conflict\nwith requirements of newer napari environments.\n\nInstallation may therefore report conflicts involving psutil, rich,\nand typer.\n\nWe have successfully tested dataset creation and upload using\nwebknossos 4.3.3 with napari 0.10.0. This is a temporary compatibility workaround.\n\n### Create a desktop launcher\n\nThese launchers open a terminal, activate the environment, and start napari.\nKeep the terminal open while napari runs; it also shows progress and errors.\nReplace `atlas-napari` below if you chose a different environment name.\n\n#### Windows\n\n1. Open your Conda terminal and run `conda info --base`. Note the path it\n   prints, for example `C:\\Users\\YourName\\miniforge3`.\n2. Open Notepad and paste the following. Replace the example path with your\n   own Conda base path, keeping `\\condabin\\conda.bat` at the end:\n\n   ```bat\n   @echo off\n   call \"C:\\Users\\YourName\\miniforge3\\condabin\\conda.bat\" activate atlas-napari\n   if errorlevel 1 (\n       echo Could not activate the atlas-napari environment.\n       pause\n       exit /b 1\n   )\n   napari\n   pause\n   ```\n\n3. Choose **Save As**, select **All Files** as the file type, and save it on\n   the desktop as `Launch Atlas Napari.bat` (not `.bat.txt`). Double-click it\n   to start napari. The terminal stays open after napari closes so you can read\n   any messages; press a key to close it.\n\n#### macOS\n\n1. Open Terminal and run `conda info --base`. Note the path it prints, for\n   example `/Users/yourname/miniforge3`.\n2. Open TextEdit, choose **Format → Make Plain Text**, and paste the following.\n   Replace the example path with your own Conda base path, keeping\n   `/etc/profile.d/conda.sh` at the end:\n\n   ```bash\n   #!/bin/bash\n   source \"/Users/yourname/miniforge3/etc/profile.d/conda.sh\" || exit 1\n   conda activate atlas-napari || exit 1\n   napari\n   ```\n\n3. Save the plain-text file on the desktop as `Launch Atlas Napari.command`.\n   In Terminal, make it executable once:\n\n   ```bash\n   chmod +x ~/Desktop/\"Launch Atlas Napari.command\"\n   ```\n\n   Double-click the file to open Terminal and start napari. If your Desktop is\n   stored in another location, use that file's path in the `chmod` command.\n   See [Apple's instructions for executable scripts](https://support.apple.com/guide/terminal/apdd100908f/mac).\n\n### Update an existing environment\n\nClose napari, activate the environment in which you installed the plugin, and\nupdate both the plugin and the ATLAS backend:\n\n```bash\nconda activate atlas-napari\npython -m pip install --upgrade napari-atlas-cci atlas-cci-align\n```\n\nRun `napari` again. To inspect the installed versions and their locations:\n\n```bash\npython -m pip show napari-atlas-cci atlas-cci-align\n```\n\nPublished packages can lag behind changes merged on GitHub. An editable source\ninstallation uses its local checkout, so check its location before replacing it\nwith a PyPI installation.\n\n### Install from source for development\n\nAfter creating and activating the environment above, clone this repository and\ninstall it in editable mode:\n\n```bash\ngit clone https://github.com/CCI-GU-Sweden/napari-atlas-cci.git\ncd napari-atlas-cci\npython -m pip install -e \".[testing]\"\n```\n\nRestart napari after changing plugin code. The ATLAS backend is installed from\nPyPI unless it has separately been installed from a local editable checkout.\n\n## How to use\n\n### Select the ATLAS section-set folder\n\nUse **Browse...** to select the ATLAS **section set** folder: the folder that\ncontains the `S_...` section folders directly. Select the section-set folder,\nnot an individual `S_...` folder or the higher-level session folder. For\nexample:\n\n```text\nsession_740977233/\n└── Section Set 6/                         ← select this folder\n    ├── S_012_1314243284/                 ← one section\n    │   ├── MosaicInfo_S_012_1314243284.ve-mif\n    │   └── Tile_r1-c1_S_012_1314243284.tif\n    └── S_013_1234567890/\n        ├── MosaicInfo_S_013_1234567890.ve-mif\n        ├── Tile_r1-c1_S_013_1234567890.tif\n        └── Tile_r2-c1_S_013_1234567890.tif\n```\n\nNames and numbers vary between acquisitions. An S folder represents one\nsection and may contain one tile or several tiles. For stitching, each section\nfolder needs one `.ve-mif` acquisition metadata file and the `.tif` tiles\nlisted in it. The acquisition must be marked completed in the metadata, and\nthe tile names and count must match the files present. ATLAS may also create\nother files or subfolders, such as overview images and update files.\n\nThe plugin lists valid S folders found directly inside the selected section\nset. If a section is missing from the list, check that its acquisition is\ncomplete and that its metadata and tiles are present. The plugin writes the\nmaster `stitched_sections.zarr` and alignment outputs alongside the S folders\nin the selected section-set folder.\n\n![Initial status](assets/Unprocessed_folder.png)\n\n### 2D stitching\n\nFor 2D stitching, select one, multiple, or all S_ folders. Stitched sections and their metadata are stored in `stitched_sections.zarr` in the project folder. The thread count in Options controls how many sections can be stitched concurrently; higher counts require more memory.\n\n![On going stitching](assets/Stitching_ongoing.png)\n\nAfter processing, you can select one S_ folder and display the image in Napari.\n\n### Z alignment\n\nInitial Z alignment uses completed sections in the master Zarr, in numeric\nsection order or in the order specified by `correct_order.txt`. Set the axial\npixel size and unit, then click **Initial Z alignment**. The plugin calculates\nshifts and displays a downsampled preview; the downsampling factor is set in\n**Options...**. Scroll through the Z planes and inspect the alignment.\n\n![Initial align preview](<assets/Initial align preview.png>)\n\n#### Choose the section order\n\nBy default, initial alignment uses all completed sections in ascending ATLAS\nsection-number order. If a section number is missing, the backend prints a\nwarning in the terminal and treats the gap as accepted: for example, it aligns\n`S_4` directly with `S_6` if `S_5` is missing. Inspect such warnings to confirm\nthe gap is expected.\n\nTo select a subset or change the order, create a plain-text file named\n`correct_order.txt` in the selected section-set folder before running\n**Initial Z alignment**.\n\nWrite ATLAS section numbers as comma-separated integers, without the `S_`\nprefix. The order in the file is the alignment order. For example:\n\n```text\n1,...,3,6,9,...,7\n```\n\nThis selects sections `S_1, S_2, S_3, S_6, S_9, S_8, S_7`, in that order.\nThe `...` token expands the range between the two numbers, including both\nends; it works in ascending or descending order. Sections not listed are\nexcluded. Every section listed or included in a range must already be complete\nin the master Zarr; otherwise initial alignment reports an error. To include a\nrange with missing section numbers, list only the available sections instead.\n\n#### Correct the alignment by tracing\n\nThe default mode, **Trace: one point per plane**, lets you follow the same\nrecognizable feature through successive sections. The plugin turns consecutive\npoints into pairs automatically, so you only need one points layer.\n\n1. Select **Trace: one point per plane** and click **Enter Correction**. The\n   plugin creates a red **Reference Points** layer and selects it for adding\n   points.\n2. On the preview, find a feature that is visible in consecutive Z planes.\n   Place a point on that feature in the first plane, move to the adjacent plane,\n   and place a point on the same feature. Continue in the same direction,\n   placing **one point per plane**. You can trace forwards or backwards.\n3. Click **Apply Correction**. The plugin calculates the correction and\n   rebuilds the preview. Inspect the new preview by scrolling through the\n   corrected planes.\n4. If further adjustment is needed, click **Enter Correction** again and place\n   **new points on the updated preview**. Repeat as needed. The correction is\n   added to the existing alignment, so reusing old points would apply the same\n   adjustment again.\n\nFor example, points entered on planes `2, 3, 4` create pairs `2 → 3` and\n`3 → 4`. A gap starts a separate trace: `2, 3, 4, 8, 9, 10` creates pairs\n`2 → 3`, `3 → 4`, `8 → 9`, and `9 → 10`; it does not join planes 4 and 8.\nEach trace needs at least two consecutive planes. Enter each trace in order,\nwith at most one point per plane across all traces. The plugin reports duplicate\nplanes, isolated points, and invalid ordering so you can edit the points and\ntry again.\n\nThe original automatic alignment is saved as\n`alignment_results/z_alignment_results_before_manual_correction.pkl`. The\nlatest corrected results are saved in `z_alignment_results.pkl` and used for\nfinal alignment.\n\n#### Alternative: explicit point pairs\n\nFor the earlier two-layer workflow, select **Explicit point pairs** and click\n**Enter Correction**. The plugin creates red **Reference Points** and blue\n**Adjustable Points** layers. Add matching landmarks in the same order to both\nlayers: each reference point belongs to the Z plane immediately before its\nmatching adjustable point. Both layers must contain the same number of points.\nClick **Apply Correction** and inspect the regenerated preview. In trace mode,\nany existing Adjustable Points layer is ignored.\n\nWhen satisfied with the preview, click **Final Z Alignment** to generate the\nfull-resolution output. This can take time for large datasets.\n\n![Final alignment](assets/Final_align_view.png)\n\n### Options and saved preferences\n\nThe **Options...** dialog includes lower and upper saturation percentiles for\nalignment processing. Defaults are **1.0** and **99.95**; values must satisfy\n`0 ≤ lower < upper ≤ 100`. They apply to saved previews, previews regenerated\nafter manual correction, and full-resolution aligned outputs. Changing them\ndoes not modify outputs that have already been generated.\n\nWhen the plugin creates an aligned preview or full-resolution output, it\nstretches each section's intensity range using its own selected percentiles.\nThis improves contrast and can make neighboring sections look more consistent.\nValues outside the stretched range are clipped to the image data type's limits.\n**This changes the saved pixel intensities relative to the original stitched\nand raw images**; it is not just a display setting. Use the original stitched\nsections in `stitched_sections.zarr` when unmodified stitched intensities are\nneeded for quantitative analysis.\n\nClick **OK** to apply and save the Options values; **Cancel** leaves them\nunchanged. Thread count, maximum stitching shift, alignment downsampling,\nCZI compression, and both percentiles are restored next time the plugin opens.\nAxial pixel size and its explicit unit are also saved when the edit is finished\nor the unit changes. Thread count is limited to one fewer than the available CPU\ncores (with a minimum of one).\n\nPreferences are saved as readable JSON in\n`<Qt GenericConfigLocation>/napari-atlas-cci/settings.json`, under the user's\nAppData directory on Windows. They apply across projects on that computer.\nMissing preferences use the defaults; invalid files produce feedback and fall\nback to defaults. Upload tokens and project paths are excluded from this JSON\nfile. The Browse dialog remembers the last selected project folder separately\nusing Qt settings. This implements local user preferences alongside [#12](https://github.com/CCI-GU-Sweden/napari-atlas-cci/issues/12);\nportable project configurations and historical run snapshots described in\n[#14](https://github.com/CCI-GU-Sweden/napari-atlas-cci/issues/14) remain separate work.\n\n### Export and upload\n\nStitched sections and their metadata are stored in `stitched_sections.zarr` in\nthe project folder. Alignment results are saved as a pandas pickle table in\n`alignment_results`. After **Final Z Alignment**, the plugin also provides the\nfollowing outputs. The aligned arrays and exports derived from them contain\nthe percentile-stretched intensities described in **Options and saved\npreferences** above.\n\n**Disk space and time:** The current workflow creates several copies of the\nimage data for convenient viewing and export. Final alignment writes both a\nfull-resolution aligned Zarr and an OME-Zarr pyramid. A WebKnossos upload also\nbuilds a local WebKnossos dataset and pyramid before uploading it; that local\ndataset is deleted after a successful upload by default. Allow sufficient free\nspace and processing time, especially for large projects. We may review and\nreduce these intermediate copies in a future version.\n\n#### OME-Zarr\n\nThe plugin automatically creates an OME-Zarr pyramid for the downsampled\npreview and another for the full-resolution alignment. The final pyramid is\nsaved as `<project>_aligned.ome.zarr` in the project folder. Use **View** next\nto **Final Z Alignment** in the plugin or open the OME-Zarr folder with a\ncompatible viewer.\nThe pyramid contains multiple resolutions and carries the ATLAS alignment\nmetadata. A separate full-resolution aligned Zarr array,\n`<project>_aligned.zarr`, is also saved and is used as the source for CZI and\nWebKnossos export.\n\n#### CZI\n\nClick **Export to CZI** after final alignment to write\n`<project>_aligned.czi` in the project folder. The plugin reads the aligned\nZarr one plane at a time and writes tiled CZI data. XY pixel size comes from\nthe master store and Z pixel size from the axial value and unit in the UI;\ncheck the axial value before exporting. CZI compression can be set in\n**Options...**. The CZI export currently writes image data and scale; retaining\nthe complete alignment transform metadata is being investigated in\n[#20](https://github.com/CCI-GU-Sweden/napari-atlas-cci/issues/20).\n\n#### WebKnossos\n\nClick **Upload to Webknossos...** after final alignment. Enter your\n[WebKnossos](https://webknossos.org/) token, review the dataset name and XY/Z\npixel sizes, and start the upload. The dialog displays the name that will be\nused and lets you edit it. XY size is read from the master store; Z size comes\nfrom the axial value and unit in the UI. Sizes in the upload dialog are in\nnanometers.\n\nThe plugin builds a local compressed WebKnossos dataset and its resolution\npyramid before uploading. By default, the local WebKnossos dataset is deleted\nafter a successful upload; clear the checkbox to keep it. The aligned Zarr\nand OME-Zarr remain in the project folder. A successful upload displays a link\nto the dataset. An account and token are required; tokens are not saved in\nplugin preferences.\n\n![Upload to WebKnossos](assets/upload_to_wkn.png)\n\n![WebKnossos upload success](<assets/webknossos upload.png>)\n\n#### Download from WebKnossos\n\nAfter fine alignment in WebKnossos, use **Download from webknossos...** at the\nbottom of the plugin. Enter your token, the new aligned dataset's ID or full\ndataset URL, an output filename, and the destination folder (defaults to the\ncurrent project). No local aligned output is required to use this button.\n\nThe download reads the full-resolution `color` layer one Z plane at a time and\nwrites that plane as CZI tiles of at most 1024 × 1024 pixels. All channels are\npreserved, XY axes are converted to CZI order, and voxel sizes are copied from\nthe remote dataset. Source bounding-box offsets are rebased to CZI coordinates\nstarting at zero. CZI compression follows **Options...** at download start.\nAn existing destination file is never overwritten; choose a new filename.\nIf a transfer fails after writing starts, a partial CZI may remain at that path.\n\nDownloads run in a background worker, with an activity indicator and\ncompletion or error notifications. Tokens are used for the request and are not\nsaved in preferences.\n\n## Why translation-only alignment?\n\nThis alignment applies XY translations between sections. It does not apply\nrotation, scaling, or other affine transforms at this stage. Placing the\nfull-resolution sections using pixel shifts avoids the interpolation that those\ntransforms would require and keeps the original pixel spacing. The preview is\ndownsampled, and aligned outputs have their intensities stretched as described\nin **Options and saved preferences** above, so their pixel values differ from\nthe raw data. The translated volume can be used as a starting point for finer\nalignment in other tools, for example:\n\n- [WebKnossos AI Alignment](https://docs.webknossos.org/webknossos/automation/alignment.html),\n  which aligns sections after upload. See its documentation for dataset and\n  service requirements.\n- [Microscopy Image Browser (MIB) alignment](https://mib.helsinki.fi/help/main2/user-interface/menu/dataset/dataset-alignment.html),\n  part of the open-source MATLAB-based image analysis software.\n- [TrakEM2 in Fiji](https://imagej.github.io/plugins/trakem2/tutorials), which\n  includes tools for aligning serial sections.\n\nCheck the chosen tool's supported input formats and import instructions before\nstarting.\n\n## Troubleshooting\n\n- **Plugin not visible:** check that napari was launched from the environment\n  where `napari-atlas-cci` is installed. Run\n  `python -m pip show napari-atlas-cci` in that environment and restart napari.\n- **Qt cannot load the `xcb` platform plugin on Linux:** check your desktop and\n  Qt runtime setup using the [napari installation guide](https://napari.org/stable/tutorials/fundamentals/installation.html).\n  When using WSL, also confirm that Linux GUI applications work in your WSL setup.\n- **WebKnossos upload:** provide an account token in the upload dialog. The\n  token is not saved in plugin preferences.\n\n## Contributing\n\nContributions are welcome. Install the source with the `testing` extra as\nshown above, then run:\n\n```bash\npython -m pytest\n```\n",
    "description_content_type": "text/markdown",
    "keywords": null,
    "home_page": null,
    "download_url": null,
    "author": null,
    "author_email": "Simon Leclerc <simon.leclerc@gu.se>",
    "maintainer": null,
    "maintainer_email": null,
    "license": "MIT License\n\nCopyright (c) 2026 LECLERC Simon\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n",
    "classifier": [
      "Development Status :: 3 - Alpha",
      "Framework :: napari",
      "Intended Audience :: Science/Research",
      "Intended Audience :: Developers",
      "License :: OSI Approved :: MIT License",
      "Operating System :: OS Independent",
      "Programming Language :: Python",
      "Programming Language :: Python :: 3",
      "Programming Language :: Python :: 3 :: Only",
      "Programming Language :: Python :: 3.11",
      "Programming Language :: Python :: 3.12",
      "Topic :: Scientific/Engineering :: Image Processing"
    ],
    "requires_dist": [
      "numpy",
      "qtpy",
      "scipy",
      "ome-zarr",
      "dask",
      "webknossos<5,>=4.0.0",
      "pylibCZIrw",
      "atlas-cci-align>=1.3.19",
      "napari[all]; extra == \"all\"",
      "pytest; extra == \"testing\"",
      "pytest-cov; extra == \"testing\"",
      "pytest-qt; extra == \"testing\"",
      "napari[qt]; extra == \"testing\"",
      "napari-omero-downloader-cci[testing]; extra == \"dev\"",
      "black; extra == \"dev\"",
      "ruff; extra == \"dev\""
    ],
    "requires_python": "<3.13,>=3.11",
    "requires_external": null,
    "project_url": null,
    "provides_extra": [
      "all",
      "testing",
      "dev"
    ],
    "provides_dist": null,
    "obsoletes_dist": null
  },
  "npe1_shim": false
}