pypindou.pattern.model

Pattern data model and render helpers.

The Pattern dataclass is the main structured output of pypindou.pattern.generate_pattern(). It stores the palette-index grid, active bead mask, rendered RGB preview data, per-pixel error, and metadata that describes how the pattern was generated.

Example:

>>> import numpy as np
>>> from pypindou.color import BeadColor, Palette
>>> from pypindou.pattern.model import Pattern
>>> palette = Palette("demo", "Demo", (BeadColor("001", (255, 255, 255)),))
>>> pattern = Pattern(1, 1, palette, np.array([[0]]), np.array([[[255, 255, 255]]], dtype=np.uint8), np.ones((1, 1), dtype=bool), np.zeros((1, 1)))
>>> pattern.bead_count
1

SymbolFormat

pypindou.pattern.model.SymbolFormat: Literal['png', 'svg'] 的别名

SymbolLabelMode

pypindou.pattern.model.SymbolLabelMode: Literal['code', 'short', 'symbol'] 的别名

Pattern

class pypindou.pattern.model.Pattern(width, height, palette, indices, rgb_image, active_mask, error, metadata=<factory>)[源代码]

A bead pattern generated from one image.

参数:

width (int) -- Pattern width in beads.
height (int) -- Pattern height in beads.
palette (pypindou.color.Palette) -- Palette used by indices.
indices (numpy.ndarray) -- Palette-index grid with shape (height, width).
rgb_image (numpy.ndarray) -- Quantized RGB preview array with shape (height, width, 3).
active_mask (numpy.ndarray) -- Boolean mask of active beads.
error (numpy.ndarray) -- Per-pixel quantization error.
metadata (Mapping[str, Any], optional) -- Generation metadata, defaults to an empty mapping.

抛出:

ValueError -- If array shapes do not match width and height.

property bead_count: int

Number of active beads.

返回:: Number of active beads.
返回类型:: int

property board_size: Tuple[int, int]

Pattern grid size as (width, height).

返回:: Pattern size.
返回类型:: Tuple[int, int]

color_counts()[源代码]

Count beads by color code.

返回:: Mapping from bead color code to usage count.
返回类型:: Dict[str, int]

color_grid()[源代码]

Return the pattern grid as color codes.

返回:: Two-dimensional grid of color codes, using None for inactive cells.
返回类型:: List[List[Optional[str]]]

legend()[源代码]

Return legend rows sorted by count descending.

返回:: Legend rows with code, name, RGB, hex, count, and unidentified flag.
返回类型:: List[Dict[str, Any]]

save_symbol_chart(path, *, format=None, cell_size=24, show_grid=True, label_mode='code')[源代码]

Save a symbol chart as PNG or SVG.

When format is omitted, it is inferred from the file suffix. The PNG path uses to_symbol_image(); the SVG path uses to_symbol_svg().

参数:

path (Union[str, pathlib.Path]) -- Output path.
format (Optional[SymbolFormat], optional) -- Output format, either "png" or "svg". When omitted, the suffix of path is used.
cell_size (int, optional) -- Size of one chart cell, defaults to 24.
show_grid (bool, optional) -- Whether to draw cell borders, defaults to True.
label_mode (SymbolLabelMode, optional) -- Label text strategy, defaults to "code".

返回:

Saved output path.

返回类型:

pathlib.Path

抛出:

ValueError -- If the format cannot be inferred or is unsupported.

to_dict()[源代码]

Convert the pattern to a JSON-serializable dictionary.

返回:: Dictionary representation of the pattern.
返回类型:: Dict[str, Any]

to_image(*, scale=16, grid=True)[源代码]

Render the pattern as a preview image.

参数:

scale (int, optional) -- Pixel size of one bead cell, defaults to 16.
grid (bool, optional) -- Whether to draw cell grid lines, defaults to True.

返回:

RGB preview image.

返回类型:

PIL.Image.Image

抛出:

ValueError -- If scale is not positive.

to_symbol_image(*, cell_size=24, show_grid=True, label_mode='code')[源代码]

Render a PNG-compatible symbol map with bead-code labels.

Labels are rendered into a transparent temporary image and scaled into the padded area of each cell. This guarantees that even long color codes stay strictly inside their own cells in the returned bitmap.

参数:

cell_size (int, optional) -- Pixel size of one cell, defaults to 24.
show_grid (bool, optional) -- Whether to draw cell borders, defaults to True.
label_mode (SymbolLabelMode, optional) -- Label text strategy, defaults to "code". Use "short" for the last three code characters or "symbol" for upstream symbol metadata when available.

返回:

RGB symbol image.

返回类型:

PIL.Image.Image

抛出:

ValueError -- If cell_size is not positive or label_mode is unsupported.

to_symbol_svg(*, cell_size=24, show_grid=True, label_mode='code', font_family='DejaVu Sans Mono, Consolas, Menlo, monospace')[源代码]

Render a symbol map as SVG text.

The SVG renderer uses the same cell padding and label strategy as to_symbol_image(). Each label is placed in a per-cell clip path and receives a conservative textLength constraint, so SVG viewers cannot draw code text outside its own cell.

参数:

cell_size (int, optional) -- SVG user-unit size of one cell, defaults to 24.
show_grid (bool, optional) -- Whether to draw cell borders, defaults to True.
label_mode (SymbolLabelMode, optional) -- Label text strategy, defaults to "code".
font_family (str, optional) -- SVG font-family declaration, defaults to a monospace fallback stack.

返回:

SVG document text.

返回类型:

str

抛出:

ValueError -- If cell_size is not positive or label_mode is unsupported.

color_for_code

pypindou.pattern.model.color_for_code(pattern, code)[源代码]

Return the palette color for code in a pattern.

参数:

pattern (Pattern) -- Pattern whose palette should be queried.
code (str) -- Palette color code.

返回:

Matching bead color.

返回类型:

pypindou.color.BeadColor

抛出:

KeyError -- If the code is not present in the pattern palette.