pypindou.color.model

Palette and bead-color data models.

This module defines the shared schema used for domestic and international bead palette resources. Resource builders normalize upstream data into BeadColor and Palette, while pattern generation consumes the same objects for color matching and reporting.

Example:

>>> from pypindou.color.model import BeadColor, Palette
>>> palette = Palette("demo", "Demo", (BeadColor("001", (255, 255, 255)),))
>>> palette.size
1

RGB

pypindou.color.model.RGB

Tuple[int, int, int] 的别名

BeadColor

class pypindou.color.model.BeadColor(code, rgb, name=None, hex=None, group=None, source=None, unidentified=False, original_code=None, metadata=<factory>)

One color entry in a fuse-bead palette.

参数:

• code (str) -- Palette-specific bead code.

• rgb (RGB) -- RGB channel tuple in 0..255.

• name (Optional[str], optional) -- Human-readable color name, defaults to None.

• hex (Optional[str], optional) -- Hex color string. When omitted it is derived from rgb.

• group (Optional[str], optional) -- Optional upstream color group.

• source (Optional[str], optional) -- Optional source label.

• unidentified (bool, optional) -- Whether upstream marks the color as unidentified, defaults to False.

• original_code (Optional[str], optional) -- Raw upstream code before normalization, defaults to None.

• metadata (Mapping[str, Any], optional) -- Extra normalized upstream fields.

Example:

>>> BeadColor("001", (255, 255, 255)).hex
'#FFFFFF'

to_dict()

Convert this color to a JSON-serializable dictionary.

返回:

Dictionary representation using plain JSON-compatible values.

返回类型:

Dict[str, Any]

Palette

class pypindou.color.model.Palette(id, title, colors, description=None, standard='domestic', source=None, source_id=None, source_url=None, metadata=<factory>)

A named collection of bead colors.

参数:

• id (str) -- Stable palette id.

• title (str) -- Human-readable palette title.

• colors (Tuple[BeadColor, ...]) -- Palette colors in source order.

• description (Optional[str], optional) -- Optional palette description, defaults to None.

• standard (str, optional) -- Palette standard, usually "domestic" or "international", defaults to "domestic".

• source (Optional[str], optional) -- Optional source family.

• source_id (Optional[str], optional) -- Optional upstream source id.

• source_url (Optional[str], optional) -- Optional upstream URL.

• metadata (Mapping[str, Any], optional) -- Extra palette metadata.

抛出:

ValueError -- If no colors are provided or color codes are duplicated.

Example:

>>> Palette("demo", "Demo", (BeadColor("001", (1, 2, 3)),)).by_code("001").rgb
(1, 2, 3)

by_code(code)

Get a color by code.

参数:

code (str) -- Palette-specific bead code.

返回:

Matching bead color.

返回类型:

BeadColor

抛出:

KeyError -- If the code does not exist in this palette.

filter(*, include_codes=None, exclude_codes=None, allow_unidentified=False, max_colors=None)

Return a filtered palette while preserving source order.

参数:

• include_codes (Optional[Iterable[str]], optional) -- Optional allow-list of color codes.

• exclude_codes (Optional[Iterable[str]], optional) -- Optional deny-list of color codes.

• allow_unidentified (bool, optional) -- Whether to keep colors marked unidentified, defaults to False.

• max_colors (Optional[int], optional) -- Maximum number of colors to keep after filtering, defaults to None.

返回:

Filtered palette.

返回类型:

Palette

抛出:

ValueError -- If max_colors is not positive.

property size: int

Number of colors in this palette.

返回:

Palette size.

返回类型:

int

to_dict()

Convert this palette to a JSON-serializable dictionary.

返回:

Dictionary representation using plain JSON-compatible values.

返回类型:

Dict[str, Any]

rgb_to_hex

pypindou.color.model.rgb_to_hex(rgb)

Convert an RGB triplet to #RRGGBB format.

参数:

rgb (Sequence[int]) -- Three RGB channel values in 0..255.

返回:

Uppercase hex color string.

返回类型:

str

抛出:

ValueError -- If rgb does not contain exactly three valid channel values.

Example:

>>> rgb_to_hex((255, 128, 0))
'#FF8000'

hex_to_rgb

pypindou.color.model.hex_to_rgb(value)

Convert #RRGGBB or RRGGBB to an RGB triplet.

参数:

value (str) -- Hex color text.

返回:

RGB tuple.

返回类型:

RGB

抛出:

ValueError -- If the input is not a six-digit hex color.

Example:

>>> hex_to_rgb("#FF8000")
(255, 128, 0)