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 Sutton

Additional Coding: Russell 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, the first four of which it can also output.

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

Introduction and File Formats

SPIERSview is a stand-alone program for viewing and manipulating of three-dimensional models. It understands five different file formats, the first four of which it can also output:

1. Compact SPIERSview files (.spv file extension). These are very small in size and intended as a practical way of distributing models over the internet; they can however take a long while to load as the software must compute isosurfaces for all objects. SPIERSedit generates files in this format.

2. Presurfaced SPIERSview files (.spv file extension). Presurfaced spv files allow SPIERSview to skip computation isosurfaces on loading; they hence normally load substantially quicker. They are, however, typically around an order of magnitude larger than compact files, and are hence impractical for moving over the internet. Presurfaced files are generated by SPIERSview itself.

3. Finalised SPIERSview files (.spvf file extension). Finalised files load very quickly, but are even larger than presurfaced files. They are ‘locked’; when a user loads a finalised file, SPIERSview enters a stripped-down view-only mode (finalised/VAXML mode), in which the model cannot be altered. Use finalised files to produce ‘finished’ versions of models for viewing by other workers, or as teaching tools.

4. VAXML datasets (.vaxml extension). VAXML (Virtual Anatomy XML) is intended as a simple interchange format for virtual anatomy (palaeontological or biogical) datasets. VAXML datasets use one or more STL or PLY files to define the geometry of objects that comprise the dataset, together with one VAXML file that provides data on the dataset as a whole, and specifies how the STL or PLY files are to be assembled. If PLY files are used, geometries incorporating surface colour information (e.g. from laser scanners) can be imported. SPIERSview can generate VAXML/STL datasets from compact or presurfaced SPIERSview files (.spv extension). SPIERSview loads VAXML datasets in the same stripped-down view-only mode (finalised/VAXML mode) as it uses for finalised files (.spvf); the latter are little more than combined and compressed combinations of a VAXML file and STL object geometries.

5. SPIERSview metafiles (.sp2 extension). These are a legacy mechanism from earlier versions of SPIERSview for combining .spv files together; while SPIERSview can still read them, no currently maintained software generates them.

System Requirements and Triangle Count

System Requirments

SPIERSview has no minimum requirements as such, and will run simple models on most systems. Performance will benefit from high processor speed, a large amount of system RAM, and a fast graphics card with a 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. SPIERSview has been tested on Windows 10.

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.

Triangle Count

SPIERSview measures the complexity of models in thousands of triangles (KTr). At the time of writing, typical workstation systems with 4Gb of RAM can comfortably cope with models of up to 25-30,000 KTr, while basic laptop systems may struggle with models of over 3,000 KTr. Difficulty with a model can manifest itself as either slow responses (a slow frame rate, see bottom left of status bar – anything less than 5 frames per second is slow), or crashing. Approaches to the reduction of triangle count in SPIERSedit exports include avoiding ‘speckly’ data (see SPIERSedit manual), the use of restricted numbers of slices, and the use of downsampling or ‘binning’. SPIERSview itself can simplify models using one of two ‘fidelity reduction’ algorithms (see below); using these it may be possible to use a powerful system to convert a difficult model to a lower triangle count model that can be handled by lower-powered systems.

Starting SPIERSview

Opening a file

SPIERSview uses a single-document model – it only views one file at once. To view another files you simply open multiple copies of the program, and to close a file you close the program.

SPIERSview can be launched in one of two ways

1) Launching the SPIERSview program directly: this will bring up a dialog allowing you to select the file you want to load. If you cancel the load dialog, the program will close.

2) (Recommended) Double-clicking a ‘.spv’, ‘.spvf’, ‘.vaxml’ or ‘.sp2’ file will launch SPIERSview on this data.

Initial processing

When launched, SPIERSview first processes the data to generate viewable objects, first calculating ‘isosurfaces’ (3D triangle-meshes) from slice-based data using the Marching Cubes algorithm, and then by the conversion of these into a viewable format; this entire process may take anything from a second or two to several minutes, and depends on the type of file opened (see above) and the complexity of the objects. Note that for VAXML files, these tasks may include the downloading of STL or PLY data from a remote server, which may be slow. Progress bars show the progress of this work; the top bar represents overall progress, and the lower bar the progress of each subtask. Note that the user can begin interacting with the model before once the first object has been loading; subsequent objects will appear as they become available.

Basic viewing and manipulation

The default SPIERSview screen setup has the main view window (black) on the right, the ‘objects panel’ on the left, and progress panel at the bottom (see Fig. 1). The Main view window and the Zoom slider (see below) are permanently visible – the panels can be hidden, resized, repositioned or set to ‘float’ as the user desires. In addition to the two initially visible panels there are three more, the Clipping panel, Info panel and Pieces panel (discussed later). Panels are switched on and off using the view menu, or the keyboard shortcuts indicated in their title bars (F1, F2, F3, F4 and F6).

Figure 1. Default anatomy of a SPIERSview window

The status bar at the bottom gives total model size in KTr (1 Ktr = 1000 triangles). If objects are selected in the objects panel, the size given is for the selected objects only. A volume for selected objects is also given in cubic millimetres; this is calculated from raw data exported from SPIERSedit, and does not take into account any reduction from island removal, smoothing, fidelity reduction etc. Note that volume calculations are not currently corrected for any inconsistent slice-spacings specified in SPIERSedit.

When viewing models in SPIERSview finalised format (.spvf) or VAXML format (.vaxml), the interface is simplified; many menu options will not appear, and the pieces panel is not available. Volume measurements (see above) are also not available.

Moving, rotating and zooming

The model can be moved by dragging using the left mouse button, and rotated in three dimensions by dragging with the right mouse button. You can also rotate around the z-axis (the viewing direction) using the left 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). Also see “Touch screens” below.

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). 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 has a similar effect to zooming, but may be preferable if, for instance, the model is so close to the camera that perspective distortions are 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

SPIERSview models consist of a number of objects and groups of objects (see below) which are listed in the Object panel on the left of the screen (Fig. 1). Each object is normally given a different colour, and each object or group can be independently turned on or off (hidden from view), enabling the user to perform ‘virtual dissections’. This can be done by double-clicking the ‘eye’ icon for each object in the object panel (see Figure 1), or by using the keyboard key assigned to the object (the single character A-Z or 0-9 visible to the right of the eye icon). Objects are not required to have a key assigned, in which 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 (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 (Crtl+I) command also exists, which hides all currently shown objects, and vice versa.

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

SPIERSview can run in several 3D display modes (top five options in the Mode menu). These are:

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 (Ctrl-P): Normal display without any form of stereoscopic 3D, but with perspective rendering (distant objects will appear smaller). This is the default.

Anaglyph Stereo (Ctrl-A): Anaglyph stereo mode splits the left and right eye images using red (left) and cyan (right) filters, and allows 3D viewing using red/cyan or red/green glasses; the former will work better, but the latter are normally adequate. This is intended as a cheap and effective means of viewing 3D images, but (unlike Split Stereo or QuadBuffer Stereo modes) does not fully preserve colour information. Anaglyph stereo viewing may also be hampered if the model contains strong colours; the Mute Colours command (Ctrl-M) on the Mode menu can help in these cases, as it reduces colour saturation.

Split Stereo (Ctrl-S): This mode splits the Main view window in two, displaying the left and right eye images in the left and right halves. Direct viewing in this mode requires viewer to be able to separately 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 (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 mode to produce stereoscopic 3D output using most 3D screens and projectors. Please note that no guarantee of success for any particular hardware can be provided.

The user may find that the default ‘medium’ stereo-separation (the strength of the stereoscopic effect) is too high or too low in some 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

By default SPIERSview uses a black background for specimens, but this can be changed at will using the Background Colour… command on the View menu. Changes to the background colour are saved in SPV files, but not in VAXML or SPVF files.

Bounding Box Mode

Selecting the Bounding Box Mode command on the Mode menu causes all items to render as wireframe boxes. Bounding box rendering is far faster than normal rendering, and may, for instance, assist with the initial placement of objects when assembling multi-piece models.

Anti-aliasing

SPIERSview supports hardware anti-aliasing (jagged edge reduction) through OpenGL; not all hardware will support this facility, and on some systems antialiasing will not work in QuadBuffer Stereo mode. Anti-aliasing is off by default, but can be set to x2, x4, x8 or x16 using the view menu. Higher anti-aliasing settings improve image quality by smoothing jagged edges, but reduce performance and may use more memory. Consider turning anti-aliasing on before performing screen captures or generating animations. Changing the anti-aliasing mode forces a full resurfacing of all objects; for compact or presurfaced SPIERSview files (.spv format) this may take a considerable amount of time.

Object Panel

Groups

Objects can be combined into groups; groups can also exist as subgroups within other groups (see Fig. 2), enabling the user to build up a hierarchy of objects to describe an anatomy. For instance, an arthropod model might include a group called ‘appendages’ – this in turn might include a subgroup called ‘cephalic’ appendages, which might in turn include a ‘mandibles’ group, consisting of a left and right mandible. Object grouping not only provides a convenient way to explain relationships, but also allows visiblity to be controlled for sets of objects – in the above example for instance a key could be assigned to the appendages group, allowing the entire appendage set to be quickly hidden or shown.

Groups are indicated in the panel in a standard way (Fig. 2); they can be expanded or collapsed to show their contents. Groups only have two properties; their shortcut key, and their visibility.

Groups are created by selecting a number of objects and using the Group command (Ctrl-G) on the Objects menu. You should normally rename groups after creating them. Groups are removed by selecting the group and using the Ungroup command (Ctrl-G) on the Objects menu. Selecting objects and using the Ungroup command will remove them from 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 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 ‘Trunk Apps’ group are currently invisible (whatever their individual visibility setting), as this group is set to invisible. Once visibililty is turned on again for the parent group, the individual visibility settings of its contained objects (or groups) are used again.

Position in object panel

Objects (and groups) can be moved up and down the list in the objects panel using the Move Up and Move Down commands (F12 and F11 respectively) on the Objects menu. These changes affect only the panel, and have no effect on the way the model is displayed.

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 (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 Shininess) are set using commands on the object menu. Of these, only transparency and shininess are available in Finalised/VAXML mode.

Advanced Object properties

Fidelity

SPIERSview can reduce the number of triangles in an object (referred to as its fidelity) using one of two algorithms (see below). Reducing triangle-count enables objects to display effectively on lower powered systems, and may also help when exporting geometries to other software. Fidelity reduction is however computationally expensive, ‘lossy’ (resultant geometries will not be exactly the same as the original), and may require a large amount of system memory to perform successfully. To change fidelity select the objects to be affected, and use the ‘Set Fidelity’ command in the Objects menu to enter a new value – a fidelity of 100% represents the original triangle count (no fidelity reduction). Objects will then need to be resurfaced (see below).

By default fidelity-reduction uses a relatively fast and ‘safe’ algorithm that is normally only able to reduce fidelity by up to 50% - settings lower than this will not always result in smaller models. Alternatively, a ‘Quadric’ fidelity-reduction algorithm is available, selected by ticking the so-named menu item in the Objects menu. This alternative algorithm is slower and more memory hungry (it may fail and crash for some very complex objects on systems with limited memory), but normally produces better results, especially at low fidelities.

Fidelity reduction is not available in Finalised/VAXML mode.

Fidelity reduction is performed before Island Removal or Smoothing

Transparency

SPIERSview can display objects in a translucent form; transparency is by default off, but can be set to one of four preset levels by selecting object(s) and using the Transparency commands in the Objects menu or their keyboard shortcuts (Ctrl-1 is ‘transparency off’, ctrl-2 through ctrl-5 are increasingly high levels of translucency). A facility is also provided, on the Transparency sub-menu of the Objects menu, to set a custom transparency level (0 is opaque, 99, almost transparent).

Transparency is not easy to implement perfectly, and in all software the method used is a trade-off between speed and ‘correctness’. SPIERSview provides a relatively fast implementation that is normally sufficient, but can in some cases produce unexpected results, especially when viewing translucent objects through other translucent objects. If ‘true’ transparency is required for publication-quality images, export of the model to another rendering package (e.g. a ray-tracer) is recommended.

Changes to transparency do not require objects to be resurfaced (see below).

Shininess

As of version 2.20, SPIERSview renders objects using a ‘phong’ shading model, which approximates highlights and reflections from objects. These are visually appealing, and can assist in visualizing surface morphology. The shininess of objects can be set to one of four preset levels by selecting object(s) and using the Shininess sub-menu in the Objects menu; levels are ‘Off’, ‘Less’, ‘Default’ and ‘Full’. If more precise control is required, a custom shininess level can also be set using the appropriate command in the Shininess sub-menu ; values range from 0 (Matte, Off) to 100 (equivalent to ‘Full’).

Changes to shininess do not require objects to be resurfaced (see below).

Island Removal

SPIERSview provides a filter to remove ‘islands’ from data – islands are groups of triangles not connected with the main object, which often represent noise. Island removal level is set using the commands of the Island removal sub-menu on the Objects menu. It can either be off (the default), ‘all’ (where all islands of triangles not connected to the largest object are removed), or one of four intermediate settings where increasingly large islands are removed. A custom island-removal level can also be specified using the appropriate command on the Island removal sub-menu; here the user specifies a minimum size (in triangles) for islands; all smaller are removed. Note that it is possible to remove all islands, including the largest, by specifying too high a threshold.

Island removal can be slow and memory hungry; it may fail for some very complex objects on systems with limited memory. Note that the remove ‘all’ option is usually faster and less demanding on the system than the intermediate options. Objects will need to be resurfaced (see below) after changes are made to Island Removal settings.

Island removal is not available in Finalised/VAXML mode.

Island removal is performed after fidelity reduction but before smoothing.

Smoothing

Surfaces created by SPIERSview as isosurface from slice-based (tomographic) data may be rather ‘blocky’. A smoothing filter may be applied to smooth out blockiness artefacts and other fine-scale noise, providing what is hopefully a better approximation to an original biological surface; excessive smoothing can however modify the geometry in unhelpful ways, and hence it should always be used with care. Smoothing is by default off for all objects, but the degree applied is set using the commands of the Smoothing sub-menu on the Objects menu. Seven levels, from ‘off’ to ‘strongest’ are available; the stronger the smoothing the slower the process will be. A custom smoothing level can also be specified using the appropriate command on the Smoothing sub-menu; here the user specifies the number of iterations of the smoothing algorithm; the equivalent to ‘strongest’ is 100, but higher values can be specified if desired.

Smoothing is not available in Finalised/VAXML mode.

Smoothing is performed after both fidelity reduction and island removal.

Resurfacing

Changes to smoothing, island removal or fidelity can be time consuming, and are hence not applied immediately. To manually apply changes and force recalculation of objects with new settings, use the Resurface Now command on the View menu (F5). This approach is used to save 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.

Manipulating objects independently

While normal use of SPIERSview is to keep objects in the same position relative to each other, there is sometimes a need to shift, rotate and scale certain objects independently. This facility, turned on or off using the Reposition Selected command under the Mode menu, is especially useful in conjunction with multi-piece datasets (see below).

With this mode selected, all rotates and shifts made using the mouse or menu commands affect only the objects currently selected in the object panel, as do any scale changes (see below).

Reposition Selected mode is not available when SPIERSview is running in Finalised/VAXML mode.

Multi-piece datasets

SPIERSview can combine two or more ‘.spv’ format files (both compact and presurfaces varieties) into a single multi-piece model; this facility is useful for combining parts of an object initilly reconstructed as multiple SPIERSedit datasets (e.g. part and counterpart of a fossil). Each ‘.spv’ file incorporated is known as a piece. The Pieces panel (see Fig. 2) shows all the pieces making up the currently open file – if no extra pieces have been imported, there will be only one such piece.

Items in the pieces panel by default have the filename imported – they can be renamed (by double clicking) to provide a more helpful name.

New pieces can be imported into SPIERSview using the Import piece command on the SPIERSview menu. These must be ‘.spv’ files, and must be files saved by SPIERSview itself – files exported by SPIERSedit cannot be imported directly (to get around this restriction simply load any such file into SPIERSview, then save it again). Pieces can be removed by selecting them in the Pieces panel and using the Remove Piece command on the SPIERSview menu. They can also be replaced with new versions using the Replace Piece command on the SPIERSview menu; this preserves any re-positioning, grouping of objects, etc performed on the piece being replaced, so is useful to re-import updated files from a SPIERSedit dataset.

Objects from all pieces are shown in the objects panel. On import the objects from a new piece will appear at the bottom, but they can be grouped with objects from other pieces, and/or moved up and down the list at will.

When new pieces are imported they will not typically be correctly positioned relative to one-another. To manually reposition, the user should use the Reposition Selected mode described above. To assist with this, selecting a piece in the pieces panel automatically selects all the objects in the piece in the Object panel, ensuring that the correct objects are moved.

Legacy ‘.sp2’ files (see above) are opened by SPIERSview as multi-piece files.

Clipping panel

SPIERSview provides a simple system for performing limited virtual sectioning, using the Clipping panel (see Fig. 3). All models are ‘clipped’ front and back by two notional invisible planes, perpendicular to the viewing direction – objects in front of the front plane or behind the back plane are not shown. The front plane is by default very close to the viewing position, and the futher plane a long way away. The Start slider on the clipping panel controls how far from the viewer the front plane is – moving the slider upwards moves the plane away from the viewer; at some point it will be seen to intersect the model, removing objects from the front. The depth slider controls how far beyond the front plane the back plane is. Moving this slider downwards decreases the depth of the visible region between the planes – bringing it to very near the bottom (as in Fig. 3) produces a thin slice through the specimen.

Figure 3. Info and Clipping panels

Clipping is a view-only feature – it does not affect how models are exported.

Info panel

SPIERSview allows models to be supplemented by textual metadata, viewed and input through the Info panel (see Fig. 3). This data is broken into the following headings: Title (A title for the model – this will appear in the title bar of the SPIERSview window), Classification, Authors (intended as authors of this model), References (either to papers or URLs to web resources), Specimen (Specimen numbers etc), Provenance (where specimen is from, including geological age if applicable) and Comments (for miscellaneous notes not falling into above categories, including copyright messages). Each of these categories can have none, one or more textual notes contained within it, 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 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 category to view them). To view the data in a category simply select it: all items will then be displayed in order in the lower Info detail window of the panel.

Items can be added by double-clicking on the category heading in the Info items window, deleted by selecting the item in Info items then using the delete key, or edited by double-clicking on the item itself. Attempting to delete a category will delete all items within it, but will not remove the category heading.

Saving and exporting

SPIERSview compact and presurfaced files (.spv)

When viewing an ‘spv’ format file, the Save Changes command (Ctrl-V) on the SPIERSview menu will save the file in whatever format (compact or presurfaced) it was opened in. SPIERSview will also ask if you want to save changes before exiting; this also will use the format the file was opened in. The Save Compact As… or Save Presurfaced As… commands on the SPIERSview menu are also provided – these force the file to save in whichever of these two formats you specify, and can hence be used to convert between the two

SPIERSview finalised files (.spvf)

The Export Finalised… command on the SPIERSview menu saves a copy of the current ‘.spv’ file in Finalised format (see above), for rapid view-only loading. As finalised format is internally implemented using VAXML, a few restrictions apply and are checked at save-time. The most significant of these is that all groups must have unique names; if this is not true you will receive a warning, and the file will not be written.

If the Export Hidden Objects item on the SPIERSview menu is ticked, all objects are exported. If it is not ticked, the visibility of each object is used to determine whether or not it is exported. Note that this is simply the presence of absence of the ‘eye’ icon next to the object in the Objects panel; an object might be set to visible (and hence be exported) but not appear onscreen in SPIERSview because the group it belongs to is hidden.

Groups are always exported, whether hidden or not.

VAXML/STL datasets

The Export VAXML/STL… command on the SPIERSview menu exports the current ‘.spv’ file as a VAXML file, plus associated STL files (SPIERSview cannot export PLY files). One STL file is created per object, and these are placed in a subdirectory called <filename>_stl where <filename> is the supplied name for the VAXML file. There is no option to export STL files without also creating a VAXML file (although the latter can of course be manually deleted if it is not required).

The Export Hidden Objects item on the SPIERSview menu works in the same way as for SPIERSview finalised files.

DXF files

The Export DXF… command on the SPIERSview menu exports the current ‘.spv’ file as a DXF triangle mesh. Objects are exported with their correct names, but neither groups nor colours are preserved.

The Export Hidden Objects item on the SPIERSview menu works in the same way as for SPIERSview finalised files.

Screen Capture

The Screen Capture… command on the SPIERSview menu exports the current Main view windows as either a JPEG (.jpg), Windows Bitmap (.bmp), Portable Network Graphic (.png) or Tagged Image File Format (.tiff) file. The exact image visible (at the resolution visible) is used – for best quality remove all panels and maximise the SPIERSview window to obtain a large view window, and use Anti-aliasing (see previous section).

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 (Fig. 5).

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 an image file is saved to disk. The user may choose to modify the view in any other way at any stage (e.g. changing transparency, performing a dissection, etc etc) to produce more complex animations.

Understanding Image Output

Note that until an output folder is specified using the Set Image Output Folder menu command, all commands and settings concerned with creating output images are disabled. Files, when created, are given a filename consisting of stub#####.EEE, where stub is the text entered in the ‘Filename Stub’ box of the Animation Panel, ##### is a five-digit version of the Next File # of the Animation Panel (with leading 0’s), and EEE is the file extension. File type and extension are chosen from the Set Image Output Format submenu of the Animation Menu; note that there are three different compression levels available for JPEG.

Images are created by direct screen capture of the Main View window – they are thus created at whatever resolution this is currently displayed at. It may however be convenient instead to create images at a different resolution. To facilitate this SPIERSview incorporates a rescaling facility. If the Rescale Output menu item is ticked, the output image is rescaled to the width entered in the ‘Rescale to width’ box of the Animation Panel (which defaults to 640 pixels). The height of the output image will depend on the aspect ratio of thw Main View window – the actual height which will be output if Rescale Output is turned on is given next the to width in the Animation Panel. If the user requires both the height and width to be particular values, they should set the width and then resize the window until the height is correct.

Users should consider using Anti-aliasing (see above) when generating animations, to maximise the quality of exported images.

The conversion of a sequence of image files into a video file is beyond the scope of SPIERS; many third party software solutions exist for this task. For users on a Windows platform, the authors recommend the free version of VideoMach (http://gromada.com/videomach/).

Rotation and Zoom Settings

The rotations and zoom to be perfored in each step are specified in the Animation Panel. The rotations are in degrees, and are around the axis specified (the Y axis is vertical onscreen, the X axis horizontal, and the Z axis comes directly out of the screen). The zoom is in arbitrary units – a zoom of 10 is equivalent to zooming in one press of Page-Up, and a zoom of -10 equivalent to zooming out by one press of Page-Down.

Commands Applying Animation Steps

The Apply Single Step command (Ctrl-N) is the simplest animation command – it simply applies the roatations and zoom specified in the Animation panel. It does not generate any output files. Apply Multiple Steps does the same, but asks the user for a number of steps, and applies the animation that number of times.

The Apply Single Step Saving Image command (Ctrl-Shift-N) saves the currently visible image using the rules described above, then applies the rotations and zoom specified in the Animation panel. It also increments the ‘Next File #’ given in the Animation Panel. Multiple animation frames can thus be produced simply by repeated uses of this command, although the Apply Multiple Steps Saving Images provides a more convenient means of achieving the same effect. As an alternative to the use of menus, two buttons are provided in the animation panel to perform either single or multiple steps; a checkbox next to them controls whether images are to be saved or not.

Scale

Scale Grid

Select Show Scale Grid on the Scale menu, or Ctrl+K, to overlay a grid on the specimen; the grid scales in resolution as the user zooms in and out. As perspective effects can complicate measurement it is normal to use this grid in Orthographic mode. Measurement in perspective modes is possible however, although the user will need to bear in mind the relative distances to the grid and to the model. To facilitate these judgements all portion of the model beyond the plane of the grid are partially greyed-out.

The scale grid will change the displayed mesurment unit based on the current field of view and model scale. Units that can be shown are meters (m), centimeters (cm), millimeters (mm), and micrometer/micron (um). Major scale lines and text are displayed in bold. Note: the current field of view (FOV) is shown in the status bar at the bottom left of the SPIERSview program.

Scale grid setings can be found under the Scale > Scale Grid Settings… sub-menu. Options include: Show Minor Scale Lines, Show Minor Scale Values, Major Grid Colour…, Minor Grid Colour…, and Font Size…. Also under this sub-menu is the Reset Scale Grids to Defaults option.

Figure 6. The scale grid

Note that as of version 2.20 the older ‘Scale Ball’ system has been removed.

For files imported from SPIERSedit the internal scale should automatically be correct, assuming the pixels / mm and slices / mm values were set correctly at export time. If however the scale is not correct, the entire model can be rescaled (see below) as necessary.

Rescaling objects

The Scale menu has four commands that can be used to change the scale of either the whole model or, if Reposition Selected is ticked in the Mode menu, individual objects. These commands are Increase Size (+), Decrease Size (-), Rescale By…, and Reset Size. The first two increase or decrease size by a small increment. Rescale By… allows resizes of arbitrary amounts, input as a decimal factor (e.g. 0.5 is half size, 2.5 is 2 and a half times bigger, etc). Reset size undoes any scale changes.

Update system

SPIERSview incorporates an auto-updating system (as do the other two SPIERS applications). If connected to the internet, it will check for updates every time it is run. If it finds an update it will give you the option of downloading and installing it. Agreeing to this will close SPIERSview once the updater has been downloaded.

Note: this part of SPIERS is under review as it does not necessarily work across all operating system. This functionality may change or be removed in the future.

Appendix A – VTK Usage

Introduction

VTK (the Visualisation Toolkit; http://www.vtk.org/) is a an open-source, freely available software system for 3D computer graphics, image processing and visualisation. SPIERSview makes use of VTK version 8.1 for some data-processing purposes (although not for visualisation, which uses custom code to increase speed and memory efficiency). Certain VTK classes used are documented here, where knowing details of algorithms used may help a user understand exactly what SPIERSview is doing with their data. Interested users are referred to the VTK documentation to interpret the notes below.

Fidelity Reduction

SPIERSview default ‘fast and safe’ fidelity reduction uses the vtkDecimatePro filter. AccumulateError is set to ‘off’, PreserveTopology is set to on; no other settings are changed from defaults.

SPIERSview ‘Quadric’ fidelity reduction uses the vtkQuadricDecimation filter. No settings are changed from defaults.

Island Removal

Island removal uses the vtkPolyDataConnectivityFilter class. ColorRegions is set to off; no other settings are changed from defaults. ‘All’ mode uses SetExtractionModeToLargestRegion; otherwise the filter is run in SetExtractionModeToAllRegions mode. Tiny, Small, Medium and Large settings remove regions of up to 20, 100, 600 and 4000 triangles in size respectively.

Smoothing

Smoothing uses multiple passes of the vtkWindowedSincPolyDataFilter filter. FeatureEdgeSmoothing, BoundarySmoothing, GenerateErrorScalars and GenerateErrorVectors are set to off, and PassBand is set to 0.05. Very Weak, Weak, Medium, Strongish, Strong, and Strongest settings use 5, 10, 20, 40, 60, and 100 iterations respectively.

STL reader

SPIERSview uses the vtkSTLreader class to import STL triangle meshes during VAXML import; its restrictions and capabalities are thus those of this VTK class.

PLY reader

SPIERSview uses the vtkPLYreader class to import PLY triangle meshes and surface colour information during VAXML import; it’s restrictions and capabalities are thus those of this VTK class; in particular colour information input is restricted to ‘red’, ‘green’ and ‘blue’ properties of vertex elements.