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

From The SBN Wiki
Jump to navigation Jump to search
(Update - Safety Save)
m ()
Line 394: Line 394:
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
| ''There seems to be a necessary assumption in this class that terms withing 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.''
+
| ''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.''
 
|}
 
|}
  

Revision as of 14:42, 19 August 2015

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

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.

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

<Body_Identification_Base>

OPTIONAL

This class provides a number of options for identifying a physical object to be subsequently referenced in this instance of the <Geometry> 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 <Central_Body_Identification> and <Target_Identification> classes.

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>

OPTIONAL

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.

It is not clear if or how this value will be validated and verified for correctness.

<name>

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

<Local_Internal_Reference>

OPTIONAL

As with <Internal_Reference>, above, the attributes withing this class come from the PDS code namespace and need to be associated with that namespace in an appropriate manner.

I can't see anything this could possibly reference. It should likely be deleted.

<Central_Body_Identification>

OPTIONAL

Except for the opening and closing tag, this class is identical to the <Body_Identification_Base> class described above.

<Target_Identification>

OPTIONAL

Except for the opening and closing tag, this class is identical to the <Body_Identification_Base> class described above.

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.

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

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 <Object_Orientation_RA_Dec> must be included.

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

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

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>

OPTIONAL

The identifier for this reference frame recognized by the SPICE toolkit.

It is not clear how this would be validated and verified.

<name>

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.

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

Does this make sense for reference frames (as opposed to coordinate systems)?

<Local_Internal_Reference>

OPTIONAL

I don't see what this could possible refer to. Probably should be deleted.

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

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

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>

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

<Quaternion_1>

OPTIONAL

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

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

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.

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

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 #.3CReference_Frame_Identification.3E in <Object_Orientation_North_East> class, described above.