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

From The SBN Wiki
Jump to navigation Jump to search
(Creation - Safety Save)
(Creation - Safety Save)
Line 235: Line 235:
  
 
''OPTIONAL''
 
''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.:
 +
<pre>
 +
      <celestial_north_clock_angle unit="deg">12.34</celestial_north_clock_angle>
 +
</pre>
  
 
=== <celestial_north_clock_angle> ===
 
=== <celestial_north_clock_angle> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
This attribute is the angle measured from the vertical to the direction of celestial north.
  
 
=== <ecliptic_north_clock_angle> ===
 
=== <ecliptic_north_clock_angle> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
This attribute contains the angle measured from the vertical to the direction of ecliptic north.
  
 
=== <central_body_north_pole_clock_angle> ===
 
=== <central_body_north_pole_clock_angle> ===
  
 
''OPTIONAL''
 
''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> ===
 
=== <target_north_pole_clock_angle> ===
  
 
''OPTIONAL''
 
''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> ===
 
=== <target_positive_pole_clock_angle> ===
  
 
''OPTIONAL''
 
''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.
  
 
=== <body_positive_pole_clock_angle> ===
 
=== <body_positive_pole_clock_angle> ===
  
 
''OPTIONAL''
 
''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> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
This attribute provides the angle between the vertical and the direction to the sun.
  
 
=== <Reference_Frame_Identification> ===
 
=== <Reference_Frame_Identification> ===

Revision as of 15:12, 12 May 2015

The <Image_Display_Geometry> class maps the orientation of cardinal directions (North and East, typically) 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).

<Display_Direction>

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 <Display_Settings> 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 <Display_Settings>, and least in terms of attribute content. See Filling Out the Display_Dictionary Classes: Display_Direction for details.

If you are going to use the version that is included inside this <Image_Geometry_Class>, 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 Namespace Reference topic on the "Schema Referencing" page on this wiki before proceeding.

If you use the disp: prefix on your tags, for example, then they will look like this:

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

<Object_Orientation_North_East>

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.

One of either this class or <Object_Orientation_RA_Dec> must be included. You may also repeat this class (or that one) multiple times.

<north_azimuth>

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.

Note: The direction of measurement is not specified.

<east_azimuth>

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.

Note: The direction of measurement is not specified.

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

Waiting on SPICE-related class adjustments.

<body_spice_name>

OPTIONAL

<body_spice_id>

OPTIONAL

<frame_space_name>

OPTIONAL

<frame_spice_id>

OPTIONAL

<name>

OPTIONAL

<Internal_Reference>

OPTIONAL

<Local_Internal_Reference>

OPTIONAL

<pds:comment>

OPTIONAL

<pds:local_identifier_reference>

REQUIRED

<pds:local_reference_type>

REQUIRED


<Object_Orientation_RA_Dec>

OPTIONAL

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 <Object_Orientation_North_East> must be included. You may also repeat this class (or that one) multiple times.

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

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

OPTIONAL

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>

OPTIONAL

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>

REQUIRED

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


<Quaternion_SPICE_Style>

OPTIONAL

<qcos>

REQUIRED

<qsin1>

REQUIRED

<qsin2>

REQUIRED

<qsin3>

REQUIRED


<Quaternion_non_SPICE_Style>

OPTIONAL

<qsin1>

REQUIRED

<qsin2>

REQUIRED

<qsin3>

REQUIRED

<qcos>

REQUIRED


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

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

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

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>

OPTIONAL

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 the <Object_Orientation_North_East> class, described above.