Modeling in Livebook

Livebook lets you edit a model one stage at a time and inspect each result. This guide covers setup and previews. The lessons below teach modeling; you do not need to read every feature guide before starting the first one.

Setup

Install Livebook and the toolkit described in the OCEx installation guide. The runtime executing the notebook needs the toolkit, compiler, and OTP headers. For a remote runtime, install them on that machine.

Mix.install([{:smith, "~> 0.4.0"}, {:kino, "~> 0.19.0"}])

Run this in the setup cell. Smith brings OCEx in as a dependency. Kino provides Livebook outputs; ordinary modeling scripts do not need it. After changing native code or dependencies, restart the runtime and reevaluate setup. When compilation fails, read the native error above Mix's dependency summary. The installation guide covers missing tools, headers, and Xcode license acceptance.

If the runtime already compiled Smith without Kino, rebuild once with Mix.install(deps, force: true), then remove force: true for normal use. The release notebooks use Hex dependencies; local development can replace Smith with a path dependency and add a local OCEx override in setup.

Show each stage

Put each block in its own cell. Recipes are ordinary Elixir values, and each operation returns a new one. A fillet rounds edges; a hole removes material. See CAD concepts for unfamiliar terms.

blank = Smith.box(60, 40, 5)
Smith.Kino.render(blank, label: "1 · Blank")

rounded = blank |> Smith.fillet(edges: {:parallel, :z}, count: 4, radius: 2)
Smith.Kino.render(rounded, label: "2 · Rounded corners")

finished = rounded |> Smith.hole(on: :top, diameter: 8, through: :all)
{:ok, result} = Smith.evaluate(finished)
Smith.Kino.render(result, label: "3 · Drilled plate")

render/2 returns the Kino directly, so leave it as the cell's final expression. It accepts recipes, sketches, paths, native shapes, assemblies, evaluated results, and tagged {:ok, result} values. For example, finished |> Smith.evaluate() |> Smith.Kino.render() displays the result. Match on evaluation first when you also need the result for measurements or export. Rendering errors raise with the failed operation and reason.

Inspect the preview

Drag to orbit and scroll to zoom. View chooses a standard orthographic view; Edges shows native boundaries. Open Clipping to choose a plane, move the cut with the position slider, or flip the visible side. Clipping reveals interior surfaces without modifying or capping geometry. Use Smith.section/2 when you need an actual measurable cross-section.

Fullscreen expands the output; Esc returns to the notebook. Download PNG saves the current 3D view. The toolbar buttons have tooltips with these names. Each output has its own camera and clipping settings, which reset when the output is replaced. The renderer uses WebGL in your browser; no separate graphics server is needed.

Set the initial view explicitly when it helps explain a feature:

Smith.Kino.render(result, label: "Hole from above", view: :top, edges: true)

Top looks from +Z, front from −Y, and right from +X. These are world directions; Smith does not infer the front of a product. The default preview mesh uses 0.03 mm linear and 0.5 rad angular deflection. Larger tolerance: values can make large previews lighter without changing the native geometry.

Reuse an evaluated stage

Rendering a recipe evaluates it. Evaluating the same recipe again repeats that work. When an expensive stage feeds several operations, keep its result and branch with Smith.from_result/1:

blank_snapshot = Smith.from_result(result)
upper = Smith.split(blank_snapshot, Smith.Plane.xy(z: 2.5), keep: :positive)
Smith.Kino.render(upper, label: "Upper half from the existing geometry")

Keep the original recipe as the editable source. A snapshot holds native geometry in this runtime; it does not update itself or survive a runtime restart. After editing upstream parameters, reevaluate the affected cells in order.

Drawings and colored stages

Drawings also use Smith.Kino.render/2. The preview fits the complete drawing within the output area, with fullscreen and SVG download controls. Display size does not change the exported dimensions.

{:ok, width} = Smith.Measure.extent(result, :x)
{:ok, drawing} = Smith.Drawing.new(result, on: :xy)
{:ok, drawing} = Smith.Drawing.dimension(drawing, width, orientation: :horizontal, offset: -8)
Smith.Kino.render(drawing, label: "Measured plate", hidden: false)

For a colored 3D scene, pass [{source, {red, green, blue}}, ...]. The inspection lesson uses this to distinguish added and removed material. Layers are opaque; orbit or clip to see hidden areas. These colors are presentation choices, not assembly material assignments.

Assemblies and files

A direct assembly preview shows installed manufactured parts. Fetch a reference with Smith.Assembly.fetch/2 to include it in a colored scene. For display offsets or an exploded arrangement, pass Smith.Assembly.view(result, :display) or :exploded into the renderer. Export the original assembly to retain its part names and print placements.

{:ok, files} = Smith.export(result, "output", name: "plate", on_bed: true)
files.three_mf

Files are written on the runtime's machine. PNG and SVG show views; STL and 3MF contain printable geometry. See exporting for verification and print orientation.

Choose a lesson

The SVG artwork notebook imports a local SVG, previews its CAD regions, and builds a personalized volleyball keychain with raised or engraved detail.

The notebooks are included in the Hex package's examples/ directory and shown in HexDocs. Open their .livemd source in Livebook to edit and run the cells. Within each group, the order below moves from simpler concepts to larger models.

The enclosure is the complete design walkthrough. The phone is an advanced study with an unresolved edge-roll defect and incompletely specified camera surfaces; it is not yet an accurate case-fit reference. Both distinguish model checks from physical print testing.