pypindou.image.quantize

Image quantization against bead palettes.

The quantizers in this module map RGB pixels to indices in a pypindou.color.Palette. The high-level pattern generator uses the same result structure for direct nearest-color matching and Floyd-Steinberg dithering, then optionally runs post-processing that makes the final bead grid more practical for manual assembly.

Example:

>>> import numpy as np
>>> from pypindou.color import BeadColor, Palette
>>> from pypindou.image.quantize import quantize_image
>>> palette = Palette("bw", "Black/White", (BeadColor("K", (0, 0, 0)), BeadColor("W", (255, 255, 255))))
>>> result = quantize_image(np.array([[[250, 250, 250]]], dtype=np.uint8), np.ones((1, 1), dtype=bool), palette)
>>> result.indices.tolist()
[[1]]

QuantizeMethod

pypindou.image.quantize.QuantizeMethod

Literal['nearest', 'floyd-steinberg'] 的别名

CleanupMode

pypindou.image.quantize.CleanupMode

Literal['none', 'majority'] 的别名

QuantizationResult

class pypindou.image.quantize.QuantizationResult(indices, active_mask, rgb_image, error)

Result of mapping an image to palette indices.

参数:

• indices (numpy.ndarray) -- Integer palette-index grid, using -1 for inactive pixels.

• active_mask (numpy.ndarray) -- Boolean mask that marks beads included in the pattern.

• rgb_image (numpy.ndarray) -- Quantized RGB preview image.

• error (numpy.ndarray) -- Per-pixel root mean square RGB error.

nearest_indices

pypindou.image.quantize.nearest_indices(pixels, palette, *, color_space='lab')

Map (n, 3) RGB pixels to nearest palette indices.

参数:

• pixels (numpy.ndarray) -- RGB pixels with shape (n, 3).

• palette (pypindou.color.Palette) -- Palette used for matching.

• color_space (pypindou.color.ColorSpace, optional) -- Distance space, defaults to "lab".

返回:

Palette indices and per-pixel RMS RGB error.

返回类型:

Tuple[numpy.ndarray, numpy.ndarray]

Example:

>>> import numpy as np
>>> from pypindou.color import BeadColor, Palette
>>> palette = Palette("p", "P", (BeadColor("R", (255, 0, 0)), BeadColor("B", (0, 0, 255))))
>>> nearest_indices(np.array([[250, 0, 0]], dtype=np.uint8), palette, color_space="rgb")[0].tolist()
[0]

reduce_palette_for_image

pypindou.image.quantize.reduce_palette_for_image(rgb, active_mask, palette, *, max_colors, color_space='lab', random_state=0)

Choose a palette subset for one image.

Dominant colors are estimated from active image pixels and then snapped to the nearest real bead colors. The result is useful for human-friendly charts where the number of colors should be capped before final quantization.

参数:

• rgb (numpy.ndarray) -- Source RGB image with shape (h, w, 3).

• active_mask (numpy.ndarray) -- Boolean active-pixel mask with shape (h, w).

• palette (pypindou.color.Palette) -- Source palette.

• max_colors (Optional[int]) -- Maximum number of colors to keep. None keeps the original palette.

• color_space (pypindou.color.ColorSpace, optional) -- Distance space, defaults to "lab".

• random_state (int, optional) -- Random seed for MiniBatchKMeans, defaults to 0.

返回:

Filtered palette.

返回类型:

pypindou.color.Palette

抛出:

ValueError -- If max_colors is not positive.

cleanup_quantization

pypindou.image.quantize.cleanup_quantization(indices, active_mask, *, mode='majority', passes=1, threshold=5)

Smooth isolated palette-index noise after quantization.

The majority cleaner looks at the 8-neighborhood of every active pixel and replaces the current index when at least threshold neighbors agree on a different color. It is intentionally conservative: inactive pixels and boundaries are preserved.

参数:

• indices (numpy.ndarray) -- Palette-index grid, using -1 for inactive pixels.

• active_mask (numpy.ndarray) -- Boolean active-pixel mask.

• mode (CleanupMode, optional) -- Cleanup strategy, defaults to "majority".

• passes (int, optional) -- Number of cleanup passes, defaults to 1.

• threshold (int, optional) -- Minimum equal-neighbor count needed to replace one pixel, defaults to 5.

返回:

Cleaned palette-index grid.

返回类型:

numpy.ndarray

抛出:

ValueError -- If arguments are outside supported ranges.

Example:

>>> import numpy as np
>>> grid = np.array([[1, 1, 1], [1, 0, 1], [1, 1, 1]], dtype=np.int32)
>>> cleanup_quantization(grid, np.ones((3, 3), dtype=bool), threshold=5).tolist()
[[1, 1, 1], [1, 1, 1], [1, 1, 1]]

merge_small_regions

pypindou.image.quantize.merge_small_regions(indices, active_mask, *, min_size=0, connectivity=4)

Merge tiny connected components into neighboring colors.

Components smaller than min_size are replaced with the most frequent neighboring palette index around the component. This reduces single-bead islands without requiring any image-domain dependencies.

参数:

• indices (numpy.ndarray) -- Palette-index grid, using -1 for inactive pixels.

• active_mask (numpy.ndarray) -- Boolean active-pixel mask.

• min_size (int, optional) -- Minimum region size to preserve. 0 disables merging, defaults to 0.

• connectivity (int, optional) -- Neighbor connectivity, either 4 or 8, defaults to 4.

返回:

Region-cleaned palette-index grid.

返回类型:

numpy.ndarray

抛出:

ValueError -- If shapes or argument values are invalid.

quantize_image

pypindou.image.quantize.quantize_image(rgb, active_mask, palette, *, method='nearest', color_space='lab', dither_strength=1.0, cleanup='none', cleanup_passes=0, cleanup_threshold=5, min_region_size=0)

Quantize an RGB image to bead palette indices.

nearest maps every active pixel independently. floyd-steinberg diffuses quantization error to later pixels and accepts dither_strength in [0.0, 1.0]. Cleanup runs after quantization and is intended to make human assembly easier.

参数:

• rgb (numpy.ndarray) -- Source RGB image with shape (h, w, 3).

• active_mask (numpy.ndarray) -- Boolean active-pixel mask.

• palette (pypindou.color.Palette) -- Palette used for matching.

• method (QuantizeMethod, optional) -- Quantization method, defaults to "nearest".

• color_space (pypindou.color.ColorSpace, optional) -- Distance space, defaults to "lab".

• dither_strength (float, optional) -- Floyd-Steinberg diffusion strength in [0.0, 1.0], defaults to 1.0.

• cleanup (CleanupMode, optional) -- Post-quantization cleanup mode, defaults to "none".

• cleanup_passes (int, optional) -- Number of cleanup passes, defaults to 0.

• cleanup_threshold (int, optional) -- Majority threshold, defaults to 5.

• min_region_size (int, optional) -- Regions smaller than this value are merged into neighboring colors, defaults to 0.

返回:

Quantization result.

返回类型:

QuantizationResult

抛出:

ValueError -- If inputs or options are invalid.