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

From The SBN Wiki
Jump to navigation Jump to search
(Update for dictionary version 1B00)
 
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
The display dictionary is a ''discipline dictionary'', which means that its classes will appear in the ''<Discipline_Area&gt'' 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 correct 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.
 +
 
 +
''Last Update: 2020-07-31, for version 1B00 of this dictionary.''
  
 
== <Display_Settings> ==
 
== <Display_Settings> ==
Line 5: Line 7:
 
''REQUIRED''
 
''REQUIRED''
  
This is the main wrapper class for the Display Dictionary.  It must be  
+
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.
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.
 
 
 
  
=== <Local_Internal_Reference> ===
+
=== <pds:Local_Internal_Reference> ===
 
----
 
----
 
''REQUIRED''
 
''REQUIRED''
Line 15: 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.
  
==== <comment> ====
+
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''
 
''OPTIONAL''
Line 21: Line 23:
 
This is a free-text field for any clarifying comments you might wish to include.
 
This is a free-text field for any clarifying comments you might wish to include.
  
==== <local_identifier_reference> ====
+
==== <pds:local_identifier_reference> ====
  
 
''REQUIRED''
 
''REQUIRED''
Line 27: Line 29:
 
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.  
 
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.  
  
==== <local_reference_type> ====
+
==== <pds:local_reference_type> ====
 
   
 
   
 
''REQUIRED''
 
''REQUIRED''
  
 
This must have the value ''display_settings_to_array''.
 
This must have the value ''display_settings_to_array''.
 
  
 
=== <Display_Direction> ===
 
=== <Display_Direction> ===
Line 87: Line 88:
 
''REQUIRED''
 
''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
+
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 108: Line 109:
 
''REQUIRED''
 
''REQUIRED''
  
This attribute us 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).
+
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> ====
 
==== <blue_channel_band> ====
Line 114: Line 115:
 
''REQUIRED''
 
''REQUIRED''
  
This attribute us 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).
+
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> ===
 
=== <Movie_Display_Settings> ===
Line 128: 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> ====
Line 143: Line 143:
  
 
:::<code>&lt;frame_rate unit="frames/s"&gt;12&lt;/frame_rate&gt;</code>
 
:::<code>&lt;frame_rate unit="frames/s"&gt;12&lt;/frame_rate&gt;</code>
 +
 +
The minimum valid value for this attribute is 1.0.
  
 
==== &lt;loop_flag&gt; ====
 
==== &lt;loop_flag&gt; ====
Line 154: Line 156:
 
''OPTIONAL''
 
''OPTIONAL''
  
This attribute contains the number of times the movie should be looped before being stopped. '''''Note''''' that logically, this should be a positive integer, but as of this writing this is not validated.
+
This attribute contains the number of times the movie should be looped before being stopped. It may have a minimum value of one (1).
  
 
==== &lt;loop_delay&gt; ====
 
==== &lt;loop_delay&gt; ====
Line 164: Line 166:
 
:::<code>&lt;loop_delay unit="ms"&gt;500&lt;/loop_delay&gt;</code>
 
:::<code>&lt;loop_delay unit="ms"&gt;500&lt;/loop_delay&gt;</code>
  
'''''NOTE''''' that this should logically be a non-negative number, but as of this writing that is not validated.
+
This may have a minimum value of zero (0).
  
 
==== &lt;loop_back_and_forth_flag&gt; ====
 
==== &lt;loop_back_and_forth_flag&gt; ====

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.