Graphical Interface ################### *shapeViewer* aims to be intuitive and ready to use out of the box. 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". Most menu items have an associated keyboard shortcut, explicitly indicated in the menu entry. For instance, "View/Set Time" uses the letter [T]. 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. 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: *Main object:* - Z axis (positive, counter-clockwise spin) is pointing UP - X axis (longest, often the prime meridian) is pointing towards the OBSERVER *Secondary objects:* - Z axis (positive, counter-clockwise spin) is pointing UP - X axis (longest, often the prime meridian) is pointing towards the MAIN OBJECT This mimics the most common case of a secondary rotationally locked to its primary (e.g. Earth/Moon), but **does not represent the real relative orientation of each object**. Use "View/Set Time" to see the real world orientation. ________ File menu =========== .. image:: images/scrn_menu_file.jpg :scale: 70% :align: center | The "File" menu lets you load additional data in the software. *Missions* ---------- .. figure:: images/scrn_menu_file_missions.jpg :width: 70% :align: center A mission package is a bundle of files that contains everything needed for visualizing a given scenario. This includes shape models, `SPICE kernels `_, instrument details, and so on. Each package comes with a JSON file which summarizes the relevant information. When starting, *shapeViewer* will scan the "missions" sub-folder and detect available. When closing the software, it will remember the last mission you were working with. The structure of a mission package is self-explanatory. To create your own, simply copy an existing JSON file and update it to describe your project. *Shapes* -------- *shapeViewer* was originally designed to visualize **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 `_. Here is a short description: .. admonition:: SHAPE format 3D models are represented as a collection of triangular surface facets. Shape files are a textual representation of those triangles with the following format: - The first line of the file gives the number of vertices and facets, - then follow the x, y, z coordinates of each vertex, one vertex per line - then for each facet the order numbers of facet vertices (anticlockwise seen from outside the body), one facet per line 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 JSON 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* ------------ User 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. It is foreseen that a new JSON-based data interface will be added in future versions of the software. .. figure:: images/scrn_menu_file_load_data.jpg :width: 70% :align: center 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, followed by the relevant information. Version 4.1.0 supports 4 basic types: * "ms" or "mc" for markers, * "f" for facet data, * "g" for geographic data. A line starting with any other character will be ignored. .. Note:: 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. **"markers" data**: Displays a line marker and a text label at the given coordinates. Vector information can be provided in spherical ("ms") or cartesian ("mc") form. .. code-block:: text ms latitude longitude altitude data | "latitude" and "longitude" in degrees, altitude in km | "data" is a string, the first space-separated token may be a float number .. code-block:: text mc x y z data | x y z are 3D cartesian coordinates, in km | "data" is a string, the first space-separated token may be a float number **"facet" data**: Paint the given facets with the given color. .. code-block:: text f facet_id R G B data | "facet_id" is the facet index in the shape model, starting at zero | "R, G, B" are red-green-blue floats, between 0.0 and 1.0 | "data" is a string, the first space-separated token may be a float number **Line of "geographic" data**: Assign data to the shape model, in areas defined by their central coordinate and angular size. The display will use the current color scheme, which can be changed afterward using the :ref:`console`. .. code-block:: text g latitude longitude angular_area data | "latitude, longitude", in degrees, define a point of interest on the shape model | "angular _area" is the radius of the area that should be considered, in degrees | "data" is a string, the first space-separated token must be a float number .. note:: Loading this type of data can be slow, depending on the number of points and angular size of the regions of interest. Once loaded, it is recommended to export the data to a "facet" file which can be loaded almost instantly in future sessions. See :ref:`console` for further information. *Load sequence* ---------------- Sequences of images can be defined in an JSON 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 an instrument and a time of observation.** An optional texture can be specified and will be projected on the shape. **Example of a sequence.json file:** .. code-block:: json { "sequence": [ { "camera": "WAC", "time": "2015-01-03T05:35:00", "texture":"WAC_image.jpg" }, { "camera": "NAC", "time": "2015-01-03T05:35:00" } ] } *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. .. figure:: images/scrn_menu_proj_im.jpg :width: 70% :align: center 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 *shapeViewer* folder. 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. ________ View menu =========== .. image:: images/scrn_menu_view.jpg :width: 70% :align: center | *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. "Movie mode" does the same for the whole mission, and let you select the time displayed simply by clicking on a progress bar 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. .. image:: images/scrn_menu_view_movie.jpg :width: 100% :align: center 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: - axes, coordinate system - elevation - gravity, slopes - surface roughness - direction of the Sun, Observer - incidence, emission, phase 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 :ref:`command line interface `. .. figure:: images/scrn_elevation.jpg :width: 100% :align: center 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. .. admonition:: A note on gravity *shapeViewer* provides a model of **effective gravitational acceleration** (gravity corrected with centrifugal force). The acceleration is calculated for each facet using the model by Cheng+2012, equivalent to the classical 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 acceleration. Note that this is a slow process ! .. admonition:: A note on roughness **Surface roughness** is defined as the mean angle between a facet nornal vector and its neighbours. It is calculated when the shape is loaded. Details on the algorithm and examples for several small bodies are available in Vincent+2023. *Center view* -------------- The items under this submenu will reset the view to preset configurations, 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. - `Equirectangular projection `_ - `Kavrayskiy VII projection `_ - `Orthographic (North/South) projection `_ .. figure:: images/sv_maps.jpg :width: 100% :align: center Examples of map projections rendered with *shapeViewer* *Photometric model* -------------------- This menu gives you some control on how the shape is being renderd. A few simple photometric models are available in v4 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). Better model will be included in future versions of the software. *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, angles are 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 :ref:`command line interface `. .. figure:: images/scrn_menu_view_footprint.jpg :width: 70% :align: center 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 ============ .. image:: images/scrn_menu_tools.jpg :width: 70% :align: center | This menu controls what happens when you *right-click* an object. Most tools are being rewritten and are currently disabled. *Local information* ------------------- Right-clicking on a shape model gives you access to local information. The amount of information depends on the current selection in the "View menu" and the data available. You can remove this selection by using the menu item "Tools/Clear selection"or the keyboard shortuct [k]. *Command line tools* ---------------------- Open a :ref:`command line interface` for advanced options. The command line can also be opened/closed with either the keys [F12] or [=]. Help menu =========== .. image:: images/scrn_menu_help.jpg :width: 70% :align: center | *About shapeViewer* --------------------- Some information about the current version. *User Manual* --------------- Open a PDF version of this user manual.