> ## Documentation Index
> Fetch the complete documentation index at: https://docs.claviscage.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Exporting Data

> Export analysis results, images, render frames, and videos from Clavis

# Exporting Data

Clavis supports standard scene screenshots, structured analysis exports, path-traced publication renders, and trajectory videos.

## Unified Export Center

Open the **RENDER** tab to use the Export Center. It presents only the actions that apply to the loaded scene and locks the remaining actions while an export is active.

| Action                | Output                    | Availability                                                           |
| --------------------- | ------------------------- | ---------------------------------------------------------------------- |
| **Standard image**    | PNG                       | Current WebGL camera and scene                                         |
| **Path-traced image** | PNG                       | Current path-tracer settings and account entitlement                   |
| **Blender bundle**    | `.claviscage.zip`         | Current displayed scene, available analyses, and editable styles (Pro) |
| **Frame sequence**    | ZIP of numbered PNG files | Multi-frame scenes with supported frame access                         |
| **Standard movie**    | MP4                       | Multi-frame scenes with browser video encoding                         |
| **Path-traced movie** | MP4                       | Multi-frame scenes with GPU path tracing and account entitlement       |

Single-frame scenes omit frame-sequence and movie actions instead of showing a permanent “Requires multiple frames” error. When a trajectory exists but a specific export path is unavailable, the action explains the actual requirement.

## Image Export (PNG)

Press **Ctrl/Cmd + E** or click the export button to save a PNG of the current 3D view.

* Captures visible atoms, cages, rings, guests, H-bonds, axes, and PBC box
* Uses the current camera pose and, when Preview Mode is active, the configured render-frame crop and output dimensions
* Honors layer visibility and opacity settings
* Excludes preview-only guide artifacts such as yellow frame guides, focus markers, light-position indicators, and drag handles

## Render Frame Export

The **RENDER** tab includes configurable output width/height and common aspect presets. Preview Mode displays a centered render frame overlay so you can compose a figure before exporting. Drag Frame mode uses the exact drawn crop, and output dimensions follow that crop aspect without increasing the current pixel area. Standard PNG export and path-traced still export now share this render-frame contract, so a 4:5 preset or user crop produces a matching output image instead of the raw browser viewport.

## Data Export

After running analysis, export results as CSV or JSON.

### CSV Export

CSV files include one row per detected cage with fields such as:

| Column            | Description                           |
| ----------------- | ------------------------------------- |
| **cage\_index**   | Sequential cage number                |
| **cage\_type**    | Face signature, e.g. `5^12·6^2`       |
| **quality**       | `SEC`, `nSEC`, or `IC` when available |
| **center\_x/y/z** | Cage center coordinates               |
| **vertices**      | Water oxygen indices forming the cage |

### JSON Export

JSON export preserves structured cage, ring, occupancy, and trajectory data for programmatic use. Trajectory rows include their algorithm and both zero-based `frameIndex` and one-based display frame, preventing results from different algorithms or frame conventions from being merged silently.

## Batch and Video Export

For trajectories, Pro workflows can export frame ranges and MP4 videos. Choose start/end frame, step, FPS, quality, loop count, and WebGL or path-traced render mode. The CPU still-image fallback is for still PNG export only; video export remains WebGL or GPU path-traced. FFmpeg runs in the browser through WebAssembly for MP4 encoding.

Frame-sequence and movie exports capture frames sequentially. If Clavis cannot load a frame, capture its image, or prepare an active TRACE/H-bond overlay, it stops and reports the failing stage instead of producing a silently incomplete archive or movie. On exit—success, cancellation, or failure—the exporter restores the original frame and the cage, ring, H-bond, and occupied-guest visibility state that was active before export.

<Warning>
  HTR ring and occupied-guest overlays cannot currently be refreshed safely for every exported frame. If either overlay is visible, Clavis asks you to hide it before a multi-frame export. TRACE cages and H-bonds use the frame-aware preparation path.
</Warning>

## Blender Bundle Export

Pro users can choose **Blender bundle** in the Export Center to download a versioned `.claviscage.zip`. Import the archive as one bundle; the JSON files inside it are consumed by the ClavisCage Blender extension.

<Warning>
  This workflow requires a bundle-capable ClavisCage extension build. If the Blender **Input** panel shows only **Topology**, **Trajectory**, and **Guests**, that installed build does not support web bundles yet; there is no valid field in that UI for the ZIP or either JSON member. Update the extension before following the steps below.
</Warning>

### Import the bundle in Blender

1. Keep the downloaded `.claviscage.zip` intact. Do not extract the archive or select one of its JSON files.
2. In Blender, open the 3D Viewport sidebar and select the **ClavisCage** tab.
3. Under **Input → ClavisCage Bundle**, select the `.claviscage.zip` file itself.
4. Click **Import Web Bundle**. The extension validates both JSON members before replacing the ClavisCage scene.
5. Adjust the restored molecule, residue, CHILL+, H-bond, cage, PBC, material, lighting, and render controls as needed, then save your own `.blend` file.

If macOS or your browser automatically expands ZIP downloads, use the original file ending in `.claviscage.zip` rather than the extracted folder. The Blender file picker should point to the archive itself.

### What the JSON files do

| Bundle member   | Purpose                                                                                                                                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `manifest.json` | Identifies the `claviscage.bundle` format and schema version, records the originating web-app version and creation time, and lists warnings when stale analyses were omitted. Blender uses it for compatibility and integrity checks.             |
| `scene.json`    | Carries the current frame, water/guest/non-water coordinates, box/cell data, matching CHILL+ and H-bond data, supported styles, and the selected algorithm-owned cage analysis. Blender uses it to construct editable scene objects and overlays. |

You may inspect these files to audit what was exported, but editing them is not a supported public editing API. The importer deliberately requires an exact, internally consistent schema and rejects missing or extra archive members, unsupported schema versions, invalid indices, malformed coordinates, and inconsistent styles. Make presentation changes after import with the Blender extension controls instead.

The web exporter writes **schema v2**. Its `cageAnalysis` object identifies `trace`, `htr`, or `grade`; records the zero-based source `frameIndex`; distinguishes total and currently visible cages; stores the relevant cutoff/angle/planarity parameters; and carries only geometry owned by that algorithm and frame. Blender restores it through editable scene and overlay controls; the file is not a pre-rendered image or a generated `.blend`.

The Blender extension also accepts legacy **schema v1** bundles, where the cage field is HTR-specific. Schema v1 cannot express TRACE or GRADE provenance. Both versions are intentionally offline and single-frame: they do not contain a trajectory or provide live browser-to-Blender synchronization. When cached analysis belongs to another frame, Clavis omits it and records a warning rather than exporting stale results.

<Tip>
  For publication images, set the render frame first, preview the crop, then export either the standard WebGL view or a path-traced render.
</Tip>

## Empty Render Recovery

If a path-traced render reports background-only output, first use **Center Frame** or **Reset 16:9** from the recovery panel, then confirm the target molecule and visible layers are inside the yellow Preview Mode frame. This usually means the export crop or camera target missed the visible molecule, although truly empty or hidden scenes can also produce the same warning.