> ## 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.

# Introduction

> Clavis - Hydrate Cage Structure Visualization

# Welcome to Clavis

Clavis is a browser-based workspace for analyzing and visualizing gas hydrate cage structures. It combines WebAssembly-powered analysis, interactive 3D rendering, trajectory tools, guest occupancy workflows, and publication-quality export in a single web app.

## What is Clavis?

Clavis (Latin for "key") helps hydrate researchers inspect structure and occupancy without installing a desktop pipeline:

* **Detect general cage structures** with TRACE SEC/nSEC/IC face signatures
* **Inspect oxygen-topology rings and generalized cages** with HTR
* **Count three canonical cage families and filled cages** with native GRADE
* **Calculate F3/F4 order parameters** for crystallinity and hydrate ordering
* **Classify local water environments** with CHILL+ colors, class filters, network visualization, and trajectory time series
* **Analyze guest occupancy** with θ\_S, θ\_L, overall occupancy, and per-cage-type summaries across TRACE, GRADE, and complete HTR cage results
* **Continue in Blender** with the platform extension and schema v1/v2 `.claviscage.zip` bundles; cached Analyze All Frames results keep TRACE, HTR, GRADE, F3/F4, CHILL+, and H-bond provenance attached to the source frame
* **Visualize occupied guests** with algorithm-owned cage-type filters, neon guest highlights, and atom-level multi-atom guest rendering
* **Work with trajectories** using frame navigation, large-file streaming, selected-frame native playback, and sampled range analysis
* **Create publication outputs and Blender handoffs** with configurable render frames, PNG/MP4 export, versioned offline `.claviscage.zip` bundles, Render Resource visibility, GPU path tracing, and a runtime-supported CPU still-image fallback <Icon icon="crown" iconType="solid" color="#facc15" /> **PRO**

## Supported File Format

Clavis supports GROMACS `.gro`, PDB `.pdb`, and CIF/mmCIF `.cif`/`.mmcif` text structures, including water networks, guest-containing systems, and mixed material systems. Large `.gro` trajectories are streamed in the browser to avoid loading every frame into memory at once. Native GROMACS binary trajectory sessions are available when users upload a paired `.gro + .xtc`, `.gro + .trr`, `.tpr + .xtc`, or `.tpr + .trr` set; Clavis indexes frame byte ranges and decodes selected frames in a worker instead of materializing every binary frame during session open. Normal/large GRO, mapped LAMMPS, and native XTC/TRR workflows support selected TRACE/HTR/GRADE/F3F4 ranges; native GROMACS and mapped LAMMPS also apply the same Start/End/Step range to CHILL+. Use a matching `.gro` topology when exact residue labels are more important than TPR-only metadata.

## Browser-Local Workflow

Analysis and visualization are designed around browser-side interaction. Normal-size text-structure scenes can be recovered from session-local browser storage after an accidental refresh or quick Changelog visit. Large streaming trajectories intentionally skip scene recovery because browser storage is not appropriate for very large coordinate payloads.

Clavis uses live progress overlays for long-running browser-local work, including parsing, frame streaming, analysis, and render preparation, so the scene reports what Clavis is doing instead of appearing frozen.

## Quick Start

1. **Upload** a supported structure file
2. **Choose** a workflow: visualize, run TRACE/HTR/GRADE, inspect F3/F4, or analyze guest occupancy
3. **Filter and style** atoms, CHILL+ classes, cages, rings, H-bonds, guests, and residue channels
4. **Export** images, numbered frame archives, analysis tables, trajectory videos, or a current-frame Blender bundle from the Render tab

<CardGroup cols={2}>
  <Card title="Upload Files" icon="upload" href="/getting-started/upload">
    Prepare single-frame files, multi-frame trajectories, and guest-containing structures
  </Card>

  <Card title="Visualization" icon="eye" href="/getting-started/visualization">
    Learn camera, layer, cage, H-bond, guest, and mobile controls
  </Card>

  <Card title="CHILL+ Classification" icon="snowflake" href="/analysis/chill-plus">
    Classify ice, hydrate, interfacial, and liquid water environments in frames and trajectories
  </Card>

  <Card title="Guest Occupancy" icon="chart-column" href="/analysis/occupancy">
    Calculate θ\_S, θ\_L, overall occupancy, and occupied guest highlights
  </Card>

  <Card title="Path Tracer" icon="crown" color="#facc15" href="/pro/path-tracer">
    Create photorealistic GPU WebGL renders with Render Resource status and a runtime-supported CPU still-image fallback (PRO)
  </Card>
</CardGroup>

## Pricing

| Plan     | Price      | Features                                                                    |
| -------- | ---------- | --------------------------------------------------------------------------- |
| **Free** | \$0/month  | Monthly frame quota, standard visualization, core analysis workflows        |
| **Pro**  | \$19/month | Unlimited frames, path-traced rendering, video export, and priority support |

All users can access the core analysis algorithms. Pro unlocks higher-throughput and publication-output workflows.