pypindou.image.preprocess

Image loading and preprocessing helpers.

This module keeps image preparation independent from palette quantization. The high-level pypindou.pattern.generate_pattern() API uses these helpers to load user images, remove transparent background noise, resize to a bead grid, and optionally apply lightweight photographic adjustments before color matching.

Example:

>>> from PIL import Image
>>> from pypindou.image.preprocess import enhance_image, resize_image
>>> image = Image.new("RGBA", (16, 16), (200, 120, 80, 255))
>>> resize_image(enhance_image(image, contrast=1.1), (8, 8)).size
(8, 8)

FitMode

pypindou.image.preprocess.FitMode

Literal['contain', 'cover', 'stretch'] 的别名

BackgroundMode

pypindou.image.preprocess.BackgroundMode

Literal['keep', 'white', 'transparent'] 的别名

ResampleMode

pypindou.image.preprocess.ResampleMode

Literal['nearest', 'box', 'bilinear', 'bicubic', 'lanczos'] 的别名

PreprocessMode

pypindou.image.preprocess.PreprocessMode

Literal['none', 'smooth', 'median', 'edge'] 的别名

load_image

pypindou.image.preprocess.load_image(image)[源代码]

Load an image as RGBA.

参数:

image (Union[str, pathlib.Path, PIL.Image.Image]) -- Source image, image path, or PIL.Image.Image.

返回:

Loaded image converted to RGBA mode.

返回类型:

PIL.Image.Image

抛出:

FileNotFoundError -- If image is a path and does not exist.

Example:

>>> from PIL import Image
>>> load_image(Image.new("RGB", (1, 1))).mode
'RGBA'

resize_image

pypindou.image.preprocess.resize_image(image, size, *, fit='contain', background=(255, 255, 255, 0), resample='lanczos')[源代码]

Resize an image to a bead-grid size.

contain preserves the full image and pads the remaining grid with background. cover fills the grid and crops overflow from the center. stretch ignores the source aspect ratio.

参数:

  • image (PIL.Image.Image) -- Source image.

  • size (Tuple[int, int]) -- Target size as (width, height).

  • fit (FitMode, optional) -- Aspect-ratio strategy, defaults to "contain".

  • background (Tuple[int, int, int, int], optional) -- RGBA background used by contain, defaults to (255, 255, 255, 0).

  • resample (ResampleMode, optional) -- Pillow resampling strategy, defaults to "lanczos".

返回:

Resized RGBA image.

返回类型:

PIL.Image.Image

抛出:

ValueError -- If size is not positive or fit/resample is unsupported.

Example:

>>> from PIL import Image
>>> resize_image(Image.new("RGBA", (10, 20)), (5, 5)).size
(5, 5)

enhance_image

pypindou.image.preprocess.enhance_image(image, *, brightness=1.0, contrast=1.0, saturation=1.0, sharpness=1.0, grayscale=0.0)[源代码]

Apply lightweight photographic adjustments while preserving alpha.

Adjustment factors follow Pillow's PIL.ImageEnhance convention: 1.0 leaves the channel unchanged, values below 1.0 reduce the effect, and values above 1.0 increase it. grayscale is a blend ratio from the adjusted RGB image to its grayscale version.

参数:

  • image (PIL.Image.Image) -- Source image.

  • brightness (float, optional) -- Brightness factor, defaults to 1.0.

  • contrast (float, optional) -- Contrast factor, defaults to 1.0.

  • saturation (float, optional) -- Color saturation factor, defaults to 1.0.

  • sharpness (float, optional) -- Sharpness factor, defaults to 1.0.

  • grayscale (float, optional) -- Grayscale blend ratio in [0.0, 1.0], defaults to 0.0.

返回:

Adjusted RGBA image.

返回类型:

PIL.Image.Image

抛出:

ValueError -- If a factor is negative or grayscale is outside [0.0, 1.0].

Example:

>>> from PIL import Image
>>> enhance_image(Image.new("RGBA", (2, 2)), contrast=1.2).mode
'RGBA'

prefilter_image

pypindou.image.preprocess.prefilter_image(image, *, mode='none', radius=1.0)[源代码]

Denoise or sharpen an image before it is resized to the bead grid.

smooth applies a mild Gaussian blur, median removes isolated sensor/compression speckles, and edge combines median filtering with a light unsharp mask. The alpha channel is preserved unchanged.

参数:

  • image (PIL.Image.Image) -- Source image.

  • mode (PreprocessMode, optional) -- Pre-filtering strategy, defaults to "none".

  • radius (float, optional) -- Filter radius or median radius, defaults to 1.0.

返回:

Filtered RGBA image.

返回类型:

PIL.Image.Image

抛出:

ValueError -- If radius is negative or mode is unsupported.

Example:

>>> from PIL import Image
>>> prefilter_image(Image.new("RGBA", (4, 4)), mode="median").size
(4, 4)

remove_background_by_alpha

pypindou.image.preprocess.remove_background_by_alpha(image, *, alpha_threshold=16)[源代码]

Set low-alpha pixels to fully transparent.

参数:

  • image (PIL.Image.Image) -- Source image.

  • alpha_threshold (int, optional) -- Pixels with alpha at or below this value become fully transparent, defaults to 16.

返回:

RGBA image with low-alpha pixels cleared.

返回类型:

PIL.Image.Image

抛出:

ValueError -- If alpha_threshold is outside [0, 255].

Example:

>>> from PIL import Image
>>> img = Image.new("RGBA", (1, 1), (1, 2, 3, 0))
>>> remove_background_by_alpha(img).getpixel((0, 0))
(0, 0, 0, 0)

rgba_to_rgb_array

pypindou.image.preprocess.rgba_to_rgb_array(image, *, background='white', alpha_threshold=16)[源代码]

Convert an RGBA image to an RGB array and an active-pixel mask.

参数:

  • image (PIL.Image.Image) -- Source image.

  • background (BackgroundMode, optional) -- Alpha handling strategy, defaults to "white".

  • alpha_threshold (int, optional) -- Alpha threshold used by transparent mode, defaults to 16.

返回:

RGB uint8 array and boolean active-pixel mask.

返回类型:

Tuple[numpy.ndarray, numpy.ndarray]

抛出:

ValueError -- If background is unsupported.

Example:

>>> from PIL import Image
>>> rgb, active = rgba_to_rgb_array(Image.new("RGBA", (1, 1)))
>>> rgb.shape, active.shape
((1, 1, 3), (1, 1))