Smith.Kino (Smith v0.1.0)

Copy Markdown View Source

Interactive 3D previews for Livebook through Kino.JS.

Add Kino alongside Smith in the notebook setup. render/2 returns a Kino directly; leave the call as the last expression in a Livebook cell. Each output holds an independent mesh snapshot with its own camera.

The renderer and controls are Smith's JavaScript/WebGL code. Kino supplies Livebook's asset and data integration; OCEx supplies the mesh. Rendering does not use a CDN or a server-side graphics process.

Previews support rotation, zoom, fullscreen, and PNG download. They show one surface color and do not provide part selection, dimensions, or automatic exploded assembly views. Use Smith.Assembly.view/2 to create a display or exploded snapshot before rendering. See the Livebook guide for stage-by-stage examples and local dependency setup.

Summary

Functions

render(model, opts \\ [])

Creates an interactive preview and returns the Kino directly.

Functions

render(model, opts \\ [])

@spec render(
  Smith.Model.t()
  | Smith.Sketch.t()
  | Smith.Assembly.t()
  | Smith.Result.t()
  | Smith.Assembly.Result.t()
  | {:ok, Smith.Result.t() | Smith.Assembly.Result.t()}
  | {:error, term()},
  keyword()
) :: Kino.JS.t()

Creates an interactive preview and returns the Kino directly.

Accepts a model, sketch, assembly, evaluated result, or {:ok, result} from Smith.evaluate/1 or Smith.Assembly.view/2. Recipes are evaluated on each call; passing an existing result skips that step. The shape is then meshed into a snapshot. Assemblies show installed manufactured parts only. Sketches show their faces; edge-only recipes have no triangle surface to display.

Options

  • :label — toolbar text, default "Smith preview".
  • :tolerance — linear mesh deflection in mm, default 0.03.
  • :angular_tolerance — angular mesh deflection in radians, default 0.5.

Deflections must satisfy OCEx's native minimum (greater than 1.0e-7). Invalid options, evaluation failures, and meshing failures raise RuntimeError with the failure reason. Passing {:error, reason} raises the same error; modeling failures include the Smith.Error fields, such as operation and step. To handle modeling failures yourself, match on Smith.evaluate/1 before rendering. The preview does not run the print export checks.

Display in Livebook

Leave the render call as the cell's last expression:

iex> preview = Smith.Kino.render(Smith.box(20, 10, 4), label: "Blank")
iex> is_struct(preview, Kino.JS)
true

Evaluation results can be piped straight into the preview:

iex> Smith.box(20, 10, 4) |> Smith.evaluate() |> Smith.Kino.render() |> is_struct(Kino.JS)
true

Use Kino.render/1 to display an additional preview before the cell's final expression. Drag to rotate, scroll to zoom, and use the toolbar for fullscreen or PNG download. PNG captures the current browser canvas; there is no server-side image renderer.

Optional dependency

Smith must be compiled with Kino available. Otherwise this raises RuntimeError with reason :kino_not_available. Add {:kino, "~> 0.19.0"} to the same dependency list and rebuild Smith. In a notebook, restart the runtime and run Mix.install(deps, force: true) once if Smith was previously compiled without Kino.