# GDALColorTable C++ API

## Include file

gdal_colortable.h

## GDALColorTable class

class GDALColorTable

  A color table / palette.

  Public Functions

  explicit GDALColorTable(GDALPaletteInterp = GPI_RGB)

    Construct a new color table.

    This constructor is the same as the C GDALCreateColorTable() function.

    Parameters:

      eInterpIn -- the interpretation to be applied to GDALColorEntry values.

  GDALColorTable(const GDALColorTable&) = default

    Copy constructor.

  GDALColorTable &operator=(const GDALColorTable&) = default

    Copy assignment operator.

  GDALColorTable(GDALColorTable&&) = default

    Move constructor.

  GDALColorTable &operator=(GDALColorTable&&) = default

    Move assignment operator.

  ~GDALColorTable()

    Destructor.

    This destructor is the same as the C GDALDestroyColorTable() function.

  GDALColorTable *Clone() const

    Make a copy of a color table.

    This method is the same as the C function GDALCloneColorTable().

  int IsSame(const GDALColorTable *poOtherCT) const

    Returns if the current color table is the same as another one.

    Parameters:

      poOtherCT -- other color table to be compared to.

    Returns:

      TRUE if both color tables are identical.

  GDALPaletteInterp GetPaletteInterpretation() const

    Fetch palette interpretation.

    The returned value is used to interpret the values in the GDALColorEntry.

    This method is the same as the C function GDALGetPaletteInterpretation().

    Returns:

      palette interpretation enumeration value, usually GPI_RGB.

  int GetColorEntryCount() const

    Get number of color entries in table.

    This method is the same as the function GDALGetColorEntryCount().

    Returns:

      the number of color entries.

  const GDALColorEntry *GetColorEntry(int i) const

    Fetch a color entry from table.

    This method is the same as the C function GDALGetColorEntry().

    Parameters:

      i -- entry offset from zero to GetColorEntryCount()-1.

    Returns:

      pointer to internal color entry, or NULL if index is out of range.

  int GetColorEntryAsRGB(int i, GDALColorEntry *poEntry) const

    Fetch a table entry in RGB format.

    In theory this method should support translation of color palettes in non-RGB color spaces into RGB on the fly, but currently it only works on RGB color tables.

    This method is the same as the C function GDALGetColorEntryAsRGB().

    Parameters:

      - i -- entry offset from zero to GetColorEntryCount()-1.

      - poEntry -- the existing GDALColorEntry to be overwritten with the RGB values.

    Returns:

      TRUE on success, or FALSE if the conversion isn't supported.

  void SetColorEntry(int i, const GDALColorEntry *poEntry)

    Set entry in color table.

    Note that the passed in color entry is copied, and no internal reference to it is maintained. Also, the passed in entry must match the color interpretation of the table to which it is being assigned.

    The table is grown as needed to hold the supplied offset.

    This function is the same as the C function GDALSetColorEntry().

    Parameters:

      - i -- entry offset from zero to GetColorEntryCount()-1.

      - poEntry -- value to assign to table.

  int CreateColorRamp(int nStartIndex, const GDALColorEntry *psStartColor, int nEndIndex, const GDALColorEntry *psEndColor)

    Create color ramp.

    Automatically creates a color ramp from one color entry to another. It can be called several times to create multiples ramps in the same color table.

    This function is the same as the C function GDALCreateColorRamp().

    Parameters:

      - nStartIndex -- index to start the ramp on the color table [0..255]

      - psStartColor -- a color entry value to start the ramp

      - nEndIndex -- index to end the ramp on the color table [0..255]

      - psEndColor -- a color entry value to end the ramp

    Returns:

      total number of entries, -1 to report error

  bool IsIdentity() const

    Returns if the current color table is the identity, that is for each index i, colortable[i].c1 = .c2 = .c3 = i and .c4 = 255.

    Since

      GDAL 3.4.1

  Public Static Functions

  static std::unique_ptr<GDALColorTable> LoadFromFile(const char *pszFilename)

    Load a color table from a (text) file.

    Supported formats are:

    - QGIS Layer Style File (.qml) or QGIS Layer Definition File (.qlr) using "Palette/unique values" raster renderer or "Single band pseudocolor" renderer

    - GMT or GRASS text files, when entry index are integers

    Since

      GDAL 3.12

    Returns:

      a new color table, or NULL in case of error.

  static inline GDALColorTableH ToHandle(GDALColorTable *poCT)

    Convert a GDALColorTable* to a GDALRasterBandH.

  static inline GDALColorTable *FromHandle(GDALColorTableH hCT)

    Convert a GDALColorTableH to a GDALColorTable*.