Difference between revisions of "Filling Out the Image Product Information Class"

From The SBN Wiki
Jump to navigation Jump to search
(: Update for version 1.5.1.0)
(: Update for version 1.5.1.0)
 
(8 intermediate revisions by the same user not shown)
Line 342: Line 342:
 
''OPTIONAL''
 
''OPTIONAL''
  
This attribute indicates the filter passband.  It is required to be in units of frequency.
+
This attribute indicates the filter bandwidth in units of wavelength.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
Since the filter center is given in wavelength, a bandwidth in frequency is highly problematic.
+
The description notes different ways that are used to define "bandwidth", but does not indicate how the value presented should be interpreted.  Neither is there an attribute to specify how bandwidth is defined.
 
|}
 
|}
 
  
 
=== <center_filter_wavelength> ===
 
=== <center_filter_wavelength> ===
Line 354: Line 353:
 
''OPTIONAL''
 
''OPTIONAL''
  
This attribute specifies the wavelength at the center of the filter passband. You must include units of measure (wavelength units).
+
This attribute specifies the wavelength at the center of the filter. You must include units of measure (wavelength units).
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
Both this and ''bandwidth'' are optional.  This seems problematic.  If a filter is employed, should it not have at least a central wavelength specified?  Or, if this class is also used for polarization filters, should there not be an attribute to indicate the type of filter being employed, with the appropriate essential characteristics?
 +
|}
  
 
=== <comment> ===
 
=== <comment> ===
Line 367: Line 371:
 
|}
 
|}
  
=== <Bayer_Parameters> ===
+
 
 +
== <Color_Filter_Array_Parameters> ==
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
This class is used to identify images acquired using a color filter array and indicates whether and how the filter pattern was removed prior to archiving.
 +
 +
=== <color_filter_array_type> ===
 +
 +
''REQUIRED''
 +
 +
This must have the value '''Bayer RGGB'''.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This class is described as defining an encoding for the data. Encoded is not allowed in images, so it's not clear when this class could ever be used.
+
This class is required, but the definition, which starts out reasonably, then says it is optional "if there is no CFA", and goes on to make other statements that seem more appropriate to the containing class than to this attribute.
 +
 
 +
The only required value for this class makes it look like the issue of encoded images in the archive, previously identified with the Bayer algorithm-related classes now removed, has been deliberately disguised. In fact, there is an encoded state apparently coded into the Schematron file in the elaborate test for ''Color_Filter_Array_Parameters'' that seems to represent validation of an encoded format.  Encoded formats are prohibited in the archive no matter how obscurely they are identified in the metadata.
 
|}
 
|}
  
==== <bayer_state> ====
+
=== <color_filter_array_state> ===
  
'REQUIRED''
+
''REQUIRED''
  
This attribute indicates the current state of the data with respect to Bayer encoding.  It must have one of these values:
+
This attribute must have one of the following values:
  
:* '''Bayer Encoded''' - The image is currently Bayer encoded.
+
;;* '''Encoded''' - The image is encoded to a CFA pattern
:* '''Debayered''' - The image was originally Bayer encoded, but has been de-Bayered using the algorithm described, following.
+
;;* '''Decoded''' - The image has been decoded from a CFA pattern
:* '''No Bayer''' - The image was never and is not Bayer-encoded.
+
;;* '''No CFA''' - The image was never encoded
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
The first value should not be valid in an archive - encoded data is prohibited.
+
Under what circumstances would it be appropriate to have a ''Color_Filter_Array_Parameter'' class, with the required ''color_filter_array_type'' of '''Bayer RGGB''' (the only allowed value), but also have a ''color_filter_array_state'' of '''No CFA'''? Logically, the '''No CFA'' value can never be used.
 
|}
 
|}
  
==== <debayer_venue> ====
+
=== <color_filter_array_venue> ===
  
''REQUIRED'' for '''Debayered''' data
+
''OPTIONAL''
  
This attribute is required if the ''&lt;bayer_state&gt;'' attribute is '''Debayered''', but optional otherwise.  It indicates where de-Bayering was applied. It must have one of these values:
+
This attribute identifies where the filter pattern removal was performed. It must have one of the following values:
  
:* '''Ground'''
+
;;* Ground
:* '''Onboard'''
+
;;* None
 +
;;* Onboard
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This should probably be prohibited when it is not required, to avoid confusion and typos.
+
This class is required, but the definition, which starts out reasonably, then says it is optional "if there is no CFA", and goes on to make other statements that seem more appropriate to the containing class than to this attribute.
 +
 
 +
The value '''None''' is not logical in this context.  '''Neither''' might be better, but this is an optional attribute.  If no pattern removal was done, the data are still encoded and should not be in the archive - and logically this optional attribute would be omitted.  If there is somewhere other than on the ground or on the spacecraft where the pattern removal could have been done, it should be added here.
 
|}
 
|}
  
==== <debayer_algorithm> ====
+
=== <bayer_algorithm> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
If present, this attribute must have one of the following values:
+
This attribute identifies the algorithm used to remove the Bayer color filter pattern. It must have one of these values:
  
:* '''Malvar'''
+
;;* Averaged
:* '''Zhang-Wu'''
+
;;* Bilinear
 +
;;* Bue Averaged
 +
;;* Blue Bilinear
 +
;;* Green Averaged
 +
;;* Green Bilinear
 +
;;* Identity
 +
;;* Malver
 +
;;* None
 +
;;* Panchromatic
 +
;;* Raw Bayer
 +
;;* Red Averages
 +
;;* Red Bilinear
 +
;;* Zhang-Wu
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
'''None''' is not an appropriate value for an optional attribute.
 +
|}
  
 
== <Sampling_Parameters> ==
 
== <Sampling_Parameters> ==
Line 428: Line 463:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
Note that the name of this attribute and its definition seem to imply different processes.  It is not clear which applies.
+
Note that the name of this attribute (summing) and its definition (count of values averaged) seem to imply different processes.  It is not clear which applies.
 
|}
 
|}
  
Line 446: Line 481:
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
This attribute defines the (minimal) number of bits needed to represent the data values in the file.  This may be less than the number of bits allocated by the data type (12-bit data would be stored in 2-byte - 16-bit - integers).  The data are zero-extended to fill any high-order bits beyond ''sample_bits''.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
The definition given for this attribute is from a PDS3 context and is nonsensical in this one.
+
Logically, the definition provided here implies that when this attribute is present, the data object ''must'' have integer pixels, with number of bits greater than or equal to ''sample_bits'', and no values less than zero (and any scaling factor or offset effects are also not noted).  This is not validated.
 
|}
 
|}
  
Line 458: Line 495:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
The definition given for this attribute is from a PDS3 context and is nonsensical in this one.
+
The definition given for this attribute is somewhat mystifying.  It talks about various integer types but never mentions byte ordering; it seems to imply that ''sample_bit_mask'' is independent of ''sample_bits'', but then negates that in the last sentence; that last sentence begins, "NOTE: In the PDS...", but this is an exclusively PDS-context - which implies the entire preceding definition is not relevant.
 
|}
 
|}
  
Line 465: Line 502:
 
''OPTIONAL''
 
''OPTIONAL''
  
 +
This attribute indicates a sampling interval, in both the line and scan direction, used to derive the current data object.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
The definition given for this attribute is incomplete and unclear.
+
This attribute has a string data type. Does it make any sense for it to have any value other than an integer > 1?  Given the definition, shouldn't there be some indication which of the several methods mentioned were used in deriving the present data object?
 
|}
 
|}
  
Line 508: Line 546:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This attribute is poorly defined and not currently usable.
+
This attribute is defined as having values that are "mission-specific".  What mechanism is planned to ensure that there are values properly defined in a missions dictionary before this attribute can be used?  If no values are ever defined, is there any point in having the containing class in the label?
 +
 
 +
The definition goes on to give a list of "recommended values", but none of these is defined as permissible values.
 
|}
 
|}
  
Line 540: Line 580:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
In the context of this class, where only one set of parameters can be specified, the value ''Both'' appears to be nonsensical.
+
This attribute is both optional and nillable. This is not in keeping with PDS core/discipline dictionary best practices.  Under what circumstances would it be appropriate to have this optional attribute present but set to nil?
 
|}
 
|}
  
Line 549: Line 589:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This attribute is poorly defined and not usable.
+
This attribute requires that the mission dictionary supply permissible values in order to validate. This is problematic without some mechanism to ensure that values are both provided and well-defined in the mission dictionary.
 
|}
 
|}
  
Line 557: Line 597:
  
 
This class provides the height and width dimensions used in averaging pixels in the original data to produce the associated, downsampled version.
 
This class provides the height and width dimensions used in averaging pixels in the original data to produce the associated, downsampled version.
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
The class definition refers to "compression" rather than "downsampling".  This is inappropriate in an archive where compression is not permitted.
 +
|}
  
 
==== <height_pixels> ====
 
==== <height_pixels> ====
Line 566: Line 611:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
"Vertical" is not defined in this context and any unit of measure other than "pixel" doesn't make sense, does it?
+
"Vertical" is not defined in this context, and the value is a count, not a measurement - so a unit of measurement is not appropriate.
 
|}
 
|}
  
Line 574: Line 619:
 
''REQUIRED''
 
''REQUIRED''
  
The number of pixels in the horizontaldirection that were averaged.  You must specify a unit of measure.
+
The number of pixels in the horizontal direction that were averaged.  You must specify a unit of measure.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
"Horizontal" is not defined in this context and any unit of measure other than "pixel" doesn't make sense, does it?
+
"Horizontal" is not defined in this context, and the value is a count, not a measurement - so a unit of measurement is not appropriate.
 
|}
 
|}
  
Line 593: Line 638:
 
''OPTIONAL''
 
''OPTIONAL''
  
Values: Mono, Stereo
+
{| class="wikitable" style="background-color: yellow"
 
 
{| class="wikitable" style="background-color: lavenderblush"
 
 
|
 
|
Why is this field repeatable?
+
No permissible values are defined for this field.
 
|}
 
|}
  
Line 604: Line 647:
 
''OPTIONAL''
 
''OPTIONAL''
  
 +
The time between successive frames of an image. You must provide a unit of time.
  
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
"Delay" seems like an odd way to indicate "interval", rather than, say, downtime between frame acquisition periods.  If it does not matter whether this is measure from start-to-start or midpoint-to-midpoint, then that should probably be said.  If it does matter, that should definitely be said.
  
 +
The definition implies that this may only be specified in seconds, but that is not enforced.
 +
|}
  
 
== <Subframe_Parameters> ==
 
== <Subframe_Parameters> ==
Line 611: Line 660:
 
''OPTIONAL''
 
''OPTIONAL''
  
{| class="wikitable" style="background-color: lavenderblush"
+
{| class="wikitable" style="background-color: yellow"
 
|
 
|
What does it mean to repeat this classHow would you, e.g., map a specific set of parameters to a particular frame (or would you)?
+
The definition doesn't make sense in the context of metadata for an archival data product.  What would be the "original image"Is there an assumption that a product contains multiple data objects, and this describes the relationship between two of them? etc.
 
 
It's a little odd that the required fields occur at the bottom of the class, after all the optional attributes.
 
 
|}
 
|}
  
Line 621: Line 668:
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
The definition does not indicate whether the first "line" is numbered zero or one. Neither does it indicate how the "first" line is identified - is it storage order, or the origin of a particular display orientation?
 +
|}
  
 
=== <first_sample> ===
 
=== <first_sample> ===
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
The definition does not indicate whether the first "sample" is numbered zero or one.  Neither does it indicate how the "first" sample is identified - is it storage order, or the origin of a particular display orientation?
 +
|}
  
 
=== <lines> ===
 
=== <lines> ===
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
The reference to "data instances" is very odd and potentially confusing.  Where the word "lines" would have been easily understood, there is now a question whether this number represents whole line, or perhaps a count of individual pixels starting at the (first_line,first_sample) location - since the same odd terminology is also used to describe the ''samples'' attribute.
 +
 +
"Vertical" is not defined in this context.
 +
 +
There is no validation that the value of ''lines'' does not exceed the dimension of the source image, in the event that that image is actually part of the same data product.
 +
|}
  
 
=== <samples> ===
 
=== <samples> ===
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
"Horizontal" is not defined in this context.
 +
 +
There is no validation that the value of ''lines'' does not exceed the dimension of the source image, in the event that that image is actually part of the same data product.
 +
|}
  
 
=== <name> ===
 
=== <name> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
This attribute is mysterious.  There is no indication of what is being named, and the pds:name definition refers to an "Agency" that is being named.
 +
|}
  
 
=== <description> ===
 
=== <description> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
This attribute is unexplained.  What would need describing at this point?
 +
|}
 +
  
 
=== <subframe_type> ===
 
=== <subframe_type> ===
Line 648: Line 732:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This attribute has a null rule defined and no standard values.
+
This is another attribute that requires the mission dictionary to provide values, but also provide a list of "recommendations" that are not coded as permissible values.  As in the other cases, no enforcement method is mentioned.
 +
|}
 +
 
 +
 
 +
 
 +
== <Color_Parameters> ==
 +
 
 +
''OPTIONAL''
 +
 
 +
=== <color_space> ===
 +
 
 +
''OPTIONAL''
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
The definition implies this should have a list of permissible values, but none are defined.
 +
|}
 +
 
 +
=== <color_component> ===
 +
 
 +
''OPTIONAL''
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
This attribute definition implies it should be forbidden in 3D color image objects, but this is not validated.
 +
|}
 +
 
 +
=== <illuminant> ===
 +
 
 +
''OPTIONAL''
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
The definition implies there should be a permissible value list, but there is none.
 +
|}
 +
 
 +
=== <encoded_display_gamma> ===
 +
 
 +
''OPTIONAL''
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
This attribute definition tells a user to apply the attribute differently depending on its formatting.  This is not good practice and makes program development dependent on intimate, human-readable knowledge available only in the natural language definition.  Two separate attributes should have been defined - one for the numberic, and one for the string value.
 +
|}
 +
 
 +
=== <Onboard_Responsivity> ===
 +
 
 +
''OPTIONAL''
 +
 
 +
==== <responsivity_r> ====
 +
 
 +
''REQUIRED''
 +
 
 +
==== <responsivity_g> ====
 +
 
 +
''REQUIRED''
 +
 
 +
==== <responsivity_b> ====
 +
 
 +
''REQUIRED''
 +
 
 +
=== <Onboard_Color_Matrix> ===
 +
 
 +
''OPTIONAL''
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
The definition of this class reads more like instructions for using it rather than a description of the origin/significance of the metadata. The last sentence says, "If the label is not present, ..." which is not an allowed circumstance in the archive and makes no sense.
 
|}
 
|}
 +
 +
==== <onboard_R_r> ====
 +
 +
''REQUIRED''
 +
 +
 +
==== <onboard_R_g> ====
 +
 +
''REQUIRED''
 +
 +
 +
==== <onboard_R_b> ====
 +
 +
''REQUIRED''
 +
 +
 +
==== <onboard_G_r> ====
 +
 +
''REQUIRED''
 +
 +
 +
==== <onboard_G_g> ====
 +
 +
''REQUIRED''
 +
 +
 +
==== <onboard_G_b> ====
 +
 +
''REQUIRED''
 +
 +
 +
==== <onboard_B_r> ====
 +
 +
''REQUIRED''
 +
 +
 +
==== <onboard_B_g> ====
 +
 +
''REQUIRED''
 +
 +
 +
==== <onboard_B_b> ====
 +
 +
''REQUIRED''

Latest revision as of 21:38, 4 March 2019

The Image_Product_Information class contains parameters describing the collection of the data, including exposure, filter, sampling, correction, and framing parameters.

Contents

<Autoexposure_Parameters>

OPTIONAL

This class is used to identify the histogram thresholding algorithm that was applied to the data, with the input parameters. Parameters can be provided explicitly here, via the Algorithm_Parameter subclass, or by referencing them in the data file via the pds:Local_Internal_Reference class.

<autoexposure_algorithm_name>

REQUIRED

The name or ID used by the pipeline processing or documentation for the specific algorithm applied. This is typically mission-defined, and should be validated by a Schematron statement in the associated mission or project dictionary.

<Algorithm_Parameter>

OPTIONAL

This class is used to name and provide a value for one of the parameters input to the previously named thresholding algorithm. It may be repeated as needed.

<name>

REQUIRED

A string containing a variable name. This string may contain blanks and UTF-8 non-ASCII characters.

<value>

REQUIRED

A string containing the value of the preceding named variable. This string must contain only ASCII characters, but it may contain embedded blanks.

This attribute may be repeated as needed. If the variable named in the associated <name> takes a vector as input, for example, then use one <value> attribute to hold each of the vector components.

<Exposure_Parameters>

OPTIONAL

Use this class to define configuration and parameters of the image exposure.

Note: In the Image_Product_Information class, these parameters are of the exposure the produced the data. When this class is used in the Command_Parameters class, it indicates the parameters that were commanded to the spacecraft, which may not be the same.

<exposure_count>

OPTIONAL

This attribute is defined as "the number of exposures taken during a certain interval", but there is no way to specify what interval, or what the relationship is between exposure_count and exposure_duration.

<exposure_duration>

REQUIRED

This is the total time for which light was gathered to produce the data object. You must specify units of time for this value.

This is defined as "the amount of time the instrument sensor was gathering light", but does not define the relationship between this and exposure_count.

You must specify a unit of time for this attribute.

If this class appears in the <Command_Parameters> class, exposure_duration is optional.

<exposure_duration_count>

OPTIONAL

This attribute represents the <exposure_duration> in units of data number (DN) rather than time.

This attribute is allowed to be zero, but it's not clear what a zero value here would mean.

<exposure_type>

OPTIONAL

This attribute must contain one of the following values:

* Manual
* Auto
* Test

What these values mean is not quite clear.

<Data_Correction_Parameters>

OPTIONAL

This class describes the processing applied to the data to remove instrumental artifacts. This processing might have been applied onboard the spacecraft prior to transmission, or after the data were received on the ground.

In the Image_Product_Information class, these attributes reflect processing that is known to have been applied. In the Command_Parameters class, these attributes indicate the processing that was commanded, whether or not it was ultimately carried out.

<Data_Correction>

OPTIONAL

This class provides details about the processing performed. It may be repeated as needed.

It also includes flag fields to indicate whether specific processing has been performed.

<active_flag>

REQUIRED

This attribute must have a value of true or false. True indicates that the associated correction(s) are "active".

What "active" means is not defined.

<data_correction_type>

REQUIRED

This attribute defines the specific type of correction described by the containing <Data_Correction> class. It must have one of the following values:

  • Antiblooming
  • Bad Pixel
  • Blemish Protection
  • Brightness
  • Dark Current
  • Flat Field
  • Inverse LUT
  • Light Flood
  • Radiometric
  • Responsivity
  • Shutter Subtraction

<data_correction_venue>

OPTIONAL

This attribute indicates where the associated correction(s) where applied. It must have one of two values:

  • Ground: Data correction applied by software on the ground
  • Onboard: Data correction applied onboard the spacecraft

<Data_Correction_File>

OPTIONAL

This class is used to link to a detailed description of the specific processing applied. A <pds:External_Reference> is used for citing publications in the literature; a <pds:Internal_Reference> is used to cite a product available from the PDS archives. Exactly one of those two classes must be included.

<description>

OPTIONAL

Use this attribute to describe the general content of the reference cited, following.

<pds:External_Reference>

OPTIONAL

This class is in the core "pds:" namespace, and follows the same format as the class of the same name on the Filling Out the Reference List Classes page on this wiki. Note that you may have to specify the "pds:" namespace prefix for each element of this class (depending on label design).

<pds:Internal_Reference>

OPTIONAL

This class is in the core "pds:" namespace, and follow the same format as the class of the same name on the Filling Out the Reference List Classes page on this wiki. Note that you may have to specify the "pds:" namespace prefix for each element of this class (depending on label design).

You must specify a value of data_to_data_correction_file for the <pds:reference_type> attribute in this class.

<Flat_Field_Correction_Parameters>

OPTIONAL

This class is used to provide parameters for onboard flat-fielding correction.

It's not clear why this is constrained to onboard flat-fielding, nor is any validation done to ensure that the data_correction_venue flag is set to 'Onboard' when this class is present.

<flat_field_algorithm>

REQUIRED

Use this attribute to provide a name or identifier for the algorithm used to perform flat-fielding. This attribute may be repeated.

Standard values and sample values are not provided. It is not clear what it means to repeat this attribute, or how the Correction_Parameter classes are mapped to the algorithms when there is more than one.


<Correction_Parameter>

REQUIRED

This class provides parameter identification and value for a single correction parameter.

<sequence_number> or <name> or <id>
REQUIRED
One of these is required; all may be supplied or any one of them can be repeated for a total of up to three occurrences. Note that name may contain UTF-8 characters, but sequence_number and id' are constrained to ASCII only. Apart from that different, all three are defined as strings of less than 256 character that are otherwise unconstrained.

It is not clear what it means to repeat any single one of these attributes twice or three times.

<value_number> or <value_string>
REQUIRED
Exactly one of these must be present. Both are defined as ASCII_Real data, however.

Both attribute have the same ASCII_Real data type without further constraint.

<Radiometric_Correction_Parameters>

OPTIONAL

This class claims to be "a container for the type and details of the radiometric calibration performed", but it contains only one type attribute and no details or actual parameters of any kind.

<radiometric_correction_type_name>

REQUIRED

This attribute is supposed to indicate the method used for the radiometric correction. There are no permissible values defined, nor any examples provided.

There are no permissible values defined, nor any examples provided. Oddly, the definition of <radiance_scaling_factor> does seem to define values for this attribute, but then that definition goes on to discuss units of the data object, which is not appropriate, and references Mars data specifically, which calls into question the applicability of the attribute/class to image data generally.

<radiance_scaling_factor>

OPTIONAL

Either both radiance_scaling_factor and radiance_offset must be included, or neither may be.

The bulk of this definition does not appear to be concerned with scaling factor. Further, even though a unit of measure is required on the value, the definition of the attribute seems to refute the applicability of whatever that unit might be, based on specific types of radiance correction that are not enumerated in the expected field.

There is no indication whether or when it is valid to have neither of these attributes present, and what that might imply for the data.

<radiance_offset>

OPTIONAL

Either both radiance_scaling_factor and radiance_offset must be included, or neither may be.

All the issues with the <radiance_scaling_factor> field are reproduced in the definition of this field.


<Shutter_Subtraction_Parameters>

OPTIONAL

The class definition is unintelligible to me. The only "sentence" ends with an adjective.

<shutter_subtraction_mode>

REQUIRED

This attribute must have one of two values:

  • Conditional
  • True

The meanings are unclear. Traditionally, the opposite of "True" is "False"...

There is a Schematron check that appears to be attempting to require that if shutter_subtraction_mode is "True" (specifically, not Conditional), then the Shutter_Subtraction_Parameters class must also contain an exposure_duration_threshold_count. But that attribute is schematically required to be present in all cases, so the test is pointless.

<exposure_duration_threshold_count>

REQUIRED

The meaning of this attribute is not clear. It seems to be implying it should only be present when the preceding shutter_subtraction_mode attribute has a value of Conditional, but it is schematically required to be present all the time.

Further, it is defined as "raw counts", which are typically integral, but has a data type of ASCII_Real. It is also allowed to be both negative and zero, which seems nonsensical.

<Filter>

OPTIONAL

Use this class to identify and define the attributes of the filter associated with the image data being described.

This class may be repeated. Does it make sense for this class to be repeatable? Under what circumstances would an image product need to reference several filters?


<filter_name>

OPTIONAL

This attribute contains the filter name.

The definition refers to the name being defined in "mission documentation", but there is no mission documentation for non-mission data, and many ground-based observers used filters with standard names (or IDs). This seems to be prohibited.

<filter_id>

OPTIONAL

This attribute contains a short identifier for the filter - 16 character limit.

<filter_number>

OPTIONAL

This attribute contains a number associated with the filter in the context of the mission or data collection program.

<bandwidth>

OPTIONAL

This attribute indicates the filter bandwidth in units of wavelength.

The description notes different ways that are used to define "bandwidth", but does not indicate how the value presented should be interpreted. Neither is there an attribute to specify how bandwidth is defined.

<center_filter_wavelength>

OPTIONAL

This attribute specifies the wavelength at the center of the filter. You must include units of measure (wavelength units).

Both this and bandwidth are optional. This seems problematic. If a filter is employed, should it not have at least a central wavelength specified? Or, if this class is also used for polarization filters, should there not be an attribute to indicate the type of filter being employed, with the appropriate essential characteristics?

<comment>

OPTIONAL

If there are any additional notes about the exposure you would like to leave for users, this is the place to do it.

Because this is based on the pds:comment type, it is restricted to ASCII characters. That could be a problem for a comment field in a class that deals with measurements that are frequently given in units that are expressed using non-ASCII characters.


<Color_Filter_Array_Parameters>

OPTIONAL

This class is used to identify images acquired using a color filter array and indicates whether and how the filter pattern was removed prior to archiving.

<color_filter_array_type>

REQUIRED

This must have the value Bayer RGGB.

This class is required, but the definition, which starts out reasonably, then says it is optional "if there is no CFA", and goes on to make other statements that seem more appropriate to the containing class than to this attribute.

The only required value for this class makes it look like the issue of encoded images in the archive, previously identified with the Bayer algorithm-related classes now removed, has been deliberately disguised. In fact, there is an encoded state apparently coded into the Schematron file in the elaborate test for Color_Filter_Array_Parameters that seems to represent validation of an encoded format. Encoded formats are prohibited in the archive no matter how obscurely they are identified in the metadata.

<color_filter_array_state>

REQUIRED

This attribute must have one of the following values:

  • Encoded - The image is encoded to a CFA pattern
  • Decoded - The image has been decoded from a CFA pattern
  • No CFA - The image was never encoded

Under what circumstances would it be appropriate to have a Color_Filter_Array_Parameter class, with the required color_filter_array_type of Bayer RGGB' (the only allowed value), but also have a color_filter_array_state of No CFA? Logically, the No CFA value can never be used.

<color_filter_array_venue>

OPTIONAL

This attribute identifies where the filter pattern removal was performed. It must have one of the following values:

  • Ground
  • None
  • Onboard

This class is required, but the definition, which starts out reasonably, then says it is optional "if there is no CFA", and goes on to make other statements that seem more appropriate to the containing class than to this attribute.

The value None is not logical in this context. Neither might be better, but this is an optional attribute. If no pattern removal was done, the data are still encoded and should not be in the archive - and logically this optional attribute would be omitted. If there is somewhere other than on the ground or on the spacecraft where the pattern removal could have been done, it should be added here.

<bayer_algorithm>

OPTIONAL

This attribute identifies the algorithm used to remove the Bayer color filter pattern. It must have one of these values:

  • Averaged
  • Bilinear
  • Bue Averaged
  • Blue Bilinear
  • Green Averaged
  • Green Bilinear
  • Identity
  • Malver
  • None
  • Panchromatic
  • Raw Bayer
  • Red Averages
  • Red Bilinear
  • Zhang-Wu

None is not an appropriate value for an optional attribute.

<Sampling_Parameters>

OPTIONAL

This class contains attributes documenting processing done to compress of reduce the resolution of the data.

<crosstrack_summing>

OPTIONAL

This attribute gives the number of detector pixel values, in the crosstrack direction, that were averaged to produce the actual pixel value in the data file.

Note that the name of this attribute (summing) and its definition (count of values averaged) seem to imply different processes. It is not clear which applies.

<downtrack_summing>

OPTIONAL

This attribute gives the number of detector pixel values, in the downtrack direction, that were averaged to produce the actual pixel value in the data file.

Note that the name of this attribute and its definition seem to imply different processes. It is not clear which applies.


<sample_bits>

OPTIONAL

This attribute defines the (minimal) number of bits needed to represent the data values in the file. This may be less than the number of bits allocated by the data type (12-bit data would be stored in 2-byte - 16-bit - integers). The data are zero-extended to fill any high-order bits beyond sample_bits.

Logically, the definition provided here implies that when this attribute is present, the data object must have integer pixels, with number of bits greater than or equal to sample_bits, and no values less than zero (and any scaling factor or offset effects are also not noted). This is not validated.

<sample_bit_mask>

OPTIONAL

The definition given for this attribute is somewhat mystifying. It talks about various integer types but never mentions byte ordering; it seems to imply that sample_bit_mask is independent of sample_bits, but then negates that in the last sentence; that last sentence begins, "NOTE: In the PDS...", but this is an exclusively PDS-context - which implies the entire preceding definition is not relevant.

<sampling_factor>

OPTIONAL

This attribute indicates a sampling interval, in both the line and scan direction, used to derive the current data object.

This attribute has a string data type. Does it make any sense for it to have any value other than an integer > 1? Given the definition, shouldn't there be some indication which of the several methods mentioned were used in deriving the present data object?

<Companding_Parameters>

OPTIONAL

This class is used when the data have been companded or expanded (from a companded version) to reduce/expand bit depth to the current level.

<companding_state>

REQUIRED

The value here must be one of the following:

  • Companded: The present data are companded.
  • Expanded: The present data have been expanded from a previously companded version.
  • None: The data are not and have not been companded previously.

<companding_venue>

REQUIRED

This attribute indicates how the companding/expanding was achieved. It must have one of the following values:

  • Hardware: The processing was performed in hardware.
  • Software: The processing was performed by software.
  • None: No processing was performed.

Note: The value None only makes sense here if the preceding attribute also had the value None, but there is no validation to check this. Type carefully.

<companding_method>

REQUIRED

This attribute is defined as having values that are "mission-specific". What mechanism is planned to ensure that there are values properly defined in a missions dictionary before this attribute can be used? If no values are ever defined, is there any point in having the containing class in the label?

The definition goes on to give a list of "recommended values", but none of these is defined as permissible values.

<Downsampling_Parameters>

OPTIONAL

This class provides the parameters used in creating the present downsampled image from the source.

<downsampling_flag>

OPTIONAL

A value of true here indicates the associated data object is downsampled. Otherwise, if present this would be false.

Seems like the mere presence of the class implies that this better have a value of true, but then why would the rest of the attributes ever be optional?

<downsampling_venue>

OPTIONAL

This attribute indicates how the downsampling process was executed. It must be one of the following values:

  • Hardware: Downsampling was performed by hardware.
  • Software: Downsampling was performed programmatically.
  • Both

This attribute is both optional and nillable. This is not in keeping with PDS core/discipline dictionary best practices. Under what circumstances would it be appropriate to have this optional attribute present but set to nil?

<downsampling_method>

OPTIONAL

This attribute requires that the mission dictionary supply permissible values in order to validate. This is problematic without some mechanism to ensure that values are both provided and well-defined in the mission dictionary.

<Pixel_Averaging_Dimensions>

OPTIONAL

This class provides the height and width dimensions used in averaging pixels in the original data to produce the associated, downsampled version.

The class definition refers to "compression" rather than "downsampling". This is inappropriate in an archive where compression is not permitted.

<height_pixels>

REQUIRED

The number of pixels in the vertical direction that were averaged. You must specify a unit of measure.

"Vertical" is not defined in this context, and the value is a count, not a measurement - so a unit of measurement is not appropriate.


<width_pixels>

REQUIRED

The number of pixels in the horizontal direction that were averaged. You must specify a unit of measure.

"Horizontal" is not defined in this context, and the value is a count, not a measurement - so a unit of measurement is not appropriate.

<Frame_Parameters>

OPTIONAL

<frame_id>

OPTIONAL

<frame_type_name>

OPTIONAL

No permissible values are defined for this field.

<interframe_delay>

OPTIONAL

The time between successive frames of an image. You must provide a unit of time.

"Delay" seems like an odd way to indicate "interval", rather than, say, downtime between frame acquisition periods. If it does not matter whether this is measure from start-to-start or midpoint-to-midpoint, then that should probably be said. If it does matter, that should definitely be said.

The definition implies that this may only be specified in seconds, but that is not enforced.

<Subframe_Parameters>

OPTIONAL

The definition doesn't make sense in the context of metadata for an archival data product. What would be the "original image"? Is there an assumption that a product contains multiple data objects, and this describes the relationship between two of them? etc.

<first_line>

REQUIRED

The definition does not indicate whether the first "line" is numbered zero or one. Neither does it indicate how the "first" line is identified - is it storage order, or the origin of a particular display orientation?

<first_sample>

REQUIRED

The definition does not indicate whether the first "sample" is numbered zero or one. Neither does it indicate how the "first" sample is identified - is it storage order, or the origin of a particular display orientation?

<lines>

REQUIRED

The reference to "data instances" is very odd and potentially confusing. Where the word "lines" would have been easily understood, there is now a question whether this number represents whole line, or perhaps a count of individual pixels starting at the (first_line,first_sample) location - since the same odd terminology is also used to describe the samples attribute.

"Vertical" is not defined in this context.

There is no validation that the value of lines does not exceed the dimension of the source image, in the event that that image is actually part of the same data product.

<samples>

REQUIRED

"Horizontal" is not defined in this context.

There is no validation that the value of lines does not exceed the dimension of the source image, in the event that that image is actually part of the same data product.

<name>

OPTIONAL

This attribute is mysterious. There is no indication of what is being named, and the pds:name definition refers to an "Agency" that is being named.

<description>

OPTIONAL

This attribute is unexplained. What would need describing at this point?


<subframe_type>

OPTIONAL

This is another attribute that requires the mission dictionary to provide values, but also provide a list of "recommendations" that are not coded as permissible values. As in the other cases, no enforcement method is mentioned.


<Color_Parameters>

OPTIONAL

<color_space>

OPTIONAL

The definition implies this should have a list of permissible values, but none are defined.

<color_component>

OPTIONAL

This attribute definition implies it should be forbidden in 3D color image objects, but this is not validated.

<illuminant>

OPTIONAL

The definition implies there should be a permissible value list, but there is none.

<encoded_display_gamma>

OPTIONAL

This attribute definition tells a user to apply the attribute differently depending on its formatting. This is not good practice and makes program development dependent on intimate, human-readable knowledge available only in the natural language definition. Two separate attributes should have been defined - one for the numberic, and one for the string value.

<Onboard_Responsivity>

OPTIONAL

<responsivity_r>

REQUIRED

<responsivity_g>

REQUIRED

<responsivity_b>

REQUIRED

<Onboard_Color_Matrix>

OPTIONAL

The definition of this class reads more like instructions for using it rather than a description of the origin/significance of the metadata. The last sentence says, "If the label is not present, ..." which is not an allowed circumstance in the archive and makes no sense.

<onboard_R_r>

REQUIRED


<onboard_R_g>

REQUIRED


<onboard_R_b>

REQUIRED


<onboard_G_r>

REQUIRED


<onboard_G_g>

REQUIRED


<onboard_G_b>

REQUIRED


<onboard_B_r>

REQUIRED


<onboard_B_g>

REQUIRED


<onboard_B_b>

REQUIRED