Updated documentation

Update includes new section on touch screens and full screen mode, update of shortcuts used in program, and new images with the latest theme styling.
palaeoware · Oct 24, 2018 · b410841 · b410841
1 parent 912200c
commit b410841
Show file tree

Hide file tree

Showing 15 changed files with 65 additions and 27 deletions.
diff --git a/docs/_static/figure_1.png b/docs/_static/figure_1.png
diff --git a/docs/_static/figure_2.png b/docs/_static/figure_2.png
diff --git a/docs/_static/figure_3.png b/docs/_static/figure_3.png
diff --git a/docs/_static/figure_4.png b/docs/_static/figure_4.png
diff --git a/docs/_static/figure_5.png b/docs/_static/figure_5.png
diff --git a/docs/_static/figure_6.png b/docs/_static/figure_6.png
diff --git a/docs/advobjectproperties.rst b/docs/advobjectproperties.rst
@@ -128,9 +128,4 @@ time; resurfacing can be slow, and typically a user will want to change
 several settings before triggering a resurface. Alternatively, an
 *Auto-Resurface* mode is provided (*Mode* Menu, Shift-F5), turned off by
 default; with this mode enabled resurfacing is triggered after every
-change to smoothing, island removal or fidelity.
-
-.. figure:: _static/figure_2.png
-    :align: center
-
-    Figure 2. Objects and Pieces panels.
+change to smoothing, island removal or fidelity.
diff --git a/docs/animationsystem.rst b/docs/animationsystem.rst
@@ -6,7 +6,12 @@ Animation System
 SPIERSview incorporates a simple system for generating sequences of
 images that can be converted (via third-party software) into video-file
 animations. The commands for this system are found on the *Animation
-menu*, and settings are modified in the Animation Panel.
+menu*, and settings are modified in the Animation Panel (Fig. 5).
+
+.. figure:: _static/figure_5.png
+    :align: center
+
+    Figure 5. Default anatomy of the SPIERSview animation pannel
 
 SPIERS view animations are generated step-by-step by the user – each
 step rotations and/or zooms to the model are performed, and optionally

diff --git a/docs/basicviewing.rst b/docs/basicviewing.rst
@@ -42,16 +42,16 @@ and right arrow keys (hold shift down to make rotate faster), or by
 holding the shift-key down while dragging with the right mouse button.
 It is also possible to ‘lock’ the viewer into rotate mode by ticking the
 *rotate lock* command (Ctrl-R) on the Mode menu (this is primarily
-useful on single-button OSX systems).
+useful on single-button OSX systems). Also see "Touch screens" below.
 
-The *Simple* *Autospin* command (Ctrl-U) on the Animation menu sets the
+The *Simple Autospin* command (Ctrl-U) on the Animation menu sets the
 model spinning around the y-axis (up/down on the screen) until the
 command is selected a second time. More advanced spins and animation
 exports are covered in the Animation System section (below).
 
 The *Zoom slider* (see Fig. 1) is used to zoom the view; the Page Up and
 Page Down keys also perform the same function, as does the mouse-wheel
-(if present).
+(if present). Also see "Touch screens" below.
 
 The *Move closer* and *Move further* commands ([ and ] keys) on the View
 menu are used to move the camera closer to or away from the model; this
@@ -61,6 +61,16 @@ unacceptable. Hold shift down ({ and } keys) for larger moves closer or
 away. Note that in Orthographic mode there will be no visible effect of
 moving the model backwards or forwards in this way.
 
+Touch screen support
+--------------------
+
+Modern computers with touch screens should be compatible with SPIERSview for basic object moving,
+roatating, and zooming. The model can be moved by one finger dragging, and 
+rotated around around the z-axis (the viewing direction) using two finger rotation.
+Rotated in three dimensions can be achieved by toggling the *rotate lock* command (Ctrl-R),
+or by holding down Crlt while one finger dragging. Zooming in/out can be achieved
+by using the two finger pinch-to-zoom gesture.
+
 Object visibility
 -----------------
 
@@ -77,12 +87,12 @@ case they can only have their visibility toggled with the ‘eye’ icon. If
 a group is hidden then all objects or groups within it, irrespective of
 their visibility setting, are not visible.
 
-The objects menu has *Show All* and *Hide All* commands which can be
+The objects menu has *Show All* (Shift+H) and *Hide All* (Ctrl+H) commands which can be
 used to set the visibility of all objects either on or off. An *Invert
-Show* command also exists, which hides all currently shown objects, and
+Show* (Crtl+I) command also exists, which hides all currently shown objects, and
 vice versa.
 
-Note that transparency (see below) can be used as an alternative to
+Note that transparency (see section on transparency later on) can be used as an alternative to
 simply hiding objects in some situations.
 
 Stereoscopic 3D viewing
@@ -91,12 +101,12 @@ Stereoscopic 3D viewing
 SPIERSview can run in several 3D display modes (top five options in the
 Mode menu). These are:
 
-*Orthographic:* Orthographic rendering without perspective effects
+*Orthographic (Ctrl-O)*: Orthographic rendering without perspective effects
 (distant objects will not appear any smaller than close ones). This is
 mode is useful for measuring specimens, in conjunction with the scale
 grid.
 
-*Perspective:* Normal display without any form of stereoscopic 3D, but
+*Perspective (Ctrl-P)*: Normal display without any form of stereoscopic 3D, but
 with perspective rendering (distant objects will appear smaller). This
 is the default.
 
@@ -117,7 +127,7 @@ focus on each image. Screen captures (see below) in this mode can be
 used to generate printed stereo-pairs for viewing with a magnifying
 stereoscope.
 
-*QuadBuffer Stereo*: This mode sends the left and right eye images
+*QuadBuffer Stereo (Ctrl-Q)*: This mode sends the left and right eye images
 separately to the OpenGL rendering system where they can be interpreted
 by dedicated 3D display hardware. Most 3D display systems can handle
 OpenGl QuadBuffer input, and hence SPIERSview should be able to use this
@@ -131,6 +141,17 @@ situations. Stereo-separation can be set to one of five preset
 strengths, accessed through the View menu or using the keyboard
 shortcuts Alt+1 (very low) through Alt+5 (very high).
 
+Full Screen Mode
+----------------
+
+SPIERSview can run in a full screen (Crtl+F) mode where the 3D view is maximised to
+the maxiumum monitor height and width. Under Windows a frameless and undecorated
+window is produced. While under Linux a minimal framed and decorated window is used. 
+When in full screen mode use (Crtl+F) to toggle back to normal mode.
+
+Note that under full screen mode only the 3D view is displayed, all other pannels and menus
+are not shown. However, all shortcut key combinations will still work.
+
 Background Colour
 -----------------
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -28,7 +28,7 @@
 # The short X.Y version
 version = '3.0.0'
 # The full version, including alpha/beta/rc tags
-release = '3.0.0-alpha'
+release = '3.0.0-rc.1'
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/index.rst b/docs/index.rst
@@ -8,11 +8,11 @@ Welcome to SPIERSview's User Manual
 
 [S]erial [P]alaeontological [I]mage [E]diting and [R]endering [S]ystem: Three-dimensional interactive viewer
 
-**Main Coding:** Mark D. Sutton
+**Main Coding:** Mark Sutton
 
-**Additional Coding:** Russell J. Garwood, Alan R.T. Spencer
+**Additional Coding:** Russell Garwood, Alan R.T. Spencer
 
-**Documentation:** Mark D. Sutton, Russell J. Garwood, Alan R.T. Spencer
+**Documentation:** Mark Sutton, Russell Garwood, Alan R.T. Spencer
 
 SPIERSview is a stand-alone program for viewing and manipulating of
 three-dimensional models. It understands five different file formats,
@@ -28,8 +28,8 @@ 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
+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

diff --git a/docs/infopanel.rst b/docs/infopanel.rst
@@ -17,6 +17,11 @@ the exception being Title which can have at most one. Classification
 also differs in that items consist of two parts, a rank (e.g. Genus) and
 a name (e.g. *Homo*), which are input separately.
 
+.. figure:: _static/figure_4.png
+    :align: center
+
+    Figure 4. Default anatomy of the SPIERSview info pannel
+
 The upper window of the the Info panel, is known as the *Info items*
 window. It lists these categories, and if any contain data, these are
 listed subsidiary to the category as items (you will need to expand the

diff --git a/docs/objectpannel.rst b/docs/objectpannel.rst
@@ -31,6 +31,11 @@ the group they are currently in. You can also move an object into an
 existing group with the *Move To Group* command (Ctrl-G) on the
 *Objects* menu.
 
+.. figure:: _static/figure_2.png
+    :align: center
+
+    Figure 2. Default anatomy of a SPIERSview object pannel
+
 Turning visibility off for a group does not alter the individual
 visibiity settings of contained objects (or groups), but overrides them
 so they are all hidden. In Figure 2 for instance, all objects in the
@@ -52,9 +57,9 @@ Object properties
 
 Objects listed in the object panel have seven properties detailed in
 columns to the right of the name (see Fig. 2; not all columns are
-visible at default panel size). The name (1:sup:`st` column), visibility
-(2:sup:`nd` column), shortcut key (3:sup:`rd` column) and display colour
-(4:sup:`th` column) are all modified simply by double-clicking. Note
+visible at default panel size). The name (1st column), visibility
+(2nd column), shortcut key (3rd column) and display colour
+(4th column) are all modified simply by double-clicking. Note
 that display colour has no effect for VAXML/PLY datasets where the
 imported object has surface colour. The properties in the right hand
 five columns (Fidelity, Transparency, Island Reduction, Smoothing and

diff --git a/docs/requirements.rst b/docs/requirements.rst
@@ -14,9 +14,11 @@ large amount of onboard RAM.
 *Linux*: [tba]
 
 *Windows*: Windows 7 or higher is recommended, and **a 64-bit version of
-the operating system is required**.
+the operating system is required**. SPIERSview has been tested on Windows 10.
 
-*Mac* *OSX:* OSX 10.5 or higher is required. SPIERSview makes use of the
+*Mac OSX:* This version of SPIERSview does not yet support Mac OS. Please see 
+www.spiers-software.org to download v2.14 which is supported. SPIERS v2.14 requires: 
+OSX 10.5 or higher is required. SPIERSview makes use of the
 right mouse-button; on single-button Mac OSX systems use the
 control-click combination to simulate right-clicking.
 

diff --git a/docs/scale.rst b/docs/scale.rst
@@ -16,6 +16,11 @@ judgements all portion of the model beyond the plane of the grid are
 partially greyed-out. Two menu commands are provided on the *Scale* menu
 to change grid colours.
 
+.. figure:: _static/figure_6.png
+    :align: center
+
+    Figure 6. The scale grid
+
 Note that as of version 2.20 the older ‘Scale Ball’ system has been
 removed.