Modeling in Livebook

Copy Markdown View Source

Livebook makes a model a sequence of executable, editable steps. Keep each stage in its own variable and display it with Smith.Kino.render/2. Earlier stages stay available for comparison and reuse. Changing a parameter and reevaluating dependent cells rebuilds the geometry using native OCEx operations.

Setup

Install Livebook and the pinned toolkit described in the OCEx installation guide. The Elixir runtime evaluating the notebook needs OCCT, a compiler, and its headers. Installing OCCT on your laptop does not install it in a remote or container runtime.

In the notebook's setup cell:

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

Smith brings in OCEx as a Hex dependency; no sibling checkout or dependency override is needed.

OCEx discovers Homebrew CMake even when the Livebook desktop runtime omits it from PATH. If dependency compilation already failed, restart the runtime and run setup again.

Kino is optional. Ordinary scripts and applications need only Smith. If adding Kino to an already compiled application, recompile Smith to enable the renderer. Without it, Smith.Kino.render/2 raises with reason :kino_not_available. For a notebook previously compiled without Kino, restart its runtime and use Mix.install(deps, force: true) once, then remove force: true for normal use.

Show each stage

Use separate cells for these steps. render/2 returns the Kino directly, so the render call can be the final expression in each cell:

blank = Smith.box(60, 40, 5)
Smith.Kino.render(blank, label: "1 · Blank")
rounded = blank |> Smith.fillet(edges: {:parallel, :z}, 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")

Drag to rotate and scroll to zoom. Fullscreen expands the preview to the screen while retaining the current camera and controls. Choose Exit fullscreen or press Esc to return to the notebook. The canvas resizes with the available space; Download PNG saves the view at its current canvas resolution. Reset view restores the initial camera. Fullscreen requires browser/iframe support; the button is disabled when unavailable, and a denied request displays a message. Geometry and the renderer's JavaScript are sent to your browser through Livebook. Rendering uses WebGL with no external CDN, Python process, or graphics server. Every preview includes its geometry revision.

render/2 accepts a recipe, sketch, assembly, or evaluated result. It also accepts {:ok, result}, so evaluation and assembly views can pipe directly into it:

finished
|> Smith.evaluate()
|> Smith.Kino.render(label: "Finished plate")

Passing an existing result avoids reevaluating the recipe. Preview failures raise RuntimeError with the reason, including the operation and step for modeling failures. A piped {:error, reason} raises the same error. Match on Smith.evaluate/1 before rendering when you need to handle a failure yourself.

The default mesh uses 0.03 mm linear and 0.5 rad angular deflection. Large meshes increase notebook transfer and browser memory use; raise tolerance: for a lighter preview. Camera position is local to each output and resets when that cell is reevaluated. Assembly display_offset: and exploded_offset: do not move a direct assembly preview. Use Smith.Assembly.view(result, :display) or :exploded to create a snapshot with these offsets applied, then pass that result to Smith.Kino.render/2.

Assemblies and files

An assembly preview shows installed manufactured parts. Fetch a member with Smith.Assembly.fetch/2 to inspect a reference or a printable extra individually. The initial preview has one surface color; it does not offer part selection, dimensions or material rendering. Exploded placement comes from Smith.Assembly.view/2; export the original assembly result to preserve its installed and print placements.

To generate printable files, export the evaluated result:

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

PNG is an illustration, not a fabrication file. Export produces verified STL and 3MF geometry plus STEP and reports; see exporting. Files are written on the machine running the notebook's Elixir runtime.

Runnable notebooks

Download or open these from the repository in Livebook:

The notebooks are also included under examples/ in the Hex package. Their setup cells install Smith and Kino from Hex.

The mechanical parts notebook builds a slotted plate in stages, adds blind and recessed holes, inspects selections, mirrors the result, and exports the parts with a torus and sphere.