PixelOE (Detail-Oriented Pixelization)

Common errors

• ModuleNotFoundError: No module named 'pixeloe'

  cause The pixeloe library has not been installed or is not accessible in the current Python environment.
  fix Install the library using pip: `pip install pixeloe`

• AttributeError: 'numpy.ndarray' object has no attribute 'convert'

  cause You are attempting to pass a NumPy array (e.g., from OpenCV) directly to `pixeloe.pixelize`, but it expects a `PIL.Image` object.
  fix Convert your NumPy array to a PIL Image. Example: `from PIL import Image; pil_img = Image.fromarray(cv2.cvtColor(numpy_img, cv2.COLOR_BGR2RGB))`

• AttributeError: 'Image' object has no attribute 'to_numpy'

  cause You're trying to save a `PIL.Image` object returned by `pixeloe.pixelize` using a method that expects a NumPy array (e.g., `cv2.imwrite`).
  fix Save the PIL Image directly using its `save()` method: `output_pil_image.save('output.png')` or convert it to a NumPy array first if you need to use OpenCV functions: `numpy_array = np.array(pil_image)`.

Warnings

• gotcha PixelOE requires Python 3.10 or newer. Installing on older Python versions will fail or result in dependency issues.
  Fix: Ensure your Python environment is 3.10 or higher. Use `python --version` to check.
• gotcha The `pixelize` function exclusively expects a `PIL.Image` object as input. Passing NumPy arrays (common for OpenCV) or other image formats will lead to `AttributeError` or `TypeError`.
  Fix: Convert your image to a PIL Image first. E.g., for an OpenCV (NumPy) image: `pil_img = Image.fromarray(cv2.cvtColor(np_img, cv2.COLOR_BGR2RGB))`.
• gotcha Processing very large images (e.g., several megapixels) can be slow and consume significant memory due to the detailed analysis performed by the algorithm. Consider downscaling images if performance is critical.
  Fix: For performance-critical applications, pre-process large images by resizing them to a smaller resolution using `PIL.Image.resize()` before passing them to `pixeloe.pixelize()`.

Install

• pip install pixeloe Install stable release

Imports

• pixelize
  wrong:

  from pixeloe import pixelize

  correct:

  import pixeloe
  output_image = pixeloe.pixelize(...)

  While 'from pixeloe import pixelize' works, the official examples generally use 'import pixeloe' and then call 'pixeloe.pixelize' for clarity, indicating `pixelize` is the primary function within the pixeloe module.

Quickstart

This quickstart loads an image (a dummy one created for the example), applies the `pixelize` function with common parameters, and saves the resulting pixelized image. The `pixelize` function takes a `PIL.Image` object as input and returns a new `PIL.Image` object.

from PIL import Image
import pixeloe
import os

# Create a dummy image for demonstration
img_path = "example_input.png"
Image.new('RGB', (100, 100), color = 'red').save(img_path)

# Load the image
img = Image.open(img_path).convert("RGB")

# Pixelize the image with specified parameters
# pixels: size of pixelization blocks
# contrast: contrast awareness level
# outline: whether to include outlines
# levels: number of color levels to quantize to
out_img = pixeloe.pixelize(img, pixels=8, contrast=250, outline=True, levels=8)

# Save the output image
output_path = "pixelized_output.png"
out_img.save(output_path)
print(f"Original image saved to {img_path}")
print(f"Pixelized image saved to {output_path}")

# Clean up dummy image
os.remove(img_path)