Basic Usage

shapeViewer is designed to be ready to use out immediately, with very little knowledge required.

When starting the software, a mission is already preconfigured and you can immediately visualize the field of view of different instruments for any epoch covered by the mission scenario.

The most common functions are accessible directly from the graphical user interface, and via keyboard shortcuts. For instance to simulate observations at a given time: simply click on “View/Set time” or press [T].

Main window

The main window displays a 3D view of the shape(s) currently loaded. Left-click and drag to orient the view, right click to use the current tool. By default, this will give you the coordinates of any point on the surface.

Note

At start, objects are displayed in the following orientation:

  • Z axis (positive, counter-clockwise spin) is pointing up

  • X axis (longest) is pointing right

This view is useful for comparing objects, but does not represent the real relative orientation of each object. Use “View/Set Time” to see the real world orientation.

File menu

_images/scrn01.jpg

The “File” menu lets you load additional data in the software. The default configuration is sufficient for most users, but you will need to use this menu if you want to test your own mission scenarios.

“Load mission package”

A mission package is a bundle of files that contain everything you need for a given mission. This includes shape models, SPICE kernels, and an XML file describing all relevant information. shapeViewer is pre-configured with a mission package which can be found in the “missions” directory. Each subfolder contains one mission; open the associated XML with a text editor to get more information on how to configure your own package.

“Load shape”

shapeViewer was originally designed to display SHAPE files. Although not a common file format in the 3D graphics industry, this has become a standard description for asteroids and comets.

You can find more information on the SHAPE format in the Database of Asteroid Models from Inversion Techniques.

SHAPE format

3D models are represented as polyhedrons with triangular surface facets. The format of shape files (.shp or .shape) is as follows:

  • The first line gives the number of vertices and facets,

  • then follow the vertex x, y, z coordinates,

  • then for each facet the order numbers of facet vertices (anticlockwise seen from outside the body).

In addition, shapeViewer also support OBJ and PLY files, with some restrictions:

  • OBJ files can be of any complexity but only vertices and naked facets are read. Textured facets will not be recognized. Other data is ignored.

  • PLY format is very versatile, shapeViewer 4 supports headers of the two following types:

Header for PLY Type 1 (Geometry only):

ply
format binary_little_endian 1.0
element vertex ***
property float x
property float y
property float z
element face ***
property list uchar int vertex_indices
end_header

Header for PLY Type 2 (Geometry + vertex color):

ply
format binary_little_endian 1.0
element vertex ***
property float x
property float y
property float z
property uchar red
property uchar green
property uchar blue
element face ***
property list uchar int vertex_indices
end_header

“Load SPICE meta kernel”

This function lets you replace the current set of SPICE kernels with a new one. In practice, it is recommended to change the default meta kernel in the mission package XML file.

“Load map overlay”

Load an image (JPG, PNG) that will be interpreted as a 2D equirectangular map of the current shape model. The image data will be used as a texture for the whole shape.

“Load data”

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.

_images/scrn01_load_data.jpg

Example of a data file showing region names and borders on comet 67P.

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 4.0.0 supports 3 basic types: “c” for coordinates, “v” for vectors, and “f” for facet data. A line starting with any other character will be ignored.

Line of “coordinates” data:

c latitude longitude altitude data

| "latitude" and "longitude" in degrees, altitude in km
| "data" is a string

Line of “vector” data:

v x y z data

| x y z are 3D cartesian coordinates, in km
| "data" is a string

Line of “facet” data:

f facet_id R G B data

| "facet_id" is the facet index in the shape model, starting at zero
| "RGB" are red-green-blue 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. One could for instance load the thermal map of a given regions, and add coordinate markers to point at areas of interest.

“Load XML 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.

Each observation in the sequence must define a camera and a time of obseravtion. An optional texture can be specified and will be projected on the shape.

Example of a sequence.xml file:

<?xml version="1.0"?>
<sequence>
    <img>
        <camera>WAC</camera>
        <time>2015-01-03T05:35:00</time>
        <texture>WAC_image.jpg</texture>
    </img>
    <img>
        <camera>NAC</camera>
        <time>2015-01-03T05:35:00</time>
    </img>
    ...
</sequence>

“Project Image”

Load an image corresponding to the current field of view, and project it on the shape. This requires that you have set a time and a camera, the program will remind you to do so if you didn’t.

One projected, the image can be visualized in all views provided by shapeViewer. This means in 3D, but also in the various map projections available in the “View/Projection” menu.

_images/scrn01_im01.jpg

Note: this shape model is shaded with a darker photometric model, to illustrate where the image has been projected. In general, you should use a photmoetric model that matches the data.

“Export View”

Export the current view to a PNG file in the folder where you extracted shapeViewer.

Note

This exported view is a PNG using the RGBA color encoding, i.e. the data resolution is limited to 32 bit colors (65536 values) or 8-bit (256) shades of gray. High depth photometric rendering is planned in the near future.

“Exit”

This one should be obvious ;)

View menu

_images/scrn02.jpg

Most entries in this menu are self-explanatory and should be easy to understand.

“Set time” and “Movie mode”

Probably the most used features. “Set time” let you define an epoch for which you want to simulate what instruments are going to observe. The “movie mode” does the same for the whole mission, and let you select the time displayed simply by clicking on a progress bat at the bottom of the screen (see figure below).

Note that all views are interactive. You can always pause the movie to visualize the shape from another angle than the one displayed, or activate different viewing options interactively.

_images/scrn02_movie.jpg

By default the movie mode is configured to display the full mission. You can update the boundaries of the movie in the option windows that appears automatically. Selecting the option “save frames” will export each frame as a PNG file in the “screenshots” folder.

“Active Object”

The 3D mode displays all objects at once but that is not always possible in other view modes, e.g. map views. In that case, this menu option let you select the object that should be displayed in priority.

Right-clicking an object in 3D view will automatically set that object as active.

“Toggle display”

shapeViewer can display a lot more information than just a shape model:

  • shape axes

  • elevation

  • gravity

  • slopes

  • direction of the Sun, Observer

  • …

All these options are activated via the “Toggle” menu.

Note

Some information, e.g elevation, is displayed using a color scale. For multiple bodies with very different dimensions (e.g. Didymos and Dimorphos), it is difficult to find a color scale that would fit both objects so shapeViewer will adapt the scale to the current active object. Simply right-click on any object to st it to active

Color scale and limits can be changed using the command line interface.

_images/scrn02_elev.jpg

Distance from center of shape in a binary asteroid system. Left: color scale adapted to dimensions of the main object. Right: color scale adapted to dimensions of the secondary.

A note on gravity

shapeViewer provides a model of effective gravitational acceleration (gravity corrected with centrifugal force) and gravitational force. The acceleration is calculated for each facet using the model by Cheng+2012, equivalent to the Werner&Scheeres+1997 but faster to calculate. shapeViewer assumes a constant density throughout the object.

Results are stored in the “gravity” subfolder. Deleting files in that folder will trigger a prompt for input parameters when trying to display gravity again. Effectively, this allows you to recalculate the accelration. Note that this is a slow process !

“Center view”

The items under this submenu will reset the view to some standard configuration, by forcing the Sun and Observer position along one of the shape axes (X,Y,Z, -X,-Y,-Z).

“Projection”

This menu gives you access to several map projections of the active shape.

_images/sv_maps.jpg

Examples of map projections rendered with shapeViewer

“Photometric model”

This menu gives you some control on how the shape is being renderd. Several photometric models are available to calculate the reflectance F 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).

We plan to include more photometric model when rewriting the export function,

“i, e, phase”

Display a representation of the incidence, emission, and phase angle at the time of observation. Each angle can be shown individually, or together. In the latter case, incidence is encoded in the RGB values of the image (incidence => Red, emission => Green, phase => Blue) with a resolution of 256 values per color.

“Field of View”

Select the field of view (instrument) to be displayed. The current view will be adjusted to fit this FoV in the frame. This menu is automatically populated from data defined in the mission package.

“Footprint”

This setting will overlay a box representing an instrument field of view on top of the current scene. It is possible to project the field of view boundaries onto the 3D shape using the command line interface..

_images/scrn02_fov.jpg

Example of display showing the field of view of Hera’s TIRI instrument as full frame, with the additional footprint of Hera’s AFC instrument.

Tools menu

_images/scrn03.jpg

This menu controls what happens when you right-click an object.

“Time, Distance”

This is the default option when you set a time or are in movie mode. Right-click a shape to get the distance to the spacecraft at thi sspecific time.

“Coordinates, Angles”

This is the default mode when starting the program, and can also be used after setting a time of observation. Right-click on a shape will give you the coordinates of that location in the local reference frame, as well as any other available information (angles, gravity, slope, …).

“Paint area”

Disabled in version 4.0.0. Will come back with detailed GIS capabilities in the near future.

“Topographic profile”

Disabled in version 4.0.0. Will come back with detailed GIS capabilities in the near future.

“Command line tools”

Open a command line interface for advanced options.

Help menu

_images/scrn04.jpg

“About shapeViewer”

Some information about the current version.

“User Manual”

Open a PDF version of this user manual.

“Updates”

Selecting this entry will compare your current version of shapeViewer against the latest version available on the server. You can check for yourself at https://comet-toolbox.com/download/shapeViewer_latest

Note

shapeViewer only reads data from the server, no information from your system is ever transmitted.