Quick Introduction to the Geometry Dictionary

From The SBN Wiki
Jump to navigation Jump to search

If you're not already well-versed in geometry as it relates to observational meta-data, the Geometry Discipline Dictionary can be fairly intimidating. This page is here to help orient you to terminology and structure so you can navigate the Geometry Dictionary more easily. It is written for the non-specialist.

Terminology and Concepts

To start with, here are some key terms and concepts you'll find throughout the Geometry Dictionary.

Central Body
Sometimes the field of view contains one thing that is orbiting around another thing. When the smaller thing is the target of interest, Central Body is the term used to refer to the larger thing that the target is orbiting.
Clock Angle
Clock angles are a way of specifying the direction of something, like North or the Sun, from the center of an image. They are measured clockwise from "up" - a vertical running from the middle of the image to the center of the top edge. In order to correctly interpret a clock angle, you must be displaying the image correctly. "Correctly", in the PDS case, means according to the explicit display directions included in the <geom:Image_Display_Geometry> class.
Coordinate System vs Reference Frame
In the geometry dictionary, these two terms are distinct, and they are used here the same way they are used in the documentation for the NAIF SPICE toolkit (the software most missions and PDS nodes are using to calculate geometric values for PDS4 labels). A Reference Frame is defined by three orthogonal axes and an orientation in space; a Coordinate System is the result of fixing a Reference Frame to a specific origin. So (loosely speaking), "celestial coordinates" is a reference frame, "celestial coordinates centered on the Sun" is a coordinate system.
North Pole
For solar system objects, the IAU defines the "north" pole of a planet as the pole that is on the same side of the invariant plane of the solar system as the Earth's north pole. For larger planets and satellites, the poles are commonly referred to as "north" and "south" and you will see classes with "north pole" in their name or description. Only use these classes for things that have a well-defined "north". For small bodies, which tend to tumble and have complicated rotational states, "north" is not an applicable concept. For these cases, use classes with the "positive pole" notation, instead.
Object
In the Geometry Dictionary, the word "object" is used strictly to refer to the digital data object in the data file(s) referenced by the label. It will not be used to refer to physical objects like planets, comets, rings, dust, spacecraft, instruments, or any other thing that might be found in the field of view or involved in actually recording the observation. So if you are writing a label for an image of Titan, "object" will always mean the image, not Titan.
Positive Pole
This term is used to indicate the direction of positive angular momentum (according to the "right-hand rule") for a body that is rotating. The positive pole may or may not be considered the "north" pole, depending on a number of things including the overall rotational state of the body. Typically, asteroids and comets will be described in terms of their "positive" poles, while larger planets and their satellites will be described in terms of their "north" poles.
Specific vs Generic
Certain geometric quantities recur in data from widely varying sources, and are of particular interest to users, researchers, and analysts. In order to make those data quickly recognizable to both humans and programs, many classes and attributes are defined with "specific" names - names that indicate the observer and/or target. For example, <spacecraft_target_center_distance> is the attribute that contains the scalar distance between the spacecraft and the center of the target. "Generic" classes, on the other hand, allow a data preparer to define distances between arbitrary points, but require an explicit specification of start and end point. You should use the defined specific classes and attributes wherever they are applicable to support correlative studies across data sources, and use the generic classes only when there is no specific alternative.
SPICE
This is an acronym that has come to be the primary identifier for a toolkit that is widely used by missions and end-users to calculate observational geometry for spacecraft data, and is very useful for ground-based observers as well. When you see this acronym used in a class or attribute name it indicates that the associated concepts are mapped directly from the SPICE toolkit and documentation. See the NAIF website for details: http://naif.jpl.nasa.gov/naif. In particular, the *_spice_name attributes should contain the NAIF-issued SPICE identifier for the thing (spacecraft, instrument, reference frame, etc.) being referenced, if any/known.
Target
The term target is used in this dictionary to refer to the thing of interest in the enclosing geometry class. It may or may not be the same thing named in the <Target_Identification> area elsewhere in your label. In fact, if you have multiple things of interest in your field of view, you may well have distinct <Geometry> classes in your label, each one of which provides geometry for one specific thing of interest ("target"). So target will be defined locally in your Geometry classes and subclasses. The <Geometry_Target_Identification> class is used throughout the Geometry dictionary structures to identify a thing of interest as the local target of reference.

Label Structures

The full details of the class structures in the Geometry dictionary are detailed in the page Filling Out the Geometry Dictionary Classes, elsewhere on this wiki. Here's the broad overview.

<Geometry>

The Geometry dictionary is a discipline dictionary. As such, its classes are included in the <Discipline_Area> of your label. For each set of geometric parameters you want to provide, you will include one <geom:Geometry> class in your label. (For this and the rest of this discussion, I'm going to assume you have defined the "geom:" prefix and will be using it to identify classes from the Geometry Discipline Dictionary. If that sounds like gibberish to you, see the Using Local Dictionaries page on this wiki.)

The Geometry class has four major subclasses:

  1. <SPICE_Kernel_Files>: Include this class (once only) to list the SPICE kernels used to calculate the geometry in the other classes. If the NAIF toolkit was not used to calculate geometry, the class will be absent.
  2. <Image_Display_Geometry>: This class is used to define how the corresponding image should be drawn on a display so that clock angles and directions like North can be correctly interpreted. It contains a required class specifically to define display direction, and optional classes to define image orientation (north/east or RA/Dec), a target, a central body, various clock angles for directions of interest, and a quarternion to define rotation from one frame to another. This class contains orientation values that are useful for ground-based data as well as spacecraft, so if you're dealing with ground-based images, this is where you'll find your applicable values. The class is matched to an Image object in your label using the <local_identifier> attribute of the image class, which you may omit if there is no ambiguity.
  3. <Geometry_Orbiter>: This is where you'll find distances, positions, velocities, illumination angles, surface coordinates, and pixel dimensions for observations made by both orbiting and flyby spacecraft. This is itself a large class, and will be described in a little more detail below.
  4. <Geometry_Lander>: This is the class that provides details of individuals motions and orientations for static and articulating hardware used in making observations and measurements on the surface of something other than Earth. This section of the Geometry Dictionary is still in development. If you need it, contact your PDS consultant for the information.

The <Geometry_Orbiter> Subclass

This class is repeatable, should you need to. If you have multiple targets about which to report geometry (say, multiple small moons in the same field of view), then you would have a separate Geometry_Orbiter class for each target. Note that you must have an enclosing ""Geometry in order to use this class.

Every Geometry class starts with one or more reference times (either a single point in time or a start/stop pair - but you may include both). These indicate the point(s) in time for which the values in the class were calculated. Following that there is a set of classes, each of which is optional, but none of which can be repeated (add a new Geometry_Orbiter class if you need to). Here are the major subclasses of this class:

Orbiter_Identification
This class is where you identify by name the things you will be referencing by the more generic titles of "target", "coordinate system", and possibly "central body" elsewhere in the Geometry_Orbiter class.
Pixel_Dimensions
This class allows you to describe a single pixel field of view as both an angle and a distance calculated at the target.
Distances
This class lists scalar distances between standard points (spacecraft and target, target and Sun, spacecraft and Earth, etc.) as well as providing classes to define distances between arbitrary (data-preparer defined) points.
Surface_Geometry
Use this class to define pixel intercepts, boresight intercepts, and observational footprints of the field of view projected onto the surface of (or at the distance of) the target.
Illumination_Geometry
This is where you will find phase angle, emission angle, incidence angle, and solar elongation.
Vectors
This class contains specific and generic vectors to define position, velocity, and acceleration in three dimensional space to and from either named points of interest (sun, target, spacecraft, etc.), or from data-preparer specified points (via the generic options). Use whatever is appropriate, but note that in all cases you will be required to specify whether stellar aberration and light travel time corrections have been applied.