Smith.Kino (Smith v0.2.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 named orthographic views, rotation, zoom, edges, clipping, fullscreen, and PNG download. Colored layers can show modeling differences. They do not provide part selection, dimension editing, 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 notebook setup.

Summary

Functions

render(model, opts \\ [])

Creates an interactive preview and returns the Kino directly.

Functions

render(model, opts \\ [])

@spec render(
  OCEx.Shape.t()
  | [{Smith.Measure.source(), Smith.Render.color()}]
  | Smith.Drawing.t()
  | {:ok, Smith.Drawing.t()}
  | Smith.Model.t()
  | Smith.Path.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, path, assembly, native shape, 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; paths and edge-only recipes show sampled curves. A mixed shape with faces displays its surfaces.

A Smith.Drawing (or {:ok, drawing}) produces a responsive 2D SVG preview with fullscreen and SVG download. The drawing fills the available width; its exported millimeter dimensions remain unchanged. Drawings accept :label and the options of Smith.Drawing.svg/2. Choose their plane with Smith.Drawing.new/2; 3D camera, edge, and clipping options do not apply.

Options for 3D previews

  • :label — toolbar text, default "Smith preview".
  • :view — initial orthographic view: :isometric (default), :top, :bottom, :front, :back, :left, or :right. Top looks from +Z, front from −Y, and right from +X, matching Smith.Render.
  • :edges — show sampled native edges initially, default false.

  • :clip — {Smith.Plane.t(), :positive | :negative} to retain one side visually. This clips the preview without capping or modifying geometry. Use Smith.section/2 for a measured cross-section.

  • :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.

A list of {source, {red, green, blue}} layers creates a colored scene; RGB channels are integers from 0 through 255. This is useful for rendering the added and removed results of Smith.Inspection.compare/2. Layers are opaque. Toolbar controls select views, show edges, and move axis-aligned clipping planes. A supplied arbitrary clipping plane is also supported.

Display in Livebook

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

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

Interactive preview available in HexDocs.

Evaluation results can be piped straight into the preview:

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

Interactive preview available in HexDocs.

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.