VESPA Contribution to NASA-JPL WebGeoCalc tool

EPN2020-RI

EUROPLANET2020 Research Infrastructure 

H2020-INFRAIA-2014-2015 

Grant agreement no: 654208

Document: VESPA-009-TN  v0.4

VESPA Contribution to NASA-JPL WebGeoCalc tool

Date: 2020-03-04

Responsible WP Leader: Stéphane Erard

Table of Contents

Reference Documents

• RD1: IVOA VOTable Specification. http://www.ivoa.net/documents/latest/VOT.html
• RD2: IVOA STC Model. http://www.ivoa.net/documents/latest/STC.html
• RD3: IVOA UCD Recommendation. http://www.ivoa.net/documents/latest/UCDlist.html
• RD4: Proposed Update of UCD for Planetary Sciences. http://wiki.ivoa.net/internal/IVOA/IvoaSemantics/WD-UCDlist-1.3-20150608.pdf 

1. WebGeoCalc Capabilities

WebGeoCalc (WGC) is an online interface to the NAIF/SPICE kernel library developed at NASA-JPL. It proposes various types of calculations, as shown on Figure 1. For each calculation the user can select tabular data output or various plotting options. Tabular data can currently be exported into 3 formats: Excel, CSV (Comme Separated Values), or plain text. In appendix we present all the output parameters for each calculation type. These parameters include the calculation inputs, the computed parameters and the SPICE kernel used for the computation.  

Fig. 1. WebGeoCalc entry page screen shot.

2. VOTable output formatting

VOTable [RD1] is an XML based format dedicated to tabular data. It has been forged by IVOA, and is now used in many science domains linked to astronomy, space sciences and space exploration. VOTable can be used a simple container including minimal metadata allowing table column description (name, unit, data type...). A more complete use is also possible, taking advantage of other IVOA data models, in particular the STC [RD2] data model (Space Time Coordinates) and the Characterization data model (axes descriptions). While the minimal use is fully acceptable for all VOTable compliant tools, the latter allows more flexible automated processing. 

There are two main types of header metadata in a VOTable: the PARAM and FIELD elements. The PARAM elements are used to described generic metadata, whereas FIELD elements are describing each columns of the table.  Each PARAM or FIELD must have a UCD (Unified Content Descriptor) [RD3,RD4] attribute.

PARAM metadata

The input parameters of the calculation should be placed into PARAM elements. It is always proposed to group metadata covering the same area or concept with a  GROUP element. The following example shows a GROUP element containing all the calculation input parameters of a "State Vector" output. 

Another GROUP shall be used to specify the kernels used for the calculation:

NB: It would probably be nicer to have an array of char strings instead of a series of PARAM elements, but such string arrays are not really supported in VOTable (as far as we understood). 

FIELD metadata

The FIELD metadata are the VOTable column descriptors.

3. Examples of VOTable outputs for ephemeris calculations

Miriade

The Miriade query interface at IMCCE is providing VOTable output of ephemeris computations. Here is an output example:

The full VOTable file is available here: miriade-output.xml

CDPP

The CDPP team has developed an online "Space physics coordinate and time transformation tool"  named TREPS. It is proposing to output data in VOTable, but the capabilities of VOTable were not fully implemented. The CDPP team will update this export format following the recommendation presented in this document. 

Example of TREPS vocable export: treps_export_A9rHNJ7q9l.xml

Appendix A - WebGeoCalc Calculations

For each calculation, we propose the UCD to be put into the PARAM and FIELD descriptors of the VOTable header. 

The Date and Time parameters are common for all calculations, and the corresponding FIELD header section unit, UCD, datatype, utype and xtype should be

Geometry Calculator - State Vector

Purpose : Calculate the position and velocity of a target with respect to an observer.

Inputs: Target, Observer, Reference frame, Light propagation, Time system, Time format, Time range, State representation

Outputs: Date, Time at Target, Light Time (s), and depending on the selected State representation, the other parameters are the following:

• Rectangular:  Distance (km),  Speed (km/s),  X (km),  Y (km),  Z (km),  dX/dt (km/s),  dY/dt (km/s),  dZ/dt (km/s)
• Right Ascension, Declination, Range: Right Ascension (deg),  Declination (deg),  Range (km),  d Right Ascension/dt (deg/s),  d Declination/dt (deg/s),  d Range/dt (km/s),  Speed (km/s)
• Planetocentric: Longitude (deg),  Latitude (deg),  Radius (km),  d Longitude/dt (deg/s),  d Latitude/dt (deg/s),  d Radius/dt (km/s),  Speed (km/s)
• Planetodetic and Planetographic: Longitude (deg),  Latitude (deg),  Altitude (km),  d Longitude/dt (deg/s),  d Latitude/dt (deg/s),  d Altitude/dt (km/s),  Speed (km/s)
• Cylindrical: Longitude (deg), Z (km), Radius (km), d Longitude/dt (deg/s), dZ/dt (km/s), d Radius/dt (km/s), Speed (km/s)
• Spherical: Longitude (deg),  Colatitude (deg),  Radius (km),  d Longitude/dt (deg/s),  d Colatitude/dt (deg/s),  d Radius/dt (km/s),  Speed (km/s)
  

The FIELD header section unit, UCD, datatype and utype should be:

Notes:

• Adding generic spherical/cartesian/cylindrical UCD should be studied with IVOA Semantic group.

Geometry Calculator - Angular Separation

Purpose: Calculate the angular separation between two targets as seen from an observer.

Inputs: Target 1, Target 1 shape, Target 2, Target 2 shape, Observer, Light propagation, Time system, Time format, Time range

Outputs: Date, Angular Separation (deg)

The FIELD header section unit, UCD, datatype, utype and xtype should be:

Geometry Calculator - Angular Size

Purpose: Calculate the angular size of a target as seen from an observer.

Inputs: Target, Observer, Light propagation, Time system, Time format, Time range

Outputs: Date, Angular Size (deg)

The FIELD header section unit, UCD, datatype, utype and xtype should be:

[to be updated]

Geometry Calculator - Frame Transformation

Purpose: Calculate the transformation between two reference frames.

Inputs: Frame 1, Frame 2, Light propagation, Time system, Time format, Time range, Orientation Representation, Rotation Order, Angular Units, Angular Velocity form, Angular velocity units

Outputs: Date, and depending on the selected Orientation Representation and Angular Units the other parameters are the following:

• Eurler Angles:  Angle 1 (deg or rad), Angle 2 (deg or rad), Angle 3 (deg or rad)
• Rotation Axis and Angle:  Angle (deg or rad), Axis X, Axis Y, Axis Z
• Quaternion: QCos, QSin1, QSin2, QSin3
• Matrix: Row, Column 1, Column 2, Column 3
• Matrix, "flagged":  Column 1, Column 2, Column 3

[to be updated]

Geometry Calculator - Illumination Angles

Purpose: Calculate the emission, phase and solar incidence angles at a point on a target as seen from an observer.

Inputs: Target, Reference Frame, Observer, Coordinate System, Latitude, Longitude, Light Propagation, Time system, Time format, Time range

Outputs: Date, Incidence Angle (deg), Emission Angle (deg), Phase Angle (deg), Observer Distance (km), Time at Point, Light Time (s)

The FIELD header section unit, UCD, datatype, utype and xtype should be:

[to be updated]

Geometry Calculator - Sub-solar Point

Purpose: Calculate the sub-solar point on a target as seen from an observer.

Inputs: Target, Reference Frame, Observer, Sub-point Type, Light Propagation, Time system, Time format, Time range, Position Representation

Outputs: Date, Longitude (deg), Latitude (deg), Sub-Point Radius (km), Observer Distance (km), Incidence Angle (deg), Emission Angle (deg), Phase Angle (deg), Time at Point, Light Time (s)

Geometry Calculator - Sub-observer Point

Purpose: Calculate the sub-observer point on a target as seen from an observer.

Geometry Calculator - Surface Intercept Point

Purpose: Calculate the intercept point of a vector or vectors on a target as seen from an observer.

Geometry Calculator - Orbital Elements

Purpose: Calculate the osculating elements of the orbit of a target body around a central body.

Geometry Event Finder - Position Finder

Purpose: Find time intervals when a coordinate of an observer-target position vector satisfies a condition.

Geometry Event Finder - Angular Separation Finder

Purpose: Find time intervals when the angle between two bodies, as seen by an observer, satisfies a condition.

Geometry Event Finder - Distance Finder

Purpose: Find time intervals when the distance between a target and observer satisfies a condition.

Geometry Event Finder - Sub-Point Finder

Purpose: Find time intervals when a coordinate of the sub-observer point on a target satisfies a condition.

Geometry Event Finder - Occultation Finder

Purpose: Find time intervals when an observer sees one target occulted by, or in transit across, another.

Geometry Event Finder - Surface Intercept Finder

Purpose: Find time intervals when a coordinate of a surface intercept vector satisfies a condition.

Geometry Event Finder - Target in Field of View

Purpose: Find time intervals when a target intersects the space bounded by the field-of-view of an instrument.

Geometry Event Finder - Ray in Field of View

Purpose: Find time intervals when a specified ray is contained in the space bounded by an instrument's field-of-view.

Time Calculator - Time Conversion

Purpose: Convert times from one time system or format to another.

[to be updated]

Appendix B - Using STC Data Model

More complete description of FIELD including reference frame STC standard description can be done:

The utype attribute is used as a pointer to a data model element, so that the parameter or field is semantically and accurately defined. The data model used here is the IVOA STC data model. This data model includes a series of predefined coordinate systems (see this page). This list shall be updated with inputs from the planetary science community. Inputs from the NAIF/SPICE team would be very valuable.

The coordinate frame description (including state representation, name, center...) should be defined in the COO_SYS_FRAME group. This will be investigated.

The following table gives the utypes that should be used for each FIELD parameter:

Appendix C - New UCDs for planetary ephemeris and attitude data

During the preparation of this document, a series of missing UCDs were identified. We list them here, with a tentative definition. This list will be discussed with the IVOA Semantics Working Group.