Tevemadar · Majpuc · Oct 5, 2021 · Oct 5, 2021 · Oct 5, 2021 · Oct 5, 2021
diff --git a/.github/workflows/ebrains.yml 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
@@ -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
@@ -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
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image10.png b/Docs/6bef45ee36424df69f030c687f030605/media/image10.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image11.png b/Docs/6bef45ee36424df69f030c687f030605/media/image11.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image12.png b/Docs/6bef45ee36424df69f030c687f030605/media/image12.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image13.png b/Docs/6bef45ee36424df69f030c687f030605/media/image13.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image14.png b/Docs/6bef45ee36424df69f030c687f030605/media/image14.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image15.png b/Docs/6bef45ee36424df69f030c687f030605/media/image15.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image16.png b/Docs/6bef45ee36424df69f030c687f030605/media/image16.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image17.png b/Docs/6bef45ee36424df69f030c687f030605/media/image17.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image18.png b/Docs/6bef45ee36424df69f030c687f030605/media/image18.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image19.png b/Docs/6bef45ee36424df69f030c687f030605/media/image19.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image2.png b/Docs/6bef45ee36424df69f030c687f030605/media/image2.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image20.png b/Docs/6bef45ee36424df69f030c687f030605/media/image20.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image3.png b/Docs/6bef45ee36424df69f030c687f030605/media/image3.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image4.png b/Docs/6bef45ee36424df69f030c687f030605/media/image4.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image5.png b/Docs/6bef45ee36424df69f030c687f030605/media/image5.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image6.png b/Docs/6bef45ee36424df69f030c687f030605/media/image6.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image7.png b/Docs/6bef45ee36424df69f030c687f030605/media/image7.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image8.png b/Docs/6bef45ee36424df69f030c687f030605/media/image8.png
diff --git a/Docs/6bef45ee36424df69f030c687f030605/media/image9.png b/Docs/6bef45ee36424df69f030c687f030605/media/image9.png
diff --git a/Docs/Acknowledgements.rst 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
diff --git a/Docs/FAQ.rst 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
@@ -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
@@ -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 <https://visualign.readthedocs.io/en/latest/>`_ 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 <https://ebrains.eu/service/quint/>`_ for more information about the QUINT workflow. Find full user documentation `here <https://quint-workflow.readthedocs.io>`_. 
+
+**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
diff --git a/Docs/adjust.rst 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
@@ -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
@@ -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). 
+