Difference between revisions of "Quick Introduction to the Geometry Dictionary"

From The SBN Wiki
Jump to navigation Jump to search
m
m ()
 
(13 intermediate revisions by the same user not shown)
Line 8: Line 8:
 
: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.
 
: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 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.
+
: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 line 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
 
;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''.
 
: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''.
 +
;Coordinate System ''vs'' Coordinate Space
 +
:For data obtained by orbiter or flyby spacecraft, labels will generally only need to refer to one or two reference frames, and one or two coordinate systems.  But for landed missions, and in particular rovers, the the situation is much more complicated, as coordinate systems are needed to describe in detail the location and orientation of individual pieces of hardware (sampling arms, drills, etc.) that move, as well as the lander/rover itself. New coordinate systems are defined pretty much at every stop, with each of these bootstrapping off of the previously defined coordinate system. Typically, an index is used to identify the individual coordinate system steps in these sequences. The term ''coordinate space'' is used in classes that refer to these indexed sequences of coordinate systems.
 
;North Pole
 
;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.
 
: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
 
;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.
 
: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.
 +
;Observer
 +
:The designation of ''observer'' is used in the Geometry dictionary as a general way of identifying the origin of a vector or other quantity with a sense of direction.  So, for example, in the vector class ''<Vector_Cartesian_Position_Sun_to_Spacecraft>'', which defines a position vector from the center of the Sun to the center of the spacecraft, the Sun is in the ''observer'' role and the spacecraft is in the ''target'' role.
 
;Positive Pole
 
;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.
 
: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
 
;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 program, many classes and attributes are define 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 prepare 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, because they support correlative studies across data sources, and use the generic classes only when there is no specific alternative.
+
: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
 
;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 observations - though it has routines 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.
+
:"SPICE" is an acronym representing a system of data files (called "kernels") and the associated software toolkit that supports them.  SPICE 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
 
;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.
+
:The term ''target'' is used in this dictionary primarily 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.
 +
 
 +
:"''Target''" is also employed in a much broader sense when generic classes are used to define vectors that are outside of the specific classes provided in this dictionary. In these cases ''observer'' indicates the origin or starting point, while ''target'' indicates the destination or ending point. Context should make the distinction in meaning clear.
  
 
= Label Structures =
 
= Label Structures =
Line 30: Line 36:
 
== <Geometry> ==
 
== <Geometry> ==
  
The Geometry dictionary is a discipline dictionary.  As such, its classes are included in the ''&lt;Discipline_Area&gt;'' of your label.  For each set of geometric parameters you want to provide, you will include one ''&lt;geom:Geometry&gt;'' 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 dictionary is a discipline dictionary.  As such, its classes are included in the ''&lt;Discipline_Area&gt;'' of your label.  In general, you will only have one ''&lt;geom:Geometry&gt;'' class in your label, but it may contain subclasses which are repeated for different targetsFor very complex cases, you may also have more than one ''&lt;geom:Geometry&gt;'' class in the ''&lt;Discipline_Area&gt;''.
 +
 
 +
:''(For this and the rest of this discussion, I'm going to elide the "geom:" prefix in the interest of clarity for explanations, but bear in mind that all the attributes and classes described below ''must'' be placed in the Geometry namespace in PDS4 labels.  If that sounds like gibberish to you, see the [[Using Local Dictionaries]] page on this wiki.)''
  
The ''Geometry'' class has four major subclasses:
+
The ''Geometry'' class has five major subclasses:
  
#'''&lt;SPICE_Kernel_Files&gt;''': 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.  
+
#'''&lt;SPICE_Kernel_Files&gt;''': Include this class (once only) to list the SPICE kernels, if any, used to calculate the geometry in the other classes.  
#'''&lt;Image_Display_Geometry&gt;''': 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 ''&lt;local_identifier&gt;'' attribute of the image class, which you may omit if there is no ambiguity.
+
#'''&lt;Expanded_Geometry&gt;''': Use this class to link the observational data to detailed geometry values in a separate data object in this product, or a separate data product.  This may be (and usually should be) used in addition to providing median values or ranges in other Geometry classes.
 +
#'''&lt;Image_Display_Geometry&gt;''': 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 quaternion 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 ''&lt;local_identifier&gt;'' attribute of the image class, which you may omit if there is no ambiguity.
 
#'''&lt;Geometry_Orbiter&gt;''': 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.
 
#'''&lt;Geometry_Orbiter&gt;''': 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.
#'''&lt;Geometry_Lander&gt;''': 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.
+
#'''&lt;Geometry_Lander&gt;''': This class will be a container for all geometric information relating to landed spacecraft, including rovers. It will document the incremental coordinate systems (described as ''coordinate spaces'') for rovers, and the relative orientations for static and articulating hardware used in making observations and measurements on the surface of something other than Earth. '''N.B.:''' This section of the Geometry Dictionary is still in development.  If you need it, contact your PDS consultant for the latest information.
  
 
== The <Geometry_Orbiter> Subclass ==
 
== 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.
+
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 always have an enclosing ''&lt;Geometry&gt;'' class to contain this class and any siblings.
  
 
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).
 
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).

Latest revision as of 17:14, 22 April 2019

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 line 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.
Coordinate System vs Coordinate Space
For data obtained by orbiter or flyby spacecraft, labels will generally only need to refer to one or two reference frames, and one or two coordinate systems. But for landed missions, and in particular rovers, the the situation is much more complicated, as coordinate systems are needed to describe in detail the location and orientation of individual pieces of hardware (sampling arms, drills, etc.) that move, as well as the lander/rover itself. New coordinate systems are defined pretty much at every stop, with each of these bootstrapping off of the previously defined coordinate system. Typically, an index is used to identify the individual coordinate system steps in these sequences. The term coordinate space is used in classes that refer to these indexed sequences of coordinate systems.
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.
Observer
The designation of observer is used in the Geometry dictionary as a general way of identifying the origin of a vector or other quantity with a sense of direction. So, for example, in the vector class <Vector_Cartesian_Position_Sun_to_Spacecraft>, which defines a position vector from the center of the Sun to the center of the spacecraft, the Sun is in the observer role and the spacecraft is in the target role.
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
"SPICE" is an acronym representing a system of data files (called "kernels") and the associated software toolkit that supports them. SPICE 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 primarily 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.
"Target" is also employed in a much broader sense when generic classes are used to define vectors that are outside of the specific classes provided in this dictionary. In these cases observer indicates the origin or starting point, while target indicates the destination or ending point. Context should make the distinction in meaning clear.

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. In general, you will only have one <geom:Geometry> class in your label, but it may contain subclasses which are repeated for different targets. For very complex cases, you may also have more than one <geom:Geometry> class in the <Discipline_Area>.

(For this and the rest of this discussion, I'm going to elide the "geom:" prefix in the interest of clarity for explanations, but bear in mind that all the attributes and classes described below must be placed in the Geometry namespace in PDS4 labels. If that sounds like gibberish to you, see the Using Local Dictionaries page on this wiki.)

The Geometry class has five major subclasses:

  1. <SPICE_Kernel_Files>: Include this class (once only) to list the SPICE kernels, if any, used to calculate the geometry in the other classes.
  2. <Expanded_Geometry>: Use this class to link the observational data to detailed geometry values in a separate data object in this product, or a separate data product. This may be (and usually should be) used in addition to providing median values or ranges in other Geometry classes.
  3. <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 quaternion 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.
  4. <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.
  5. <Geometry_Lander>: This class will be a container for all geometric information relating to landed spacecraft, including rovers. It will document the incremental coordinate systems (described as coordinate spaces) for rovers, and the relative orientations for static and articulating hardware used in making observations and measurements on the surface of something other than Earth. N.B.: This section of the Geometry Dictionary is still in development. If you need it, contact your PDS consultant for the latest 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 always have an enclosing <Geometry> class to contain this class and any siblings.

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.