Build a model with bricky

Work in a loop: write a build script, build it, read the report and look at the images, fix the script, and build again. Stop when the report says 0 errors, you have weighed every warning, and the images show what you meant. The report alone cannot tell you the last part.

Loop

1. Plan the footprint and height in studs and plates. One stud is 8 mm, one plate 3.2 mm, and a brick is three plates.
2. Write models/<name>.py (create models/ if needed), defining build() that returns a bricky.ModelBuilder. The scripts in examples/, also on GitHub, show the style.
3. Run uv run bricky build models/<name>.py. The command runs the script, saves the model, checks it and renders it. Where bricky is installed as a tool or with pip, run bricky without uv run.
4. Read the report, then open the image it names (models/<name>.png): perspective, front, right and top views, with rulers in studs and plates. Elements that errors name are tinted red, those that warnings name orange, and each diagnostic labels its first element with its rule.
5. Fix the script and build again.

Writing the script

from bricky import ModelBuilder


def build() -> ModelBuilder:
    builder = ModelBuilder("name")
    builder.place("3001", at=(0, 0, 0), color="Red")
    return builder

• at=(x, y, z): x east and y north in studs, z up in plates. The corner at is the minimum corner of the rotated bounding box of what you place, a part or a whole component.
• Sizes read x by y when a part is unrotated: Brick 2 x 4 (3001) is 2 studs along x and 4 along y. The rotation R90 makes it 4 along x. The commands bricky parts and bricky catalog show print sizes that way.
• rotation: R0, R90, R180 or R270 about the vertical axis, counterclockwise seen from above: R90 rotates the part's x axis to +y. Any of the 24 grid rotations can be named by where the part's x and y axes go. To stand a part up, its top then faces: +x+z → -y, -x+z → +y, +y+z → +x, -y+z → -x; +x-y rotates it upside down.
• Parts that face a way say so in uv run bricky parts slope. Unrotated, slopes fall toward -y (the front), arches span along y, and bricks with side studs list the faces their studs are on. Rotate them with rotation, for example R180 for a slope falling toward +y.
• Baseplates are half a plate thick: parts standing on one start at z = 0.5.
• Building sideways: a tile or plate rotated +x+z faces -y, so its underside grips a side stud facing -y. The example examples/cottage.py shows one, with an arch, a roof of slopes and a jumper.
• Use loops and functions for anything that repeats. Use builder.component(...) with builder.instance(...) for identical groups.
• For shapes easiest to describe as voxels (curves, domes, terrain, anything copied from a plan), build a dict {(x, y, z): color}. Then call builder.fill(voxels, id="name"), which lays bricks and plates in staggered courses, every part resting on the layer below.
• The command uv run bricky catalog show 3001 --render describes one part and renders it, with its studs and anti-studs as maps. For slopes and other parts with an uneven top, it also maps the height over each square, showing which way the part falls. Parts the catalog lists without a shape cannot be placed; bricky parts lists only parts that can be.
• Find parts with uv run bricky parts "plate 2x4" (20 at a time; --limit 100 lists more), or from Python with builder.catalog.find(family="plate", size=(1, 6)). List colors with uv run bricky colors gray, or the nearest to an RGB value with uv run bricky colors "#F2CD37"; names follow BrickLink, such as Dark Bluish Gray.
• Give important parts an id= of letters, digits, ., _ and -; the report and the images label elements by id.
• To compare with a plan or another model, use from bricky import voxels. The call voxels(builder.build()) maps every filled voxel (x, y, z), in studs, studs and plates, to the element's uid and its color id. The expression builder.catalog.resolve_color("Red").id gives a color name's id.
• Call print() freely: the build shows what the script printed.

Reading the feedback

• Every diagnostic names its elements, what they are and the script line that placed them. The by source line summary says which lines to look at first.
• From the second build on, since the last build counts the elements added, removed, changed and unchanged, by script line. A changed element keeps its id and part but has a new position, rotation or color. The same section counts the voxels filled, emptied and recolored. The sheet outlines new and changed elements in purple. Check that an edit changed what you meant, and nothing else.
• Each diagnostic names its rule, such as floating-group, and uv run bricky explain floating-group gives the exact condition behind it.
• Read positions off the orthographic views: their rulers use the same units as at.
• Look closer with uv run bricky render models/<name>.bricky.json, which writes models/<name>.<view>.png and leaves the build's sheet alone:
  • --views front --views top for single, larger views.
  • --views perspective-north-west (or -south-west, -north-east) to see the sides the south-east perspective hides.
  • --highlight "sign*" or --highlight @roof (a function of your script) to see what those parts are; everything else is rendered faintly.
  • --clip "z<130" (plates) or --clip "x<10" (studs) to clip the model open and look inside.
  • --html to write a viewer people can orbit and inspect in a browser.
• When the model is done, uv run bricky export models/<name>.bricky.json writes its parts as a BrickLink Wanted List, models/<name>.wanted.xml, to buy them on BrickLink.
• uv run bricky instructions models/<name>.bricky.json writes models/<name>.instructions.html, a page that walks people through building the model step by step.
• Every build also checks that the model stands under its own weight. The rule unbalanced-group warns of groups that tip or fall, however firmly their studs grip.
• Two stud rules are off by default, since their search takes minutes on a large model. The rule overloaded-studs names studs that need more than their clutch to hold the model. The rule strained-studs names studs that need more than half of it. For a model someone will build for real, build once with --warn overloaded-studs --warn strained-studs and fix what they report.

Building well

The advice below is yours to weigh; bricky only reports facts.

• Stagger joints between courses, like a brick wall, so every brick bridges the ones below it.
• Overhanging parts must reach back over something that holds them: floating-group reports anything that is not connected to the ground through studs.
• A long or heavy overhang needs many studs far from the edge it would rotate about. Studs in one line, or a single stud, hold little weight at a distance: overloaded-studs and strained-studs name them. Interleave plates across the joint so that more studs share the load.
• Compare the images with the subject: proportions, silhouette from each side, colors. A model with no errors can still look wrong.