Added logo and updated version in docs

SPIERSalign/docs/.vscode/tasks.json

@@ -0,0 +1,17 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "build docs",
+            "type": "shell",
+            "command": "sphinx-build ./ ../docs_build",
+            "problemMatcher": [],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        }
+    ]
+}

SPIERSalign/docs/build_docs.sh

@@ -0,0 +1,8 @@
+#This command will build the documentation on a system that has python3, sphinx, and the correct theme installed. 
+#On Linux that erquires these commands (assuming Python3 is already installed):
+#sudo apt-get install python3-sphinx
+#sudo apt install python3-pip
+#sudo pip3 install sphinx_rtd_theme
+echo "Now building trevosim doc"
+sphinx-build ./ ../docs_build
+

SPIERSalign/docs/conf.py

@@ -22,13 +22,13 @@
 # -- Project information -----------------------------------------------------
 
 project = 'SPIERSalign'
-copyright = '2018-2019, Russell Garwood, Mark Sutton, Alan R.T. Spencer'
+copyright = '2018-2021, Russell Garwood, Mark Sutton, Alan R.T. Spencer'
 author = 'Russell Garwood, Mark Sutton, Alan R.T. Spencer'
 
 # The short X.Y version
-version = '3.0.0'
+version = '3.1.1'
 # The full version, including alpha/beta/rc tags
-release = '3.0.0'
+release = '3.1.1'
 
 
 # -- General configuration ---------------------------------------------------
@@ -125,7 +125,7 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = '_static/SPIERS.jpg'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

SPIERSalign/docs_build/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 7ddc7654171152e1ccffbd9c5b6c5291
+tags: 645f666f9bcd5a90fca523b33c5a78b7

SPIERSalign/docs_build/_sources/advancednavigation.rst.txt

@@ -0,0 +1,28 @@
+.. _advancednavigation:
+
+Advanced Navigation
+===================
+
+Hiding Images
+-------------
+
+Occasionally users may find an image in the sequence that they wish to hide temporarily (for example they wish to visually compare images 10 and 12 by flicking between them, without 11 always appearing in the way). To hide the currently viewed image use the *Hide Image* command on the *Navigate* menu. The image will remain on screen (the status bar notes that it is hidden), but if the user navigates forward and then back again with the ‘.’ and ‘,’ keys they will find that the hidden image is skipped. Using *Ctrl-Shift-'.'* and *Ctrl-Shift-','* to navigate will move to the next/previous image whether or not it is hidden; hidden images can also be accessed using both the spin box and horizontal file slider. To unhide the currently viewed image use the *Hide Image* command on the *Navigate* menu. An *Unhide All* command is also available on the *Navigate* menu.
+
+Hidden images are still processed during cropping and propagation; it is advisable to perform an Unhide All operation before cropping to ensure that objects of interest do not extend outside the crop-box on hidden images.
+
+Propagation
+-----------
+
+SPIERSalign provides a facility to record changes made to one image, and then apply those changes to all subsequent or previous images in the sequence. This feature is useful, for instance, where one image has been omitted during alignment and all of the changes made to this need to be applied to the subsequent (aligned) images. To use this mode select the Propagation Mode item on the Locking/Propagation menu **while viewing the image from which you want to apply the changes**. SPIERSalign will ask you whether you want to propagate forwards (to the end of the dataset) or backwards (to the beginning). Propagation mode limits navigation to the propagation image and one either before it (forwards propagation) or after it (backwards propagation). Only the propagation image can be rotated, scaled or shifted. Once all changes to the propagation image have been made, the *Apply Progagation* command on the *Locking/Propagation* menu will then apply the changes to the required images.
+
+Propagation mode (forward flavour) can be used on the first image of a dataset to make changes to the entire dataset; for instance to adjust size or orientation.
+
+File Locking
+------------
+
+SPIERSalign provides a 'file locking' feature (*Lock Forward* or *Lock Backward* on the *Locking/Propagation* menu). When activated, this mode restricts navigation to just two images, and only enables rotations, scales or shifts to be applied to one of these. *Forward Locking* allows changes to be performed on the second image of the pair, and *Backward Locking* on the first. The *Move Forward/Back* command on the *Locking/Propagation* menu moves the pair either forward or back in the dataset, depending on the mode. This mode is intended as an aid to alignment, enabling a user to work through the dataset one slice at a time without accidentally moving the wrong image. Note that when viewing the locked image of the pair, the Lock File option in the Locking/Propagation menu will be ticked; unticking this temporarily overrides the locking.
+
+Swapping Files
+--------------
+
+Occasionally you may find that two images are the wrong way round in the sequence, and need to be swapped over. The *Swap Image* command on the *Transform* menu will swap the current image with the next one. Note that it is possible to move images to any desired position in the sequence by successive swap operations.

SPIERSalign/docs_build/_sources/advancedsettings.rst.txt

@@ -0,0 +1,14 @@
+.. _advancedsettings:
+
+Advanced Settings File Usage
+============================
+
+Loading Backups
+---------------
+
+A backed-up settings file (see above) can be loaded and applied to the dataset using the Load Settings File command on the File menu. This operation overwrites the current settings file (which should be backed-up beforehand), and applies the settings to the image list. This will only work with the original dataset; if there have been any changes to the file names or any additions to or deletions from the dataset, it will fail.
+
+Constant Autosave
+-----------------
+
+If SPIERSalign crashes after a long period of work, it is possible that changes since the last save will be lost. This loss may not be apparent until you next try and transform any given image, at which point the new transformation will be applied to the original image, not the altered .xxx file which will have been loaded on initial viewing. To guard against this, the Constant Autosave option in the File menu is provided; with this selected SPIERSalign will resave settings.txt after every transformation, removing the risk of losing unsaved work. This should make no noticeable difference in performance on all but the oldest PCs, and so is checked as standard.

SPIERSalign/docs_build/_sources/automatedalignment.rst.txt

@@ -0,0 +1,32 @@
+.. _automatedalignment:
+
+Automated Alignment
+===================
+
+Semi-automated Align
+--------------------
+
+The *Semi-automated Align*, or automated markers system is a fast way of aligning images using the markers system. To do this markers should be placed to pick out fiduciary markings and features of interest, as outlined above, on the datum image. Automated markers should then be toggled by clicking the *Auto Markers* button in the *Markers* panel. This places a grid over the markers and underlying images (Fig. 4A). The user can then navigate through the dataset. When viewing an image requiring alignment, clicking and dragging the mouse can manipulate the automarker grid. Dragging the corners will rotate the grid, and anywhere near the centre will physically drag it (Fig. 4B). The markers will be move with the grid, allowing them to be aligned with the features of interest or fiduciary marks in the underlying image. When the markers lie in the correct position relative to the fossil, the button *AM:Align* (keyboard shortcut Alt-A) aligns the slice (Fig. 4C). This is done by returning the grid and markers to their original positions – which were defined on the datum image – and applying the same 'correcting' transformation to the current image. This process can then be repeated moving through the dataset.
+
+Semi-automated alignment is best suited to datasets with drilled fiduciary holes or no fiduciary features; markers can be placed over each hole or parts of the specimen and the slice corrected; an entire dataset can be rapidly in this way, although subsequent finer adjustments are likely to be required.
+
+.. figure:: _static/figure_4.png
+    :align: center
+
+    Figure 4. The default user interface of SPIERSalign with semi-automated alignment toggled. Note the grid in addition to the markers; this is shown superimposed on the reference tomogram. B. An unaligned tomogram, with the grid rotated (white arrow) to align the markers with the boundaries of the fossil. C. The same tomogram, aligned by resetting the grid and transforming the underlying image.
+
+Clicking *AM:Edit Grid* in the *Markers* panel allows the user to change the size, position and line thickness of the grid, in addition to the number of cells. Clicking the *Auto Markers* button in the *Markers* panel will turn off automated markers, allowing markers to be readjusted and used as usual. While using *Auto Markers* it is not possible to add or remove, or adjust the position, colour thickness or shape of the markers.
+
+True Automated Align (Auto Align)
+---------------------------------
+
+SPIERSalign provides a facility for the automated alignment of images based upon straight edges within the image. This algorithm will only work on datasets which possess two non-parallel fiduciary edges throughout the zone to be aligned. The system has its own panel (*Auto Align*, F3) showing the options for auto aligning - the panel should open in the left docking area when a dataset is loaded. Before alignment can occur, the user should click the *Setup* button; this displays two boxes on the image, one horizontal and one vertical. These should be placed over the edges upon on which the alignment is to be performed by resizing, dragging and rotating the boxes. These 'edge zones' should cover as much of the fiduciary edges as possible, on every image to be aligned, but without overshooting the edge on any image. Neither box should be rotated more than sixty degrees from their original position. They can go over the edge of the image (i.e. the top, bottom left or right boundary of the file) but should not be placed entirely off the image (Fig 5).
+
+.. figure:: _static/figure_4.png
+    :align: center
+
+    Figure 5. Auto align in setup mode showing the correct placement of setup boxes.
+
+Once these zones are correctly positioned, the user can exit by clicking setup again. An instruction box will appear, explaining the next steps and giving the option of a *Verbose Mode*. This is usually not necessary – if chosen it will display the line equations for the detected edges on both datum and subsequent images, and the required adjustment of the current image. The user can then highlight the slices to be aligned in the *Auto Align* selection box. *Clicking Align* in the *Auto Align* panel will then align selected slices against the currently displayed, datum image. Often the setup boxes will have to be quite large on the initial align to satisfy the conditions above, providing sub-optimal aligning. *Auto Align* can be run repeatedly, however, with increasingly tighter setup boxes around the fiduciary edges. This will allow a more accurate alignment, and can align many datasets so they only need minor corrections after three such iterations.
+
+This algorithm only works on straight edges (more details on how it works are available: https://spiral.imperial.ac.uk/handle/10044/1/6334). It does not take into account any scale errors in images. If any of the images are very poorly aligned, the *Reset Image* button will return the image to its original position. Very noisy images could hinder its performance, as can poorly positioned setup boxes – i.e. those which feature a large area without an edge, and those at a low angle to each other.

SPIERSalign/docs_build/_sources/basicaligningprocedure.rst.txt

@@ -0,0 +1,14 @@
+.. _basicaligningprocedure:
+
+Basic Aligning Procedure
+========================
+
+A SPIERSalign session in which you wish to align a set of 100 unregistered images will normally involve the following stages:
+
+1) Open a series of images and select one (arbitrarily) to act as the datum – all other images will be rotated/shifted/scaled to line up with this one. Typically, the datum image is near the centre of the run; this example will assume that image 50 out of 100 has been selected.
+2) Set up lines and/or circles on image 50 to mark the fiduciary points (see Markers Panel below). These markers don’t actually do anything, but provide visual reference points that can be used as a guide for alignment.
+3) Move to image 51 (see *Navigating Datasets*), and perform rotate, shift and if necessary rescale operations until the image position fits the fiduciary markings (see *Shifting, Rotating and Scaling Images*). It is advisable also to flick repeatedly between image 50 and 51 to check visually that alignment has been achieved.
+4) Repeat step 3 for image 52 (checking against image 51), and continue until the end of the run (image 100) has been reached.
+5) Return to the datum image (50), and repeat steps 3 and 4, this time going backwards through the sequence (aligning 49 to 50, 48 to 49 etc.)
+6) When happy with alignment (it is advisable to run through the entire sequence to ensure that all movement is as smooth as possible), enter crop mode (see *Crop Panel*) and resize it, ensuring that the object of interest is contained within the box on every image.
+7) Finalise this process by selecting crop. SPIERSalign will process the images, producing sub-directory with the aligned and cropped images ready for SPIERSedit.

SPIERSalign/docs_build/_sources/index.rst.txt

@@ -0,0 +1,53 @@
+.. SPIERSalign documentation master file, created by
+   sphinx-quickstart on Thu Oct  5 14:07:27 2018.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to SPIERSalign's User Manual
+====================================
+
+[S]erial [P]alaeontological [I]mage [E]diting and [R]endering [S]ystem: Alignment and data-preparation utility
+
+Main Coding: Russell J. Garwood
+Additional Coding: Mark D. Sutton, Alan R.T. Spencer
+Documentation: Russell J. Garwood, Mark Sutton, Alan R.T. Spencer
+
+SPIERSalign is a stand-alone program which enables the user to align (or register) and crop a sequence of images (a tomographic dataset) prior to editing and/or reconstruction with SPIERSedit.
+
+.. figure:: _static/palaeoware_logo_square.png
+    :align: center
+
+t:@palaeoware
+
+w:https://github.com/palaeoware.
+
+Relevant references
+-------------------
+
+Sutton, M.D., Garwood, R.J., Siveter, D.J. & Siveter, D.J. 2012. Spiers and VAXML;
+A software toolkit for tomographic visualisation, and a format for virtual specimen
+interchange. Palaeontologia Electronica 15(2): 15.2.5T
+
+Table of Contents
+=================
+.. toctree::
+   :maxdepth: 3
+   :numbered:
+
+   introduction
+   requirements
+   whatspiersalignproduces
+   interface
+   basicaligningprocedure
+   usingctdata
+   startingspiersalign
+   savingexitingrestarting
+   navigatingdatasets
+   zooming
+   shiftingrotatingscaling
+   panels
+   automatedalignment
+   advancednavigation
+   advancedsettings
+   updatesystem
+   keyboardreference

SPIERSalign/docs_build/_sources/interface.rst.txt

@@ -0,0 +1,14 @@
+.. _interface:
+
+Interface
+=========
+
+.. figure:: _static/figure_2.png
+    :align: center
+
+    Figure 2. Interface in aligning mode
+
+.. figure:: _static/figure_3.png
+    :align: center
+
+    Figure 3. Interface in cropping mode.

SPIERSalign/docs_build/_sources/introduction.rst.txt

@@ -0,0 +1,11 @@
+.. _introduction:
+
+Introduction
+============
+
+SPIERSalign is a stand-alone program which enables the user to align (or register) and crop a sequence of images (a tomographic dataset) prior to editing and/or reconstruction with SPIERSedit. Although correct alignment is always required for reconstruction, some tomographic datasets (e.g. CT scans) come pre-aligned, and hence this step is not always necessary. Nevertheless, SPIERSalign can be useful for cropping and converting the image format of such datasets. SPIERSalign is primarily a manual alignment tool, which allows the user to move (shift), rotate and rescale each image individually. Automatic alignment tools are provided, but will not always successfully register a dataset. SPIERSalign also provides a facility to define a ‘crop box’ (a region of interest), which will produce a set of cropped images for use in SPIERSedit. Note that alignment is considerably easier and more accurate if there are fiduciary marks in the image whose position is invariant between sections. Such marks include edges cut near the specimen or holes drilled through it (Fig. 1).
+
+.. figure:: _static/figure_1.png
+    :align: center
+
+    Figure 1. Fiduciary markings. Top, blocks with edge (left) and holes for as fiduciary markings. Bottom; photos of blocks showing markings in images