shapeViewer 3.0.4 - 22/02/2021
Jean-Baptiste Vincent


shapeViewer is built upon several Free libraries: shapeViewer is distributed under a BSD license:
    Copyright (c) 2010-2019, Jean-Baptiste Vincent
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of [shapeViewer] nor the names of its contributors
      may be used to endorse or promote products derived from this software
      without specific prior written permission.



shapeViewer is a publicly available scientific software designed to display a 3D model of a comet/asteroid, simulate its observations from a space missions, and project data on the shape. It provides a series of tools specifically developed for mapping and geomorphological investigation.

shapeViewer has been extensively used for planning and scientific analysis in the Rosetta and Dawn missions since 2010.

As of 2018, shapeViewer officially supports the missions CAESAR, Lucy, Hayabusa 1 and 2.

In addition to basic shape visualization, the software has been extended to provide many tools supporting geomorphological investigation: Most options are self explanatory (i.e. "load shape model" or "show axis") and are available from the menu bar of the graphical interface.
Keyboard shortcuts are also indicated in the menu when available.  
Several photometric models are available to calculate the shading of the surface.
LAMBERT:         f = u0
LOMMEL_SEELIGER: f = u0/(u0+u)
LUNAR-LAMBERT:   f = u0(1 - L) + 2L * u0/(u0 + u), L in [0,1]
MINNAERT:        f = u0^k * u^(k - 1), k in [0,1]

with u0 = cos(incident angle) and u = cos(emergent angle).


The software provide three major modes: SHAPE, MOVIE, MAPS.
  1. SHAPE (default mode):
  2. MOVIE:
  3. MAPS:
The software is provided with several "mission packages": folders containing all information needed to simulate data from a given mission, and an XML file which describes the data. shapeViewer is distributed with a few mission packages by default: More packages can be downloaded from the official website.

3D file format

For historical reasons, shapeViewer uses the 3D format defined in DAMIT (Database of Asteroid Models from Inversion Techniques) and routinely used by astronomers and space scientists. More exactly, we support mainly the SHAPE and VER implementations of the shape models. These format are relatively similar to the more commonly used OBJ or STL, and it is very easy to convert an existing shape model to SHAPE or VER.

The shape models are represented as polyhedrons with triangular surface facets. The format of shape files (.shp or .shape) is as follows:
The .ver files are exactly the same, with an additional "3" prefixing the facet lines to indicate that each facet is made of 3 vertices. shapeViewer does not supports models with non-triangular facets.
For convenience, shapeViewer 3.0.0 and future versions also supports basic implementations of the industry standards OBJ and PLY with the following caveats:

   | PLY TYPE 1 HEADER (Geometry only)                      | PLY TYPE 2 HEADER (Geometry + Vertex color)
   |     ply                                                |     ply
   |     format binary_little_endian 1.0                    |     format binary_little_endian 1.0
   |     element vertex ***                                 |     element vertex ***
   |     property float x                                   |     property float x
   |     property float y                                   |     property float y
   |     property float z                                   |     property float z
   |     element face ***                                   |     property uchar red
   |     property list uchar int vertex_indices             |     property uchar green
   |     end_header                                         |     property uchar blue
   |                                                        |     element face ***
                                                            |     property list uchar int vertex_indices
                                                            |     end_header

Image projection

shapeViewer can be used to project images on the 3D shape model.
However, it will not attempt to understand your data, and you are responsible for setting up the right parameters.
shapeViewer expects images in standard exchange format (jpg, png, bmp, ...). The current version does not support more advanced files like FITS or PDS, we plan to add this functionality in the near future.
Workflow: Once the image has been projected, you can interact freely with the shape, zoom, rotate, or switch to map mode. The image texture will remain.
You can toggle the texture display with "View/Overlay image" or [I].
An example image is provided for Rosetta in the folder "image". To try it, set first the time to the default value with [T] followed by [Enter]; then switch to the NAC view [Ctrl+2]; and finally load the image with [Ctrl+I]. Alternatively, you can use the menu bar and click on the same options.
Textured shapes can be exported to an OBJ file for further processing with other software. Use the console command "export" for that (see inline help).

Images sequence:

Sequences of images can be defined in an XML file. Once loaded, it will be used to automatically generate simulated images for the given sequence.
You must set up what to display (labels, gravity, axes, camera footprints, ...) before loading the sequence file.
Example of a sequence.xml file
<?xml version="1.0"?>

User defined data files:

Data files can be loaded and displayed. So far, shapeViewer only supports a simple ASCII format to describe the data, similar to the OBJ format for 3D files.
Data is provided as a text file, with one entry per line. Each line starts with the type of data, following by the relevant information.
Version 3.0.0 supports p basic types: "c" for coordinates, "v" for vectors, and "f" for facet data. A line starting with any other character will be ignored.

Syntax "coordinates" data:
    c latitude longitude altitude data
    Spherical coordinates of the vector to be displayed
    "latitude" and "longitude" in degrees
    "data" is a string

Syntax "vector" data:
    v x y z data
    3D cartesian coordinates of the vector to be displayed
    "data" is a string

Syntax "facet" data:
    f facet_id R G B data
    "f" begins the line
    "facet_id" is the facet index in the shape model, starting at zero
    "RGB" are floats, between 0.0 and 1.0
    "data" is a string
It is possible to mix several types of data in the same file, and/or load multiple files. A data file showing the landing sites of Philae and Rosetta on comet 67P is provided as an example.

Internal CLI

shapeViewer has its own command line interface embedded in the software,
which can be toggled on/off with the keys [=] or [F12].
It provides many customization options in addition to those available in the default graphical interface.
A specific user manual with the list of functions and inline help is available by typing "help" in this console interface.

Change log

|          BRANCH 3.0 "Multiple missions support"                           |

shapeViewer 3.0.4 - 22/02/2021
        - "exportgrat" command to write a grid of the current graticule to a file
        - "exportgrav" command to export the surface gravity in spherical coordinates
        - a progress bar is now displayed for the more expensive calculations (shadows, image projection, gravity)
        - if gravity/slopes data exists, selecting a point with right-click in "Coordinates" mode will display the local gravity/slopes value
        - upgraded FLTK to version 1.4, no change for the user
        - no more loss of precision when loading gravity data from a file

shapeViewer 3.0.3 - 01/09/2019
        - "turbo" colormap is the new default (see Google AI Blog)
        - wireframe set to black when background color is white
        - UP and DOWN keys in console navigate history of commands (instead of both commands+results)
        - incorrect position of a camera footprint in the field of view of another camera.
          Non-aligned boresights are now properly modeled.

shapeViewer 3.0.2 - 27/07/2018
        - support for Hayabusa 2 mission (config files not publicly available for now)
        - "activecolor" command to define the color of selected lines/facets
        - "paintfov"    command to paint the facets currently in the FOV with the active color
        - "outlinefov"  command to mark the projected contour of the current FOV (EXPERIMENTAL)
        - "exportfov"   command to write facets currently in FOV to a data file
        - "clean"       command to reset the colors
        - "export" command renamed to "export3d"
        - "clim" command now works also when displaying angles (i, e, phase)
        - corrected syntax for loading "facet" data in this help file
        - wrong FOV definition in Lutetia package
        - typos in user manual

shapeViewer 3.0.1 - 26/06/2018
        - "sun" command to define the subsolar point
        - "clim" command to define the boundaries of the current color map
        - simplified output format of topographic profiles
        - improved loading of large files, and startup time
        - sequence files with no textures are now rendered properly once again

shapeViewer 3.0.0 - 16/03/2018
        - new concept of "mission packages", which let the user define and load various mission scenarios
        - info command displays more information about the shape
        - loading of multiple data types, to easily mark regions or landmarks
        - "Help" menu now offers an option to check for shapeViewer updates on the server
        - support of OBJ files
        - Removed external CLI interface as it was quite broken and very rarely used.
        - reorganized menu bar, moved "Set time" action to "View" menu
        - console now accepts all characters you can type, upper and lower case
        - [Esc] key disabled in console, so that you do not close shapeViewer when attempting to leave the console
        - no more out of memory when loading large models (up to ~1 million facets).
        - proper freeing of memory upon exiting the software

|          BRANCH 2.9 "Embedded console and usability improvements"         |

shapeViewer 2.9.6 - 30/11/2017
    fixed: corrected the wrong projection of some WAC images
    fixed: "real colors" options appeared toggled off in GUI

shapeViewer 2.9.5 - 15/11/2017
    modified: updated SPICE kernels to the official ESA 1.1.0 release
    modified: default 3d shape is now the DLR SHAP7 model (Preusker et al, A&A, 2017)
    modified: time/distance view now displays distances spacecraft-target center and spacecraft-surface
    modified: the coordinates tool now displays the altitude of the selected point

shapeViewer 2.9.4 - 04/10/2017
    fixed: some textured facets not showing in map mode
    modified: updated SPICE kernels to the official ESA 1.0.0 release
    added: graticule resolution can now be modified in map view as well as in 3D view
    added: "info" command to get some information from the shape file
    added: "export" command to export textured shape as an OBJ file

shapeViewer 2.9.3 - 10/07/2017
    fixed: "set time" dialog now disabled in movie mode
    fixed: "set time" dialog will remember time of last frame after exiting movie mode
    fixed: scalebar length is correct even if target not intersecting boresight
    modified: complete rewrite of the graticule function. It is now faster, and customizable
    modified: similar rewrite of the topographic profile tool, now guaranteed to catch all facets between two points
    modified: 'View Axes' now shows both positive (solid line) and negative (dashed line) axes
    modified: replaced gravity model with Cheng 2012. Slower but more accurate
    modified: some operations parallelized with openmp, slight gain of performance
    modified: slopes displayed in colors by default, use CLI to change colormap
    added: inline help in command line interface
    added: various colormaps accessible from the console

shapeViewer 2.9.2 - 11/05/2017
    Release 42 ! 2500 days since version 1.0 :)
    fixed: improved and sped-up raytracing. Shadows are now very accurate
    fixed: shift camera with arrow keys when time is set
    fixed: improved panning and zooming in all map modes
    modified: shapeViewer remembers the last valid time set
    modified: improved display of graticule, some issues with concavity remain to be fixed
    added: implemented Kavrayskiy VII conformal map projection
    added: on screen display of sub-Sun and sub-S/C coordinates when Sun or S/C display is activated
    added: many new commands in console

shapeViewer 2.9.1 - 31/03/2017
    fixed: image projection sometimes repeating the texture
    fixed: error message appearing when displaying camera footprint in movie mode
    modified: map view can be zoomed in/out and panned with the mouse

shapeViewer 2.9.0 - 26/03/2017
    fixed: application closing when exiting movie mode
    fixed: improved rendering
    added: generic colorbar for all modes (including (3d view)
    added: read basic PLY files (binary, little endian, with or without vertex color information)
    added: console interface embedded in shapeViewer (toggled with [F12])
           console implements new displays and options (fps, scalebar, vertex color, edges, ...)
           console is undocumented in this version and highly experimental

|          BRANCH 2.8 "Image projection/texturing"                          |

shapeViewer 2.8.0 - 25/01/2017
    added: Rosetta images can now be overlaid on the shape model, after time and camera have been set
           This release supports only .JPG, .PNG, and .BMP images.
    added: "Facet" files can now contain data which can be displayed in 3D
    modified: Rewrote part of the camera code to have more intuitive interaction in all views
    modified: If selected, camera footprint now showing at all levels of zoom
    modified: shapeViewer application is now resizable
    modified: Time can be input with hours/min/sec separated by ':' or '.'
    modified: updated compiler to gcc 5.3
    modified: updated SPICE library to allow processing of fast kernels (NAIF Types 6 and 19)

|          BRANCH 2.7 "Public release"                                      |

shapeViewer 2.7.1 - 12/10/2016
    modified: Harmonized console output
    modified: "Surface Area" tool now exports also facet normal vectors.

shapeViewer 2.7.0 - 04/10/2016
    First public release
    Restricted time set to 2014-07-01T12:00 to 2016-09-30T12:00
    Shape provided by default is latest NavCam model
    modified: CLI now uses the right FOV

|          BRANCH 2.6 "CLI interface"                                       |

shapeViewer 2.6.5 - 20/09/2016
    added: Rosetta NavCam FOV [Ctrl+r], and footprint [Alt+r]
    added: label to footprint drawing
    modified: frustum culling between distance/100 and distance*10 instead of [1km, 1000km].

shapeViewer 2.6.4 - 11/09/2016
    modified: Viewing geometry/time preserved when loading new shape.

shapeViewer 2.6.3 - 02/09/2016
    added: FAC "Far away camera": 90deg FOV camera for full scene view. Activate with [Ctrl+f]
    modified: CLI interface now always render in FAC mode.

shapeViewer 2.6.2 - 15/06/2016
    added: NAC and WAC footprints can be toggled with shortcuts [Alt+n], [Alt+w].
    fixed: Rendering used ortho projection instead of perspective, which created a lens distortion artifact.
    modified: The perspective view may distort the rendering when resizing the window. As resizing was rarely used, it is now disabled.

shapeViewer 2.6.1 - 07/06/2016
    added: use keys {shift+ X,Y,Z] to view and illuminate shape from axes -X, -Y, -Z.
    modified: updated SPICE library to use Type 19 kernels (much faster)
    modified: drawing pipeline. Colors/shading calculated only when needed, and not each frame.
    modified: better raytracing, not 100% accurate yet, but good and fast enough to be used.

shapeViewer 2.6.0 - 23/03/2016 - "CLI"
    added: first implementation of a command line interface
    added: option to hide labels when exporting view
    fixed: camera footprints not correct when zooming
    modified: increased line thickness for camera footprints

|          BRANCH 2.5 "Sequence mode, and usability improvements"           |

shapeViewer 2.5.10 - 17/08/2015 - "Perihelion 2"
    fixed: map overlay not aligned with shape when setting time
    fixed: movie not looping back to beginning
    fixed: shape reseting orientation when exiting movie

shapeViewer 2.5.9 - 13/08/2015 - "Perihelion"
    fixed: distance not correct in camera class

shapeViewer 2.5.8 - 17/06/2015 - "Better slopes"
    improved: slope calculations
    added: display of slopes values in black and white
    fixed: display of slopes values in legend

shapeViewer 2.5.7 - 08/05/2015 - "Improved Pointing"
    fixed: rendering implementation introduced an offset in apparent pointing
    added: simplified gravity model (2 central masses) to speed up calculation,
           future versions will let you chose between different models

shapeViewer 2.5.6 - 04/03/2015 - "Angles and facets"
    added: display of incident/emergent/phase angles with [F2, F3, F4]
    added: export of angles as one RGB image (R=i, G=e, B=phase)
    added: export area now saves all selected facets in a file
    added: such list of facets can be reloaded
    improved: facet selection

shapeViewer 2.5.5 - 14/11/2014 - "We have landed !"
    fixed: kernel keyword being ignored in config file
    fixed: when exporting view, filename gets writen on the image
    added: display of incident, emergent, phase angles

shapeViewer 2.5.4 - 31/10/2014 - "Halloween public release"
    Unified interactive display and movie mode
    Both modes will now show the correct pointing and illumination
    Unified rendering loop, merged all SPICE calls in one function
    Interactive mode displays distance and camera Id when time is set
    Added configuration file to change startup options
    Debug console can now be activated from this config file
    Added display of incident, emergent, and phase angles
    Harmonized keyboard shortcuts

shapeViewer 2.5.3 - 28/07/2014 - "SHAP1"
    Added graticule

shapeViewer 2.5.2 - 15/07/2014 - "RPMOD7"
    Added new shape model
    Change rotation rate with [ and ]
    Fixed bug in rotation

shapeViewer 2.5.1 - 26/02/2014 - "MPS release"
    Added graticules to maps
    Harmonized keyboard shortcuts
    3D view can now be shifted with the arrow keys

shapeViewer 2.5.0 - 23/09/2013 - "Sequences"
    Modified movie mode. Possibility to save frames, by default in a directory called "screenshots", automatically created.
    Generates screenshots from a given sequence, provided as an external xml file.
    Reference frames are now defined in SPICE meta-kernel.
    Possibility to load a predefined sequence from an XML file. In that case screenshots are automatically saved.

|          BRANCH 2.4 "COSSIM"                                              |

shapeViewer 2.4.1 - 20/12/2012
    Added raytracing rendering to the photometric model selection menu.
    This feature is very demanding for the CPU and can take a long time for a model with more than a few thousand facets.
    The rendering uses only the LAMBERT photometric model for the raytracing, and does not calculate reflections.
    It does, however, provide the right feel for illumination conditions.

shapeViewer 2.4.0 - 02/11/2012 - "COSSIM"
    Added COSSIM (COma Structures SIMulator) to shapeViewer.
    The user can now define active regions in an external XML file,
    and visualize the structures created by the activity in real time (movie mode).
    The example XML file (COSSIM.xml) contains a description of the format.

|          BRANCH 2.3 "Movie Mode"                                          |

shapeViewer 2.3.0 - 09/07/2012 - "Movie"
    Added a "Movie mode" which animates a trajectory based on SPICE kernels.

|          BRANCH 2.2 "Photometric models"                                  |

shapeViewer 2.2.4 - 26/06/2012
    Projection bug corrected in version 2.2.1 had not been propagated in subsequent versions...
    Added application icon.

shapeViewer 2.2.3 - 25/06/2012 - "Sliders"
    Rewrote definition of photometric models,
    parameters for Lunar-Lambert and Minnaert functions can be set interactively.

shapeViewer 2.2.2 - 22/06/2012 - "NAC & WAC"
    Added more photometric functions
    Added display of NAC and WAC FoV.

shapeViewer 2.2.1 - 23/04/2012
    Corrected bug in equatorial projection

shapeViewer 2.2.0 - 12/04/2012 - "Photometry"
    Added Lommel-Seeliger photometric model, and options to select different models

|          BRANCH 2.1 "SPICE"                                               |

shapeViewer 2.1.0 - 05/04/2012
    SPICE library is now integrated in shapeViewer, no need for spiceData.exe anymore.
    Code migrated to the CVS server.

|          BRANCH 2.0 "GUI"                                                 |

shapeViewer 2.0.2 - 22/02/2012
    Added distances and areas measurements.

shapeViewer 2.0.1 - 23/01/2012
    Finished to implement extraction of topographic profile.

shapeViewer 2.0.0 - 29/09/2011
    Rewriting of the interface. shapeViewer has now a GUI written with FLTK.

|          BRANCH 1 "Console interface only"                                |

shapeViewer 1.6 - 22/03/2011
    implemented gravity model

shapeViewer 1.5 - 22/02/2011
    performance optimization

shapeViewer 1.4 - 21/11/2010
    added calculation of solar elevation,
    selection of facets, areas measurements

shapeViewer 1.3 - 09/09/2010
    added conversion to cylindrical maps

shapeViewer 1.2 - 20/08/2010
    added SPICE support, and texture mapping

shapeViewer 1.1 - 20/07/2010
    can read both ".shape" and ".ver" file formats

shapeViewer 1.0 - 07/07/2010
    1st version.