Page tree
Skip to end of metadata
Go to start of metadata


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


Start date of project: 01 September  2015

 Duration: 48 Months

Responsible WP Leader: Stéphane Erard


Project co-funded by the European Union's Horizon 2020 research and innovation programme

Dissemination level

PU

Public

  •  

PP

Restricted to other programme participants (including the Commission Service)

  •  

RE

Restricted to a group specified by the consortium (including the Commission Services)

  •  

CO

Confidential, only for members of the consortium (excluding the Commission Services)

  •  

Project Number

654208

Project Title

EPN2020 - RI

Project Duration

48 months: 01 September 2015 – 30 August 2019

Document Number

VESPA-009-TN v0.4(69)

Delivery date

2016-03-01

Title of Document

VESPA Contribution to NASA-JPL WebGeoCalc tool

Contributing Work package (s)

WP11

Dissemination level

PU

Author (s)

Abstract: WebGeoCalc is an online interface to the NAIF/SPICE Library developed by NASA/JPL. In order to increase interoperability the WebGeoCalc team is working on adding VOTable output in the tool and asked for inputs from the VESPA team. This document is proposing VOTable output templates for WebGeoCalc.



Document history (to be deleted before submission to Commission)

Date

Version

Editor

Change

Status

 

0.1

initial issue

DRAFT

 

0.2

added more details on VOTable FIELD

DRAFT

 

0.3

simplified document and added 1 example

DRAFT

 

0.4

Added Appendix C on New UCD discussion

DRAFT


Table of Contents

Reference Documents

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

ParameterUnitdatatypeUCDxtypeNote
Date
chartime.epochdatetimeTime Format = "Calendar Date and Time"
Dateddoubletime.epoch
Time Format = "Julian Date"
Datesdoubletime.epoch
Time Format = "Seconds past J2000"
Time at Target
chartime.epochdatetimeTime Format = "Calendar Date and Time"
Time at Targetddoubletime.epoch
Time Format = "Julian Date"
Time at Targetsdoubletime.epoch
Time Format = "Seconds past J2000"
Light Timesdoubletime.duration

Time at Point
chartime.epochdatetimeTime Format = "Calendar Date and Time"
Time at Pointddoubletime.epoch
Time Format = "Julian Date"
Time at Pointsdoubletime.epoch
Time Format = "Seconds past J2000"


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:

ParameterUnitdatatypeUCDNote
Distancekmdoublepos.distance
Speedkm/sdoublephys.veloc
Xkmdoublepos.distance
Ykmdoublepos.distance
Zkmdoublepos.distance
dX/dtkm/sdoublearith.rate;pos.distance
dY/dtkm/sdoublearith.rate;pos.distance
dZ/dtkm/sdoublearith.rate;pos.distance
Right Ascensiondegdoublepos.eq.ra
Declinationdegdoublepos.eq.dec
Rangekmdoublepos.distance
d(Right Ascension)/dtdeg/sdoublearith.rate;pos.eq.ra
d(Declination)/dtdeg/sdoublearith.rate;pos.eq.dec
d(Range)/dtkm/sdoublearith.rate;pos.distance
Longitudedegdoublepos.bodyrc.lon
Latitudedegdoublepos.bodyrc.lat
Radiuskmdoublepos.distance
Altitudekmdoublepos.bodyrc.alt
d(Longitude)/dtdeg/sdoublearith.rate;pos.bodyrc.lon
d(Latitude)/dtdeg/sdoublearith.rate;pos.bodyrc.lat
d(Radius)/dtkm/sdoublearith.rate;pos.distance
d(Altitude)/dtkm/sdoublearith.rate;pos.bodyrc.alt
Colatitudedegdoublepos.bodyrc.colat *This UCD is invalid, no replacement found.
d(Colatitude)/dtdeg/sdoublearith.rate;pos.bodyrc.colat *

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:

ParameterUnitdatatypeUCDNote
Angular Separationdegdoublepos.angDistance


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:

ParameterUnitdatatypeUCDNote
Angular Sizedegdoublephys.angSize

 


[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:

ParameterUnitdatatypeUCDNotes
Incidence Angledegdoublepos.incidenceAng *UCD could be pos.posAng
Emission Angledegdoublepos.emergenceAng *UCD could be pos.posAng
Phase Angledegdoublepos.phaseAng
Observer Distancekmdoublepos.distance

[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:

ParameterutypeNotes
Datestc:astroCoords.Time.TimeInstant.ISOTimeTime Format = "Calendar Date and Time"
Datestc:astroCoords.Time.TimeInstant.JDTimeTime Format = "Julian Date"
Datestc:astroCoords.Time.TimeInstant.TimeOffsetTime Format = "Seconds past J2000"
Time at Targetstc:astroCoords.Time.TimeInstant.ISOTimeTime Format = "Calendar Date and Time"
Time at Targetstc:astroCoords.Time.TimeInstant.JDTimeTime Format = "Julian Date"
Time at Targetstc:astroCoords.Time.TimeInstant.TimeOffsetTime Format = "Seconds past J2000"
Light Timestc:astroCoords.Time.TimeInstant.TimeOffset
Distancestc:astroCoords.Position1D.Value
Speedstc:astroCoords.Velocity1D.Value
Xstc:astroCoords.Position3D.Value3.C1
Ystc:astroCoords.Position3D.Value3.C2
Zstc:astroCoords.Position3D.Value3.C3
dX/dtstc:astroCoords.Velocity3D.Value3.C1
dY/dtstc:astroCoords.Velocity3D.Value3.C2
dZ/dtstc:astroCoords.Velocity3D.Value3.C3
Right Ascensionstc:astroCoords.Position3D.Value3.C1
Declinationstc:astroCoords.Position3D.Value3.C2
Rangestc:astroCoords.Position3D.Value3.C3
d(Right Ascension)/dtstc:astroCoords.Velocity3D.Value3.C1
d(Declination)/dtstc:astroCoords.Velocity3D.Value3.C2
d(Range)/dtstc:astroCoords.Velocity3D.Value3.C3

Longitude

stc:astroCoords.Position3D.Value3.C1
Latitudestc:astroCoords.Position3D.Value3.C2
Radiusstc:astroCoords.Position3D.Value3.C3
Altitudestc:astroCoords.Position3D.Value3.C3
d(Longitude)/dtstc:astroCoords.Velocity3D.Value3.C1
d(Latitude)/dtstc:astroCoords.Velocity3D.Value3.C2
d(Radius)/dtstc:astroCoords.Velocity3D.Value3.C3
d(Altitude)/dtstc:astroCoords.Velocity3D.Value3.C3
Colatitudestc:astroCoords.Position3D.Value3.C2
d(Colatitude)/dtstc:astroCoords.Velocity3D.Value3.C2

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.

UCDDefinitionSimilar UCD (more generic)
pos.bodyrc.colatBody related coordinate (colatitude on the body)pos.bodyrc.lat
pos.incidenceAngIncidence Angle, solar zenithal anglepos.posAng
pos.emergenceAngEmergence Angle, observer zenithal anglepos.posAng
pos.cylindrical.rCylindrical coordinates, distance to Z-axispos.distance
pos.cylindrical.thCylindrical coordinates, azimuth around Z-axispos.bodyrc.lon
pos.cylindrical.zCylindrical coordinates, altitude along Z-axis pos.cartesian.z
pos.rotation.eulerAngEuler Angles representation of a rotation
pos.rotation.quaternionQuaternion representation of a rotation
pos.rotation.matrixMatrix representation of a rotation
pos.rotation.axisAxis of a rotation, spin axis
phys.componentComponent of a vector or of a matrix
  • No labels

2 Comments

  1. These are 2 different projects (both using SPICE under the hood). Cosmographia is a 3D visualization tool, where as WeGeoCalc is a query interface to SPICE. The first provides nice images, while the second provides plots and tables.

Write a comment…