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

From The SBN Wiki
Jump to navigation Jump to search
(Safety Save)
(: Update for version 1.5.1.0)
 
(27 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
The ''Image_Product_Information'' class contains parameters describing the collection of the data, including exposure, filter, sampling, correction, and framing parameters.
 
The ''Image_Product_Information'' class contains parameters describing the collection of the data, including exposure, filter, sampling, correction, and framing parameters.
 +
 +
== <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 ''&lt;name&gt;'' takes a vector as input, for example, then use one ''&lt;value&gt;'' attribute to hold each of the vector components.
  
 
== <Exposure_Parameters> ==
 
== <Exposure_Parameters> ==
Line 5: Line 37:
 
''OPTIONAL''
 
''OPTIONAL''
  
Use this class to define the exposure duration, count, and type.
+
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> ===
 
=== <exposure_count> ===
Line 13: Line 47:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This attribute is defined as "the maximum number of exposures taken during a specified interval", but there is no way to specify an interval and what is needed is the actual number of exposures, not a potential maximum.  Also, this number is allowed to be zero, which is not logical.
+
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> ===
 
=== <exposure_duration> ===
  
''OPTIONAL''
+
''REQUIRED''
  
This is the total amount of time during which data were taken (i.e., the total time for all exposures contributing to the image object).  You must specify units of time for this attribute.
+
This is the total time for which light was gathered to produce the data object.  You must specify units of time for this value.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
It seems odd that this attribute is optional.  The following attribute seems to negate the units and definition of this attribute.
+
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 ''&lt;Command_Parameters&gt;'' class, ''exposure_duration'' is optional.
  
 
=== <exposure_duration_count> ===
 
=== <exposure_duration_count> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
This attribute represents the ''&lt;exposure_duration&gt;'' in units of data number (DN) rather than time.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This is described as "the value, in raw counts, of the amount of time the instrument sensor was gathering light... .  This is a raw value either commanded or taken directly from telemetry, as opposed to the exposure_duration attributes, which has been converted to engineering units."  This is not consistent with the definition for that field, which is defined as being in units of time. It is not clear what "counts" is equivalent to or how it might be calculated.
+
This attribute is allowed to be zero, but it's not clear what a zero value here would mean.
 
|}
 
|}
  
Line 40: Line 80:
 
''OPTIONAL''
 
''OPTIONAL''
  
This attribute indicates the exposure setting on a camera.
+
This attribute must contain one of the following values:
 +
 
 +
: * '''Manual'''
 +
: * '''Auto'''
 +
: * '''Test'''
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This attribute has a 15-character limit but no defined standard values.
+
What these values mean is not quite clear.
 
|}
 
|}
  
 +
== <Data_Correction_Parameters> ==
  
== <Filter> ==
+
''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''
 
''OPTIONAL''
  
Use this class to define the attributes of each filter associated with the image data being described.
+
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".
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
Does it make sense for this class to be repeatable?  Under what circumstances would an image product need to reference several filters?
+
What "active" means is not defined.
 
|}
 
|}
  
=== <bayer_mode> ===
+
==== <data_correction_type> ====
 +
 
 +
''REQUIRED''
 +
 
 +
This attribute defines the specific type of correction described by the containing ''&lt;Data_Correction&gt;'' 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 ''&lt;pds:External_Reference&gt;'' is used for citing publications in the literature; a ''&lt;pds:Internal_Reference&gt;'' is used to cite a product available from the PDS archives. Exactly one of those two classes ''must'' be included.
 +
 
 +
===== <description> =====
  
 
''OPTIONAL''
 
''OPTIONAL''
  
This attribute either specifies that the data are encoded in a Bayer pattern, or how that pattern was removed.  It must have one of the following values:
+
Use this attribute to describe the general content of the reference cited, following.
* '''MIPL Malvar'''
+
 
* '''No Bayer'''
+
===== <pds:External_Reference> =====
* '''Onboard Color'''
+
 
* '''Raw Bayer'''
+
''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#.3CExternal_Reference.3E|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#.3CInternal_Reference.3E|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 ''&lt;pds:reference_type&gt;'' attribute in this class.
 +
 
 +
==== <Flat_Field_Correction_Parameters> ====
 +
 
 +
''OPTIONAL''
 +
 
 +
This class is used to provide parameters for onboard flat-fielding correction.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
The way the definition of this attribute is written, it should never be optional.  That seems wrong for image data in general.  The values also seem oddly inconsistent with the field definition.
+
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.
 
|}
 
|}
  
=== <filter_name> ===
+
===== <flat_field_algorithm> =====
  
''OPTIONAL''
+
''REQUIRED''
  
This attribute contains the filter name.
+
Use this attribute to provide a name or identifier for the algorithm used to perform flat-fielding. This attribute may be repeated.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
The definition says "commonly-used", but what constitutes "commonly"?  There are many standardized filters (and filter names) in ground-based
+
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.
observing, but there is no standard value list for this fieldAre spacecraft filter names similarly standardized?  If so, there should be a value list for thoseIf not, then "commonly-used" is not a reasonable definition for an archive - there should be some reason to include a colloquial name (like "This is the name used in the mission documentation", e.g.).
+
|}
 +
 
 +
 
 +
====== <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 onlyApart from that different, all three are defined as strings of less than 256 character that are otherwise unconstrained.
 +
 
 +
:{| class="wikitable" style="background-color: yellow"
 +
|
 +
It is not clear what it means to repeat any single one of these attributes twice or three times.
 
|}
 
|}
  
=== <filter_id> ===
+
: '''<value_number>''' ''or'' '''<value_string>'''
 +
 
 +
: ''REQUIRED''
 +
 
 +
: Exactly one of these must be present.  Both are defined as ASCII_Real data, however.
 +
 
 +
: {| class="wikitable" style="background-color: yellow"
 +
|
 +
Both attribute have the same ''ASCII_Real'' data type without further constraint.
 +
|}
 +
 
 +
==== <Radiometric_Correction_Parameters> ====
  
 
''OPTIONAL''
 
''OPTIONAL''
  
This attribute contains an abbreviated identifier for the ''&lt;filter_name&gt;'', if provided.
+
{| class="wikitable" style="background-color: yellow"
 +
|
 +
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.
 +
|}
  
=== <filter_number> ===
+
===== <radiometric_correction_type_name> =====
  
''OPTIONAL''
+
''REQUIRED''
  
This attribute contains a number associated with the filter in the context of the mission or data collection program.
+
This attribute is supposed to indicate the method used for the radiometric correction. There are no permissible values defined, nor any examples provided.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
The definition of this class includes a reference to "the bin class of a spectral data object", which is inappropriate in the context of the Imaging dictionary.
+
There are no permissible values defined, nor any examples provided.  Oddly, the definition of ''&lt;radiance_scaling_factor&gt;'' 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.
 
|}
 
|}
  
=== <bandwidth> ===
+
===== <radiance_scaling_factor> =====
  
 
''OPTIONAL''
 
''OPTIONAL''
  
This attribute indicates the filter passband.
+
Either both ''radiance_scaling_factor'' and ''radiance_offset'' must be included, or neither may be.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This attribute has several problems:
+
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.
* It is both nillable and optional, which is contrary to core dictionary conventions.
+
 
* It has no associated units of measure
+
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.
* It references "channels", which are not otherwise mentioned in this dictionary
 
 
|}
 
|}
  
=== <center_filter_wavelength> ===
+
===== <radiance_offset> =====
  
 
''OPTIONAL''
 
''OPTIONAL''
  
This attribute specifies the wavelength at the center of the filter passband.
+
Either both ''radiance_scaling_factor'' and ''radiance_offset'' must be included, or neither may be.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This attribute has several problems:
+
All the issues with the ''&lt;radiance_scaling_factor&gt;'' field are reproduced in the definition of this field.
* It is both nillable and optional, which is contrary to core dictionary conventions.
 
* It has no associated units of measure
 
* It references itself to "minimum and maximum instrument filter wavelength values", which are never provided.
 
* It is not clear how this value corresponds to the generalized &lt;bandwidth&gt;, preceding.
 
 
|}
 
|}
  
=== <full_width_half_maximum> ===
+
 
 +
==== <Shutter_Subtraction_Parameters> ====
  
 
''OPTIONAL''
 
''OPTIONAL''
Line 138: Line 273:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
The definition of this field is a mathematical one rather than one appropriate to the context of the class.  FWHM is also one method of specifying bandwidth, so it's not clear how this is different from ''&lt;bandwidth&gt;'', preceding. It also has units of length, but the units should depend on the units of the function it is describing, which may or may not be in units of length.
+
The class definition is unintelligible to me. The only "sentence" ends with an adjective.
 
|}
 
|}
  
=== <comment> ===
+
===== <shutter_subtraction_mode> =====
 +
 
 +
''REQUIRED''
  
''OPTIONAL''
+
This attribute must have one of two values:
  
If there are any additional notes about the exposure you would like to leave for users, this is the place to do it.
+
:* '''Conditional'''
 +
:* '''True'''
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
Because this is based on the pds:comment type, it is restricted to ASCII charactersThat 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.
+
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> =====
  
== <Data_Correction_Parameters> ==
+
''REQUIRED''
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
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''
 
''OPTIONAL''
  
=== <Data_Correction> ===
+
Use this class to identify and define the attributes of the filter associated with the image data being described.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
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''
 
''OPTIONAL''
  
==== <data_correction_flag> ====
+
This attribute contains the filter name.
  
''REQUIRED''
+
{| class="wikitable" style="background-color: yellow"
 +
|
 +
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.
 +
|}
  
==== <data_correction_subtype> ====
+
=== <filter_id> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
==== <active_flag> ====
+
This attribute contains a short identifier for the filter - 16 character limit.
 +
 
 +
=== <filter_number> ===
 +
 
 +
''OPTIONAL''
  
''REQUIRED''
+
This attribute contains a number associated with the filter in the context of the mission or data collection program.
  
==== <Constants_Indexed> ====
+
=== <bandwidth> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
This attribute indicates the filter bandwidth in units of wavelength.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This class contains a choice list in which all elements are explicitly set to minOccurs=0, allowing "none of the above" to be valid(Possible LDDTool issue.)
+
The description notes different ways that are used to define "bandwidth", but does not indicate how the value presented should be interpretedNeither is there an attribute to specify how bandwidth is defined.
 
|}
 
|}
  
===== <index_sequence_number> =====
+
=== <center_filter_wavelength> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
===== <index_name> =====
+
This attribute specifies the wavelength at the center of the filter. You must include units of measure (wavelength units).
  
''OPTIONAL''
+
{| 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?
 +
|}
  
===== <index_id> =====
+
=== <comment> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
===== <index_value_number> =====
+
If there are any additional notes about the exposure you would like to leave for users, this is the place to do it.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
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.
 +
|}
  
''REQUIRED''
 
  
==== <Data_Correction_File> ====
+
== <Color_Filter_Array_Parameters> ==
  
 
''OPTIONAL''
 
''OPTIONAL''
  
===== <description> =====
+
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.
  
''OPTIONAL''
+
=== <color_filter_array_type> ===
  
===== <pds:Internal_Reference> =====
+
''REQUIRED''
  
''OPTIONAL''
+
This must have the value '''Bayer RGGB'''.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
Seems like this should be required, or there's no point in having the class. Is it valid to have this class with just a description field?
+
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> ===
  
=== <Stereo_Product_Parameters> ===
+
''REQUIRED''
  
''OPTIONAL''
+
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
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This class also contains a choice list in which all elements have minOccurs = 0. (Possible LDDTool problem.)
+
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.
 
|}
 
|}
  
==== <geometry_projection_type> ====
+
=== <color_filter_array_venue> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
Standard values "Linearized", "Raw"
+
This attribute identifies where the filter pattern removal was performed. It must have one of the following values:
 +
 
 +
;;* Ground
 +
;;* None
 +
;;* Onboard
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
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.
 +
|}
  
==== <linearization_mode> ====
+
=== <bayer_algorithm> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
Values: Actual, Nominal, None
+
This attribute identifies the algorithm used to remove the Bayer color filter pattern. It must have one of these values:
  
==== <linearization_mode_fov> ====
+
;;* Averaged
 +
;;* Bilinear
 +
;;* Bue Averaged
 +
;;* Blue Bilinear
 +
;;* Green Averaged
 +
;;* Green Bilinear
 +
;;* Identity
 +
;;* Malver
 +
;;* None
 +
;;* Panchromatic
 +
;;* Raw Bayer
 +
;;* Red Averages
 +
;;* Red Bilinear
 +
;;* Zhang-Wu
  
''OPTIONAL''
+
{| class="wikitable" style="background-color: yellow"
 +
|
 +
'''None''' is not an appropriate value for an optional attribute.
 +
|}
  
==== <stero_baseline_length> ====
+
== <Sampling_Parameters> ==
  
 
''OPTIONAL''
 
''OPTIONAL''
  
==== <Stereo_Partner> ====
+
This class contains attributes documenting processing done to compress of reduce the resolution of the data.
 +
 
 +
=== <crosstrack_summing> ===
  
 
''OPTIONAL''
 
''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.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This class just contains an Internal ReferenceThere's no point in requiring the additional level.
+
Note that the name of this attribute (summing) and its definition (count of values averaged) seem to imply different processesIt is not clear which applies.
 
|}
 
|}
  
===== <pds:Internal_Reference> =====
+
=== <downtrack_summing> ===
 +
 
 +
''OPTIONAL''
  
''REQUIRED''
+
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.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
There is no reference_type defined for this context.
+
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''.
  
== <Sampling_Parameters> ==
+
{| class="wikitable" style="background-color: yellow"
 +
|
 +
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''
 
''OPTIONAL''
  
{| class="wikitable" style="background-color: lavenderblush"
+
{| class="wikitable" style="background-color: yellow"
 
|
 
|
What does it mean to repeat this class?
+
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.
 
|}
 
|}
  
=== <downsample_flag> ===
+
=== <sampling_factor> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
{| class="wikitable" style="background-color: lavenderblush"
+
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"
 
|
 
|
Does it make sense that this is optional?
+
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?
 
|}
 
|}
  
=== <crosstrack_summing> ===
+
=== <Companding_Parameters> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
=== <downtrack_summing> ===
+
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:
  
''OPTIONAL''
+
:* '''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.
  
=== <pixel_averaging_height> ===
+
==== <companding_venue> ====
  
''OPTIONAL''
+
''REQUIRED''
  
=== <pixel_averaging_width> ===
+
This attribute indicates how the companding/expanding was achieved.  It must have one of the following values:
  
''OPTIONAL''
+
:* '''Hardware''': The processing was performed in hardware.
 +
:* '''Software''': The processing was performed by software.
 +
:* '''None''': No processing was performed.
  
{| class="wikitable" style="background-color: lavenderblush"
+
{| class="wikitable" style="background-color: yellow"
 
|
 
|
Does it make sense that only one of this and the previous pixel_averaging keyword could be included?
+
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.
 
|}
 
|}
  
=== <sample_bit_method> ===
+
==== <companding_method> ====
  
''OPTIONAL''
+
''REQUIRED''
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
There are no standard values defined for this field. Is that intentional?
+
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.
 
|}
 
|}
  
=== <sample_bits> ===
+
== <Downsampling_Parameters> ==
  
 
''OPTIONAL''
 
''OPTIONAL''
  
=== <sample_bit_mode_id> ===
+
This class provides the parameters used in creating the present downsampled image from the source.
 +
 
 +
=== <downsampling_flag> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
A value of '''true''' here indicates the associated data object is downsampled.  Otherwise, if present this would be '''false'''.
  
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
There are no standard values defined for this field.
+
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?
 
|}
 
|}
  
=== <sampling_factor> ===
+
=== <downsampling_venue> ===
  
 
''OPTIONAL''
 
''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'''
  
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
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?
 +
|}
  
== <Frame_Parameters> ==
+
=== <downsampling_method> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
=== <frame_id> ===
+
{| class="wikitable" style="background-color: yellow"
 +
|
 +
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''
 
''OPTIONAL''
  
=== <frame_type> ===
+
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> ====
 +
 
 +
''REQUIRED''
 +
 
 +
The number of pixels in the vertical direction that were averaged.  You must specify a unit of measure.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
"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> ====
  
''OPTIONAL''
+
''REQUIRED''
  
Values: Mono, Stereo
+
The number of pixels in the horizontal direction that were averaged.  You must specify a unit of measure.
  
{| class="wikitable" style="background-color: lavenderblush"
+
{| class="wikitable" style="background-color: yellow"
 
|
 
|
Why is this field repeatable?
+
"Horizontal" is not defined in this context, and the value is a count, not a measurement - so a unit of measurement is not appropriate.
 
|}
 
|}
  
=== <interframe_delay> ===
+
== <Frame_Parameters> ==
  
 
''OPTIONAL''
 
''OPTIONAL''
  
 +
=== <frame_id> ===
  
 +
''OPTIONAL''
  
== <Subframe_Parameters> ==
+
=== <frame_type_name> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
{| class="wikitable" style="background-color: lavenderblush"
+
{| class="wikitable" style="background-color: yellow"
 
|
 
|
What does it mean to repeat this class?  How would you, e.g., map a specific set of parameters to a particular frame (or would you)?
+
No permissible values are defined for this field.
 
 
It's a little odd that the required fields occur at the bottom of the class, after all the optional attributes.
 
 
|}
 
|}
  
=== <name> ===
+
=== <interframe_delay> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
=== <description> ===
+
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.
  
''OPTIONAL''
+
The definition implies that this may only be specified in seconds, but that is not enforced.
 +
|}
  
=== <subframe_type> ===
+
== <Subframe_Parameters> ==
  
 
''OPTIONAL''
 
''OPTIONAL''
Line 382: Line 662:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
This attribute has a null rule defined and no standard values.
+
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.
 
|}
 
|}
  
Line 388: 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> ===
Line 401: Line 700:
 
''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.
 +
|}
  
== <Derived_Product_Parameters> ==
+
=== <name> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
=== <horizon_mask_elevation> ===
+
{| 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> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
{| class="wikitable" style="background-color: lavenderblush"
+
{| class="wikitable" style="background-color: yellow"
 
|
 
|
What does it mean to repeat this attribute?
+
This attribute is unexplained.  What would need describing at this point?
 
|}
 
|}
  
=== <derived_image_type> ===
+
 
 +
=== <subframe_type> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
{| class="wikitable" style="background-color: lavenderblush"
+
{| class="wikitable" style="background-color: yellow"
 
|
 
|
Why is this 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''
 +
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
There are no defined standard values for this type.
+
The definition implies this should have a list of permissible values, but none are defined.
 
|}
 
|}
  
=== <Data_Correction_File> ===
+
=== <color_component> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
  
==== <description> ====
+
{| 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''
 
''OPTIONAL''
  
==== <pds:Internal_Reference> ====
+
{| class="wikitable" style="background-color: yellow"
 +
|
 +
The definition implies there should be a permissible value list, but there is none.
 +
|}
 +
 
 +
=== <encoded_display_gamma> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
Line 443: Line 774:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
As before, this makes no sense as an optional component in an optional class that contains nothing else of substance.
+
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