Usage¶

1. Basic Import¶

import cv2
import matplotlib.pyplot as plt
import numpy as np
import colormap_tool

2. Core Recipes¶

This library provides simple, one-line solutions for common colormap conversion tasks.

Recipe 1: Use a Matplotlib Colormap in OpenCV¶

To apply a Matplotlib colormap (e.g., viridis) to an image using cv2.applyColorMap, use get_cv_colormaps.

This function automatically handles the conversion to the BGR format required by OpenCV.

# Get the 'viridis' colormap in a format suitable for OpenCV
lut = colormap_tool.get_cv_colormaps("mpl.viridis")

# Apply it to a grayscale image
gray_img = np.random.randint(0, 255, (100, 100), dtype=np.uint8)
colored_img = cv2.applyColorMap(gray_img, lut)

# Display the result
cv2.imshow("Matplotlib's Viridis in OpenCV", colored_img)
cv2.waitKey(0)
cv2.destroyAllWindows()

Recipe 2: Use an OpenCV Colormap in Matplotlib¶

To use an OpenCV colormap (e.g., jet) in a Matplotlib plot, use get_mpl_colormaps.

This function returns a matplotlib.colors.Colormap object that matplotlib understands.

# Get the OpenCV 'jet' colormap as a Matplotlib Colormap object
cmap = colormap_tool.get_mpl_colormaps("cv.jet")

# Use it in a plot
data = np.random.rand(20, 20)
plt.imshow(data, cmap=cmap)
plt.title("OpenCV's Jet in Matplotlib")
plt.colorbar()
plt.show()

Recipe 3: Get Raw Colormap Data (RGB)¶

If you need the raw RGB color data for a colormap, use get_colormaps. This is useful for custom processing, analysis, or creating custom visualizations.

You can also specify the number of entries (n) to resample the colormap.

# Get the 'viridis' colormap as a 256-entry RGB array
rgb_lut = colormap_tool.get_colormaps("mpl.viridis", n=256)

# rgb_lut is a (256, 3) numpy array with dtype=uint8
print(rgb_lut.shape)
print(rgb_lut.dtype)

3. Advanced Usage¶

Registering All Colormaps with Matplotlib¶

For maximum convenience, you can register all available colormaps with Matplotlib at the start of your script. This allows you to use them by name in any Matplotlib function.

# Register all colormaps
colormap_tool.register_all_cmps2mpl()

# Now, you can use OpenCV colormaps directly by name
data = np.random.rand(20, 20)
plt.imshow(data, cmap="cv.jet")
plt.title("Using a Registered OpenCV Colormap")
plt.show()

Custom LUT Resampling¶

The resample_lut function can resize any custom LUT to a desired length while preserving its format.

# Create a simple 2-color LUT (black to white)
my_lut = np.array([[0, 0, 0], [255, 255, 255]], dtype=np.uint8)

# Resample it to 10 entries
resampled_lut = colormap_tool.resample_lut(my_lut, 10)
print(resampled_lut.shape)  # Output: (10, 3)

Converting a Custom RGB Array to a Matplotlib Colormap¶

If you have your own colormap data as an RGB array, you can convert it into a Matplotlib Colormap object.

# Create a custom gradient from blue to yellow
custom_rgb = np.zeros((256, 3), dtype=np.uint8)
custom_rgb[:, 0] = np.linspace(0, 255, 256)      # R
custom_rgb[:, 1] = np.linspace(0, 255, 256)      # G
custom_rgb[:, 2] = np.linspace(255, 0, 256)      # B

# Convert it to a Matplotlib Colormap object
custom_cmap = colormap_tool.uint8_rgb_arr2mpl_cmp(custom_rgb, name="blue_yellow")

# Use it in a plot
plt.imshow(data, cmap=custom_cmap)
plt.title("Custom Blue-Yellow Colormap")
plt.show()

For more details, please refer to API Reference.