porytiles2::ColorIndexMap< PixelType > Class Template Reference

A bidirectional mapping between pixel color values and sequential integer indices. More...

#include <color_index_map.hpp>

Public Member Functions
	ColorIndexMap ()=default
	ColorIndexMap (const std::vector< PixelTile< PixelType > > &tiles)
	Constructs a ColorIndexMap from a collection of tiles using intrinsic transparency.
	ColorIndexMap (const std::vector< PixelTile< PixelType > > &tiles, const PixelType &extrinsic)
	Constructs a ColorIndexMap from a collection of tiles and an extrinsic transparency value.
std::size_t	size () const
	Returns the number of unique colors in the mapping.
bool	empty () const
	Determines if the mapping is empty.
std::optional< PixelType >	color_at_index (ColorIndex index) const
	Retrieves the color associated with a given index.
std::optional< ColorIndex >	index_at_color (const PixelType &color) const
	Retrieves the index associated with a given color.

Detailed Description

template<SupportsTransparency PixelType>
class porytiles2::ColorIndexMap< PixelType >

A bidirectional mapping between pixel color values and sequential integer indices.

ColorIndexMap provides a true bidirectional association between pixel color values and sequential integer indices, starting from 0. The class maintains two internal maps:

• Color-to-index mapping: look up an index given a color
• Index-to-color mapping: look up a color given an index

This class is used for palette operations where each unique non-transparent color in a collection of tiles needs to be assigned a unique integer identifier, with the ability to perform lookups in both directions.

The mapping is constructed by examining all unique non-transparent colors across a collection of tiles, filtering out both intrinsically transparent pixels (alpha=0) and extrinsically transparent pixels (e.g., magenta for Rgba32). Each unique color that passes the transparency filter is assigned the next available sequential index.

Key features:

• True bidirectional lookup (color -> index and index -> color)
• Sequential index assignment starting from 0
• Automatic filtering of transparent pixels during construction
• Deduplication of colors across multiple tiles
• Efficient lookup via std::map in both directions
• Generic support for any pixel type satisfying SupportsTransparency concept

Template Parameters

PixelType

The pixel color type, must satisfy SupportsTransparency concept

Example usage:

std::vector<PixelTile<Rgba32>> tiles = {...};
ColorIndexMap<Rgba32> color_map{tiles, rgba_magenta};
 
// Forward lookup: color -> index
auto index_opt = color_map.index_at_color(Rgba32{255, 0, 0});
if (index_opt) {
    // index_opt contains the ColorIndex for red
}
 
// Reverse lookup: index -> color
auto color_opt = color_map.color_at_index(ColorIndex{0});
if (color_opt) {
    // color_opt contains the color at ColorIndex 0
}

Definition at line 58 of file color_index_map.hpp.

Constructor & Destructor Documentation

ColorIndexMap() [1/3]

template<SupportsTransparency PixelType>

porytiles2::ColorIndexMap< PixelType >::ColorIndexMap ( )

default

ColorIndexMap() [2/3]

template<SupportsTransparency PixelType>

porytiles2::ColorIndexMap< PixelType >::ColorIndexMap ( const std::vector< PixelTile< PixelType > > &  tiles )

inline

Constructs a ColorIndexMap from a collection of tiles using intrinsic transparency.

This constructor analyzes all provided tiles to identify unique non-transparent colors and assigns each a sequential integer index starting from 0. The process:

1. Iterates through each tile in the collection
2. Extracts unique non-transparent colors from each tile (using PixelTile::unique_nontransparent_colors)
3. Filters colors based on intrinsic transparency only (e.g., index 0 for IndexPixel)
4. Assigns each unique color that passes filtering a sequential index (0, 1, 2, ...)
5. Ensures deduplication: colors appearing in multiple tiles receive the same index

This overload is only available for pixel types that support intrinsic transparency (e.g., IndexPixel).

The order of index assignment depends on the order in which colors are encountered during tile iteration.

Parameters

tiles

A vector of tiles with the specified pixel type to analyze for unique colors

Definition at line 81 of file color_index_map.hpp.

ColorIndexMap() [3/3]

template<SupportsTransparency PixelType>

porytiles2::ColorIndexMap< PixelType >::ColorIndexMap ( const std::vector< PixelTile< PixelType > > &  tiles, const PixelType &  extrinsic  )

inline

Constructs a ColorIndexMap from a collection of tiles and an extrinsic transparency value.

This constructor analyzes all provided tiles to identify unique non-transparent colors and assigns each a sequential integer index starting from 0. The process:

1. Iterates through each tile in the collection
2. Extracts unique non-transparent colors from each tile (using PixelTile::unique_nontransparent_colors)
3. Filters colors based on both intrinsic transparency (alpha=0) and extrinsic transparency (matching the provided extrinsic parameter)
4. Assigns each unique color that passes filtering a sequential index (0, 1, 2, ...)
5. Ensures deduplication: colors appearing in multiple tiles receive the same index

This overload is only available for pixel types that support extrinsic transparency (e.g., Rgba32).

The order of index assignment depends on the order in which colors are encountered during tile iteration.

Parameters

tiles	A vector of tiles with the specified pixel type to analyze for unique colors
extrinsic	The extrinsic transparency value used for transparency filtering

Definition at line 108 of file color_index_map.hpp.

Member Function Documentation

color_at_index()

template<SupportsTransparency PixelType>

std::optional< PixelType > porytiles2::ColorIndexMap< PixelType >::color_at_index ( ColorIndex  index ) const

inline

Retrieves the color associated with a given index.

Performs a lookup in the index-to-color mapping to find the pixel color assigned to the specified index. If the index exists in the map, returns the associated color. If the index does not exist (was never assigned during construction), returns std::nullopt.

This method enables efficient reverse lookup: given an index, retrieve its color.

Parameters

index

The color index to lookup

Returns

std::optional<PixelType> containing the color if found, std::nullopt otherwise

Definition at line 153 of file color_index_map.hpp.

empty()

template<SupportsTransparency PixelType>

bool porytiles2::ColorIndexMap< PixelType >::empty ( ) const

inline

Determines if the mapping is empty.

Returns

Whether the mapping is empty

Definition at line 135 of file color_index_map.hpp.

index_at_color()

template<SupportsTransparency PixelType>

std::optional< ColorIndex > porytiles2::ColorIndexMap< PixelType >::index_at_color ( const PixelType &  color ) const

inline

Retrieves the index associated with a given color.

Performs a lookup in the color-to-index mapping to find the color index assigned to the specified pixel color. If the color exists in the map, returns the associated index. If the color does not exist (was never assigned during construction or was filtered out as transparent), returns std::nullopt.

This method enables efficient forward lookup: given a color, retrieve its index.

Parameters

color

The pixel color to lookup

Returns

std::optional<ColorIndex> containing the index if found, std::nullopt otherwise

Definition at line 175 of file color_index_map.hpp.

size()

template<SupportsTransparency PixelType>

std::size_t porytiles2::ColorIndexMap< PixelType >::size ( ) const

inline

Returns the number of unique colors in the mapping.

Returns the count of unique non-transparent colors that were identified during construction. This is equivalent to the size of both the color-to-index and index-to-color maps.

Returns

The number of unique colors mapped

Definition at line 125 of file color_index_map.hpp.

---

The documentation for this class was generated from the following file:

• Porytiles2/include/porytiles2/domain/models/color_index_map.hpp