Fresco.Canvas (fresco v0.6.2)

Copy Markdown View Source

<Fresco.canvas> — a layered scene of N images positioned at absolute coordinates on a virtual canvas, plus an open extensions map for annotation tools (future Etcher), ML overlays, and other peer packages.

Single-image is just the N=1 case — use Fresco.Viewer when you want the bare "pan/zoom one image" component without the scene-document overhead.

The .fresco file format

Serializing a canvas yields a JSON document keyed by:

{
  "version": "1",
  "canvas": { "width": 4000, "height": 3000, "background": null },
  "images": [
    {
      "id": "img-1",
      "src": "/uploads/a.jpg",
      "x": 0, "y": 0,
      "width": 2000,
      "z_index": 0,
      "natural_width": 2000,
      "natural_height": 1500
    }
  ],
  "extensions": {
    "etcher":     { "version": "1", "annotations": [...] },
    "ml-overlay": { ... }
  }
}
  • canvas.width / canvas.height — the virtual canvas extent in canvas pixels. Reset-view fits this rectangle to the viewport.
  • Images are positioned at absolute canvas-pixel (x, y) with width in canvas pixels. Height is derived from natural aspect ratio if natural_width and natural_height are present (and saved into the file for forward compatibility).
  • extensions is an open map keyed by package name. Fresco never inspects the inside — each extension owns its own shape and version. Unknown extension keys are preserved verbatim across read/write so you can load → edit → save without losing data the current version doesn't understand.
  • Read-time forward-compatibility: any unknown top-level or per-image key is preserved through a private __extra__ map and re-merged on write. A v1 reader of a future v2 file keeps the v2 fields it doesn't understand and writes them back unchanged.

Building a canvas

iex> canvas =
...>   Fresco.Canvas.new(width: 4000, height: 3000)
...>   |> Fresco.Canvas.add_image(%{src: "/a.jpg", x: 0, y: 0, width: 2000})
...>   |> Fresco.Canvas.add_image(%{src: "/b.jpg", x: 2100, y: 0, width: 1800})
...>   |> Fresco.Canvas.put_extension("etcher", %{"version" => "1", "annotations" => []})
iex> Enum.map(canvas.images, & &1.id)
["img-1", "img-2"]

File I/O

Fresco.Canvas.write!("/tmp/scene.fresco", canvas)
canvas = Fresco.Canvas.read!("/tmp/scene.fresco")

Writes are atomic: write/2 writes to <path>.tmp then renames, so an interrupted save can't corrupt an existing file.

Extension contract — passive Fresco

Fresco is passive with respect to extensions. The file is the source of truth; updates flow consumer LiveView → %Fresco.Canvas{} in assigns → re-render. A peer package like the future Etcher reads its initial state via handle.getExtension("etcher") at mount, pushes edits to its own LiveView, which calls Fresco.Canvas.put_extension(canvas, "etcher", new_data) and re-assigns. Fresco's handle is intentionally read-only for extensions — no setExtension method exists, so save timing is never racing with annotation updates over channels.

See Fresco.Viewer for the simpler single-image component, and Fresco.ScrollStrip for the long-scroll reader counterpart.

Summary

Types

image()
t()

Functions

add_image(canvas, attrs)

Append an image to the canvas.

canvas(assigns)

Renders a Fresco canvas — N images positioned at absolute coordinates on a virtual canvas, with pan/zoom/fit/fullscreen identical to Fresco.viewer. Hooks the FrescoCanvas JS controller.

from_json(json)

Parse a JSON string into a canvas struct. Returns {:ok, canvas} or {:error, %Fresco.Canvas.SchemaError{}}.

from_json!(json)

Parse a JSON string into a canvas struct. Raises on invalid input.

new(opts \\ [])

Build a new empty canvas.

put_extension(canvas, name, value)

Put or overwrite an extension blob keyed by name (binary or atom).

read(path)

Read a canvas from disk. Returns {:ok, canvas} or {:error, reason}.

read!(path)

Read a canvas from disk. Raises on failure.

to_json(canvas)

Serialize a canvas to a JSON string. Returns {:ok, json} or {:error, reason} (only on Jason encode failure — schema is validated at struct-construction time).

to_json!(canvas)

Serialize a canvas to a JSON string. Raises on encode failure.

write(path, canvas)

Write a canvas to disk atomically. Writes to <path>.tmp first then renames so an interrupted save can't corrupt the existing file.

write!(path, canvas)

Write a canvas to disk atomically. Raises on failure.

Types

image()

@type image() :: %{
  :id => String.t(),
  :src => String.t(),
  :x => number(),
  :y => number(),
  :width => number(),
  optional(:z_index) => integer(),
  optional(:natural_width) => number(),
  optional(:natural_height) => number(),
  optional(:__extra__) => map()
}

t()

@type t() :: %Fresco.Canvas{
  __extra__: map(),
  canvas: %{
    :width => number(),
    :height => number(),
    optional(:background) => String.t() | nil
  },
  extensions: %{optional(String.t()) => any()},
  images: [image()],
  version: String.t()
}

Functions

add_image(canvas, attrs)

Append an image to the canvas.

Required attrs: :src (string URL/path), :x, :y, :width (numbers, width > 0). Optional: :id (auto-assigned img-N when omitted), :z_index, :natural_width, :natural_height.

Raises ArgumentError on invalid attrs.

canvas(assigns)

Renders a Fresco canvas — N images positioned at absolute coordinates on a virtual canvas, with pan/zoom/fit/fullscreen identical to Fresco.viewer. Hooks the FrescoCanvas JS controller.

Coordinate space

Everything addressed through the canvas handle — fitBounds, screenToImage / imageToScreen, the canvas extent reported by getCanvasSize(), and any geometry persisted by peer libraries (Etcher shape geometry, ML overlay boxes) — is in canvas-pixel space: a single coordinate system that spans every image on the canvas, sized in the canvas's internal pixels (the :width / :height of the :canvas field on the %Fresco.Canvas{} struct).

This is distinct from the per-image source-pixel space used by <Fresco.scroll_strip> / <FrescoStrip.viewer>, where geometry lives in each image's natural-pixel grid. Code consuming geometry off either viewer should know which space it's working in.

Attributes

  • id (:string) (required) - DOM id; must be unique on the page.

  • canvas (Fresco.Canvas) (required) - A %Fresco.Canvas{} struct describing the scene: virtual canvas extent, the list of images with their canvas-pixel positions, and an open extensions map. Build one via Fresco.Canvas.new/1 + Fresco.Canvas.add_image/2, or load one from a .fresco file via Fresco.Canvas.read!/1.

  • class (:string) - CSS classes for the canvas host container. Defaults to "w-full h-96".

  • infinite_canvas (:boolean) - When true, drops the default "canvas must cover viewport" clamp so the user can pan freely beyond the canvas edges and zoom out until the whole layout is a thumbnail in the middle of an empty workspace.

    Defaults to false.

  • theme (:atom) - Color scheme. Same semantics as Fresco.viewer's :theme. Defaults to :system. Must be one of :system, :light, :dark, or :inherit.

  • zoom_floor (:float) - Optional minimum zoom scale, in engine units (screen-px-per-canvas-px). When set, the engine clamps every zoom path — wheel, pinch, double-click, fitBounds — at this floor. nil (default) falls through to the engine's normal floor (sFit clamped mode, sFit * 0.05 infinite-canvas mode).

    Most often set at runtime via handle.setZoomFloor(scale) — paged readers recompute it each time the user navigates to a new page so the floor tracks the current page's fit-to-viewport scale, not the whole-canvas fit.

    Defaults to nil.

  • zoom_ceiling (:float) - Optional maximum zoom scale. Symmetric to :zoom_floor. nil (default) uses the engine's default ceiling (8× canvas-pixel ratio capped by the 8192-px raster safety limit).

    Defaults to nil.

  • pan_locked (:boolean) - When true, single-pointer pan gestures (mouse drag, touch drag, arrow keys) are suppressed. Two-pointer pinch still works for zoom. Toggle at runtime via handle.setPanLocked(true|false).

    Defaults to false.

  • initial_fit_image_id (:string) - If set, the engine lands at the fit-to-viewport position for the image with this :id at first paint instead of fitting the whole canvas. Avoids the brief flash of "whole-canvas visible" before an onReady callback re-fits.

    Falls back to canvas-wide fit (with a console.warn) if no image matches the id. If both :initial_fit_image_id and :initial_fit_bounds are provided, image-id wins.

    Defaults to nil.

  • initial_fit_bounds (:map) - Like :initial_fit_image_id but for a custom rect. Map of %{x: number, y: number, width: number, height: number} in canvas-pixel coords. Serialized to JSON onto a data-* attr and parsed by the JS engine at mount.

    Defaults to nil.

  • memory_window (:integer) - Auto-evict src for images more than this many viewport-widths/ heights from the current viewport. Same memory-saving trick <Fresco.scroll_strip> uses, generalized to 2D canvas layouts.

    A value of 2 keeps a 5×5 viewport-rect window of images loaded around the current view (1 viewport in the center + 2 viewports of padding on each side). Default nil = disabled. Evicted images can be detected via handle.on("image-evicted", e => ...) / image-restored events.

    Defaults to nil.

  • gestures (:list) - Allowlist of enabled gestures. Atom list: [:pan, :pinch, :wheel, :double_click, :keyboard]. Default nil enables all. Omitted entries are disabled.

    Useful for kiosks (drop :keyboard), swipe-paged readers that handle their own page-turn taps (drop :double_click), embedded viewers that defer scroll to the page (drop :wheel).

    Defaults to nil.

  • nav_buttons (:list) - Allowlist of enabled built-in nav buttons. Atom list: [:home, :zoom_in, :zoom_out, :rotate, :fullscreen].

    • nil (default) — every button enabled.
    • [] — every button hidden. Useful for consumers building their own chrome; wire your buttons to handle.zoomIn() / handle.zoomOut() / handle.rotateBy(90) / handle.toggleFullscreen() / handle.requestHome() to get identical behavior to the built-ins.
    • A subset list — only those buttons render.

    Defaults to nil.

  • initial_rotation (:integer) - Initial rotation in degrees, snapped to one of {0, 90, 180, 270} at mount time. Pre-0.5.7 behavior (no rotation) corresponds to 0. Consumers persisting a per-canvas rotation choice (a rotated single panel inside a paged reader, for example) pass it here so the first paint already shows the rotated content — no flash of unrotated → rotated.

    Runtime control via handle.setRotation(deg) / handle.rotateBy(delta); the built-in :rotate nav button cycles +90° per click. Only the stage rotates — host element, nav overlay, and any consumer overlays outside the stage stay unrotated.

    Defaults to 0.

  • view_tracking (:boolean) - Enables the view-focus / view-blur event channel for reading- time / engagement analytics. When true, the engine watches which image is dominant in the viewport and emits paired focus/blur events on the bus when that image changes. Defaults to false so consumers who don't subscribe pay zero cost.

    Consumer-side:

    handle.on("view-focus", e => {
  // e.imageId, e.previousImageId, e.atMs
})

handle.on("view-blur", e => {
  // e.imageId, e.durationMs, e.atMs, e.reason
  // e.reason ∈ "viewport-change" | "page-hidden" | "disabled" | "destroyed"
})

    Runtime alternatives if you want to toggle tracking on/off without a re-render: handle.enableViewTracking(opts) / handle.disableViewTracking() / handle.getFocusedImage().

    Defaults to false.

  • view_settle_ms (:integer) - Milliseconds the viewport must stay on a new dominant image before view-focus fires. Filters out pan-throughs and momentum-scroll fly-bys so analytics events only fire on actual reads. Only consulted when :view_tracking is true. Default 150.

    Defaults to 150.

  • view_threshold (:float) - Fraction of an image's area that must intersect the viewport for it to qualify as "dominant". Lower values make focus changes more eager; higher values make focus stickier. Only consulted when :view_tracking is true. Default 0.5.

    Defaults to 0.5.

  • Global attributes are accepted.

from_json(json)

Parse a JSON string into a canvas struct. Returns {:ok, canvas} or {:error, %Fresco.Canvas.SchemaError{}}.

Unknown top-level and per-image keys are preserved via a private __extra__ map; round-tripping through to_json/from_json keeps them intact so v1 readers of a future v2 file don't lose v2-only data.

from_json!(json)

Parse a JSON string into a canvas struct. Raises on invalid input.

new(opts \\ [])

Build a new empty canvas.

Options:

  • :width — virtual canvas width in canvas pixels (default 0)
  • :height — virtual canvas height (default 0)
  • :background — optional CSS color string for the stage background

put_extension(canvas, name, value)

Put or overwrite an extension blob keyed by name (binary or atom).

Fresco never inspects the contents — each peer package owns the inner shape and self-versions inside its own blob.

read(path)

Read a canvas from disk. Returns {:ok, canvas} or {:error, reason}.

read!(path)

Read a canvas from disk. Raises on failure.

to_json(canvas)

Serialize a canvas to a JSON string. Returns {:ok, json} or {:error, reason} (only on Jason encode failure — schema is validated at struct-construction time).

to_json!(canvas)

Serialize a canvas to a JSON string. Raises on encode failure.

write(path, canvas)

Write a canvas to disk atomically. Writes to <path>.tmp first then renames so an interrupted save can't corrupt the existing file.

Returns {:ok, path} or {:error, reason}.

write!(path, canvas)

Write a canvas to disk atomically. Raises on failure.