ImageIndexed

Inherits: Image < Resource < Reference < Object

Adds pseudo support for indexed images.

Description

The class adds support for indexed images with a color palette and provides common operations to create, generate and operate on color palette and index data. This does not actually add a FORMAT_INDEXED image format as modern GPUs don’t actually support it, yet index data is stored internally alongside regular pixels if an image has a palette. This allows to interchange (swap, extend) index data to pixel data via apply_palette, allowing for things like simple palette swapping without using shaders, finding average/dominant colors in an image as the class provides a way to generate color palette with specified number of colors which involves color quantization.

Properties

Dictionary data {"data": PoolByteArray(  ),"format": "Lum8","height": 0,"mipmaps": false,"width": 0} (overrides Image)
PoolByteArray index_data  
PoolColorArray palette  
PoolByteArray palette_data  

Methods

Error apply_palette ( )
void clear_palette ( )
Error create_indexed ( int num_palette_entries=256 )
Error create_indexed_from_data ( PoolByteArray palette_data, PoolByteArray index_data )
float generate_palette ( int num_colors=256, DitherMode dithering=0, bool with_alpha=true, bool high_quality=false )
Color get_palette_color ( int index ) const
int get_palette_size ( ) const
int get_pixel_indexed ( int x, int y ) const
bool has_palette ( ) const
Error load_indexed_png ( String path )
void lock_indexed ( )
Error save_indexed_png ( String path ) const
void set_palette_color ( int index, Color color )
void set_pixel_indexed ( int x, int y, int index )
void unlock_indexed ( )

Enumerations

enum DitherMode:

  • DITHER_NONE = 0 — Do not apply image dithering during palette generation.
  • DITHER_ORDERED = 1 — Applies ordered dithering during palette generation. The algorithm is characterized by noticeable crosshatch patterns to improve the image look with limited number of colors.
  • DITHER_RANDOM = 2 — Applies random dithering during palette generation. The algorithm is characterized by noticeable random noise patterns to improve the image look with limited number of colors.

Constants

  • MAX_PALETTE_SIZE = 256 — The maximum number of palette entries supported.

Property Descriptions

Getter get_index_data()

The internal data representing the indices pointing to palette entries of this image. Cannot be set directly, use create_indexed_from_data.

Setter set_palette(value)
Getter get_palette()

Represents the color palette of this image. The palette can be replaced if the image already has a palette with the same size. In order to change the number of palette entries, use create_indexed, generate_palette, or clear_palette. Note that changing the palette size invalidates existing index data and has to be cleared, which is done automatically.

Getter get_palette_data()

The internal data representing the palette of this image. Cannot be set directly, use palette.

Method Descriptions

  • Error apply_palette ( )

Extends color palette associated with this image from index data and overwrites the original image.

Note that the image will still be represented as true color.

  • void clear_palette ( )

Clears palette and associated index data from this image.

  • Error create_indexed ( int num_palette_entries=256 )

Internally allocates indexed image data with the same dimensions as in this image. The number of palette entries can be specified to allocate palette data to be used by image indices.

A low-level interface to allocate indexed image and color palette from raw data. Make sure that the data is valid and all indices point to valid color palette entries. The palette bitness is determined by image pixel size (in bytes).

Generates an optimal color palette for this image and maps it to indices. The maximum palette color size that can be generated is 256. Dithering can be applied to improve the overall look of the image with low number of colors, see DitherMode.

If with_alpha is true, the alpha channel will be included for quantization algorithm, set this to false if the image is already premultiplied by alpha or if you don’t want the alpha values to affect palette generation.

If high_quality is true, the quantization algorithm will go through additional iteration, potentially improving color mapping quality in expense of performance.

The image must be converted to Image.FORMAT_RGBA8 before generating palette.

Note that this method overwrites previously created or generated palette and index data.

  • Color get_palette_color ( int index ) const

Returns color palette entry at index position.

  • int get_palette_size ( ) const

Returns the total number of color palette entries.

  • int get_pixel_indexed ( int x, int y ) const

Returns an index which is mapped to color palette. See notes for Image.get_pixel.

  • bool has_palette ( ) const

Return true is this image has color palette.

Loads indexed PNG image from disk at specified path. If PNG image is not indexed, it will load the image normally without color palette, see Image.load. If loaded image is indexed, the color palette and index data will be accessible from within this image. If this image is duplicated, the color palette and index data will not be copied, use index_data, palette_data and create_indexed_from_data to manually duplicate palette and index data.

  • void lock_indexed ( )

Locks the index data for writing access.

Saves indexed PNG image to disk at specified path. If image has palette and index data associated with it, the image will be saved as indexed, else saved as true color, see Image.save_png. The image with transparency is saved in a separate PNG alpha chunk, preserving transparency in indexed image with regular RGB color palette.

  • void set_palette_color ( int index, Color color )

Sets color palette entry at index position with color.

  • void set_pixel_indexed ( int x, int y, int index )

Sets an index which should be mapped to color palette. See notes for Image.set_pixel.

  • void unlock_indexed ( )

Unlocks the index data and prevents changes.