Difference between revisions of "Filling out the Image Display Geometry Class"

From The SBN Wiki
Jump to navigation Jump to search
m ()
m ()
(22 intermediate revisions by the same user not shown)
Line 1: Line 1:
The ''<Image_Display_Geometry>'' class maps the orientation of cardinal directions (North and East, typically) either on the sky or on a specified physical object in the frame to an image-like data object, based on that image being displayed on a device according to the display settings in the label (defined in the Display Discipline Dictionary ''<Display_Direction>'' class).
+
The ''<Image_Display_Geometry>'' class maps the orientation of cardinal directions (North and East, typically) either on the sky or on a specified physical object in the frame to the axes of an image-like data object, based on that image being displayed on a device according to the display settings in the label (defined in the Display Discipline Dictionary ''<Display_Direction>'' class).
  
{| class="wikitable" style="background-color: yellow"
+
== <pds:Local_Internal_Reference> ==
| ''Number of problems in this class:''
+
 
|-
+
''OPTIONAL''
|* ''Why the requirement that you identify a small body using the ''Body_Identification'' class rather than the ''Target_identification'', and that ''Target_Identification'' only be used when the object is not the target of the observation? That seems purposefully contorted. I would have thought that ''Target_Identification'' should always be used to indicate the target of interest. Period.  ''Central Body'' I would expect to indicate the body that the thing of local interest is orbiting or otherwise related to. And I would expect ''Body'' to be used for things that were not targetted but are of interest and import to the particular instance of the Image_Display_Geometry class. ''
+
 
|-
+
Use this class to identify which image-like object in the label this particular ''&lt;Image_Display_Geometry&gt;'' class pertains to.  Note that, as in other cases in the ''&lt;Geometry&gt;'' class, the class and attributes of the ''pds:Local_Internal_Reference'' class are in the PDS4 core namespace. See [[Filling_out_the_SPICE_Kernel_Files_Class#.3Cpds:Internal_Reference.3E|Filling out the SPICE_Kernel_Files Class: pds:Internal_Reference]] for more info on referencing ''pds:'' namespace attributes in ''geom:'' classes.
|* ''Given the rest of the class, I would expect that at most one ID class could be specified if Image_Display_Geometry class is giving orientation in North/East form rather than RA/Dec form.''
+
 
|-
+
=== <pds:comment> ===
|* ''The description states that one of the ''Object_Orientation'' classes is required, but this is not enforced.''
+
 
|}
+
''OPTIONAL''
 +
 
 +
If you have something additional to say about the relationship between the image and the containing geometry class, this is the place for it.
 +
 
 +
=== <pds:local_identifier_reference> ===
 +
 
 +
''REQUIRED''
 +
 
 +
This value must be identically equal to the value of a ''&lt;local_identifier&gt;'' attribute elsewhere in the same label.  Logically, this must be associated with some array-based object that can, in some sense, be displayed as an image either in whole or in part (one plane of a cube, for example).  This is not validated, so type carefully.
 +
 
 +
=== <pds:local_reference_type> ===
 +
 
 +
''REQUIRED''
 +
 
 +
This attribute must have the value '''display_to_data_object'''.
  
 
== <Display_Direction> ==
 
== <Display_Direction> ==
 +
 +
''REQUIRED''
 +
 +
If you are providing orientation information for a data object, you must have a corresponding ''Display_Direction'' class. This class is very similar to the class of the same name in the Imaging Discipline Dictionary, so this may look familiar.  Only this class, however, is considered when defining geometry with respect to display orientation.  The names of the horizontal and vertical axes are not constrained for geometry as they are for pure image display.
 +
 +
=== <comment> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
If you are providing orientation information for a data object, you must have a corresponding ''Display_Direction'' class either here or as part of a ''&lt;Display_Settings&gt;'' class from the Display Discipline Dictionary.  Don't provide the same information twice, though - it opens up the opportunity for conflict and error. This class is filled out the same way whether it appears in here or in  ''&lt;Display_Settings&gt;'', at least in terms of attribute content.  See [[Filling_Out_the_Display_Dictionary_Classes#.3CDisplay_Direction.3E|Filling Out the Display_Dictionary Classes: Display_Direction]] for details.
+
If you have any additional explanation or comments to provide about the display of the corresponding data object, use this text field to do it.
  
If you are going to use the version that is included inside this ''&lt;Image_Geometry_Class&gt;'', though, you are going to need to specify the Display Dictionary namespace (standard abbreviation is "''disp''") for the attribute tags ''inside'' the ''Display_Direction'' class, but not for the ''Display_Direction'' tag itself, which in this class is considered part of the Geometry Dictionary namespace.  You can do this either by defining and using the standard ''disp:'' prefix with all the tags inside this class, or you can provide an explicit reference to the Display Dictionary namespace by using the ''xmlns'' XML attribute in your tags.  If that all sounds like gibberish to you, you might want to check the [[Schema_Referencing_in_PDS4_Labels#Namespace_References|Namespace Reference]] topic on the ''"Schema Referencing"'' page on this wiki before proceeding.
+
=== <horizontal_display_axis> ===
  
If you use the ''disp:'' prefix on your tags, for example, then they will look like this:
+
''REQUIRED''
<pre>
+
 
    <Display_Direction>
+
The value of this attribute is the ''&lt;axis_name&gt;'' value of the axis that should be interpreted as the horizontal axis of the image-type object associated with this ''Image_Display_Geometry'' class.
      <disp:comment>...</disp:comment>
+
 
      <disp:horizontal_display_axis>...</disp:horizontal_display_axis>
+
=== <horizontal_display_direction> ===
      <disp:horizontal_display_direction>...</disp:horizontal_display_direction>
 
      <disp:vertical_display_axis>...</disp:vertical_display_axis>
 
      <disp:vertical_display_direction>...</disp:vertical_display_direction>
 
    </Display_Direction>
 
</pre>
 
  
== <Body_Identification_Base> ==
+
''REQUIRED''
  
''OPTIONAL''
+
The value of this attribute must be either "'''Left to Right'''" or "'''Right to Left'''".
  
This class provides a number of options for identifying a physical object to be subsequently referenced in this instance of the ''&lt;Geometry&gt;'' class by the term "body".  You must provide at least one of the included attributes or subclasses; you may provide more than one but they should reference ''the same physical object''.  You may ''not'' repeat this class, but you may use it in conjunction with the ''&lt;Central_Body_Identification&gt;'' and ''&lt;Target_Identification&gt;'' classes.
+
=== <vertical_display_axis> ===
  
{| class="wikitable" style="background-color: yellow"
+
''REQUIRED''
| '''Note:''' _Base ''classes are usually abstract.  This name seems wrong.  Also, my definition above doesn't help, but the definition given for the ''Image_Display_Class'' is worse (see comments previously).''
 
|}
 
  
=== <body_spice_name> ===
+
The value of this attribute is the ''&lt;axis_name&gt;'' value of the axis that should be interpreted as the vertical axis of the image-type object associated with this ''Image_Display_Geometry'' class.
  
''OPTIONAL''
+
=== <vertical_display_direction> ===
  
This is the NAIF-assigned or NAIF-recognized identifier for a physical object.  This could be a spacecraft or instrument as well as natural targets like planets and small bodies.
+
''REQUIRED''
  
{| class="wikitable" style="background-color: yellow"
+
The value of this attribute must be either "'''Top to Bottom'''" or "'''Bottom to Top'''".
| ''It is not clear if or how this value will be validated and verified for correctness.''
 
|}
 
  
=== <name> ===
+
== <Central_Body_Identification> ==
  
 
''OPTIONAL''
 
''OPTIONAL''
  
This attribute should be a name that provides sufficient identification for the object to be uniquely identified - especially in light of the fact that no object type is indicatedYou should use whatever naming conventions would normally apply.  For example, if you are naming a small body, or submitting the data to the Small Bodies Node, then you should follow the conventions described on the [[Target_Names|SBN Target Names Stylesheet]] on this wiki.
+
Use this class when the target of the observation is orbiting another body also in the field of viewThis class is used to identify that other body (always use the ''Geometry_Target_Identification'' to identify the actual target of the observation). This class may not be repeated.  
  
=== <Internal_Reference> ===
+
=== <body_spice_name> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
If the object you're trying to identify has a corresponding context product in the PDS archives, you can use this class to link to that explicitly.
+
This is the NAIF-assigned or NAIF-recognized identifier for the central body.  Type carefully, this value is not validated.
  
As in other cases in the ''&lt;Geometry&gt;'' class, the attributes of the ''Internal_Reference'' class are in the PDS4 core namespace.  See [[Filling_out_the_SPICE_Kernel_Files_Class#.3CInternal_Reference.3E|Filling out the SPICE_Kernel_Files Class: Internal_Reference]] for more info.
+
=== <name> ===
  
{| class="wikitable" style="background-color: yellow"
+
''OPTIONAL''
| '''''Note'':''' ''The ''reference_type'' attribute for this class has no defined valuesI would expect values along the lines of ''"image_display_geometry_to_target"'' if this is going to follow the same patterns established in the PDS core namespace.''
+
 
|}
+
This attribute should be a name that provides sufficient information for the object to be uniquely identified - especially in light of the fact that no object type is indicatedYou should use whatever naming conventions would normally apply to an object of the appropriate type.  For example, if you are naming a small body, or submitting the data to the Small Bodies Node, then you should follow the conventions described on the [[Target_Names|SBN Target Names Stylesheet]] on this wiki.
  
=== <Local_Internal_Reference> ===
+
=== <pds:Internal_Reference> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
As with ''&lt;Internal_Reference&gt;'', above, the attributes withing this class come from the PDS code namespace and need to be associated with that namespace in an appropriate manner.
+
If the object you're trying to identify has a corresponding context product in the PDS archives, you can use this class to link to that explicitly.  The value of the ''pds:reference_type'' attribute must be '''geometry_to_body'''.
  
{| class="wikitable" style="background-color: yellow"
+
As in other cases in the ''&lt;Geometry&gt;'' class, this class and its attributes are in the PDS4 core namespaceSee [[Filling_out_the_SPICE_Kernel_Files_Class#.3Cpds:Internal_Reference.3E|Filling out the SPICE_Kernel_Files Class: pds:Internal_Reference]] for more info.
| ''I can't see anything this could possibly referenceIt should likely be deleted.''
 
|}
 
  
== <Central_Body_Identification> ==
+
== <Geometry_Target_Identification> ==
  
 
''OPTIONAL''
 
''OPTIONAL''
  
Except for the opening and closing tag, this class is identical to the [[#.3CBody_Identification_Base.3E|&lt;Body_Identification_Base&gt;]] class described above.
+
Use this class to define the observational target for geometry purposes. At least one of the three attributes must be provided.
  
== <Target_Identification> ==
+
=== <body_spice_name> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
Except for the opening and closing tag, this class is identical to the [[#.3CBody_Identification_Base.3E|&lt;Body_Identification_Base&gt;]] class described above.
+
This is the NAIF-assigned or NAIF-recognized identifier for the target body.  Type carefully, this value is not validated.
  
{| class="wikitable" style="background-color: yellow"
+
=== <name> ===
| ''This class has an identical name to a pds: class.  It is extremely bad form for discipline dictionary to use this name to mean something very different from what the pds: class means, which appears to be the case hereIn fact, it is bad practice to duplicate names of primary classes from other dictionaries, especially those from pds: and the discipline dictionariesIn this case, for example, the ''pds:Target_Identification'' class is '''required''' to also be in the label. The likelihood of confusion by users '''and''' software is far too great.''
+
 
|}
+
''OPTIONAL''
 +
 
 +
This attribute should be a name that provides sufficient information for the object to be uniquely identified - especially in light of the fact that no object type is indicatedYou should use whatever naming conventions would normally apply to an object of the appropriate typeFor example, if you are naming a small body, or submitting the data to the Small Bodies Node, then you should follow the conventions described on the [[Target_Names|SBN Target Names Stylesheet]] on this wiki.
  
== <Object_Orientation_North_East> ==
+
=== <pds:Internal_Reference> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
This class defines the projection of a North-East coordinate system onto the plane of the related image-type object, assuming the object is displayed as described elsewhere in the label.  The orientations are indicated by azimuthal angles determined with respect to a reference line extending from the center of the image to the center of the right edge of the image, as displayed.
+
If the object you're trying to identify has a corresponding context product in the PDS archives, you can use this class to link to that explicitly.  The ''pds:reference_type'' attribute must have a value of '''geometry_to_body'''.
 +
 
 +
As in other cases in the ''&lt;Geometry&gt;'' class, this class and its attributes are in the PDS4 core namespace.  See [[Filling_out_the_SPICE_Kernel_Files_Class#.3Cpds:Internal_Reference.3E|Filling out the SPICE_Kernel_Files Class: pds:Internal_Reference]] for more info.
  
{| class="wikitable" style="background-color: yellow"
+
== <Object_Orientation_North_East> ==
| ''The definition in the schema references an ''Image_Orientation'' class that does not appear to exist.''
 
|-
 
| ''Is it obvious the direction in which "azimuthal angles" are measured?  Are they always clockwise, always positive, or what?''
 
|}
 
  
One of either this class or ''&lt;Object_Orientation_RA_Dec&gt;'' must be included.
+
''One of this class or "&lt;Object_Orientation_RA_DEC&gt; is required; both may be used.''
  
{| class="wikitable" style="background-color: yellow"
+
This class defines the projection of a North-East coordinate system onto the plane of the related image-type object, assuming the object is displayed as described by the
| ''This requirement is not enforced, and it is not clear from the schema what the intent actually is.  There are four options in a single ''choice'' list, but a total of two may be selected.  That would imply that one could have two instances of any of the items in the list, and there are ''"Quaternion"'' classes. So it would be possible to have two instances of ''&lt;Quaternion_2&gt;'' and nothing else.''
+
[[#.3CDisplay_Direction.3E|geom:Display_Direction]] described above. The orientations are indicated by azimuthal angles determined with respect to a reference line extending from the center of the image to the center of the right edge of the image, as displayed.
|-
 
| ''It's also not obvious to me that North/East and RA/Dec cover all possible cases. The Rosetta target, for example, may have to resort to something entirely new because of the object shape, or some variation on "positive angular momentum/sunward".  Nothing to do about that at the moment, though - they're still trying to figure it out themselves.''
 
|}
 
  
 
=== <north_azimuth> ===
 
=== <north_azimuth> ===
Line 118: Line 124:
 
''REQUIRED''
 
''REQUIRED''
  
This is the angle from the reference line to the direction of north.  You must specify units of measure, preferably "''deg''", for this angle.
+
This is the angle from the reference line to the direction of north, measured clockwise.  You must specify units of measure, preferably "''deg''", for this angle.
 
 
{| class="wikitable" style="background-color: yellow"
 
|
 
'''''Note:''' The direction of measurement is not specified.
 
|}
 
  
 
=== <east_azimuth> ===
 
=== <east_azimuth> ===
Line 129: Line 130:
 
''REQUIRED''
 
''REQUIRED''
  
This is the angle from the reference line to the direction of east.  You must specify units of measure, preferably "''deg''", for this angle.
+
This is the angle from the reference line to the direction of east, measured clockwise.  You must specify units of measure, preferably "''deg''", for this angle.
  
{| class="wikitable" style="background-color: yellow"
 
|
 
'''''Note:''' The direction of measurement is not specified.
 
|}
 
  
 
=== <Reference_Frame_Identification> ===
 
=== <Reference_Frame_Identification> ===
Line 141: Line 138:
  
 
This class is used to provide a link to a reference frame (here "reference frame" is being used in the same sense as in the NAIF SPICE toolkit - a set of orthogonal axes with a fixed orientation but no specified origin).
 
This class is used to provide a link to a reference frame (here "reference frame" is being used in the same sense as in the NAIF SPICE toolkit - a set of orthogonal axes with a fixed orientation but no specified origin).
 
{| class="wikitable" style="background-color: yellow"
 
| ''Seems like SOMETHING in this class should be required, since the class itself is required to be present.  And if all there is is an uncontrolled "name", you probably want to provide space for an optional description so a data preparer can explain what's going on.''
 
|}
 
  
 
==== <frame_spice_name> ====
 
==== <frame_spice_name> ====
Line 150: Line 143:
 
''OPTIONAL''
 
''OPTIONAL''
  
The identifier for this reference frame recognized by the SPICE toolkit.
+
The identifier for this reference frame recognized by the SPICE toolkit. Type carefully, this is not validated.  Do ''not'' use this attribute if you don't have the actual SPICE frame identifier - use ''&lt;name&gt;'' instead.
 
 
{| class="wikitable" style="background-color: yellow"
 
| ''It is not clear how this would be validated and verified.''
 
|}
 
  
 
==== <name> ====
 
==== <name> ====
Line 160: Line 149:
 
''OPTIONAL''
 
''OPTIONAL''
  
The name of the reference frame.  There are some standard reference frame identifiers (like ''J2000''), so if your fram has one, please use it here.
+
The name of the reference frame.  There are some standard reference frame identifiers (like ''J2000''), so if your frame has one, please use it here.
  
==== <Internal_Reference> ====
+
==== <comment> ====
  
 
''OPTIONAL''
 
''OPTIONAL''
  
If the frame in question is defined or otherwise explained in some significant way by another PDS product (could be a SPICE kernel; could be a document), you may use this class to link to that product so users can find it.  Fill this out the same was as [[#.3CInternal_Reference.3E|&lt;Internal_Reference&gt;]] in &lt;Body_Identification&gt;, above.
+
If there is any additional explanation or clarification you'd care to provide for the reference frame, this is the place for it.
  
{| class="wikitable"  style="background-color: yellow"
+
==== <pds:Internal_Reference> ====
| ''Does this make sense for reference frames (as opposed to coordinate systems)?''
 
|}
 
 
 
==== <Local_Internal_Reference> ====
 
  
 
''OPTIONAL''
 
''OPTIONAL''
  
{| class="wikitable" style="background-color: yellow"
+
If the frame in question is defined or otherwise explained in some significant way by another PDS product (could be a SPICE kernel; could be a document), you may use this class to link to that product so users can find it. Fill this out the same was as [[#.3Cpds:Internal_Reference.3E|&lt;pds:Internal_Reference&gt;]] in &lt;Body_Identification&gt;, above. The ''pds:reference_type'' attribute must have a value of '''geometry_to_reference_frame'''.
| ''I don't see what this could possible refer to.  Probably should be deleted.''
 
|}
 
  
 
== <Object_Orientation_RA_Dec> ==
 
== <Object_Orientation_RA_Dec> ==
  
''OPTIONAL''
+
''One of this class or "&lt;Object_Orientation_North_East&gt; is required; both may be used.''
  
 
This class is used to define the orientation of the celestial sphere with respect to the plane of the image, when the image is displayed as indicated elsewhere in the label.
 
This class is used to define the orientation of the celestial sphere with respect to the plane of the image, when the image is displayed as indicated elsewhere in the label.
  
One of either this class or ''&lt;Object_Orientation_North_East&gt;'' must be included.
+
{| class="wikitable" style="background-color:lightcyan"
 
+
| ''Note that it is not necessarily true that East will always be 90&deg; clockwise of North in images - especially in ground-based images, where the image is frequently reflected.  So in general, the "north" and "east" clock angles in this class should be used in pairs.''
{| class="wikitable" style="background-color: yellow"
 
| ''Same issues as with the previous class.''
 
|-
 
| ''In addition, there is not sufficient information in this class to unambiguously identify orientation. In ground based data, in particular, you must specify the direction of increasing hour angle, because it is common to get images that are reflected either because of focal plane optics or analyst's preferenceIn the previous class, at least the relative locations of North and East will tell you whether East is the to the right or left of North, but this class does not have a similar fall-back for discovering reflection.''
 
|}
 
 
 
=== <geometry_reference_time> ===
 
 
 
''REQUIRED''
 
 
 
This attribute contains the UTC time in standard format (''YYYY-MM-DD'''''T'''''hh:mm:ss.sss'''''Z''') for which the values in the rest of this class were calculated.
 
 
 
{| class="wikitable" style="background-color: yellow"
 
| ''Why does this class have a time requirement while the other classes in the same ''choice'' list do not even allow it optionally?''
 
|-
 
| ''What does it mean if this class time is not identical to the reference time required in other classes in the same ''&lt;Geometry&gt;'' instance?''
 
 
|}
 
|}
  
Line 251: Line 218:
  
 
These attributes contain the right ascension of the reference pixel specified above. Exactly one of these two must be supplied.  If you are reporting right ascension in hours, use ''right_ascension_hour_angle'' and specify a unit of "''hr''"; if you are reporting right ascension in degrees, use ''right_ascension_angle'' and specify a unit of "''deg''". In either case, the value must be given in standard decimal floating-point format, ''not'' sexigesimal notation.
 
These attributes contain the right ascension of the reference pixel specified above. Exactly one of these two must be supplied.  If you are reporting right ascension in hours, use ''right_ascension_hour_angle'' and specify a unit of "''hr''"; if you are reporting right ascension in degrees, use ''right_ascension_angle'' and specify a unit of "''deg''". In either case, the value must be given in standard decimal floating-point format, ''not'' sexigesimal notation.
 
{| class="wikitable" style="background-color: yellow"
 
| ''Couple of '''MAJOR''' problems with the definition of ''right_ascension_hour_angle'' here: ''
 
|-
 
|* ''The value is a floating-point type, but the description in the schema - presumably the one data preparers would see - strongly implies the value should be in UTC-style sexigesimal notation.''
 
|-
 
|* ''The former attribute is described as being right ascension measured as an hour angle, not a spatial angle. Hour angles are measure in units of time - thus the name.  This value, however, is defined as requiring units of angle.  This is wrong and will lead to error, as there is a scale factor involved in the conversion.  I have no idea how "hour angle" is interpreted on/from the surface of anything other than Earth, so there may be more information required than just a simple number and unit for the general case - but it's hard to imagine anyone trying to state right ascension as an hour angle on the surface of anything other than Earth.  Maybe the Moon.''
 
|}
 
  
 
=== <declination_angle> ===
 
=== <declination_angle> ===
Line 268: Line 227:
 
=== <celestial_north_clock_angle> ===
 
=== <celestial_north_clock_angle> ===
  
''OPTIONAL''
+
''Either this or &lt;ecliptic_north_clock_angle&gt; must be specified; both may be used''
  
 
This attribute contains an angle that indicates the direction of celestial north.  It is the angle, measured clockwise, between a vertical line running from the center of the image to the center of the top edge (as displayed), and a line running from the center of the image to the celestial north pole.  You must specify a unit of "''deg''" for this attribute.
 
This attribute contains an angle that indicates the direction of celestial north.  It is the angle, measured clockwise, between a vertical line running from the center of the image to the center of the top edge (as displayed), and a line running from the center of the image to the celestial north pole.  You must specify a unit of "''deg''" for this attribute.
 
At least one of ''celestial_north_clock_angle'' and ''ecliptic_north_clock_angle'' must be provided.  You may include both.
 
  
 
=== <ecliptic_north_clock_angle> ===
 
=== <ecliptic_north_clock_angle> ===
  
''OPTIONAL''
+
''Either this or &lt;celestial_north_clock_angle&gt; must be specified; both may be used''
  
 
This attribute contains an angle that indicates the direction of ecliptic north.  It is the angle, measured clockwise, between a vertical line running from the center of the image to the center of the top edge (as displayed), and a line running from the center of the image to the ecliptic north pole.  You must specify a unit of "''deg''" for this attribute.
 
This attribute contains an angle that indicates the direction of ecliptic north.  It is the angle, measured clockwise, between a vertical line running from the center of the image to the center of the top edge (as displayed), and a line running from the center of the image to the ecliptic north pole.  You must specify a unit of "''deg''" for this attribute.
 
At least one of ''celestial_north_clock_angle'' and ''ecliptic_north_clock_angle'' must be provided.  You may include both.
 
  
 
=== <Reference_Frame_Identification> ===
 
=== <Reference_Frame_Identification> ===
Line 288: Line 243:
 
This class is the same here as [[#.3CReference_Frame_Identification.3E|&lt;Reference_Frame_Identification&gt;]] in the ''&lt;Object_Orientation_North_East&gt;'' class, described above.
 
This class is the same here as [[#.3CReference_Frame_Identification.3E|&lt;Reference_Frame_Identification&gt;]] in the ''&lt;Object_Orientation_North_East&gt;'' class, described above.
  
== <Quaternion_1> ==
+
== <Quaternion_Plus_To_From> ==
  
 
''OPTIONAL''
 
''OPTIONAL''
  
{| class="wikitable" style="background-color: yellow"
+
This class defines a quaternion for a rotation ''to'' one specified frame ''from'' another. It contains the four elements comprising the quaternion, plus required classes for indicating the initial (''from'') frame and final (''to'') frame. For the following definitions, '''theta''' is the angle of rotation, and '''''a''''' is the unit vector around which the rotation occurs, with elements '''ax''', '''ay''', and '''az'''.
| Quaternion_1/2 ''seems a particularly problematic set of names for these classes, as they seem like they ought to be a sequence or otherwise related, when in fact they have different content requirements.''
 
|-
 
| ''Those content differences could have been handled by a ''choice'' statement, as they typically are elsewhere. I suspect this is an LDDTool limitation, yes?  Can't blame LDDtool for the names, though... :)''
 
|}
 
 
 
This class defines a quaternion for a rotation in a specified relative direction. For the following definitions, '''theta''' is the angle of rotation, and '''''a''''' is the unit vector around which the rotation occurs, with elements '''a1''', '''a2''', and '''a3'''.
 
 
 
=== <qcos> ===
 
 
 
''REQUIRED''
 
 
 
This element is computed as cos('''theta'''/2).
 
 
 
=== <qsin1> ===
 
 
 
''REQUIRED''
 
 
 
This element is computed as sin('''theta'''/2)*'''a1'''.
 
 
 
=== <qsin2> ===
 
 
 
''REQUIRED''
 
 
 
This element is computed as sin('''theta'''/2)*'''a2'''.
 
 
 
=== <qsin3> ===
 
 
 
''REQUIRED''
 
 
 
This element is computed as sin('''theta'''/2)*'''a3'''.
 
 
 
=== <rotation_direction> ===
 
 
 
''REQUIRED''
 
 
 
This attribute provides a description of the rotation in relative terms.  It must be one of the following values:
 
  
:::* Forward
+
You may repeat this class if you have more than one rotation you wish to define.
:::* From Base
 
:::* Present to Reference
 
:::* Reference to Present
 
:::* Reverse
 
:::* Toward Base
 
 
 
{| class="wikitable" style="background-color: yellow"
 
| ''Not surprisingly, these values make no sense to me.  Is it sufficiently obvious to reasonable users what constitutes "Forward" or "Base" in this context?  These values certainly don't tie to anything else in this class or any Geometry class by name.
 
|}
 
 
 
== <Quaternion_2> ==
 
 
 
''OPTIONAL''
 
 
 
This class defines a quaternion for a rotation from one specified frame to another.  For the following definitions, '''theta''' is the angle of rotation, and '''''a''''' is the unit vector around which the rotation occurs, with elements '''a1''', '''a2''', and '''a3'''.
 
  
 
=== <qcos> ===
 
=== <qcos> ===
Line 357: Line 261:
 
''REQUIRED''
 
''REQUIRED''
  
This element is computed as sin('''theta'''/2)*'''a1'''.
+
This element is computed as '''ax'''*sin('''theta'''/2).
  
 
=== <qsin2> ===
 
=== <qsin2> ===
Line 363: Line 267:
 
''REQUIRED''
 
''REQUIRED''
  
This element is computed as sin('''theta'''/2)*'''a2'''.
+
This element is computed as '''ay'''*sin('''theta'''/2).
  
 
=== <qsin3> ===
 
=== <qsin3> ===
Line 369: Line 273:
 
''REQUIRED''
 
''REQUIRED''
  
This element is computed as sin('''theta'''/2)*'''a3'''.
+
This element is computed as '''az'''*sin('''theta'''/2).
  
 
=== <Rotate_From> ===
 
=== <Rotate_From> ===
Line 375: Line 279:
 
''REQUIRED''
 
''REQUIRED''
  
This class identifies the reference frame in which the rotation starts. Apart from the enclosing tag names (''Rotate_From'' rather than ''Reference_Frame_Identification''), this class is filled out identically to the to [[#.3CReference_Frame_Identification.3E|&lt;Reference_Frame_Identification&gt;]] class described above.
+
This class identifies the reference frame in which the rotation starts. Apart from the enclosing tag names (''Rotate_From'' rather than ''Reference_Frame_Identification''), this class is filled out identically to the [[#.3CReference_Frame_Identification.3E|&lt;Reference_Frame_Identification&gt;]] class described above.
  
 
=== <Rotate_To> ===
 
=== <Rotate_To> ===
Line 381: Line 285:
 
''REQUIRED''
 
''REQUIRED''
  
This class identifies the reference frame in which the rotation ends. Apart from the enclosing tag names (''Rotate_To'' rather than ''Reference_Frame_Identification''), this class is filled out identically to the to [[#.3CReference_Frame_Identification.3E|&lt;Reference_Frame_Identification&gt;]] class described above.
+
This class identifies the reference frame in which the rotation ends. Apart from the enclosing tag names (''Rotate_To'' rather than ''Reference_Frame_Identification''), this class is filled out identically to the [[#.3CReference_Frame_Identification.3E|&lt;Reference_Frame_Identification&gt;]] class described above.
 
 
  
 
== <Object_Orientation_Clock_Angles> ==
 
== <Object_Orientation_Clock_Angles> ==
Line 392: Line 295:
 
       <celestial_north_clock_angle unit="deg">12.34</celestial_north_clock_angle>
 
       <celestial_north_clock_angle unit="deg">12.34</celestial_north_clock_angle>
 
</pre>
 
</pre>
 
{| class="wikitable" style="background-color: yellow"
 
| ''There seems to be a necessary assumption in this class that terms within tag names, like "target" and "body" are well-defined, but they are not.  Given the problems listed with the identification classes, it is not at all clear that a user would correctly interpret "target", for example, and programmatically it is even more problematic.''
 
|}
 
  
 
=== <celestial_north_clock_angle> ===
 
=== <celestial_north_clock_angle> ===
Line 402: Line 301:
  
 
This attribute is the angle measured from the vertical to the direction of celestial north.
 
This attribute is the angle measured from the vertical to the direction of celestial north.
 +
 +
=== <celestial_east_clock_angle> ===
 +
 +
''OPTIONAL''
 +
 +
This attribute is the angle measured from the vertical to the direction of celestial east.
  
 
=== <ecliptic_north_clock_angle> ===
 
=== <ecliptic_north_clock_angle> ===
Line 408: Line 313:
  
 
This attribute contains the angle measured from the vertical to the direction of ecliptic north.
 
This attribute contains the angle measured from the vertical to the direction of ecliptic north.
 +
 +
=== <ecliptic_east_clock_angle> ===
 +
 +
''OPTIONAL''
 +
 +
This attribute contains the angle measured from the vertical to the direction of ecliptic east.
  
 
=== <central_body_north_pole_clock_angle> ===
 
=== <central_body_north_pole_clock_angle> ===
Line 415: Line 326:
 
This attribute contains the angle between the vertical and the direction of the north (positive) pole of the central body relative to the observation.  "Central body" is the term used to reference, for example, the planet that a satellite is orbiting, when it is the satellite that is the target of interest.  
 
This attribute contains the angle between the vertical and the direction of the north (positive) pole of the central body relative to the observation.  "Central body" is the term used to reference, for example, the planet that a satellite is orbiting, when it is the satellite that is the target of interest.  
  
{| class="wikitable" style="background-color: yellow"
+
=== <central_body_positive_pole_clock_angle> ===
| ''You seem to be assuming that no small body will ever be considered a "central body".  Since there are documented comets and asteroids with moons, and we now have Rosetta images showing boulders being thrown off of a nucleus where you can easily imagine geometry being supplied where the boulder is the target and the comet the "central body", this is not a good assumption.  If you're going to maintain the "separate but equal" approach used for targets, then I would expect both a ''central_body_positive_pole_clock_angle'' and a ''body_north_pole_clock_angle''.  I'm not sure it's worth the effort, but at least it would allow for consistent usage.  The descriptions below are '''not''' consistent with the usage in the identification classes, or maybe they are and that is in itself sufficient evidence for the potential confusion to make my point...''
+
 
|}
+
''OPTIONAL''
 +
 
 +
This is ''central_body_north_pole_clock_angle'' for small bodies for which the poles are described in terms of positive and negative angular momentum, rather than "north" and "south".
  
 
=== <target_north_pole_clock_angle> ===
 
=== <target_north_pole_clock_angle> ===
Line 430: Line 343:
  
 
This attribute specifies the angle between the vertical and the positive pole (the direction of the positive angular momentum vector in a right-hand rule system), of a target for which the concept of "north" is not apropos - asteroids and comets, primarily.
 
This attribute specifies the angle between the vertical and the positive pole (the direction of the positive angular momentum vector in a right-hand rule system), of a target for which the concept of "north" is not apropos - asteroids and comets, primarily.
 
=== <body_positive_pole_clock_angle> ===
 
 
''OPTIONAL''
 
 
This attribute contains the angle between the vertical and the positive pole of some body which is not the target of the observation.
 
 
{| class="wikitable" style="background-color: yellow"
 
|
 
'''''Note:''' There is no way to indicate what "body" this angle is referencing.  If you think you have a need for this angle, please check with your PDS node consultant for additional guidance.''
 
|}
 
  
 
=== <sun_direction_clock_angle> ===
 
=== <sun_direction_clock_angle> ===
Line 447: Line 349:
  
 
This attribute provides the angle between the vertical and the direction to the sun.
 
This attribute provides the angle between the vertical and the direction to the sun.
 
=== <Reference_Frame_Identification> ===
 
 
''REQUIRED''
 
 
This class is the same here as in [[#.3CReference_Frame_Identification.3E|&lt;Reference_Fram_Identification&gt;]]
 
in ''&lt;Object_Orientation_North_East&gt;'' class, described above.
 

Revision as of 21:04, 17 January 2017

The <Image_Display_Geometry> class maps the orientation of cardinal directions (North and East, typically) either on the sky or on a specified physical object in the frame to the axes of an image-like data object, based on that image being displayed on a device according to the display settings in the label (defined in the Display Discipline Dictionary <Display_Direction> class).

<pds:Local_Internal_Reference>

OPTIONAL

Use this class to identify which image-like object in the label this particular <Image_Display_Geometry> class pertains to. Note that, as in other cases in the <Geometry> class, the class and attributes of the pds:Local_Internal_Reference class are in the PDS4 core namespace. See Filling out the SPICE_Kernel_Files Class: pds:Internal_Reference for more info on referencing pds: namespace attributes in geom: classes.

<pds:comment>

OPTIONAL

If you have something additional to say about the relationship between the image and the containing geometry class, this is the place for it.

<pds:local_identifier_reference>

REQUIRED

This value must be identically equal to the value of a <local_identifier> attribute elsewhere in the same label. Logically, this must be associated with some array-based object that can, in some sense, be displayed as an image either in whole or in part (one plane of a cube, for example). This is not validated, so type carefully.

<pds:local_reference_type>

REQUIRED

This attribute must have the value display_to_data_object.

<Display_Direction>

REQUIRED

If you are providing orientation information for a data object, you must have a corresponding Display_Direction class. This class is very similar to the class of the same name in the Imaging Discipline Dictionary, so this may look familiar. Only this class, however, is considered when defining geometry with respect to display orientation. The names of the horizontal and vertical axes are not constrained for geometry as they are for pure image display.

<comment>

OPTIONAL

If you have any additional explanation or comments to provide about the display of the corresponding data object, use this text field to do it.

<horizontal_display_axis>

REQUIRED

The value of this attribute is the <axis_name> value of the axis that should be interpreted as the horizontal axis of the image-type object associated with this Image_Display_Geometry class.

<horizontal_display_direction>

REQUIRED

The value of this attribute must be either "Left to Right" or "Right to Left".

<vertical_display_axis>

REQUIRED

The value of this attribute is the <axis_name> value of the axis that should be interpreted as the vertical axis of the image-type object associated with this Image_Display_Geometry class.

<vertical_display_direction>

REQUIRED

The value of this attribute must be either "Top to Bottom" or "Bottom to Top".

<Central_Body_Identification>

OPTIONAL

Use this class when the target of the observation is orbiting another body also in the field of view. This class is used to identify that other body (always use the Geometry_Target_Identification to identify the actual target of the observation). This class may not be repeated.

<body_spice_name>

OPTIONAL

This is the NAIF-assigned or NAIF-recognized identifier for the central body. Type carefully, this value is not validated.

<name>

OPTIONAL

This attribute should be a name that provides sufficient information for the object to be uniquely identified - especially in light of the fact that no object type is indicated. You should use whatever naming conventions would normally apply to an object of the appropriate type. For example, if you are naming a small body, or submitting the data to the Small Bodies Node, then you should follow the conventions described on the SBN Target Names Stylesheet on this wiki.

<pds:Internal_Reference>

OPTIONAL

If the object you're trying to identify has a corresponding context product in the PDS archives, you can use this class to link to that explicitly. The value of the pds:reference_type attribute must be geometry_to_body.

As in other cases in the <Geometry> class, this class and its attributes are in the PDS4 core namespace. See Filling out the SPICE_Kernel_Files Class: pds:Internal_Reference for more info.

<Geometry_Target_Identification>

OPTIONAL

Use this class to define the observational target for geometry purposes. At least one of the three attributes must be provided.

<body_spice_name>

OPTIONAL

This is the NAIF-assigned or NAIF-recognized identifier for the target body. Type carefully, this value is not validated.

<name>

OPTIONAL

This attribute should be a name that provides sufficient information for the object to be uniquely identified - especially in light of the fact that no object type is indicated. You should use whatever naming conventions would normally apply to an object of the appropriate type. For example, if you are naming a small body, or submitting the data to the Small Bodies Node, then you should follow the conventions described on the SBN Target Names Stylesheet on this wiki.

<pds:Internal_Reference>

OPTIONAL

If the object you're trying to identify has a corresponding context product in the PDS archives, you can use this class to link to that explicitly. The pds:reference_type attribute must have a value of geometry_to_body.

As in other cases in the <Geometry> class, this class and its attributes are in the PDS4 core namespace. See Filling out the SPICE_Kernel_Files Class: pds:Internal_Reference for more info.

<Object_Orientation_North_East>

One of this class or "<Object_Orientation_RA_DEC> is required; both may be used.

This class defines the projection of a North-East coordinate system onto the plane of the related image-type object, assuming the object is displayed as described by the geom:Display_Direction described above. The orientations are indicated by azimuthal angles determined with respect to a reference line extending from the center of the image to the center of the right edge of the image, as displayed.

<north_azimuth>

REQUIRED

This is the angle from the reference line to the direction of north, measured clockwise. You must specify units of measure, preferably "deg", for this angle.

<east_azimuth>

REQUIRED

This is the angle from the reference line to the direction of east, measured clockwise. You must specify units of measure, preferably "deg", for this angle.


<Reference_Frame_Identification>

REQUIRED

This class is used to provide a link to a reference frame (here "reference frame" is being used in the same sense as in the NAIF SPICE toolkit - a set of orthogonal axes with a fixed orientation but no specified origin).

<frame_spice_name>

OPTIONAL

The identifier for this reference frame recognized by the SPICE toolkit. Type carefully, this is not validated. Do not use this attribute if you don't have the actual SPICE frame identifier - use <name> instead.

<name>

OPTIONAL

The name of the reference frame. There are some standard reference frame identifiers (like J2000), so if your frame has one, please use it here.

<comment>

OPTIONAL

If there is any additional explanation or clarification you'd care to provide for the reference frame, this is the place for it.

<pds:Internal_Reference>

OPTIONAL

If the frame in question is defined or otherwise explained in some significant way by another PDS product (could be a SPICE kernel; could be a document), you may use this class to link to that product so users can find it. Fill this out the same was as <pds:Internal_Reference> in <Body_Identification>, above. The pds:reference_type attribute must have a value of geometry_to_reference_frame.

<Object_Orientation_RA_Dec>

One of this class or "<Object_Orientation_North_East> is required; both may be used.

This class is used to define the orientation of the celestial sphere with respect to the plane of the image, when the image is displayed as indicated elsewhere in the label.

Note that it is not necessarily true that East will always be 90° clockwise of North in images - especially in ground-based images, where the image is frequently reflected. So in general, the "north" and "east" clock angles in this class should be used in pairs.

<Reference_Pixel>

OPTIONAL

This class identifies a pixel position within the image to which the rest of the geometry in the containing class is referenced. The reference pixel does not necessarily correspond to a physical pixel. The terms "vertical" and "horizontal" here refer to the orientation of the associated image-type object when displayed according to the corresponding Display_Direction class specifications, and the counting order is the display order (left to right for horizontal measurement, and either top to bottom or bottom to top for vertical measurements).

Fractional pixels may be indicated if necessary, and the first pixel is taken to be at coordinates (0,0). For purposes of coordinate evaluation, pixels are assumed to be square and centered on their coordinate, so that the leading edge of the first pixel is at -0.5 pixel, the center is at 0.0 pixels, the edge abutting the next pixel is at +0.05 pixel, and so on.

<vertical_coordinate_pixel>

REQUIRED

The vertical location of the the reference pixel, measured from the first displayed horizontal line towards the last displayed horizontal line - that is, in the same direction as the corresponding <vertical_display_direction> of the <Display_Direction> class. You must specify a unit of "pixel" for this value:

       <vertical_coordinate_pixel unit="pixel">255.5</vertical_coordinate_pixel>

<horizontal_coordinate_pixel>

REQUIRED

The horizontal location of the the reference pixel, measured from left to right- that is, in the same direction as the corresponding <horizontal_display_direction> of the <Display_Direction> class. You must specify a unit of "pixel" for this value:

       <horizontal_coordinate_pixel unit="pixel">255.5</horizontal_coordinate_pixel>

<reference_pixel_location>

OPTIONAL

Alternately or in addition to the explicit coordinates in the preceding <Reference_Pixel> class, you may use this attribute to provide a more human-readable location for the reference pixel. This attribute must contain one of the following values:

  • Center
  • Lower Left Corner
  • Lower Right Corner
  • Upper Left Corner
  • Upper Right Corner

These descriptions must apply to the orientation of the image as indicated by the corresponding <Display_Direction> class.

<right_ascension_hour_angle> or <right_ascension_angle>

REQUIRED

These attributes contain the right ascension of the reference pixel specified above. Exactly one of these two must be supplied. If you are reporting right ascension in hours, use right_ascension_hour_angle and specify a unit of "hr"; if you are reporting right ascension in degrees, use right_ascension_angle and specify a unit of "deg". In either case, the value must be given in standard decimal floating-point format, not sexigesimal notation.

<declination_angle>

REQUIRED

This attribute contains the declination of the reference pixel as a standard decimal floating-point number (not sexigesimal notation). You must indicate a unit of "deg".

<celestial_north_clock_angle>

Either this or <ecliptic_north_clock_angle> must be specified; both may be used

This attribute contains an angle that indicates the direction of celestial north. It is the angle, measured clockwise, between a vertical line running from the center of the image to the center of the top edge (as displayed), and a line running from the center of the image to the celestial north pole. You must specify a unit of "deg" for this attribute.

<ecliptic_north_clock_angle>

Either this or <celestial_north_clock_angle> must be specified; both may be used

This attribute contains an angle that indicates the direction of ecliptic north. It is the angle, measured clockwise, between a vertical line running from the center of the image to the center of the top edge (as displayed), and a line running from the center of the image to the ecliptic north pole. You must specify a unit of "deg" for this attribute.

<Reference_Frame_Identification>

REQUIRED

This class is the same here as <Reference_Frame_Identification> in the <Object_Orientation_North_East> class, described above.

<Quaternion_Plus_To_From>

OPTIONAL

This class defines a quaternion for a rotation to one specified frame from another. It contains the four elements comprising the quaternion, plus required classes for indicating the initial (from) frame and final (to) frame. For the following definitions, theta is the angle of rotation, and a is the unit vector around which the rotation occurs, with elements ax, ay, and az.

You may repeat this class if you have more than one rotation you wish to define.

<qcos>

REQUIRED

This element is computed as cos(theta/2).

<qsin1>

REQUIRED

This element is computed as ax*sin(theta/2).

<qsin2>

REQUIRED

This element is computed as ay*sin(theta/2).

<qsin3>

REQUIRED

This element is computed as az*sin(theta/2).

<Rotate_From>

REQUIRED

This class identifies the reference frame in which the rotation starts. Apart from the enclosing tag names (Rotate_From rather than Reference_Frame_Identification), this class is filled out identically to the <Reference_Frame_Identification> class described above.

<Rotate_To>

REQUIRED

This class identifies the reference frame in which the rotation ends. Apart from the enclosing tag names (Rotate_To rather than Reference_Frame_Identification), this class is filled out identically to the <Reference_Frame_Identification> class described above.

<Object_Orientation_Clock_Angles>

OPTIONAL

This class holds clock angles, which define various directions of interest in the plane of the associated image(s). In all cases, and assuming the image is displayed according to the information in the associated <Display_Direction> class, these angles are measure at the center of the image, clockwise from the vertical (running from image center to the center of the top edge) to the direction of interest. Also in all cases, you must specify a unit of deg for these attributes, e.g.:

       <celestial_north_clock_angle unit="deg">12.34</celestial_north_clock_angle>

<celestial_north_clock_angle>

OPTIONAL

This attribute is the angle measured from the vertical to the direction of celestial north.

<celestial_east_clock_angle>

OPTIONAL

This attribute is the angle measured from the vertical to the direction of celestial east.

<ecliptic_north_clock_angle>

OPTIONAL

This attribute contains the angle measured from the vertical to the direction of ecliptic north.

<ecliptic_east_clock_angle>

OPTIONAL

This attribute contains the angle measured from the vertical to the direction of ecliptic east.

<central_body_north_pole_clock_angle>

OPTIONAL

This attribute contains the angle between the vertical and the direction of the north (positive) pole of the central body relative to the observation. "Central body" is the term used to reference, for example, the planet that a satellite is orbiting, when it is the satellite that is the target of interest.

<central_body_positive_pole_clock_angle>

OPTIONAL

This is central_body_north_pole_clock_angle for small bodies for which the poles are described in terms of positive and negative angular momentum, rather than "north" and "south".

<target_north_pole_clock_angle>

OPTIONAL

This attribute contains the angle between the vertical and the north pole of a target for which "north pole" is a well-defined concept (major planets and their satellites, generally).

<target_positive_pole_clock_angle>

OPTIONAL

This attribute specifies the angle between the vertical and the positive pole (the direction of the positive angular momentum vector in a right-hand rule system), of a target for which the concept of "north" is not apropos - asteroids and comets, primarily.

<sun_direction_clock_angle>

OPTIONAL

This attribute provides the angle between the vertical and the direction to the sun.