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

From The SBN Wiki
Jump to navigation Jump to search
(Update for 1.2.0.0)
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"
 
{| class="wikitable" style="background-color: yellow"
Line 10: Line 10:
 
|* ''The description states that one of the ''Object_Orientation'' classes is required, but this is not enforced.''
 
|* ''The description states that one of the ''Object_Orientation'' classes is required, but this is not enforced.''
 
|}
 
|}
 +
 +
== <Local_Internal_Reference> ==
 +
 +
''OPTIONAL''
 +
 +
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 attributes of the ''Local_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 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 ''&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.
 +
 +
=== <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.
 +
 
 +
=== <horizontal_display_axis> ===
 +
 
 +
''REQUIRED''
 +
 
 +
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.
 +
 
 +
=== <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 ''&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.
 +
 
 +
=== <vertical_display_direction> ===
  
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.
+
''REQUIRED''
  
If you use the ''disp:'' prefix on your tags, for example, then they will look like this:
+
The value of this attribute must be either "'''Top to Bottom'''" or "'''Bottom to Top'''".
<pre>
 
    <Display_Direction>
 
      <disp:comment>...</disp:comment>
 
      <disp:horizontal_display_axis>...</disp:horizontal_display_axis>
 
      <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> ==
+
== <Central_Body_Identification> ==
  
 
''OPTIONAL''
 
''OPTIONAL''
  
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.
+
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.
 
 
{| class="wikitable" style="background-color: yellow"
 
| '''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> ===
 
=== <body_spice_name> ===
Line 44: Line 81:
 
''OPTIONAL''
 
''OPTIONAL''
  
This is the NAIF-assigned or NAIF-recognized identifier for a physical objectThis could be a spacecraft or instrument as well as natural targets like planets and small bodies.
+
This is the NAIF-assigned or NAIF-recognized identifier for the central bodyType carefully, this value is not validated.
 
 
{| class="wikitable" style="background-color: yellow"
 
| ''It is not clear if or how this value will be validated and verified for correctness.''
 
|}
 
  
 
=== <name> ===
 
=== <name> ===
Line 54: Line 87:
 
''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 indicated.  You 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.
+
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 [[Target_Names|SBN Target Names Stylesheet]] on this wiki.
  
 
=== <Internal_Reference> ===
 
=== <Internal_Reference> ===
Line 65: Line 98:
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
| '''''Note'':''' ''The ''reference_type'' attribute for this class has no defined values. I 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.''
+
| '''''Note'':''' ''The ''reference_type'' attribute for this class has no defined values.  
 
|}
 
|}
  
=== <Local_Internal_Reference> ===
+
== <Geometry_Target_Identification> ==
  
 
''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.
+
Use this class to define the observational target for geometry purposes.  At least one of the three attributes must be provided.
 +
 
 +
=== <body_spice_name> ===
  
{| class="wikitable" style="background-color: yellow"
+
''OPTIONAL''
| ''I can't see anything this could possibly reference.  It should likely be deleted.''
 
|}
 
  
== <Central_Body_Identification> ==
+
This is the NAIF-assigned or NAIF-recognized identifier for the target body.  Type carefully, this value is not validated.
 +
=== <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 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 [[Target_Names|SBN Target Names Stylesheet]] on this wiki.
  
== <Target_Identification> ==
+
=== <Internal_Reference> ===
  
 
''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.
+
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.
 +
 
 +
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.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
| ''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 here.  In fact, it is bad practice to duplicate names of primary classes from other dictionaries, especially those from pds: and the discipline dictionaries.  In 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.''
+
| '''''Note'':''' ''The ''reference_type'' attribute for this class has no defined values.  
 
|}
 
|}
  
 
== <Object_Orientation_North_East> ==
 
== <Object_Orientation_North_East> ==
  
''OPTIONAL''
+
''One of this class or "&lt;Object_Orientation_RA_DEC&gt; 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 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.
 
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.
Line 102: Line 138:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
| ''The definition in the schema references an ''Image_Orientation'' class that does not appear to exist.''
 
| ''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.
 
 
{| class="wikitable" style="background-color: yellow"
 
| ''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.''
 
|-
 
| ''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.''
 
 
|}
 
|}
  
Line 118: Line 144:
 
''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 150:
 
''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 157:
  
 
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 162:
 
''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 168:
 
''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"
+
==== <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 [[#.3CInternal_Reference.3E|&lt;Internal_Reference&gt;]] in &lt;Body_Identification&gt;, above.
| ''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: yellow"
 
{| class="wikitable" style="background-color: yellow"
| ''Same issues as with the previous class.''
+
| ''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 preference.  In 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.''
|-
 
| ''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 preference.  In 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.''
 
 
|}
 
|}
  
Line 251: Line 249:
  
 
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 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 258:
 
=== <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 292: Line 278:
 
''OPTIONAL''
 
''OPTIONAL''
  
{| class="wikitable" style="background-color: yellow"
+
This class defines a relative rotation as a quaternion.
| 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'''.
+
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 336: Line 318:
 
:::* Reverse
 
:::* Reverse
 
:::* Toward Base
 
:::* 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> ==
 
== <Quaternion_2> ==
Line 393: Line 371:
 
</pre>
 
</pre>
  
{| class="wikitable" style="background-color: yellow"
+
=== <Reference_Frame_Identification> ===
| ''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.''
+
 
|}
+
''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.
  
 
=== <celestial_north_clock_angle> ===
 
=== <celestial_north_clock_angle> ===
Line 414: Line 395:
  
 
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"
 
| ''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...''
 
|}
 
  
 
=== <target_north_pole_clock_angle> ===
 
=== <target_north_pole_clock_angle> ===
Line 430: Line 407:
  
 
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 413:
  
 
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 19:48, 26 January 2016

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).

Number of problems in this class:
* 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.
* 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.
* The description states that one of the Object_Orientation classes is required, but this is not enforced.

Contents

<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 attributes of the Local_Internal_Reference class are in the PDS4 core namespace. See Filling out the SPICE_Kernel_Files Class: 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.

<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.

<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.

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

Note: The reference_type attribute for this class has no defined values.

<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.

<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.

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

Note: The reference_type attribute for this class has no defined values.

<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 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.

The definition in the schema references an Image_Orientation class that does not appear to exist.

<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.

<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 <Internal_Reference> in <Body_Identification>, above.

<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.

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 preference. In 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-DDThh:mm:ss.sssZ) for which the values in the rest of this class were calculated.

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 <Geometry> instance?

<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_1>

OPTIONAL

This class defines a relative rotation as a quaternion.

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
  • From Base
  • Present to Reference
  • Reference to Present
  • Reverse
  • Toward Base

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

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.

<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 to <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 to <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>

<Reference_Frame_Identification>

REQUIRED

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

<celestial_north_clock_angle>

OPTIONAL

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

<ecliptic_north_clock_angle>

OPTIONAL

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

<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.

<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.