Shadowbricks

CI Release License: MIT Python 3.11+

Two silhouettes in. One verified brick shadow sculpture out.

Shadowbricks turns a front silhouette and a side silhouette into a real layer-by-layer build made from seven common interlocking-brick sizes. It exports an LDraw model, bill of materials, printable HTML instructions, source projection preview, and a manifest that can independently prove the model still matches both shadows.

中文说明

The checked-in heart and diamond source projections

Shadow-art optimizers and voxel-to-brick converters already exist, but they leave a maker to bridge geometry, inventory, instructions, and acceptance by hand. Shadowbricks joins those stages into one deterministic local workflow:

front image + side image
 -> exact orthographic visual hull
 -> inventory-aware brick cover with layer support
 -> LDraw + BOM + HTML steps + SVG + verifiable manifest

The repository's differentiation research records adjacent projects and the limits of the search. It does not claim that similar work cannot exist.

The checked-in ×ばつ12 demo is generated by the same CLI users run:

Requirements: Python 3.11+ and uv.

git clone https://github.com/KanadeK/shadowbricks.git
cd shadowbricks
uv sync --all-groups --locked
uv run shadowbricks build \
 examples/front-heart.pbm \
 examples/side-diamond.pbm \
 --output build/heart-diamond
uv run shadowbricks verify build/heart-diamond/manifest.json

The build command refuses to overwrite an existing output path. Choose a new path when repeating the command.

To prove a finite inventory is honored, use the exact demo inventory:

uv run shadowbricks build \
 examples/front-heart.pbm \
 examples/side-diamond.pbm \
 --inventory examples/inventory-exact.json \
 --output build/heart-diamond-inventory

Every exported brick:

• names one of the documented LDraw parts;
• covers only required cells and overlaps no other brick;
• stays within the supplied finite inventory, when present; and
• above the base layer, overlaps at least one occupied stud on the layer below.

That is a precise connectivity contract, not a clutch-power, load-bearing, or drop-test certification. The verifier reconstructs coverage and both projections without trusting the build command's success message.

Use any Pillow-readable raster image. Dark pixels are foreground; transparent pixels are background. The front image defines X/Z and the side image defines Y/Z.

• Both images must have the same height.
• On each row, both images must be non-empty or both empty.
• The resulting exact visual hull must contain at least one foreground cell.
• Every axis is limited to 64 pixels and the visual hull to 50,000 cells.
• Use --threshold 0..255 to change the dark-pixel cutoff.

Portable bitmap (P1) examples are included because they remain readable in a Git diff. PNG, JPEG, and other Pillow-supported inputs work too.

v0.1 supports 3005.dat (×ばつ1), 3004.dat (×ばつ2), 3622.dat (×ばつ3), 3010.dat (×ばつ4), 3003.dat (×ばつ2), 3002.dat (×ばつ3), and 3001.dat (×ばつ4), including rotated orientations. Without --inventory, quantities are unlimited. In an inventory JSON object, omitted parts have zero availability.

shadowbricks build FRONT SIDE -o OUTPUT
 [--inventory INVENTORY.json]
 [--threshold 0..255]
 [--color 0..511]
 [--max-search-nodes POSITIVE_INT]
shadowbricks verify MANIFEST.json
shadowbricks --version

Expected domain failures return exit code 2. Unexpected defects are not swallowed.

For each model layer z, let F(z) contain foreground X coordinates in the front image and S(z) contain foreground Y coordinates in the side image. Shadowbricks creates the exact visual hull:

V = {(x, y, z) | x in F(z) and y in S(z)}

It then performs a deterministic depth-first exact cover with rectangular brick footprints, finite inventory counts, and per-brick support constraints. A visible search budget prevents an unbounded run; reaching that budget is reported separately from a proven no-cover result.

The LDraw exporter follows the official file format specification for Type 1 part references and 0 STEP commands. Package metadata and the console entry point use the PyPA pyproject.toml standard.

uv sync --all-groups --locked
uv run ruff check .
uv run mypy src tests scripts
uv run pytest --cov=shadowbricks --cov-report=term-missing --cov-fail-under=90
uv run python -m build
uv run python scripts/release_check.py

The final command repeats the quality gates, builds distributions, generates a fresh demo in a temporary directory, and verifies its manifest. See troubleshooting and repair flows when any command fails.

v0.1 deliberately excludes arbitrary light angles, more than two silhouettes, hollowing, structural physics, plates/slopes, color mosaics, a browser UI, cloud storage, telemetry, and AI image generation. The full contract is in the specification and the core architecture decision is in ADR 0001.

See CONTRIBUTING.md for the development loop. Report vulnerabilities through a private GitHub security advisory as described in SECURITY.md.

Code and original documentation are licensed under the MIT License.

LEGO® is a trademark of the LEGO Group, which does not sponsor, authorize, or endorse this project. LDrawTM is a community CAD format. Shadowbricks is an unofficial compatibility tool.