Models¶

The canonical model format: what a build is, stored once.

A model is a small tree: top-level elements and instances, plus the named components that instances place. The model refers to catalog parts and colors by id and never copies their data, so analyses derive everything else, such as world geometry and connections. Positions are in 0.4 mm base units, and rotations use the grid rotation names of :mod:bricky.geometry.

element_count() -> int

Reading and writing model files and their source maps.

A model file (name.bricky.json) holds the model alone. Its source map (name.bricky.map.json) records the build-script lines that placed each element and the SHA-256 of the model file it describes, so bricky detects a stale map and ignores it.

load_model(path: Path) -> Model

save_model(model: Model, path: Path) -> None

load_source_map(model_path: Path) -> Provenance | None

save_source_map(
    provenance: Provenance,
    *,
    script: Path,
    model_path: Path,
) -> Path

Fill voxels with bricks and plates, the way a builder lays courses.

Many models are easiest to describe as voxels: which color fills each stud square, one plate tall. :func:plan_fill converts such a plan into parts a script places: bricks where the three layers of a course share a color, plates everywhere else, each part as large as fits.

The courses bond. Each layer lays its parts along x or along y, alternating from layer to layer, so joints rarely line up above each other. Every part rests on at least one voxel of the layer below, so an overhang takes a part that reaches back over what holds it. Overhangs, and the squares beside them, take plates, so each layer of an overhang reaches back on its own. A voxel that no part can hold still gets a part; the checks then report it as floating.

BRICKS: Final[dict[tuple[int, int], str]] = {
    (1, 1): "3005",
    (1, 2): "3004",
    (1, 3): "3622",
    (1, 4): "3010",
    (1, 6): "3009",
    (1, 8): "3008",
    (2, 2): "3003",
    (2, 3): "3002",
    (2, 4): "3001",
    (2, 6): "2456",
    (2, 8): "3007",
    (2, 10): "3006",
}

PLATES: Final[dict[tuple[int, int], str]] = {
    (1, 1): "3024",
    (1, 2): "3023",
    (1, 3): "3623",
    (1, 4): "3710",
    (1, 6): "3666",
    (1, 8): "3460",
    (2, 2): "3022",
    (2, 3): "3021",
    (2, 4): "3020",
    (2, 6): "3795",
    (2, 8): "3034",
    (2, 10): "3832",
    (4, 4): "3031",
    (4, 6): "3032",
    (4, 8): "3035",
    (6, 6): "3958",
    (6, 8): "3036",
}

Placement(
    part: str,
    at: tuple[int, int, int],
    rotation: str,
    color: int | str,
)

at: tuple[int, int, int]

rotation: str

plan_fill(
    voxels: Mapping[tuple[int, int, int], int | str],
    *,
    made_in: MadeIn | None = None,
) -> list[Placement]

>>> wall = {(x, 0, z): "Red" for x in range(4) for z in range(3)}
>>> [(p.part, p.at, p.rotation) for p in plan_fill(wall)]
[('3010', (0, 0, 0), 'R90')]

The model as voxels: which element fills each voxel.

A voxel is one stud wide, one stud deep and one plate tall: the grid that parts are placed on. An element fills a voxel when the voxel's center lies inside its body. Every voxel of a model free of overlaps therefore belongs to at most one element, and a comparison with a target made of voxels is exact. Studs belong to no body and fill no voxel.

VoxelKey = tuple[int, int, int]

Voxel(uid: str, color: int)

uid: str

color: int

model_voxels(
    model: Model, catalog: Catalog | None = None
) -> dict[VoxelKey, Voxel]

>>> from bricky import ModelBuilder, voxels
>>> builder = ModelBuilder("wall")
>>> builder.place("3004", at=(0, 0, 0), color="Red")  # Brick 1 x 2
'e1'
>>> sorted(voxels(builder.build()))
[(0, 0, 0), (0, 0, 1), (0, 0, 2), (0, 1, 0), (0, 1, 1), (0, 1, 2)]

world_voxels(world: World) -> dict[VoxelKey, Voxel]