Syntax

   @RasterPaletteAttributes([REJECTABLE], <mode>, <paletteAttribute>)

Arguments

   REJECTABLE

      Specifies if the function will supply a rejection code and message
      to the invalid feature and output it to the rejected port, or will
      fail upon being supplied invalid features.

      A feature can be rejected for the following reasons:
         - The feature has invalid geometry
         - The raster has no bands

   <mode>

      In ADD mode, the function will create a palette from <paletteAttribute>
      and add it to selected bands. In EXTRACT mode, the function will take an
      existing palette and write it to <paletteAttribute>.

      Range: (ADD|EXTRACT)

   <paletteAttribute>

      The attribute from which the palette will be read, or to which the palette
      will be written.

      Range: String

Description

   The @RasterPaletteAttributes function is used to convert between palettes and
   attributes.

   In ADD mode, the function will create a palette from an attribute, and add
   this palette to all selected bands. Selected bands are required to have an
   interpretation of UINT8, UINT16, or UINT32.

      Note: Palette entries will be discarded if they do not fit within the
      interpretation of a selected band. For example, when adding a palette to a
      UINT8 band, all keys that are greater than 255 will be dropped.

   In EXTRACT mode, the function will create a string representation of an
   existing palette and save it to an attribute. In this mode, exactly one
   palette must be selected on the raster.

      Note: This function may be used in combination with @File to read palettes
      from files or write palettes to files. For example, one could use @File to
      read a file into an attribute, then use @RasterPaletteAttributes to create
      a palette from the attribute.

   See the Palette Format section for a description of the format of palette
   attributes.

   This function supports raster band and palette selection. @SelectRaster can
   be used to modify selection.

   Palette Format
   ~~~~~~~~~~~~~~

   The general format of a palette attribute is as follows:

      <value interpretation> [<string length>]
      <key 0> <value 0>
      <key 1> <value 1>
      ...
      <key n> <value n>

   The first line of the palette must contain the value interpretation. Valid
   values for the value interpretation are RGBA32, RGB24, RGBA64, RGB48, GRAY8,
   GRAY16, and STRING.

   When an interpretation of STRING is specified, the first line may optionally
   specify the maximum string length of the palette values. This value must be a
   positive integer. If no string length is explicitly specified, a default of
   32 will be assumed.

   RGBA and RGB palette values consist of comma-delimited strings of integers
   between 0 and the maximum value of the datatype. For example, a valid RGBA32
   value would 64,128,255,255, and a valid RGB48 value would be
   16384,32768,65535.

   GRAY palette values consist of a single integer between 0 and the maximum
   value of the datatype.

   STRING palette values may consist of any arbitrary text, except for the
   newline character.

   All lines after the first are key-value pairs. Palette keys must be organized
   in ascending order, but they are not required to be contiguous. For example,
   you can have palette entries for keys 0, 2, and 4, but not 1 or 3. All
   missing palette entries are assumed to look up to 0 or an equivalent value,
   such as 0,0,0 for RGB or an empty string for string palettes.

   Palette Examples
   ~~~~~~~~~~~~~~~~

   Here is an example of a color palette:

      RGB24
      0 0,49,190
      1 50,255,50
      2 172,0,255
      3 255,0,0

   And here is an example of a string palette:

      STRING 10
      0 Water
      1 Forest
      2 Commercial
      3 Urban