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

From The SBN Wiki
Jump to navigation Jump to search
(: Update for IMG 1.9.0.0)
(: Update for IMG 1.9.0.0)
Line 419: Line 419:
 
''OPTIONAL''
 
''OPTIONAL''
  
This attribute give the number of detector pixel values, in the crosstrack direction, that were averaged to produce the actual pixel value in the data file.
+
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"
 +
|
 +
Note that the name of this attribute and its definition seem to imply different processes.  It is not clear which applies.
 +
|}
  
 
=== <downtrack_summing> ===
 
=== <downtrack_summing> ===
  
 
''OPTIONAL''
 
''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.
 +
 +
{| 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.
 +
|}
 +
  
 
=== <sample_bits> ===
 
=== <sample_bits> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
The definition given for this attribute is from a PDS3 context and is nonsensical in this one.
 +
|}
  
 
=== <sample_bit_mask> ===
 
=== <sample_bit_mask> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
The definition given for this attribute is from a PDS3 context and is nonsensical in this one.
 +
|}
  
 
=== <sampling_factor> ===
 
=== <sampling_factor> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
The definition given for this attribute is incomplete and unclear.
 +
|}
  
 
=== <Companding_Parameters> ===
 
=== <Companding_Parameters> ===
  
 
''OPTIONAL''
 
''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> ====
 
==== <companding_state> ====
  
 
''REQUIRED''
 
''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> ====
 
==== <companding_venue> ====
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
Rather than where, this attribute seems to indicate 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.
 +
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
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> ====
 
==== <companding_method> ====
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
This attribute is poorly defined and not currently usable.
 +
|}
  
 
== <Downsampling_Parameters> ==
 
== <Downsampling_Parameters> ==

Revision as of 22:27, 22 July 2018

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.

<pds:Local_Internal_Reference>

OPTIONAL

Use this class to point to autoexposure parameters that are documented as part of this data product. Note that this class and its attributes are defined in the pds: namespace. We indicate that here by explicitly including the "pds:" prefix to indicate we are not in the img: namespace.

<pds:comment>

OPTIONAL

Use this attribute as needed to provide additional explanation about the content or format of the data object being referenced.

<pds:local_identifier_reference>

REQUIRED

This attribute must contain the value of the <local_identifier> attribute in the data object being referenced.

<pds:local_reference_type>

REQUIRED

This attribute must have the value to_mission_autoexposure_parameters.


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

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.

This class may be repeated.

<Data_Correction>

OPTIONAL

This class provides details about the processing 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 Protextion
  • 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
  • Onboard

<Data_Correction_File>

OPTIONAL


This class is apparently intended to identify a file of descriptive information, but the class contains only a <description> attribute and an empty choice list.

<description>

OPTIONAL


UNKNOWN

UNKNOWN

The schema contains an empty choice list at this point.

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


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

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

<Shutter_Subtraction_Parameters>

OPTIONAL

The class definition is unintelligible to me.

<shutter_subtraction_mode>

REQUIRED

This attribute must have one of two values:

  • Conditional
  • True

The meanings are unclear.

<exposure_duration_threshold_count>

REQUIRED

The meaning of this attribute is not clear.

<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 passband. It is required to be in units of frequency.

Since the filter center is given in wavelength, a bandwidth in frequency is highly problematic.


<center_filter_wavelength>

OPTIONAL

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

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

<Bayer_Parameters>

OPTIONAL

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.

<bayer_state>

'REQUIRED

This attribute indicates the current state of the data with respect to Bayer encoding. It must have one of these values:

  • Bayer Encoded - The image is currently Bayer encoded.
  • Debayered - The image was originally Bayer encoded, but has been de-Bayered using the algorithm described, following.
  • No Bayer - The image was never and is not Bayer-encoded.

The first value should not be valid in an archive - encoded data is prohibited.

<debayer_venue>

REQUIRED for Debayered data

This attribute is required if the <bayer_state> attribute is Debayered, but optional otherwise. It indicates where de-Bayering was applied. It must have one of these values:

  • Ground
  • Onboard

This should probably be prohibited when it is not required, to avoid confusion and typos.

<debayer_algorithm>

OPTIONAL

If present, this attribute must have one of the following values:

  • Malvar
  • Zhang-Wu

<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 and its definition 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

The definition given for this attribute is from a PDS3 context and is nonsensical in this one.

<sample_bit_mask>

OPTIONAL

The definition given for this attribute is from a PDS3 context and is nonsensical in this one.

<sampling_factor>

OPTIONAL


The definition given for this attribute is incomplete and unclear.

<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

Rather than where, this attribute seems to indicate 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 poorly defined and not currently usable.

<Downsampling_Parameters>

OPTIONAL

<downsampling_flag>

OPTIONAL

<downsampling_venue>

OPTIONAL

<downsampling_method>

OPTIONAL

<Pixel_Averaging_Dimensions>

OPTIONAL

<height_pixels>

REQUIRED

<width_pixels>

REQUIRED

Does it make sense that only one of this and the previous pixel_averaging keyword could be included?



<Frame_Parameters>

OPTIONAL

<frame_id>

OPTIONAL

<frame_type_name>

OPTIONAL

Values: Mono, Stereo

Why is this field repeatable?

<interframe_delay>

OPTIONAL



<Subframe_Parameters>

OPTIONAL

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

It's a little odd that the required fields occur at the bottom of the class, after all the optional attributes.

<first_line>

REQUIRED

<first_sample>

REQUIRED

<lines>

REQUIRED

<samples>

REQUIRED

<name>

OPTIONAL

<description>

OPTIONAL

<subframe_type>

OPTIONAL

This attribute has a null rule defined and no standard values.