Catalog¶

The parts and colors bricky knows.

The catalog keys parts and colors by their BrickLink ids. BrickLink, the LEGO Group's marketplace, lists every part. bricky catalog import imports BrickLink's catalog into a catalog file (see :mod:bricky.catalog.importing), and bricky uses the small sample shipped with it until then.

Each catalog part carries BrickLink's facts and, when bricky has one, a shape: the family that generates the part's geometry and the numbers the family needs. The catalog generates a part's geometry on first use, so a catalog of every part loads quickly.

SAMPLE_CATALOG: Final = Path(
    str(
        files("bricky.catalog").joinpath(
            "data", "sample.toml"
        )
    )
)

IMPORTED_CATALOG: Final = (
    user_data_path("bricky", appauthor=False)
    / "catalog.json"
)

Catalog(
    parts: Iterable[CatalogPart | Mapping[str, Any]] = (),
    colors: Iterable[Color] = (),
    *,
    source: str = "",
)

is_sample: bool

entries: tuple[CatalogPart, ...]

parts: tuple[Part, ...]

colors: tuple[Color, ...]

from_data(
    data: Mapping[str, Any], *, origin: str = "catalog data"
) -> Catalog

entry(part_id: str) -> CatalogPart | None

shape(part_id: str) -> Shape | None

part(part_id: str) -> Part | None

color(color_id: int) -> Color | None

resolve_color(value: int | str) -> Color

find(
    *,
    family: Family | str | None = None,
    size: tuple[int, int] | None = None,
) -> list[Part]

>>> [
...     part.id
...     for part in default_catalog().find(family="plate", size=(6, 1))
... ]
['3666']

search_colors(query: str = '') -> list[Color]

search_parts(
    query: str, *, shapeless: bool = False
) -> list[CatalogPart]

dump() -> bytes

load_catalog(path: Path) -> Catalog

default_catalog() -> Catalog

catalog_path(settings: Settings | None = None) -> Path

Catalog data types: catalog parts, shapes, generated parts, connectors and colors.

A catalog part pairs BrickLink's facts about a part (its id, name, category and the colors it comes in) with the shape bricky generates its geometry from, when bricky has one.

Part(
    id: str,
    name: str,
    family: Family,
    size: Vector,
    solids: tuple[Solid, ...],
    connectors: tuple[Connector, ...],
    note: str = "",
    category: str | None = None,
)

note: str = ''

category: str | None = None

stud_count: int

footprint: tuple[int, int]

Connector(
    kind: ConnectorKind, position: Vector, normal: Vector
)

position: Vector

normal: Vector

transformed(pose: Pose) -> Connector

STUD = 'stud'

ANTI_STUD = 'anti_stud'

mate: ConnectorKind

BOXES = 'boxes'

Build a catalog: BrickLink for what exists, names and LDraw for shapes.

Each source supplies what it knows best:

• BrickLink, the LEGO Group's marketplace, lists every part and color: ids, names, categories, and the colors each part comes in (:mod:bricky.catalog.bricklink).
• Names: a part whose official name follows a pattern, such as "Slope 45 2 x 4", gets that family's shape, exact and oriented by bricky's conventions (:mod:bricky.catalog.names).
• Printed parts take the shape of the part they are printed on.
• LDraw, the LDraw.org Parts Library, gives every other part its shape, converted into boxes and connectors (:mod:bricky.catalog.ldraw).

An import without BrickLink's downloads takes the parts from LDraw alone, with LDraw's names, and the colors from the sample catalog. The import compares the two shapes of a part that has both a shape from its name and an LDraw file. The two agree for almost every part, which checks both.

The import reports every disagreement. Where LDraw's shape only lacks anti-studs that the name gives, the part keeps its name's shape: the conversion finds anti-studs by the room under a body on a 0.8 mm grid, which misses sockets under thin and curved bodies. Any other disagreement means the name hides a detail that changes the part, so the part takes LDraw's shape.

import_catalog(
    bricklink: Downloads | None,
    ldraw: Library | None,
    progress: Progress | None = None,
) -> tuple[CatalogFile, Coverage]