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

From The SBN Wiki
Jump to navigation Jump to search
(→‎<Local_Internal_Reference>: Update for 1.6.0.0)
Line 17: Line 17:
 
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.
  
==== &lt;comment&gt; ====
+
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.
 +
 
 +
==== &lt;pds:comment&gt; ====
  
 
''OPTIONAL''
 
''OPTIONAL''
Line 23: Line 25:
 
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.
  
==== &lt;local_identifier_reference&gt; ====
+
==== &lt;pds:local_identifier_reference&gt; ====
  
 
''REQUIRED''
 
''REQUIRED''
Line 29: Line 31:
 
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 ''&lt;local_identifier&gt;'' 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 ''&lt;local_identifier&gt;'' 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.  
  
==== &lt;local_reference_type&gt; ====
+
==== &lt;pds:local_reference_type&gt; ====
 
   
 
   
 
''REQUIRED''
 
''REQUIRED''
  
 
This must have the value ''display_settings_to_array''.
 
This must have the value ''display_settings_to_array''.
 
  
 
=== &lt;Display_Direction&gt; ===
 
=== &lt;Display_Direction&gt; ===

Revision as of 17:45, 22 March 2016

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.

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

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>


REQUIRED

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.

<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 (although as of this writing this is not validated).

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

<blue_channel_band>

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


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

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

<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. Note that logically, this should be a positive integer, but as of this writing this is not validated.

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

NOTE that this should logically be a non-negative number, but as of this writing that is not validated.

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