Filling out the Image Display Geometry Class

From The SBN Wiki
Jump to navigation Jump to search

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, <Object_Orientation_RA_DEC>, or <Object_Orientation_Clock_Angles> is required; all 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, <Object_Orientation_North_East>, or <Object_Orientation_Clock_Angles> is required; all 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.


<Object_Orientation_Clock_Angles>

One of this class, <Object_Orientation_North_East>, or <Object_Orientation_RA_Dec> is required; all may be used.

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.



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