Skip to content

Rendering

The renderer resolves a model into a scene of plain data, then renders that scene in headless Chromium or a standalone viewer.

scene

Scenes: a model resolved into the boxes, meshes, studs, colors and marks to render.

A scene is plain data in base units (0.4 mm), laid out as compact arrays so a large model crosses into the browser quickly. An element made only of boxes appears as boxes. An element with other solids, such as a slope or a round part, appears as a mesh: its corners, its faces and the edges worth outlining. :func:build_scene is pure Python, and :mod:bricky.render.browser renders its result.

Scene

Everything to render, in base units (0.4 mm).

View

One image of a scene.

SHEET class-attribute instance-attribute 

SHEET = 'sheet'

The perspective, front, right and top views on one image.

PERSPECTIVE class-attribute instance-attribute 

PERSPECTIVE = 'perspective'

In perspective, from above the south-east.

PERSPECTIVE_SOUTH_WEST class-attribute instance-attribute 

PERSPECTIVE_SOUTH_WEST = 'perspective-south-west'

In perspective, from above the south-west.

PERSPECTIVE_NORTH_WEST class-attribute instance-attribute 

PERSPECTIVE_NORTH_WEST = 'perspective-north-west'

In perspective, from above the north-west.

PERSPECTIVE_NORTH_EAST class-attribute instance-attribute 

PERSPECTIVE_NORTH_EAST = 'perspective-north-east'

In perspective, from above the north-east.

FRONT class-attribute instance-attribute 

FRONT = 'front'

Orthographic, looking north, with x and z rulers.

BACK class-attribute instance-attribute 

BACK = 'back'

Orthographic, looking south, with x and z rulers.

LEFT class-attribute instance-attribute 

LEFT = 'left'

Orthographic, looking east, with y and z rulers.

RIGHT class-attribute instance-attribute 

RIGHT = 'right'

Orthographic, looking west, with y and z rulers.

TOP class-attribute instance-attribute 

TOP = 'top'

Orthographic plan, north up, with x and y rulers.

Clip

A plane and the side of it that a render keeps, to look inside a model.

parse classmethod 

parse(text: str) -> Clip

Parse a clip such as "z<130" or "x>=12".

A clip on z counts in plates, and a clip on x or y in studs.

Raises:

Type Description
BrickyError

If the text is not a clip or lands off the grid.

Flag

How the renderer shows an element.

HIGHLIGHT class-attribute instance-attribute 

HIGHLIGHT = 1

Chosen by a highlight selector.

GHOST class-attribute instance-attribute 

GHOST = 2

Rendered faintly: outside a highlight, and named by no error or warning.

ERROR class-attribute instance-attribute 

ERROR = 4

Named by an error.

WARNING class-attribute instance-attribute 

WARNING = 8

Named by a warning.

CHANGED class-attribute instance-attribute 

CHANGED = 16

New or changed since the last build.

Label

Text pinned to an element.

Mark

A diagnostic's region: a box outlined over everything else.

Mesh

An element rendered by its faces, for an element with solids other than boxes.

SceneColor

A color the scene uses.

build_scene 

build_scene(
    model: Model,
    catalog: Catalog,
    *,
    provenance: Provenance | None = None,
    report: Report | None = None,
    highlight: Sequence[str] = (),
    clips: Sequence[Clip] = (),
    changed: Sequence[str] = (),
    cull: bool = True,
    instructions: Instructions | None = None,
) -> Scene

Resolve a model into the scene to render.

Parameters:

Name Type Description Default
model Model

The model.

 required
catalog Catalog

The catalog that resolves parts and colors.

 required
provenance Provenance | None

The script lines that placed each element; @ selectors need it.

 None
report Report | None

A report whose errors and warnings mark the elements they name.

 None
highlight Sequence[str]

Selectors of the elements to highlight; the renderer shows the rest faintly. A selector is a uid pattern such as "sign*" or "i2/*", or @ followed by a function name, a file, or a file and line of the build script, such as "@roof" or "@cottage.py:151".

 ()
clips Sequence[Clip]

The clips that keep part of the model, to look inside it.

 ()
changed Sequence[str]

The uids of elements new or changed since the last build, to mark.

 ()
cull bool

Whether to leave out faces pressed against opaque neighbors. A viewer that clips the model interactively sets it to false, as clipping can bring buried faces into view.

 True
instructions Instructions | None

The steps to build the model, for a viewer to show one by one. Each step reveals the studs the next steps cover, so the scene then keeps every stud.

 None

Raises:

Type Description
BrickyError

If the model has no element to render, a selector matches nothing, or the clips keep nothing.

Renderer 

Renderer(browser: Path | None = None)

Renders scenes with three.js in headless Chromium.

Launching the browser and compiling shaders take the most time, so a renderer keeps one page open for every render. A renderer starts once and serves many renders, as an async context manager or through :meth:start and :meth:close. Renders on one renderer run one at a time.

Create a renderer.

Parameters:

Name Type Description Default
browser Path | None

The Chromium executable to use; Playwright's own browser when None.

 None

start async 

start() -> None

Launch the browser, unless it is already running.

Raises:

Type Description
BrickyError

If Chromium cannot be started.

close async 

close() -> None

Close the page and the browser.

render async 

render(
    scene: Scene,
    views: Sequence[View],
    *,
    width: int,
    height: int,
) -> list[bytes]

Render each view of a scene and return PNG images, in the same order.

Raises:

Type Description
BrickyError

If the browser cannot start or the page fails to render.

write_html 

write_html(
    scene: Scene,
    path: Path,
    downloads: Sequence[Download] = (),
    *,
    heading: str | None = None,
    mode: Literal["explore", "instructions"] = "explore",
) -> Path

Write a standalone HTML viewer for a scene and return its path.

Parameters:

Name Type Description Default
scene Scene

The scene to view.

 required
path Path

The file to write.

 required
downloads Sequence[Download]

Files the viewer offers to download, such as the model's exports.

 ()
heading str | None

The model's name as people read it; by default, the model's name with spaces for hyphens and a capital first letter.

 None
mode Literal['explore', 'instructions']

What the page opens on: the model to explore, or its first building step, which needs a scene with steps.

 'explore'

Raises:

Type Description
BrickyError

If the file cannot be written.