Portable Snapshots
Landscape and Clustergram expose snapshot() and restore_snapshot() independently
of agent interfaces and notebook widgets. The goal is to preserve an interactive
observation as reproducible visual evidence. A Snapshot keeps the rendered image,
memo, semantic visualization state, bounded scientific observations, complete
supported replay settings, and provenance together.
The exported PNG is the Snapshot file: it contains both the image and the metadata needed to replay supported settings. Python also writes a human-readable Markdown companion. No separate JSON file is required.
Terms and scope
A Snapshot combines a screenshot (raster image of the visualization), a memo
(description) and reproducibility metadata. The screenshot is the visual component;
Snapshot names the complete Celldega artifact. The same name covers the in-memory
capture and its exported PNG. Python also writes a readable Markdown companion.
See Snapshots for the concept and notebook workflow.
A raster capture provides the image component on its own. A state query reports what the visualization shows, and a saved view holds the settings and data identity used to restore the view. A Snapshot brings these together with the memo and provenance; neither an image-only capture nor a state query is a complete Snapshot.
| Operation | JavaScript | Python |
|---|---|---|
| Capture in memory | await viz.snapshot() |
widget.request_snapshot(), then widget.latest_snapshot |
| Save a Snapshot PNG | celldega.snapshot_png(snapshot); SNAP downloads it |
widget.snapshot(name="..."), dega.viz.snapshot(linked), or SNAP |
| Display a notebook postcard | — | dega.viz.Snapshot(landscape=landscape, snapshot="name") |
| Restore | await viz.restore_snapshot(snapshot) |
widget.restore_snapshot(snapshot) or the postcard's blue link |
| Reopen from disk | await celldega.from_png(el, file) |
dega.viz.from_png(path) |
Snapshots can serve as evidence in an explanation or report. The lightweight
notebook postcard displays the
picture and memo without loading data. Older screenshot API spellings remain
compatible; the PNG metadata schema is unchanged.
A scientist can use this API for exploration, figures, tutorials, reports, web or desktop applications without constructing an agent. Agents consume this same contract.
await viz.apply_state({ /* supported changes */ });
const saved = await viz.snapshot({
max_size: 1600,
state: { max_rows: 25 }, // Observation cap only; replay settings are uncapped.
description: 'The marker-enriched population occupies the tissue boundary.',
author: 'scientist',
});
const json = JSON.stringify(saved);
// A separately constructed visualization with the same data and canvas dimensions:
await freshViz.restore_snapshot(JSON.parse(json));
The browser waits for its canvas to initialize, then reads the image, observations, replay settings and data identity in one JavaScript task. Capture represents the current rendered frame: wait for animations and data loading to settle when you need a stable figure. Each widget in a composite has its own capture time; a composite is not a cross-widget transaction.
The contract
The JSON envelope uses schema: "celldega.view" and version: 2:
| Field | Meaning |
|---|---|
kind |
landscape, clustergram or yearbook |
renderer |
Celldega package version used to capture the view |
captured_at |
UTC timestamp for the coordinated capture |
state |
Semantic replay inputs from get_replay_state(), independent of observation caps |
description, author |
Why the observation matters, and who recorded it |
source |
Data URLs, name, declared revision, widget type and supported constructor options for reopening |
observed_state |
The scientific observations returned by the getter |
image |
Base64 PNG, thumbnail and dimensions |
identity |
What data the view is of: counts and hashes of its names (see below) |
viewport |
Canvas size in CSS pixels |
capture |
Image size and observation options used |
restoration |
partial: see the control coverage |
restore_snapshot rejects other schema versions, wrong widget kinds, different data
and a different canvas size before changing the view, and its error names what
differs. allow_resize: true permits a different canvas size; the same camera then
frames a different extent. The size is in CSS pixels, so a view saved on a
high-density display restores on a standard one. Additive fields may be ignored by
readers; incompatible schema changes require a new version (version 1 views, which
hashed all loaded data, need recapturing). This is a data/view contract, not a
promise of identical pixels across browser, GPU or Celldega renderer versions.
Python Snapshot and report records also record the installed Celldega version. The
original PNG remains the visual evidence.
What the identity checks
A saved view records what its data is by name, cheaply enough to compute on every capture:
| Visualization | Identity |
|---|---|
| Landscape (and the spatial clouds) | Cell names, gene names and each cell's cluster label (with the cluster attribute), each as a count and a fast hash |
| Yearbook | Landscape identity plus portrait grid rows, columns, size and gap |
| Clustergram | Row names and column names, each as a count and a fast hash |
Restoring onto other cells, genes, clusterings, rows or columns is refused. Hashes are computed once per loaded array, so captures stay fast on large datasets, and need no secure (HTTPS) page. They tell datasets apart; they are not cryptographic and do not cover values: the same names with different expression values match.
For exact content identity, declare a data_revision when constructing the
visualization: any immutable identifier, such as a release tag, a commit hash, or a
digest of the files. Saved views record it, and restoring compares it whenever both
the view and the visualization declare one. For a local dataset:
revision = dega.viz.fingerprint_dataset("data/my-dataset")
landscape = dega.viz.Landscape(base_url=dataset_url, data_revision=revision)
fingerprint_dataset hashes file contents and relative names. It can be slow for
large stores; compute it when publishing immutable data, keep exports outside the
dataset, and regenerate it after edits. Clustergram and the JS constructors accept
data_revision too.
Restoring a Clustergram view never discards annotations made since it was saved:
an axis's saved manual annotations are applied only when that axis has none now (or
the same ones), and the result lists any axis whose current annotations were kept.
Use apply_state({annotations: ...}) to replace them deliberately.
Notebook use
request_id = cgm.request_snapshot(max_rows=25)
# In a later cell, after the browser replies:
saved = cgm.latest_snapshot
restore_id = fresh_cgm.restore_snapshot(saved)
# In a later cell: None while pending, else {"event": "applied" or "apply_error", ...}
fresh_cgm.get_apply_result(restore_id)
The browser's reply reaches Python only after the cell that sent the request
finishes, so don't await it in that cell (wait_for_apply would time out). From a
background task or an application, await fresh_cgm.wait_for_apply(restore_id)
raises on failure or timeout.
latest_snapshot, snapshot_error and snapshot_capture_id are Python-side traits,
never synced into the notebook's saved widget state. Requests carry IDs and responses
are matched individually, so concurrent captures cannot substitute a newer image for
an older request. widget.snapshot() and the SNAP button use this same capture path.
Reopen a PNG as an interactive visualization
In a notebook, from_png reads the metadata, constructs the appropriate widget from
its recorded data source and dimensions, and restores the supported settings when
the widget first renders:
view = dega.viz.from_png("figure.png")
display(view)
# In a later cell, inspect the browser's acknowledgement:
view.get_apply_result(view.apply_request_id)
The returned widget is interactive. A result of None means restoration is pending;
an apply_error result explains why restoration failed. As with restore_snapshot,
do not wait for the reply inside the notebook cell that displays the widget.
The PNG references the scientific data; it does not embed the dataset. It records
links (a base_url, zarr_url, or the Zarr store a Matrix was read from with
Matrix.read_zarr) and constructor options, typically a few KB in all. The source
must still be accessible, and private data needs the same access as a normal
constructor call.
An object passed in memory has no link to record: a Matrix built in the notebook, or
an AnnData given as adata= (read_h5ad keeps no path). The PNG stores its shape and
marks it as required, and from_png asks for it by name. Supply the original object:
cgm = dega.viz.from_png("markers.png", matrix=mat)
# The PNG still records the Landscape's base_url; adata adds its in-memory metadata.
landscape = dega.viz.from_png("tissue.png", adata=adata)
To make a Matrix reopenable from its link alone, write it once with
mat.write_zarr(path) and open it with Matrix.read_zarr(path) before displaying it.
Constructor keyword arguments can also relocate a source, for example
base_url="https://example.org/data". Reopening still checks the saved schema,
data identity and canvas size. Pass allow_resize=True only when accepting the
different field of view implied by a different canvas size. The original renderer
version is recorded; exact pixel equality across versions or GPUs is not promised.
Each call opens one panel. For a composite Snapshot, use panel=0, panel=1,
and so on to reopen its widgets separately; cross-widget links must be reconnected.
An existing widget with its data already loaded can instead use
request_id = widget.restore_png("figure.png", panel=0) and check that request's
acknowledgement in a later cell.
In a web or desktop application:
// `file` is a PNG File from an <input type="file" accept="image/png">.
const record = await celldega.read_png(file); // Inspect metadata without rendering.
const viz = await celldega.from_png(container, file);
// A saved view of an in-memory network needs that network again:
const cgm = await celldega.from_png(otherContainer, file, { network });
from_png resolves after restoration succeeds and rejects on failure. It accepts
panel, allow_resize, and constructor options, including a replacement source.
read_png accepts a File, Blob, ArrayBuffer, or Uint8Array.
What the PNG stores
The PNG's celldega iTXt metadata contains a versioned Snapshot record
(the schema key remains celldega_screenshot: 3 for compatibility). Each entry in
widgets contains a compact saved-view envelope under snapshot, with replay
settings in snapshot.state, observations
under observed_state, and source/constructor information under source. Pixels
live in the PNG image data and are not duplicated as base64 inside the metadata.
Descriptions, authors, capture times, renderer version, canvas dimensions and data
identity travel with the image.
Inspect the record from Python with dega.viz.load_snapshot("figure.png"), or
discover a folder's records with dega.viz.load_snapshots("figures"). Keep the
original exported PNG when passing it through tools that remove image metadata.
Manual exports default to celldega_files/snapshots/; set snapshot_dir or
pass path to choose a location. The notebook SNAP button writes a PNG and Markdown
companion with a description, image preview, provenance and reopening code. The
Markdown is for readers and is not required for replay. Without a kernel, SNAP
downloads the PNG with its description and saved-view metadata embedded.
For a programmatic browser export:
const saved_view = await viz.snapshot({ description: 'A marker-enriched boundary.' });
const snapshot_png = celldega.snapshot_png(saved_view); // Blob with type image/png.
An application can store this Blob or download it using
URL.createObjectURL(snapshot_png). The in-memory Snapshot is plain JSON, so an
application can also keep it and restore it with restore_snapshot(); the PNG
is the portable file, and needs no Clerk or notebook.
Earlier Snapshot records remain readable, but their plain state has no verified
data binding. apply_state remains available for intentional edits; use
restore_snapshot for compatibility-checked replay.
JavaScript-only example and browser check
The repository's examples/viz-api/index.html uses a small synthetic matrix and the
built JS bundle. It supports PNG download/upload, restoration into a new instance,
and executable checks for capture → significant change → restore, fresh-instance
state/pixel equality, PNG export and reopening with from_png (state and pixels),
and rejection of different data (a renamed row), of a different declared
data_revision, and of a future schema. The exercise includes dendrogram cuts,
selections/highlights, annotations, crop, order and camera.
From the repository root:
npm run build
python -m http.server 8000 --bind 127.0.0.1
Open http://127.0.0.1:8000/examples/viz-api/. No notebook, Python analysis runtime
or model account is needed; the command above only serves static files. For automation
in an environment with Playwright installed:
python scripts/check_viz_snapshot.py --channel chrome
The page exposes window.celldegaSnapshotExample.check() for another test runner.
The same instance methods can be called by an application renderer. See the
Clerk host contract for the separate agent orchestration layer.