Skip to content

lonboard.colormap

lonboard.colormap

DiscreteColormap module-attribute

DiscreteColormap = Mapping[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.

NLCD Land Cover Legend

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], str
]

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).

This can also be a string that refers to a matplotlib named color.

apply_categorical_cmap

apply_categorical_cmap(
    values: Union[
        NDArray,
        Series,
        Array,
        ChunkedArray,
        ArrowArrayExportable,
        ArrowStreamExportable,
    ],
    cmap: DiscreteColormap,
    *,
    alpha: int | float | None = None
) -> NDArray[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:

Other Parameters:

  • alpha (int | float | None) –

    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[floating],
    cmap: Union[Palette, Colormap],
    *,
    alpha: Union[float, int, NDArray[floating], None] = None
) -> NDArray[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.