Sometimes you do not care whether the image processing is done using NumPy or PyTorch or Pillow, and transfering between these libraries can be cumbersome. PixelCache provides a simple interface to perform image processing and transformation using these libraries, allowing you to focus on the task at hand.
PixelCache is a Python library designed for versatile image processing and transformation, integrating the power of Pillow, NumPy, and PyTorch while supporting LRU caching.
PixelCache also supports LRU caching, which can be useful when you need to reuse the results of previously computed operations. This can be particularly helpful when working with large images or when you need to apply the same operation multiple times.
- Image Manipulation: Transform and process images using a simple interface that supports Pillow, NumPy, and PyTorch.
- Smart Caching: Utilize LRU caching to enhance performance by reusing previously computed results. It can be easily disable for whatever reason using the environment variable
DISABLE_LRU_CACHE=True. - Versatile: PixelCache supports a wide range of image processing operations, including resizing, cropping, blending, transform to RGB/Binary, flipping, bounding box extraction from binary masks, several operations suitable for binary masks, and more.
You can install PixelCache using pip:
pip install pixelcacheOr poetry:
poetry add pixelcacheOr from source:
poetry add git+ssh://[email protected]:affromero/pixelcache.gitHashableImage receives as input several types of inputs, such as URLs, paths, or Pillow images, Numpy arrays, or PyTorch tensors in the following form or shape:
- Paths:
str|Path - Pillow:
Image.Image - Numpy Arrays:
UInt8[np.ndarray, "h w 3"]|UInt8[np.ndarray, "h w"]|Bool[np.ndarray, "h w"] - Torch Tensors:
Float[torch.Tensor, "1 c h w"]|Bool[torch.Tensor, "1 1 h w"]
Example:
from pixelcache.main import HashableImage
import torch
image = HashableImage(torch.rand(1, 3, 256, 256).float())
image_pil = image.pil()
image_numpy_bool = image.to_binary(0.5).numpy()At all times, it is possible to transform between them using the following methods:
pil(): Returns a Pillow Image objectnumpy(): Returns a Numpy Array objecttensor(): Returns a PyTorch Tensor object
Additionally, there is a method to convert the image to 3 channels RGB or binary:
to_rgb(): Convert to RGB, which returns another HashableImageto_binary(threshold: float): Convert to Boolean, which returns another HashableImage
Finally, there is a method to save the image to disk:
save(path: str | Path): Save the image to disk
Blending two images using PixelCache:
from pathlib import Path
from pixelcache.main import HashableDict, HashableImage, HashableList
from pixelcache.tools.logger import get_logger
logger = get_logger()
image0 = "https://images.pexels.com/photos/28811907/pexels-photo-28811907/free-photo-of-majestic-elk-standing-in-forest-clearing.jpeg"
image1 = Path("pixelcache") / "assets" / "pixel_cache.png"
images_hash = [HashableImage(image) for image in [image0, image1]]
for image in images_hash:
logger.info(f"Image: {image} - Hash: {hash(image)}")
logger.info(f"Hash for list of images: {hash(HashableList(images_hash))}")
image_size = images_hash[1].size()
logger.info(f"Image size: {image_size} - Resizing all to this size")
resized_images = [image.resize(image_size) for image in images_hash]
# blend images
blended_image = resized_images[0].blend(
resized_images[1], alpha=0.5, with_bbox=False
)
# binarize second image
blended_image_binarized = resized_images[0].blend(
resized_images[1].to_binary(0.5).invert_binary(),
alpha=0.2,
with_bbox=True,
)
output_debug = HashableDict(
{
"image base": HashableList([resized_images[0]]),
"image reference": HashableList([resized_images[1]]),
"blended_image": HashableList([blended_image]),
"blended_image_binarized": HashableList([blended_image_binarized]),
}
)
output = image1.parent / (str(image1.stem) + "_demo_blend.jpg")
HashableImage.make_image_grid(
output_debug, orientation="horizontal", with_text=True
).save(output)
logger.success(f"Output saved to: {output}")
Extracting bounding boxes for cropping / unpadding from binary masks using PixelCache:
from pathlib import Path
from pixelcache.main import HashableDict, HashableImage, HashableList, ImageSize
from pixelcache.tools.logger import get_logger
logger = get_logger()
image0 = "https://images.pexels.com/photos/18624700/pexels-photo-18624700/free-photo-of-a-vintage-typewriter.jpeg"
image1 = Path("pixelcache") / "assets" / "pixel_cache.png"
images_hash = [HashableImage(image) for image in [image0, image1]]
for image in images_hash:
logger.info(f"Image: {image} - Hash: {hash(image)}")
logger.info(f"Hash for list of images: {hash(HashableList(images_hash))}")
image_size = images_hash[1].size()
logger.info(f"Image size: {image_size} - Resizing all to this size")
resized_images = [image.resize(image_size) for image in images_hash]
# crop images
increased_size_pad = ImageSize(
width=image_size.width + 1000, height=image_size.height + 1000
)
mask = (
images_hash[1]
.center_pad(increased_size_pad, fill=255)
.resize(image_size)
.to_space_color("HSV", getchannel="S")
.to_binary(0.3)
)
cropped = resized_images[1].crop_from_mask(mask)
uncropped = cropped.uncrop_from_bbox(
base=resized_images[0], bboxes=mask.mask2bbox(margin=0.0), resize=True
)
output_debug = HashableDict(
{
"image base": HashableList([resized_images[0]]),
"image reference": HashableList([resized_images[1]]),
"cropped_image": HashableList([cropped.resize(image_size)]),
"uncropped_image": HashableList([uncropped]),
}
)
output = image1.parent / (str(image1.stem) + "_demo_cropUncrop.jpg")
HashableImage.make_image_grid(
output_debug, orientation="horizontal", with_text=True
).save(output)
logger.success(f"Output saved to: {output}")
Contributions are welcome! Please open an issue or submit a pull request.
This project is licensed under the MIT License