excolor.imagetools

excolor.imagetools.pixels_to_size_and_dpi(size, exact=True)[source]

Converts pixel dimensions to optimal size in inches and DPI.

This function takes pixel dimensions and converts them to physical size (in inches) and DPI (dots per inch) while maintaining the aspect ratio. It ensures the output size is at least 5 inches in the smaller dimension by adjusting the DPI if necessary.

Parameters:

size (Tuple[int, int]) – Image dimensions in pixels (width, height)
exact (bool, default True) – If True, the size will match the target size exactly

Returns:

A tuple containing: - Tuple[int, int]: Optimal size in inches (width, height) - int: DPI (dots per inch)

Return type:

Tuple[Tuple[int, int], int]

Examples

>>> pixels_to_size_and_dpi((1200, 800))  # ((6, 4), 200)
>>> pixels_to_size_and_dpi((300, 300))   # ((5, 5), 60)

excolor.imagetools.remove_margins()[source]

Removes figure margins in matplotlib to keep only the plot area.

This function removes all margins and axes from the current matplotlib figure, leaving only the plot area visible. It is useful for creating clean, borderless visualizations.

Return type:: None

Examples

>>> plt.figure()
>>> plt.plot([1, 2, 3])
>>> remove_margins()  # Removes all margins and axes
>>> plt.show()

excolor.imagetools.load_image(fname)[source]

Loads an image from a file or URL.

Parameters:: fname (str) – Image path or url
Returns:: img – Image
Return type:: PIL.PngImagePlugin.PngImageFile

Examples

>>> img = load_image("https://example.com/image.png")
>>> img = load_image("image.png")

excolor.imagetools.img2arr(img)[source]

Converts a PIL Image to a numpy array.

Notes

Image dimensions are (y, x). Image y axis goes from top to bottom. Array dimensions are transposed to (x, y) Array y axis is reversed and goes from bottom to top.

Parameters:: img (PIL.Image.Image) – The image to convert
Returns:: arr – The converted image
Return type:: numpy.ndarray

excolor.imagetools.arr2img(arr)[source]

Converts a numpy array to a PIL Image.

Notes

Array dimensions are (x, y). Array y axis goes from bottom to top. Image dimensions are transposed to (y, x). Image y axis goes from top to bottom.

Parameters:: arr (numpy.ndarray) – The array to convert
Returns:: img
Return type:: PIL.Image.Image

excolor.imagetools.mask2img(mask)[source]

Converts a binary numpy array to a PIL Image.

Notes

Array dimensions are (x, y). Array y axis goes from bottom to top. Image dimensions are transposed to (y, x). Image y axis goes from top to bottom. Array values are in range 0 - 1.

Parameters:: mask (numpy.ndarray) – The mask to convert
Returns:: img
Return type:: PIL.Image.Image

excolor.imagetools.fig2img(fig=None)[source]

Converts a Matplotlib figure to a PIL Image and return it

Parameters:: fig (matplotlib.figure.Figure or None) – The figure to convert. If None, use plt.gcf()
Returns:: img – The converted image
Return type:: PIL.Image.Image

excolor.imagetools.fig2img_from_canvas(fig=None)[source]

Converts a Matplotlib figure to a PIL Image from the canvas and return it

Parameters:: fig (matplotlib.figure.Figure or None) – The figure to convert. If None, use plt.gcf()
Returns:: img – The converted image
Return type:: PIL.Image.Image

excolor.imagetools.add_layer(fig, size, layer, start=(0, 0))[source]

Adds a layer to an image using plt.imshow().

Parameters:

fig (matplotlib.figure.Figure) – The base figure
size (Tuple[int, int]) – The size of the figure canvas in pixels
layer (PIL.Image.Image) – The layer to add
start (Tuple[int, int], default (0, 0)) – The starting position of the layer in the image

Return type:

None

excolor.imagetools.colorize_image(image, facecolor='blue', backgroundcolor=None, contrast=0.5)[source]

Colorizes a b&w image

Parameters:

image (str or PIL.PngImagePlugin.PngImageFile) – Image or file path
facecolor (str or tuple of float) – Face color. Can be: - A color name (e.g., ‘red’) - A hex string (e.g., ‘#FF0000’) - An RGB tuple (e.g., (1.0, 0.0, 0.0))
backgroundcolor (str or tuple of float or None, default None) – Background color. Can be: - A color name (e.g., ‘red’) - A hex string (e.g., ‘#FF0000’) - An RGB tuple (e.g., (1.0, 0.0, 0.0))
contrast (float, default 0.5) – Contrast of the colorized image (0 - 1)

Returns:

img – Colorized image

Return type:

PIL.PngImagePlugin.PngImageFile

excolor.imagetools.resize_image(image, size)[source]

Resizes an image to the specified size

Parameters:

image (str or PIL.PngImagePlugin.PngImageFile) – Image or file path
size (float or tuple of int) – If float, the image is resized to the specified scale factor. If tuple, the image is resized to the specified size in pixels (width, height).

Returns:

img – Resized image

Return type:

PIL.PngImagePlugin.PngImageFile

excolor.imagetools.greyscale_image(image)[source]

Converts an image to greyscale keeping channels

Parameters:: image (str or PIL.PngImagePlugin.PngImageFile) – Image or file path
Returns:: img – Greyscaled image
Return type:: PIL.PngImagePlugin.PngImageFile