diff --git a/.github/workflows/ebrains.yml b/.github/workflows/ebrains.yml new file mode 100644 index 0000000..7b99e9a --- /dev/null +++ b/.github/workflows/ebrains.yml @@ -0,0 +1,17 @@ +name: Mirror to Ebrains + +on: + push: + branches: [ master ] + +jobs: + to_ebrains: + runs-on: ubuntu-latest + steps: + - name: sync_master + uses: wei/git-sync@v3 + with: + source_repo: "Neural-Systems-at-UIO/QuickNII" + source_branch: "master" + destination_repo: "https://ghpusher:${{ secrets.EBRAINS_GITLAB }}@gitlab.ebrains.eu/ri/tech-hub/apps/nesys/quicknii.git" + destination_branch: "master" diff --git a/.github/workflows/issue_auto.yml b/.github/workflows/issue_auto.yml new file mode 100644 index 0000000..2cf9515 --- /dev/null +++ b/.github/workflows/issue_auto.yml @@ -0,0 +1,21 @@ +name: Issue management + +on: + issues: + types: [opened] + +jobs: + do-things: + runs-on: ubuntu-latest + steps: + - name: Auto-assign issue + uses: pozil/auto-assign-issue@v1.5.0 + with: + assignees: Tevemadar + numOfAssignee: 1 + allowSelfAssign: true + - name: Add issue to project + uses: actions/add-to-project@main + with: + project-url: https://github.com/orgs/Neural-Systems-at-UIO/projects/2 + github-token: ${{ secrets.AUTOMATION_TOKEN }} diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..b7c4072 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,35 @@ +# Read the Docs configuration file for Sphinx projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + # You can also specify other tool versions: + # nodejs: "20" + # rust: "1.70" + # golang: "1.20" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: Docs/conf.py + # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs + # builder: "dirhtml" + # Fail on all warnings to avoid broken references + # fail_on_warning: true + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: Docs/requirements.txt diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image1.png b/Docs/6bef45ee36424df69f030c687f030605/media/image1.png new file mode 100644 index 0000000..fe2631f Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image1.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image10.png b/Docs/6bef45ee36424df69f030c687f030605/media/image10.png new file mode 100644 index 0000000..f97f4ce Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image10.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image11.png b/Docs/6bef45ee36424df69f030c687f030605/media/image11.png new file mode 100644 index 0000000..3bd9fca Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image11.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image12.png b/Docs/6bef45ee36424df69f030c687f030605/media/image12.png new file mode 100644 index 0000000..0d86e21 Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image12.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image13.png b/Docs/6bef45ee36424df69f030c687f030605/media/image13.png new file mode 100644 index 0000000..a3bb20b Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image13.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image14.png b/Docs/6bef45ee36424df69f030c687f030605/media/image14.png new file mode 100644 index 0000000..d444cb0 Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image14.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image15.png b/Docs/6bef45ee36424df69f030c687f030605/media/image15.png new file mode 100644 index 0000000..eb402e1 Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image15.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image16.png b/Docs/6bef45ee36424df69f030c687f030605/media/image16.png new file mode 100644 index 0000000..2439bae Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image16.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image17.png b/Docs/6bef45ee36424df69f030c687f030605/media/image17.png new file mode 100644 index 0000000..fb141f1 Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image17.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image18.png b/Docs/6bef45ee36424df69f030c687f030605/media/image18.png new file mode 100644 index 0000000..13d4d09 Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image18.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image19.png b/Docs/6bef45ee36424df69f030c687f030605/media/image19.png new file mode 100644 index 0000000..8716796 Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image19.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image2.png b/Docs/6bef45ee36424df69f030c687f030605/media/image2.png new file mode 100644 index 0000000..e22eb93 Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image2.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image20.png b/Docs/6bef45ee36424df69f030c687f030605/media/image20.png new file mode 100644 index 0000000..45bac7a Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image20.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image3.png b/Docs/6bef45ee36424df69f030c687f030605/media/image3.png new file mode 100644 index 0000000..45c3d28 Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image3.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image4.png b/Docs/6bef45ee36424df69f030c687f030605/media/image4.png new file mode 100644 index 0000000..39c0923 Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image4.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image5.png b/Docs/6bef45ee36424df69f030c687f030605/media/image5.png new file mode 100644 index 0000000..ca97fb5 Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image5.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image6.png b/Docs/6bef45ee36424df69f030c687f030605/media/image6.png new file mode 100644 index 0000000..6eac5ec Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image6.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image7.png b/Docs/6bef45ee36424df69f030c687f030605/media/image7.png new file mode 100644 index 0000000..f8a9869 Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image7.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image8.png b/Docs/6bef45ee36424df69f030c687f030605/media/image8.png new file mode 100644 index 0000000..18bc4b5 Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image8.png differ diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image9.png b/Docs/6bef45ee36424df69f030c687f030605/media/image9.png new file mode 100644 index 0000000..875c2b0 Binary files /dev/null and b/Docs/6bef45ee36424df69f030c687f030605/media/image9.png differ diff --git a/Docs/Acknowledgements.rst b/Docs/Acknowledgements.rst new file mode 100644 index 0000000..9e131af --- /dev/null +++ b/Docs/Acknowledgements.rst @@ -0,0 +1,6 @@ +**Acknowledgements** +==================== +QuickNII is developed at the Neural Systems Laboratory, Institute of +Basic Medical Sciences,University of Oslo (Norway), with funding from the European Union’s +Horizon 2020 Framework Programme for Research and Innovation under the +Framework Partnership Agreement No. 650003 (HBP FPA) and the European Union’s Horizon Europe Programme for Research Infrastructures Grant Agreement No. 101147319 (EBRAINS 2.0). diff --git a/Docs/EBRAINS_logo.png b/Docs/EBRAINS_logo.png new file mode 100644 index 0000000..d99d1ea Binary files /dev/null and b/Docs/EBRAINS_logo.png differ diff --git a/Docs/FAQ.rst b/Docs/FAQ.rst new file mode 100644 index 0000000..28a5604 --- /dev/null +++ b/Docs/FAQ.rst @@ -0,0 +1,27 @@ +**FAQ** +-------------------------------- + +(1) I am using QuickNII to register my 2D coronal brain images with retrograde tracing. I completed all required steps through the filebuilder, but when I input my file to be registered the images does not appear, only the reference you have appears. Can you help me with this? + +--> Please place the xml file in the same folder as the jpeg images, this usually solves this issue. +You can read about it here: https://quicknii.readthedocs.io/en/latest/imageprepro.html#generate-a-xml-descriptor-file + +(2) I have an error with the QuickNII filebuilder that just shows a black screen and shuts down. + +--> This can happen if you have spaces in the path where the QuickNII software is located. For Windows 10 users, the filebuilder can be modified and it is described here: https://www.nitrc.org/plugins/mwiki/index.php/quicknii:MainPage + +(3) QuickNII filebuilder does not list my images although the size is ok. + +--> The filename pattern should be consistent and the section numbers should have the same number of digits (see naming convention). + +(4) How can I refine my QuickNII registration? + +--> Please us VisuAlign https://visualign.readthedocs.io/en/latest/. + +(5) Where can I find information about the coordinates of my images? + +--> Information can be found in this guide under "Coordinates" + +(6) How can I try QuickNII with my own atlas? + +--> Documentation of the cutlas file format is available here: https://www.nitrc.org/plugins/mwiki/index.php?title=quicknii:Cutlas_file_format diff --git a/Docs/Installation.rst b/Docs/Installation.rst new file mode 100644 index 0000000..8782660 --- /dev/null +++ b/Docs/Installation.rst @@ -0,0 +1,62 @@ + +**Installation** +----------------------------- +**System requirements** +~~~~~~~~~~~~~~~~~~~~~~~~ +Microsoft Windows: 64-bit operating system, Windows 7 or later + +Apple macOS: OS X 10.9 (Mavericks) or later + +3 gigabytes RAM + +Display resolution minimum 1440 pixels wide and minimum 650 pixels high. + +**Technical information** + +QuickNII consists of two co-located executable components implemented in +two programming languages for historical reasons. The GUI component is +implemented in MXML+ActionScript (runs on Adobe Integrated Runtime, +which is bundled as "captive runtime", requiring no installation). A +slicer service running in the background is implemented in Java (and has +a bundled JRE requiring no installation). The two components communicate +via standard output and local TCP connections (using the loopback +interface). + +**Conditions of use** +~~~~~~~~~~~~~~~~~~~~~~ + +**Licence:** + +Creative Commons Attribution-NonCommercial-ShareAlike 4.0 +International for the main component. Source code: MIT License. + + +**Citation of the tool:** + +-RRID on SciCrunch: (QuickNII, RRID:SCR_016854) + +-Puchades MA, Csucs G, Ledergerber D, Leergaard TB, Bjaalie JG (2019) + Spatial registration of serial microscopic brain images to + three-dimensional reference atlases with the QuickNII tool. PLOS ONE + 14(5): e0216796. https://doi.org/10.1371/journal.pone.0216796 + +**Download** +~~~~~~~~~~~~~ +Download of the software is from Nitrc.org +Link: https://www.nitrc.org/projects/quicknii/ + +Unzipp the QuickNII folder at your desired location. + + +**Versions and release notes** + +* Version 2.2 (2019-05-28) This release includes several reference atlases. +Linux support was added in July 2020. + +* Version 2.2preview (2019-04-02) Series descriptor builder recognizes multiple numbering variants in filenames (numbers at fixed character position from either end of names, and sequence indicator \_s prefixanywhere) +Coordinate transformation to/from Allen CCFv3 added to Mouse package. + +* Version 2.1 (2018-12-05) First stable version + + + diff --git a/Docs/Introduction.rst b/Docs/Introduction.rst new file mode 100644 index 0000000..4c69664 --- /dev/null +++ b/Docs/Introduction.rst @@ -0,0 +1,55 @@ +**What is QuickNII?** +======================= +QuickNII is one of several tools developed by the NeSys laboratory at University of Oslo with the aim of facilitating brain atlas-based analysis and +integration of experimental data and knowledge about the human and rodent brain. + +QuickNII is a stand-alone application for user-guided affine +spatial registration (anchoring) of section images, typically high +resolution histological images, to 3D reference atlas space. A key +feature of the tool is its ability to generate user-defined cut planes +through the atlas templates that match the orientation of the cutting +plane of the 2D experimental images (atlas maps). The reference atlas is +transformed to match anatomical landmarks in the corresponding +experimental images. In this way, the spatial relationship between the +experimental image and the atlas is defined, without introducing +transformations in the original experimental images. Following anchoring +of a limited number of sections containing key landmarks, +transformations are propagated across the entire series of images. These +propagations must be validated and saved by the user for each section, +with application of fine positional adjustments as required. We +recommend the use of `VisuAlign `_ to perform nonlinear adjustments after +the QuickNII registration for an optimal fit. + +.. image:: 6bef45ee36424df69f030c687f030605/media/image1.png + :width: 6.3in + :height: 4.04916in + + +.. image:: 6bef45ee36424df69f030c687f030605/media/image2.png + :width: 6.30139in + :height: 2.48678in + +.. tip:: + **QuickNII and VisuAlign are part of the QUINT workflow** + Visit `EBRAINS `_ for more information about the QUINT workflow. Find full user documentation `here `_. + +**Which atlases are supported?** +----------------------------- +1. Allen Mouse Brain Atlas Common Coordinate Framework version 3 (2015 and 2017) (CCFv3) (Wang et al. 2020. Cell, https://doi.org/10.1016/j.cell.2020.04.007. Epub 2020 May 7; RRID:JCR_020999 and RRID:JRC_021000) +2. Waxholm Atlas of the Sprague Dawley rat, version 3 and 4 (WHS rat brain atlas) (Osen et al. 2019. NeuroImage, https:doi.org/10.1016/j.neuroimage.2019.05.016; Kleven et al. Nat Methods, 2020. https://doi.org/10.1038/s41592-023-02034-3; RRID:SCR_017124) +3. Kim-UnifiedMouse-v1 (Chon et al. 2019, Nature Communications 10:5067. https://doi.org/10.1038/s41467-019-13057-w) +4. Developmental Mouse Brain Atlas, version 2 (DeMBA) (Carey et al. 2024. Nat Comm. https://doi.org/10.1038/s41467-025-63177-9; RRID:SCR_025324). + +We encourage researchers who use DeMBA to cite both the dataset and publication presenting DeMBA, and to specify the age of any template(s) used and the version of any segmentation(s) used. + +-Allen CCFv3 segmentations: Wang et al. (2020). The Allen Mouse Brain Common Coordinate Framework: A 3D Reference Atlas. Cell. https://doi.org/10.1016/j.cell.2020.04.007. + +-KimLabDev segmentations: Kronman et al. (2024). Developmental mouse brain common coordinate framework. Nature Communications. https://doi.org/10.1038/s41467-024-53254-w + +**What is the output of QuickNII?** +--------------------------------- + +-A registration file (XML or JSON format) containing the coordinates of your regisered section images in atlas space. +Use the JSON format for continuing registration in VisuALign. + +-Export of atlas maps (png format) diff --git a/Docs/QuickNII_logo.png b/Docs/QuickNII_logo.png new file mode 100644 index 0000000..d948995 Binary files /dev/null and b/Docs/QuickNII_logo.png differ diff --git a/Docs/adjust.rst b/Docs/adjust.rst new file mode 100644 index 0000000..c84299e --- /dev/null +++ b/Docs/adjust.rst @@ -0,0 +1,33 @@ +**Final adjustments of in plane position** +--------------------------------------------- + +Go to another image located at the end of the series and repeat the +anchoring procedure. Once the second image is stored, QuickNII will +automatically calculate the anteroposterior positions of the images, as +well as propagating the registered angles and scaling to the sections +between the anchored sections. This accelerates the anchoring procedure, +and ensures the section spacing and serial order are respected. However, +there might be cases where the automatically propagated parameters do +not fit the section, for example if a section has been tilted during the +mounting procedure. It is therefore essential to validate the positions +by visual inspection, and to correct any mismatch by fine adjustment of +the anteroposterior position, and scaling and rotation of the atlas maps +to match the position of the sections. + +.. tip:: + **Once defined, apply the same angles to all the sections in the series and review each section!** + +The “export propagation” button allows you to validate all the sections +at once. However, caution is recommended in the use of this feature, as +some sections might not have the correct position. We strongly recommend +reviewing all the sections in order to validate the anchoring. Perform +in plane rotations using buttons in the main window. Rotations in the +small coronal window will result in a rotation around the +anteroposterior axis. + +.. image:: 6bef45ee36424df69f030c687f030605/media/image16.png + :width: 5.43472in + :height: 3.32172in + +.. tip:: + **Adjustments made with QuickNII are linear. If considerable mismatch remains between the atlas maps and the sections, despite fine linear adjustments, further nonlinear adjustments can be applied using VisuAlign https://visualign.readthedocs.io/en/latest/** diff --git a/Docs/anchoring.rst b/Docs/anchoring.rst new file mode 100644 index 0000000..6ca34fa --- /dev/null +++ b/Docs/anchoring.rst @@ -0,0 +1,91 @@ +**Start the anchoring** +----------------------- + +**1. Open QuickNII and load the data** + +Open the QuickNII program by clicking on the .exe file. +Once the program opens, click the **Manage data button**. + +.. image:: 6bef45ee36424df69f030c687f030605/media/image5.png + :width: 6.30139in + :height: 3.54662in + +A second window, the data management window, will open. Here you can +load your data by clicking the **Load button** and choosing the +**xml** (or JSON) file related to your images, choose the “orig file” the first time. + + +.. image:: 6bef45ee36424df69f030c687f030605/media/image6.png + :width: 5.42361in + :height: 4.06771in + +.. image:: 6bef45ee36424df69f030c687f030605/media/image7.png + :width: 4.8125in + :height: 3.46793in + +Navigate between the two windows by clicking the Manage data button. +Select sections to work on by using double-clicking the section +number in the data management window. + +**2. Use landmarks in the images to find their approximate anteroposterior position** + +Select your main working plane, i.e. coronal, sagittal or horizontal by going to "values and controls"**(5)** + +The first step in a successful anchoring is to find the approximate +anteroposterior position of the slices (Y position for coronal +sections). Do this first for the first and last section of the series +(or first and last sections with clear landmarks). +Select sections to work on by using the arrows in the upper right panel or by +double-clicking the section number in the data management window. + + +.. image:: 6bef45ee36424df69f030c687f030605/media/image8.png + :width: 6.3in + :height: 4.88989in + +Choose your orientation: By clicking on the “Values and control” **(5)** button + in the bottom left corner, choose the section + orientation (coronal, sagittal or horizontal). + +Adjustment of the anteroposterior position + The anteroposterior position is adjusted by clicking and sliding + the red circle in the sagittal navigation window **(1)**. After finding + the approximate position of your section, determine whether the + midline of the section is completely vertical. If not, the rotation + of the template can be adjusted using the rotate left/right-buttons + **(2)**. +The atlas proportions might need adjustment to fit the section. + This is done separately for the horizontal and vertical + direction by using the scaling buttons **(3)**. In order to scale your + atlas, press the space bar while holding the mouse pointer over the + place you want the reference point for scaling. A small cross will + appear. Usually it is easier to choose a side and not place the + cross in the middle of the section. + Then, click on the scaling button: a double arrow will appear. + Place your mouse pointer at the opposite side of the double cross, + and press the left button of your mouse. While keeping the left + button of the mouse pressed you can now gently drag the atlas in + the direction indicated by the double arrow. To drag in the other direction, choose the other arrow. + +The transparency slider **(4)** + it can be used at any time, in order to determine how + well the atlas fits the section. + +The “outline” button **(5)** + This will allows you to shift between an outline view and a color view of the + atlas segmentations. + +Contrast adjustments **(5)** + Both the experimental image and the template can be adjusted with sliders. Making the MRI template darker or lighter can be helpful sometimes. + +Save the anchoring **(6)** + Save by clicking the Store button in the upper left panel: a green exclamation mark + appears in the upper right panel. + +.. image:: 6bef45ee36424df69f030c687f030605/media/image9.png + :width: 1.11944in + :height: 0.21563in + + + + diff --git a/Docs/angles.rst b/Docs/angles.rst new file mode 100644 index 0000000..4b04116 --- /dev/null +++ b/Docs/angles.rst @@ -0,0 +1,40 @@ +**Determine the sectioning angles** +----------------------------------- +Next, adjust the angles of the atlas slice to match the angles of +sectioning. Even the best sectioning routines can induce small +deviations from the vertical and horizontal planes. +Furthermore, those angles can vary in a whole series, especially if +the tissue was cut into two separate blocks. The cutting angles of +the atlas should be adjusted to match the mediolateral and +dorsoventral angles of the sections. This is done in the horizontal +and sagittal navigation windows, respectively. Use either the +rotation buttons (1) or rotation handles (2) to tilt the MRI +template in the direction needed. Adjust the anteroposterior +position to compensate for the rotation. + +.. image:: 6bef45ee36424df69f030c687f030605/media/image14.png + :width: 4.15694in + :height: 2.79387in + +.. image:: 6bef45ee36424df69f030c687f030605/media/image15.png + :width: 4.52083in + :height: 0.70425in + +The angles of the current atlas slice relative to the default atlas +plane can be read out in the boxes shown above, corresponding to the +sagittal (1) and horizontal (2) navigation windows. + +In coronal sections, the dorsoventral angle can be determined by +examining the relationship between landmarks in dorsal and ventral parts +of a section, e.g. between the corpus callosum and anterior commissure, +between the dorsal and ventral hippocampus, or between the pons and +inferior colliculus. The mediolateral angle can be determined by +comparing landmark structures across hemispheres. It is most easily +found by examining the development of the corpus callosum, anterior +striatum, anterior commissure, anterior hippocampus, or size differences +of the cortex in the posterior part of the brain. + +**Note**: the results might look similar with angles that deviate 180 +degrees (corresponding to looking at the animal from the back or from +the front). + diff --git a/Docs/conf.py b/Docs/conf.py new file mode 100644 index 0000000..a437c58 --- /dev/null +++ b/Docs/conf.py @@ -0,0 +1,64 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'QuickNII' +copyright = '2021, NeSys' +author = 'NeSys' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx_rtd_theme'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +#html_theme = 'alabaster' + +html_theme = 'sphinx_rtd_theme' +html_theme_options = { + 'collapse_navigation': False, + 'sticky_navigation': True, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': False} +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] +html_logo = "QuickNII_logo.png" +html_theme_options = { + 'logo_only': True, + 'display_version': False +} diff --git a/Docs/coordinates.rst b/Docs/coordinates.rst new file mode 100644 index 0000000..2739c9a --- /dev/null +++ b/Docs/coordinates.rst @@ -0,0 +1,27 @@ + +**Coordinates** +---------------------------------- +*-Coordinate systems:* +Information about the coordinate systems can be found here: https://www.nitrc.org/plugins/mwiki/index.php?title=quicknii:Coordinate_systems + +*-Image coordinates:* +Assigning voxel coordinates to image pixels. +Find out more here: https://www.nitrc.org/plugins/mwiki/index.php?title=quicknii:Image_coordinates + +Converters: + +- https://tevemadar.github.io/QuickNII-extras/HTML/QNII2AMBA-CCFv3.html + +- https://tevemadar.github.io/QuickNII-extras/HTML/QNII2WHSRat.html + +*-Lambda-Bregma:* + +Voxel coordinates of the mouse cursor can be read from the top-left corner of the main window. +Some coordinates for Bregma and Lambda are available for the WHS-SD-Rat atlas, "Coordinates v1 - v1.01.pdf" on https://www.nitrc.org/docman/?group_id=1081 . +Using those data, we provide a simple converter page, where voxel-coordinate triplets can be entered and are converted to location related to Bregma and Lambda, expressed in millimeters. + +- https://tevemadar.github.io/QuickNII-extras/HTML/WHS-SD-Rat.html + +It has to be noted that this is not an exact Stereotactic conversion, distance is measured along the axes of the volume, where Bregma and Lambda have almost a millimeter vertical separation. +The volume is tilted forwards approximately by 4 degrees, and it has a small, but noticeable rotation around the vertical axis too. + diff --git a/Docs/export.rst b/Docs/export.rst new file mode 100644 index 0000000..70032e3 --- /dev/null +++ b/Docs/export.rst @@ -0,0 +1,39 @@ +**Export of atlas maps for the QUINT workflow** +--------------------------------------------------- +In order to export custom atlas slices corresponding to your series. +Press the “export Slices” button and select the destination folder. + +.. image:: 6bef45ee36424df69f030c687f030605/media/image19.png + :width: 4.25in + :height: 2.44459in + +In the export folder, you will also find a file named "segmentation.json" for the rat atlases. This just an information file which gives an overview of the atlas regions label values of the flat files. + +.. note:: + This file should not be confused with the anchoring JSON file used for the QUINT workflow! + +**Export of atlas maps contours for overlaying with your images** +------------------------------------------------------------------ +In order to export custom atlas slices corresponding to your series. +Press the “export Slices” button and select the destination folder. + +Open the exported QuickNII rainbow png files or the exported nl.png files from VisuAlign in ImageJ + +- open colorful segmentation image xy_seg.png +- Process/Find Edges +- Image/Type > 8-bit +- Image/Adjust > Threshold..., and pull the upper slider to the far left, Apply. If you untick Dark background, it will also invert the result (to black contour on white background). Auto Local Threshold... (also in Image/Adjust) may achieve a similar result in a couple clicks less. +- Save the image +- Scale to the same dimentions as your raw experimental file (match X and Y), save +- Copy the outline file and paste using "Edit"/"Paste Control...", "Transparent-white". +- Save + +.. image:: 6bef45ee36424df69f030c687f030605/media/image20.png + :width: 4.25in + :height: 2.44459in + + + + + + diff --git a/Docs/imageprepro.rst b/Docs/imageprepro.rst new file mode 100644 index 0000000..846442a --- /dev/null +++ b/Docs/imageprepro.rst @@ -0,0 +1,80 @@ +**Image preprocessing requirements** +------------------------------------- +**Input data** +~~~~~~~~~~~~~~~~~~ +| QuickNII supports standard web-compatible image formats, **24-bit PNG + and JPEG**. Images can be loaded up to the resolution of 16 megapixels + (e.g. 4000x4000 or 5000x3000 pixels), however QuickNII does not + benefit from image resolutions exceeding the resolution of the monitor + in use. For a standard FullHD or WUXGA display (1920x1080 or 1920x1200 + pixels) the useful image area is approximately 1500x1000 pixels, using + a similar resolution ensures optimal image-loading +| performance. + +.. Note:: + **When using *Filebuilder* to generate the image series descriptor file, a warning will appear if your files are too big (details below).** + +Preprocessing of images with other software tools (e.g. Nutil Transform, +ImageMagick, Matlab scripts) or python scripts found in many open source +libraries (e.g. PIL)) is usually needed to fulfill these requirements +(converting to PNG or JPEG and downscaling to screen-like size), but +QuickNII allows storage of original image dimensions as part of its +series descriptor. + +**File naming convention** +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Serial section images should be assigned consecutive serial numbers, +preferably indicated by three-digit numbers at the end of the file +name\ **, e.g. Sample_ID_s001.png** + +The section number should reflect the serial order and spacing of the +sections (e.g. s002, s006, s010 for every 4th section starting with +section 2). + +.. Note:: + **If you plan to analyse your images with the QUINT workflow, both the image segmentation file from ilastik and the atlas map that correspond to a particular section must contain a unique ID that meets the file naming requirement described above. These unique IDs must also be present in the XML/JSON file containing the anchoring information: this happens automatically as long as the images that are anchored with QuickNII contain the unique IDs.** + +Nutil Quantifier supports IDs in the format: sXXX.., with XXX.. +representing the section number, as well as formats defined by regular +expressions. + +Example: tg2345_MMSH_s001_segmentation.png (It is fine to include a +string of letters and numbers followed by the unique ID). + +As Nutil Quantifier scans and detects the \_s part of the name, the file +name should not contain additional \_s. +Example that would not work: +tg2345_MMSH_ss_s001.png + +**Generate a XML descriptor file** +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Collect the section images in a folder. The section sampling is defined by the serial numbers. + +Remember to have a filenaming pattern that is consistent and with equal number of digits. + +Use the small program “FileBuilder.bat” provided with QuickNII to +generate the XML descriptor file. A new window will open, and ask for the folder where your +images are located. Point to the correct folder, mark all image files (ctrl+A), and click ok. + +.. image:: 6bef45ee36424df69f030c687f030605/media/image3.png + :width: 2.88889in + :height: 2.01888in + +.. image:: 6bef45ee36424df69f030c687f030605/media/image4.png + :width: 6.29306in + :height: 0.57028in + +Files will be reviewed, and an xml file will be generated when all +files passed (green OK). If the files are too big they will not pass and get a red warning. The +orange warning allows files to pass. + +Click “Save xml”and give a name to your descriptor file. You can now +open the xml in QuickNII. If the section number is not recognized, you have the option to just +number the images in filebuilder. + +**NOTE! The xml descriptor file must be located in the same folder as +the small png or jpeg images for QuickNII.** + + + diff --git a/Docs/index.rst b/Docs/index.rst new file mode 100644 index 0000000..b01c53a --- /dev/null +++ b/Docs/index.rst @@ -0,0 +1,34 @@ +QuickNII: Software for 2D image registration to 3D atlas +============================================================ + +.. toctree:: + :caption: QuickNII documentation + :maxdepth: 3 + + Introduction + Installation + Acknowledgements + support + FAQ + + + + +.. toctree:: + :caption: Operations + :numbered: + :maxdepth: 3 + + imageprepro + anchoring + landmarks + angles + adjust + saving + coordinates + export + publications + + + + diff --git a/Docs/landmarks.rst b/Docs/landmarks.rst new file mode 100644 index 0000000..5d2f4f9 --- /dev/null +++ b/Docs/landmarks.rst @@ -0,0 +1,37 @@ +**Landmarks** +--------------- +By clicking the roll-down bar in the top left corner, MRI, DTI (for WHS atlas only) or atlas templates can be chosen. +It is useful to use these different atlases actively as they give different information +that can be used when anchoring. +Detailed description of the UI can be found at: https://www.nitrc.org/plugins/mwiki/index.php?title=quicknii:Basic_operation + +.. image:: 6bef45ee36424df69f030c687f030605/media/image10.png + :width: 5.40139in + :height: 2.80739in + +It is easiest to establish the anteroposterior position of sections +that containing key anatomical landmarks. Some examples are shown below: + +.. image:: 6bef45ee36424df69f030c687f030605/media/image11.png + :width: 4.40139in + :height: 2.80739in + +**Genu of the corpus callosum** + +.. image:: 6bef45ee36424df69f030c687f030605/media/image12.png + :width: 4.40139in + :height: 2.80739in + +**Decussation of the anterior commissure** + +.. image:: 6bef45ee36424df69f030c687f030605/media/image13.png + :width: 4.40139in + :height: 2.80739in + +**Optic tract in red, mid-level of the anterior hippocampus** + +Find more lamdmark examples in this resource: https://zenodo.org/records/7575515 + + + + diff --git a/Docs/publications.rst b/Docs/publications.rst new file mode 100644 index 0000000..e404dc4 --- /dev/null +++ b/Docs/publications.rst @@ -0,0 +1,73 @@ +**Related publications** +---------------------------- +* Puchades M, Yates SC, Csucs G, Carey H, Balkir A, Leergaard T, Bjaalie J. + Software and pipelines for registration and analyses of rodent brain image data in reference atlas space. Frontiers of Neuroinformations. 2025. + https://doi.org/10.3389/fninf.2025.1629388 + +* Ham GX, Augustine GJ. + Topologically Organized Networks in the Claustrum Reflect Functional Modularization. Frontiers in Neuroanatomy. 16 June 2022. + https://doi.org/10.3389/fnana.2022.901807 + +* Szabo G.G, Farrell J.S, Dudok B, Hou W, Ortiz A.L, Varga C, Moolchand P, Gulsever C, Gschwind T, Dimidschstein J, Capogna M. and Soltesz I. + Ripple-selective GABAergic projection cells in the hippocampus. Neuron 2022 https://doi.org/10.1016/j.neuron.2022.04.002 + +* Tocco C, Øvsthus M, Bjaalie J.G, Leergaard T.B and Studer M. + Topography of corticopontine projections is controlled by postmitotic expression of the area-mapping gene Nr2f1. + bioRxiv - May 2021 https://doi.org/10.1101/2021.05.10.443413 + +* Whilden CM, Chevée M, An Seong Yeol, Pezon Brown S. + The synaptic inputs and thalamic projections of two classes of layer 6 corticothalamic neurons in primary somatosensory cortex of the mouse + J Comp Neurol. 2021 Dec;529(17):3751-3771. doi: https://doi.org/10.1002/cne.25163. Epub 2021 May 6. + +* Kim Gyeong Tae, Bahn Sangkyu, Kim Nari, Choi Joon Ho, Kim Jinseop S, Rah Jong-Cheol . + Efficient and Accurate Synapse Detection With Selective Structured Illumination Microscopy on the Putative Regions of Interest of Ultrathin Serial Sections + Front Neuroanat. 2021 Nov 15;15:759816. doi: https://doi.org/10.3389/fnana.2021.759816. eCollection 2021. + +* Kim Nari, Bahn Sangkyu, Choi Joon Ho, Kim Jinseop S, Rah Jong-Cheol. + Synapses from the Motor Cortex and a High-Order Thalamic Nucleus are Spatially Clustered in Proximity to Each Other in the Distal Tuft Dendrites of Mouse Somatosensory Cortex. Cerebral Cortex - August 2021. https://doi.org/10.1093/cercor/bhab236 + +* Oh Seung Wook, Son Sook Jin, Morris JA, Choi Joon Ho , Lee Chankyu, Rah Jong-Cheol. + Comprehensive Analysis of Long-Range Connectivity from and to the Posterior Parietal Cortex of the Mouse + Cereb Cortex. 2021 Jan 1;31(1):356-378. doi: https://doi.org/10.1093/cercor/bhaa230. eCollection 2021. + +* Guyon N, Zacharias LR, Fermino de Oliveira E, Kim H, Leite JP, Lopes-Aguiar C, Carlén M. + Network Asynchrony Underlying Increased Broadband Gamma Power. J Neurosci. 2021 Mar 31;41(13):2944-2963 + doi: https://doi.org/10.1523/JNEUROSCI.2250-20.2021 + +* McDonald MW, Jeffers MS, Filadelfi M, Vicencio A, Heidenreich G, Wu J and Silasi G. + Localizing Microemboli within the Rodent Brain through Block-Face Imaging and Atlas Registration. eNeuro 16 July 2021, 8 (4) ENEURO.0216-21.2021; DOI: https://doi.org/10.1523/ENEURO.0216-21.2021 + +* Kim Seongyeon, Jo Yehhyun, Kook Geon, Pasquinelli C, Kim Hyunggug, Kim Kipom, Hoe Hyang-Sook, Choe Youngshik, Rhim Hyewhon, Thielscher A, Kim Jeongyeon and Lee Hyunjoo Jenny. + Transcranial focused ultrasound stimulation with high spatial resolution. Brain Stimulation, 14(2), 290-300 - January 2021. https://doi.org/10.1016/j.brs.2021.01.002 + +* Bjerke IE, Yates SC, Laja A, Witter MP, Puchades MA, Bjaalie JG and Leergaard TB. + Densities and numbers of calbindin and parvalbumin + positive neurons across the rat and mouse brain. 2021, iScience.https://doi.org/10.1016/j.isci.2020.101906 + +* Groeneboom NE, Yates SC, Puchades MA and Bjaalie JG. + Nutil: A Pre- and Post-processing Toolbox for Histological Rodent Brain + Section Images. Front. Neuroinform. 2020,14:37. https://doi.org/10.3389/fninf.2020.00037 + +* Yates SC, Groeneboom NE, Coello C, Lichtenthaler SF, Kuhn PH, Demuth HU,Hartlage-Rübsamen M, Roßner S, Leergaard T, Kreshuk A, Puchades MA, Bjaalie JG. + QUINT: Workflow for quantification and spatial + analysis of features in histological images from rodent brain. *Front + Neuroinform.* 2019 Dec 3;13:75. https://doi.org/10.3389/fninf.2019.00075. + +* Puchades MA, Csucs G, Lederberger D, Leergaard TB and Bjaalie JG. + Spatial registration of serial microscopic brain images to + three-dimensional reference atlases with the QuickNII tool. PLosONE, + 2019, 14(5): e0216796. https://doi.org/10.1371/journal.pone.0216796 + +* Bjerke IE, Ovsthus M, Papp EA, Yates SC, Silvestri L, Fiorilli J,Pennartz CMA, Pavone FS, Puchades MA, Leergaard TB and Bjaalie JG. + Data integration through brain atlasing: Human Brain Project tools and strategies. *European journal of Psychiatry*, April 2018, pp70-76. + https://doi.org/10.1016/j.eurpsy.2018. + +* Bjerke IE, Ovsthus M, Andersson KA, Blixhavn CH, Kleven H, Yates SC, Puchades MA, Bjaalie JG and Leergaard TB. + Navigating the murine brain: towards best practices for determining and documenting + neuroanatomical locations in experimental studies. Frontiers in + Neuroanatomy. 2018 Nov 2; 12: article 82. https://doi.org/10.3389/fnana.2018.00082 + + + + + diff --git a/Docs/requirements.txt b/Docs/requirements.txt new file mode 100644 index 0000000..483a4e9 --- /dev/null +++ b/Docs/requirements.txt @@ -0,0 +1 @@ +sphinx_rtd_theme diff --git a/Docs/saving.rst b/Docs/saving.rst new file mode 100644 index 0000000..026400b --- /dev/null +++ b/Docs/saving.rst @@ -0,0 +1,51 @@ +**Saving results and validation** +-------------------------------- +Remember to save the anchoring result by clicking “store”. Export the +anchoring vector data by clicking “Save XML” or “save JSON”. The two are +identical; however, the JSON format is required to proceed to nonlinear +registration in VisuAlign. + +A new window will open and you will be able to export results into a new +file. Type a new name, e.g. initials and date. + +.. image:: 6bef45ee36424df69f030c687f030605/media/image17.png + :width: 6.30139in + :height: 3.1582in + +Graphs provide an initial indication of registration accuracy. If +deviations from the linear regression line are present, a revision of +the anchoring should be done. Independent validation by a curator is +recommended. + +.. image:: 6bef45ee36424df69f030c687f030605/media/image18.png + :width: 5.37222in + :height: 3.25228in + +-**Positon, Spacing**: position and spacing of section midpoints measured along the internal axis of the series, formed by the section midpoints themselves. Expressed in millimeters. Zero is positioned on the first section. + +-**MainPosition, MainSpacing**: position and spacing of section midpoints measured along the main axis selected via the operation mode (like for coronal series, anterior-posterior axis is the main one). Expressed in millimeters. Position is absolute inside the template volume, zero is positioned on the border planes (like most posterior for coronal series). + +-**Rotation1/2**: rotation around the primary (red) and secondary (green) axis, dependent on operating mode again. Expressed in degrees. In case of sagittal mode, primary axis is anterior-posterior, secondary axis is vertical. + +.. image:: 6bef45ee36424df69f030c687f030605/media/image15.png + :width: 4.52083in + :height: 0.70425in + +-**H/VStretch**: ratio between image pixels and atlas voxels. Calculated along the horizontal and vertical edges of the image. +In an ideal world all graphs are straight lines, just like the orange line behind (linear regression of actual data). Position graphs are ideally diagonal, all the others are horizontal at some constant value. + + +**Quality of the registration can also be assessed with QCAlign** + + +.. note:: + Find QCAlign user documentation `here `_. + Download `here `_. + +QCAlign was developed to support the use of the QUINT workflow for high-throughput studies. It is a quality control tool that provides information about: + +1. The quality of the section images used as input to the QUINT workflow. It enables detection of regions that are affected by tissue damage, labelling defects, artifacts, or errors in image acqusition. + +2. The quality of the atlas-registration performed in the QUINT workflow. + +In addition, QCAlign supports exploration of the reference atlas hierarchy, and the creation of a customized level to use for the investigation. diff --git a/Docs/support.rst b/Docs/support.rst new file mode 100644 index 0000000..51187c2 --- /dev/null +++ b/Docs/support.rst @@ -0,0 +1,5 @@ +**Contact us** +--------------- +To report issues: https://github.com/Neural-Systems-at-UIO/QuickNII + +For user support: support@ebrains.eu diff --git a/README.md b/README.md new file mode 100644 index 0000000..72cd647 --- /dev/null +++ b/README.md @@ -0,0 +1,37 @@ +# QuickNII + +QuickNII is one of several tools developed by the Nesys laboratory, University of Oslo with the aim of facilitating brain atlas based analysis and integration of experimental data and knowledge about the human and rodent brain. +QuickNII is a stand-alone desktop software for user guided affine spatial registration (anchoring) of sectional image data, typically high resolution histological images, to a 3D reference atlas space. +A key feature of the tool is its ability to generate user defined cut planes through the atlas templates that match the orientation of the cutting plane of the 2D experimental images (atlas maps). + +# Download +Nitrc.org: https://www.nitrc.org/frs/?group_id=1341 + +# Latest stable version +Version 2.2 (2019-05-28) This release includes several reference atlases: ABAMouse-v3-2015; ABAMouse-v3-2017 and WHSRat-v2, v3 and v4; Kim-UnifiedMouse-v1 both with Mac and Windows. + +# Documentation +https://quicknii.readthedocs.io + +# Contributors +- Programming: Gergely Csucs +- Conception, design, validation: Gergely Csucs, Maja A Puchades, Sharon C Yates, Jan G Bjaalie. + +# Licence +- Main component: Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International +- Source code: MIT licence + +# Citation +**QuickNII (RRID:SCR_016854)**. +- Puchades MA, Csucs G, Lederberger D, Leergaard TB and Bjaalie JG. Spatial registration of serial microscopic brain images to three-dimensional reference atlases with the QuickNII tool. PLosONE, 2019, 14(5): e0216796. https://doi.org/10.1371/journal.pone.0216796 +- Puchades MA, Yates SC, Csucs G, Carey H, Balkir A, Leergaard TB, Bjaalie JG. Software and pipelines for registration and analyses of rodent brain image data in reference atlas space. Front Neuroinform. 2025 Sep 24;19:1629388. https://doi.org/10.3389/fninf.2025.1629388 + +# Acknowledgements +QuickNII is developed by the Neural Systems Laboratory at the Institute of Basic Medical Sciences, University of Oslo, Norway. QuickNII was developed with support from the EBRAINS infrastructure, and funding from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Framework Partnership Agreement No. 650003 (HBP FPA) and the European Union’s Horizon Europe Programme for Research Infrastructures Grant Agreement No. 101147319 (EBRAINS 2.0). + +# Contact us +Report issues here on github or email: support@ebrains.eu + + + + diff --git a/codemeta.json b/codemeta.json new file mode 100644 index 0000000..6c487dd --- /dev/null +++ b/codemeta.json @@ -0,0 +1,93 @@ +{ + "@context": "https://w3id.org/codemeta/3.0", + "@type": "SoftwareSourceCode", + "name": "QuickNII", + "identifier": "RRID:SCR_016854", + "description": "QuickNII is a tool for user guided affine registration (anchoring) of 2D experimental image data, typically high resolution microscopic images, to 3D atlas reference space, facilitating data integration through standardized coordinate systems.", + "author": [ + { + "givenName": "Gergely", + "familyName": "Csucs", + "type": "Person", + "id": "https://orcid.org/0000-0002-2093-6274", + "affiliation": { + "type": "Organization", + "name": "NeSys lab, University of Oslo" + } + }, + { + "givenName": "Trygve B.", + "familyName": "Leergaard", + "type": "Person", + "id": "https://orcid.org/0000-0001-5965-8470", + "affiliation": { + "type": "Organization", + "name": "NeSys lab, University of Oslo" + } + }, + { + "givenName": "Maja A.", + "familyName": "Puchades", + "type": "Person", + "id": "https://orcid.org/0000-0002-4536-8197", + "affiliation": { + "type": "Organization", + "name": "NeSys lab, University of Oslo" + } + }, + { + "givenName": "Jan G.", + "familyName": "Bjaalie", + "type": "Person", + "id": "https://orcid.org/0000-0001-7899-906X", + "affiliation": { + "type": "Organization", + "name": "NeSys lab, University of Oslo" + } + } + ], + "license": [ + "https://spdx.org/licenses/MIT" + ], + "version": "2.2", + "dateModified": "2019-05-28", + "codeRepository": "https://github.com/Neural-Systems-at-UIO/QuickNII", + "downloadUrl": "https://www.nitrc.org/projects/quicknii/", + "relatedLink": [ + "https://quicknii.readthedocs.io" + ], + "softwareHelp": [ + "mailto:support@ebrains.eu" + ], + "referencePublication": "https://doi.org/10.1371/journal.pone.0216796", + "programmingLanguage": [ + "ActionScript", + "Java" + ], + "runtimePlatform": "AIR", "JRE", + "operatingSystem": [ + "Windows", + "macOS", + "Linux" + ], + "availableOnDevice": [ + "desktop" + ], + "softwareRequirements": [ + "file naming convention", + "Display resolution minimum 1440 pixels wide and minimum 650 pixels high.", + "3 gigabytes RAM" + ], + "developmentStatus": "active", + "issueTracker": "https://github.com/Neural-Systems-at-UIO/QuickNII/issues", + "continuousIntegration": "https://github.com/Neural-Systems-at-UIO/QuickNII", + "keywords": [ + "2D image registration", + "atlas" + ], + "isPartOf": "https://quint-workflow.readthedocs.io/en/latest/", + "funder": { + "type": "Organization", + "name": "H2020-EU.1.2 SGA 720270, H2020-EU.2.3 SGA 785907 and HORIZON-INFRA (EBRAINS 2.0) 101147319" + } +}