This site may be down for up to an hour for network maintenance during the period
21 January 2022 22:30 UTC - 22 January 2022 00:30 UTC.

Difference between revisions of "Filling Out the Display Dictionary Classes"

From The SBN Wiki
Jump to navigation Jump to search
m
(Update for dictionary version 1B00)
 
Line 1: Line 1:
 
The display dictionary is a ''discipline dictionary'', which means that its classes will appear in the ''<Discipline_Area>'' at the bottom of the ''<Observation_Area>'' in observational product labels (and in the ''<Context_Area>'', if appropriate, in non-observational products).  The classes in this dictionary define the appropriate way to draw or otherwise display array-type data objects in order to be able to correctly interpret geometric or other quantities referenced to, e.g., an image elsewhere in the label.
 
The display dictionary is a ''discipline dictionary'', which means that its classes will appear in the ''<Discipline_Area>'' at the bottom of the ''<Observation_Area>'' in observational product labels (and in the ''<Context_Area>'', if appropriate, in non-observational products).  The classes in this dictionary define the appropriate way to draw or otherwise display array-type data objects in order to be able to correctly interpret geometric or other quantities referenced to, e.g., an image elsewhere in the label.
  
''These descriptions are current for the 1.5.0.0 and 1.6.0.0 releases of the Display Discipline Dictionary.''
+
''Last Update: 2020-07-31, for version 1B00 of this dictionary.''
  
 
== <Display_Settings> ==
 
== <Display_Settings> ==
Line 8: Line 8:
  
 
This is the main wrapper class for the Display Dictionary.  It must be used whenever you want or need to include display information in any label that includes one or more array-type objects, in which case it is repeated for each object that needs display information.
 
This is the main wrapper class for the Display Dictionary.  It must be used whenever you want or need to include display information in any label that includes one or more array-type objects, in which case it is repeated for each object that needs display information.
{| class="wikitable" style="background-color: yellow"
 
|
 
'''Note:''' An earlier version of the PDS4 Information Model allowed data preparers to include a ''Display_2D_Image'' class at the end of an ''Array_2D_Image'' class.  This has been superseded by the Display Discipline Dictionary classes described below.  ''Do not use'' the old ''Display_2D_Image'' class in your labels.
 
|}
 
  
=== <Local_Internal_Reference> ===
+
=== <pds:Local_Internal_Reference> ===
 
----
 
----
 
''REQUIRED''
 
''REQUIRED''
Line 19: Line 15:
 
This class is used to identify the specific array-type object to which these display settings apply.
 
This class is used to identify the specific array-type object to which these display settings apply.
  
Note that, while the class name ''Local_Internal_Reference'' is in the Display Dictionary namespace, the attributes within it all come from the PDS core namespace. You will need to specify the change in namespace.  This can get rather complicated, depending on how you've set up your label to reference different namespaces. See the [[Using Local Dictionaries]] page on this wiki for gory details on that.  For the purposes of this description, we'll indicate the attributes in the PDS core namespace by adding an explicit "pds:" namespace abbreviation prefix to them.
+
Note that the class name ''Local_Internal_Reference'' and the attributes within it all come from the PDS core namespace. Depending on how you set up prefixes in your label, that may mean that there will be no prefix on the class name and its attributes, or you will use the "pds:" prefix, to indicate the change in namespace. See the [[Using Local Dictionaries]] page on this wiki for gory details on that.  For the purposes of this description, we'll indicate the attributes in the PDS core namespace by adding an explicit "pds:" namespace abbreviation prefix to them.
  
 
==== <pds:comment> ====
 
==== <pds:comment> ====
Line 94: Line 90:
 
The value of this attribute must correspond to the ''<axis_name>'' value of one of the axes of the relevant array-type object.  This is the axis that well be
 
The value of this attribute must correspond to the ''<axis_name>'' value of one of the axes of the relevant array-type object.  This is the axis that well be
 
considered the "color" or "band" axis.  Logically, it must ''not'' be the same
 
considered the "color" or "band" axis.  Logically, it must ''not'' be the same
value as found in either the ''<horizontal_display_axis>'' or ''<vertical_display_axis>'' of the ''<Display_Direction>'' class (although as of this writing this is not validated).
+
value as found in either the ''<horizontal_display_axis>'' or ''<vertical_display_axis>'' of the ''<Display_Direction>'' class, but this is not validated - so type carefully.
  
 
==== <comment> ====
 
==== <comment> ====
Line 132: Line 128:
  
 
The value of this attribute must correspond to the ''<axis-name>'' value of one of the axes of the relevant array-type object.  This is the axis that well be
 
The value of this attribute must correspond to the ''<axis-name>'' value of one of the axes of the relevant array-type object.  This is the axis that well be
considered the "time" axis.  Logically, it must ''not'' be the same value as found in either the ''<horizontal_display_axis>'' or ''<vertical_display_axis>'' of the ''<Display_Direction>'' class (although as of this writing this is not validated).
+
considered the "time" axis.  Logically, it must ''not'' be the same value as either ''<horizontal_display_axis>'' or ''<vertical_display_axis>'' of the ''<Display_Direction>'' class, but this is not validate - so type carefully.
  
 
==== <comment> ====
 
==== <comment> ====

Latest revision as of 14:01, 31 July 2020

The display dictionary is a discipline dictionary, which means that its classes will appear in the <Discipline_Area> at the bottom of the <Observation_Area> in observational product labels (and in the <Context_Area>, if appropriate, in non-observational products). The classes in this dictionary define the appropriate way to draw or otherwise display array-type data objects in order to be able to correctly interpret geometric or other quantities referenced to, e.g., an image elsewhere in the label.

Last Update: 2020-07-31, for version 1B00 of this dictionary.

<Display_Settings>

REQUIRED

This is the main wrapper class for the Display Dictionary. It must be used whenever you want or need to include display information in any label that includes one or more array-type objects, in which case it is repeated for each object that needs display information.

<pds:Local_Internal_Reference>


REQUIRED

This class is used to identify the specific array-type object to which these display settings apply.

Note that the class name Local_Internal_Reference and the attributes within it all come from the PDS core namespace. Depending on how you set up prefixes in your label, that may mean that there will be no prefix on the class name and its attributes, or you will use the "pds:" prefix, to indicate the change in namespace. See the Using Local Dictionaries page on this wiki for gory details on that. For the purposes of this description, we'll indicate the attributes in the PDS core namespace by adding an explicit "pds:" namespace abbreviation prefix to them.

<pds:comment>

OPTIONAL

This is a free-text field for any clarifying comments you might wish to include.

<pds:local_identifier_reference>

REQUIRED

This attribute identifies the array object to which the display settings apply, by citing the local_identifier value from the associated array object. All array-type objects have an optional <local_identifier> attribute, which, when present, must have a value that is unique within the label. You must assign local_identifier values to your arrays when you are providing display information.

<pds:local_reference_type>

REQUIRED

This must have the value display_settings_to_array.

<Display_Direction>


REQUIRED

This class defines the correct orientation for displaying the array axes associated with a single image plane (that is, the Line and Sample axes).

<comment>

OPTIONAL

Another opportunity for free-format comments.

<horizontal_display_axis>

REQUIRED

This attribute identifies which axis of the array is considered the horizontal (or "sample") axis by referencing the <axis_name> value. The value must match the name exactly (i.e., case counts).

<horizontal_display_direction>

REQUIRED

This attribute indicates the direction in which pixels should be drawn sequentially along the horizontal axis of the display device. It must have one of these two values (case and embedded blanks are significant):

  • Left to Right
  • Right to Left

<vertical_display_axis>

REQUIRED

This attribute identifies which axis of the array is considered the vertical (or "line") axis by reference the <axis_name> value. The value must match the name exactly (i.e., case counts).

<vertical_display_direction>

REQUIRED

This attribute indicates the direction in which lines of pixels should be stacked sequentially along the vertical direction of the display device. It must have one of these two values (case and embedded blanks are significant):

  • Top to Bottom
  • Bottom to Top


<Color_Display_Settings>


OPTIONAL

Use this class if your array object is an RGB color image, or a banded image for which you would like to define a default set of channels to be interpreted as RGB levels.

<color_display_axis>

REQUIRED

The value of this attribute must correspond to the <axis_name> value of one of the axes of the relevant array-type object. This is the axis that well be considered the "color" or "band" axis. Logically, it must not be the same value as found in either the <horizontal_display_axis> or <vertical_display_axis> of the <Display_Direction> class, but this is not validated - so type carefully.

<comment>

OPTIONAL

Free-format text for additional notes to users.

<red_channel_band>

REQUIRED

This attribute is the subscript to be used in the named color_display_axis for the red (R) value. Note that the first element along this axis is considered to have a subscript of 1 (one).

<green_channel_band>

REQUIRED

This attribute is the subscript to be used in the named color_display_axis for the green (G) value. Note that the first element along this axis is considered to have a subscript of 1 (one).

<blue_channel_band>

REQUIRED

This attribute is the subscript to be used in the named color_display_axis for the blue (B) value. Note that the first element along this axis is considered to have a subscript of 1 (one).

<Movie_Display_Settings>


OPTIONAL

Use this class to define a time axis and parameters for displaying the associated array object as a movie.

<time_display_axis>

REQUIRED

The value of this attribute must correspond to the <axis-name> value of one of the axes of the relevant array-type object. This is the axis that well be considered the "time" axis. Logically, it must not be the same value as either <horizontal_display_axis> or <vertical_display_axis> of the <Display_Direction> class, but this is not validate - so type carefully.

<comment>

OPTIONAL

Free-format text for additional notes to the user.

<frame_rate>

OPTIONAL

This attribute indicates how many images (i.e, "frames") should be displayed each second. You must specify a unit of "frames/s". For example:

<frame_rate unit="frames/s">12</frame_rate>

The minimum valid value for this attribute is 1.0.

<loop_flag>

OPTIONAL

This attribute will contain the value true if the movie should be looped, or false if not.

<loop_count>

OPTIONAL

This attribute contains the number of times the movie should be looped before being stopped. It may have a minimum value of one (1).

<loop_delay>

OPTIONAL

This attribute give the amount of time to pause between playback loops. You must include a time unit with the value, e.g.:

<loop_delay unit="ms">500</loop_delay>

This may have a minimum value of zero (0).

<loop_back_and_forth_flag>

OPTIONAL

This attribute will contain the value true if the movie should be played alternately forward and in reverse while looping; or false if it should only be played in the forward direction when looping. Note that this attribute only makes logical sense in the presence of other looping attributes, but as of this writing this is neither required nor validated.