lonboard.colormap¶

lonboard.colormap ¶

DiscreteColormap `module-attribute` ¶

DiscreteColormap = Dict[Any, RGBColor]

A type definition for a discrete colormap.

For example, for a land cover colormap, you may want to use the following dict:

color_map = {
    "Open Water": [70, 107, 159],
    "Perennial Snow/Ice": [209, 222, 248],
    "Developed, Open Space": [222, 197, 197],
    "Developed, Low Intensity": [217, 146, 130],
    "Developed, Medium Intensity": [235, 0, 0],
    "Developed, High Intensity": [171, 0, 0],
    "Barren Land": [179, 172, 159],
    "Deciduous Forest": [104, 171, 95],
    "Evergreen Forest": [28, 95, 44],
    "Mixed Forest": [181, 197, 143],
    "Shrub/Scrub": [204, 184, 121],
    "Herbaceous": [223, 223, 194],
    "Hay/Pasture": [220, 217, 57],
    "Cultivated Crops": [171, 108, 40],
    "Woody Wetlands": [184, 217, 235],
    "Emergent Herbaceous Wetlands": [108, 159, 184],
}

This corresponds to the following well-known color palette from the National Land Cover Database.

Keep in mind that the type of the key of the color_map dictionary is important. If your data is represented as a string, the keys of the color_map must also be represented as strings. If your data is represented as an integer, the keys of the colormap should be integers.

RGBColor `module-attribute` ¶

RGBColor = Union[Tuple[int, int, int], Tuple[int, int, int, int], Sequence[int]]

A type definition for an RGB or RGBA color value

All values must range between 0 and 255 (inclusive). If only three values are provided, the fourth (alpha) channel will be inferred as 255 (meaning full opacity, no transparency).

apply_categorical_cmap ¶

apply_categorical_cmap(
    values: Union[NDArray, pd.Series, pa.Array, pa.ChunkedArray],
    cmap: DiscreteColormap,
    *,
    alpha: Optional[int] = None
) -> NDArray[np.uint8]

Apply a colormap to a column of categorical values.

If you're working with categorical data in Pandas or GeoPandas, and especially when those categories are strings, you should use the pandas Categorical type. This will use much less memory and be faster to operate on. apply_categorical_cmap will be 2-3x faster (and use less memory itself) when your data is already represented as a categorical data type.

The key of the colormap must be the same as the data type of the column of values you pass in. Usually this will be string, when you perform the lookup on a string column of data.

Parameters:

values (Union[NDArray, Series, Array, ChunkedArray]) –

A numpy array, pandas Series, pyarrow Array or pyarrow ChunkedArray of data. The data type of this column must match the keys of the colormap.
cmap (DiscreteColormap) –

A dictionary mapping keys to colors. See [DiscreteColormap] for more information.

Other Parameters:

alpha (Optional[int]) –

The default alpha value for entries in the colormap that do not have an alpha value defined. Alpha must be an integer between 0 and 255 (inclusive).

Returns:

NDArray[uint8] –

A two dimensional numpy array with data type np.uint8. The second dimension will have a length of either 3 if alpha is None, or 4 is each color has an alpha value.

apply_continuous_cmap ¶

apply_continuous_cmap(
    values: NDArray[np.floating],
    cmap: Union[Palette, mpl.colors.Colormap],
    *,
    alpha: Union[float, int, NDArray[np.floating], None] = None
) -> NDArray[np.uint8]

Apply a colormap to a column of continuous values.

If you pass in a Palette object from the palettable package, this will use matplotlib's LinearSegmentedColormap under the hood. As described in Matplotlib's referenced docstring:

The lookup table is generated using linear interpolation for each primary color, with the 0-1 domain divided into any number of segments.

This means that input values are linearly combined from the two nearest colormap colors.

If you pass in a Matplotlib Colormap object, this will use the lookup method defined in that class.

Parameters:

values (NDArray[floating]) –

A numpy array of floating point values ranging from 0 to 1.
cmap (Union[Palette, Colormap]) –

Any matplotlib Colormap or Palette object from the palettable package.

Other Parameters:

alpha (Union[float, int, NDArray[floating], None]) –

Alpha must be a scalar between 0 and 1, a sequence of such floats with shape matching values, or None.

Returns:

NDArray[uint8] –

A two dimensional numpy array with data type np.uint8. The second dimension will have a length of either 3 if alpha is None, or 4 is each color has an alpha value.

lonboard.colormap¶