# AtomView

An experimental desktop Obsidian plugin for viewing local atomic structures and molecular-dynamics trajectories with Mol*. Maintained by [Kim Donghwan](https://github.com/dhwan0112).

Supports LAMMPS text dumps and data files, XYZ/basic extended XYZ, PDB, coreCIF and mmCIF. Everything runs locally: no Python server, CDN, OVITO/VMD installation or remote structure service is required.

**Preview status:** tested in Linux desktop Obsidian 1.14.4 and 1.14.5. Windows/macOS execution is not yet verified by the maintainer; mobile is unsupported. AtomView is listed in the Obsidian community directory (not manually reviewed by Obsidian staff). In-app installation of the 0.1.4 release was verified on Linux on 2026-11-04 in a synthetic vault; see VALIDATION.md.

## Install

**From the community directory:** open Settings → Community plugins → **Browse**, search for **AtomView**, then **Install** and **Enable**. Community-plugin execution must be allowed in your own security settings (Restricted mode off); AtomView never changes that setting. Obsidian appends a `/* nosourcemap */` marker to the installed `main.js`; the rest of the installed files are the attested release assets byte for byte.

**Manually:**

1. Download the runtime files from [Releases](https://github.com/dhwan0112/obsidian-atomview/releases): `main.js`, `manifest.json` and `styles.css`. These are the only release attachments; bundled dependency license notices are embedded at the top of `main.js` and listed in [THIRD_PARTY_LICENSES.txt](THIRD_PARTY_LICENSES.txt).
2. Place them in `<your-vault>/.obsidian/plugins/atomview/`. For a custom config directory, use its `plugins/atomview/` folder instead. Do not nest another `atomview` folder inside it.
3. Reopen Obsidian normally and enable **AtomView** under Settings → Community plugins → Installed plugins.

When updating, back up the existing AtomView folder and replace only runtime files; preserve `data.json`. Do not replace the vault's other settings or plugins.

## Open a structure

Use **AtomView: Open with AtomView** and enter a vault-root-relative path, or right-click a supported file and choose **Open with AtomView**. Existing extension associations are preserved. Automatic `.data` association is off by default and optional; data files are content-validated and require a supported atom-style hint/setting.

- Drag to rotate, right-drag to pan, wheel to zoom; **Fit / reset** reframes the scene.
- Spheres, element/type colors, real cell wireframes and original-ID picking.
- Play/pause, previous/next, frame slider and requested 0.2–30 FPS. Frame indices are 0-based and separate from source timesteps; physical time is not invented.
- Scalar colors such as `q`, fixed bounds or explicit per-frame auto range. Vectors require a component or magnitude selection.
- Schema-versioned copy/restore of frame, camera, mapping, scalar range and selection. Clipboard denial provides a manual-copy panel.

No chemical bonds are inferred for LAMMPS. Type numbers and masses do not establish chemical elements; map types explicitly when needed. Source coordinates/IDs/properties are preserved independently of display buffers. See [FORMAT_SUPPORT.md](FORMAT_SUPPORT.md) for exact format semantics and rejection rules.

## Embed in a note

Copy `fixtures/fe-o-q.lammpstrj` from this repository into your vault at `structures/fe-o-q.lammpstrj`, then use Reading view:

```atomview
source: "structures/fe-o-q.lammpstrj"
format: lammps-dump
frame: 0
representation: spheres
colorBy: q
showCell: true
elementMap:
  1: Fe
  2: O
height: 420
```

Ordinary paths are vault-root-relative, normalized and checked for symlink escape. Invalid YAML, missing properties/files and invalid frames show an error inside the view. Embeds keep independent camera/playback state. Hidden viewports release resources and restore when visible. Manual **Release viewer** stays released until **Reload / retry**.

### Colors and display

Colors come from three layers; the lowest wins: built-in defaults, your personal settings (Settings → AtomView), then an optional `display` mapping in the block. Personal settings cover the element palette (AtomView or Jmol/CPK), the type palette (AtomView, Okabe-Ito, Tol bright, IBM), per-element and per-type color overrides, the scalar palette (AtomView, viridis, magma, cividis, turbo, red-white-blue, greys) with reversal and distinct below-range/above-range colors, the selected-atom color, sphere scale, viewport background, and cell wireframe color/width. A preview shows the result on the viewport background and on a light background, and **Reset to built-in defaults** clears everything. Changes apply immediately to every open view, and only the keys you set are stored in the plugin's `data.json`.

Type colors are keyed by the type string in the file (LAMMPS type `1` takes the first palette color, wrapping after the last) and stay separate from element colors; a type is never mapped to an element implicitly. With a fixed scalar range, atoms below or above the bounds are drawn in the below/above colors and counted in the legend instead of being clamped to the palette ends.

A block can override any of these keys for that embed only:

```atomview
source: "structures/fe-o-q.lammpstrj"
elementMap:
  1: Fe
  2: O
display:
  elementColors:
    Fe: "#d04020"
  typeColors:
    "2": "#2080d0"
  scalarPalette: viridis
  sphereScale: 1.3
  background: "#ffffff"
```

Allowed `display` keys: `elementPalette`, `typePalette`, `elementColors`, `typeColors`, `scalarPalette`, `scalarReverse`, `underColor`, `overColor`, `selectionColor`, `background`, `cellColor`, `cellWidth` (0.005–0.3) and `sphereScale` (0.2–3); colors are `#rrggbb` (or `#rgb`). Unknown keys or invalid values show an error inside the view. Blocks with no `schemaVersion` or with `schemaVersion: 1` load unchanged; **Copy current view** writes `schemaVersion: 2` and carries the block's own `display` override (not your personal settings, which stay on your machine).

Basic Live Preview was smoke-tested, but advanced editor workflows are unverified. Native `![[structure.xyz]]` embedding is not implemented.

## Large trajectories and external files

Uncompressed text LAMMPS dumps use a byte index and bounded frame cache rather than loading the entire trajectory:

- Up to 2 GiB, 100,000 indexed frames, 50,000 atoms/frame and 16 MiB raw text/frame.
- The first frame can display before indexing finishes; the seekable range grows with the index.
- Indexing checks framing/row counts. Atom values and IDs are validated on frame access; indexing is not full scientific validation of every frame.
- At most four cached frames / 16 MiB **estimated storage** per disk-backed view. This is not a total process/GPU memory guarantee.
- Scalar fixed bounds initially come from the displayed reference frame and are labeled accordingly. Set explicit bounds or request **Scan full property range** for global extrema. A full property scan can take time and is cancellable.
- Changed/replaced files require reload. Indexes are cached in memory, not persisted to disk.

Other formats retain bounded in-memory loading: 16 MiB/file, 500 frames and 250,000 total atom records. Combined estimated widget reservations are capped at 128 MiB; at most four renderers initialize simultaneously.

To access an outside-vault file, explicitly run **AtomView: Register selected external file (read-only)** and select one absolute local path. Only that file is granted; sources are not copied, modified or uploaded. Settings → AtomView → **Revoke** removes its grant. Cloud files must be locally available.

**Multi-computer limitation:** external registrations contain device-specific paths. Registering the file on another computer creates a new source ID/view; it does not automatically repair old `external:…` embeds. Vault-relative files work when available at the same relative paths.

## Develop

Node >=22 and npm are required for development, not for running the installed plugin.

```sh
npm ci
npm run lint
npm run validate
npx playwright install chromium
npm run test:browser
node scripts/check-bundle.mjs
npm run deploy:dev -- --vault "/absolute/path/to/an/existing/vault"
```

Deployment requires an existing default `.obsidian` configuration, ownership validation and a successful build receipt. It backs up previous owned builds and preserves settings; it never changes security settings or the active-plugin list. `--plugin-only` after the vault argument updates runtime files without generating another synthetic demo.

`test:browser` uses real Mol*/WebGL/worker code with a **mocked Obsidian host**. Actual host verification is separate. See [TEST_REPORT.md](TEST_REPORT.md), [VALIDATION.md](VALIDATION.md), [ARCHITECTURE.md](ARCHITECTURE.md) and [KNOWN_ISSUES.md](KNOWN_ISSUES.md).

## Roadmap

Personal element/type color and display settings are implemented (0.2.0; see "Colors and display" above). Playback multipliers/stride controls, PNG and local GIF export, distance/angle measurement, and later explicit editing with undo/redo are planned, in that order, and are **not implemented** in this preview. See [ROADMAP.md](ROADMAP.md).

## License

MIT — Copyright (c) 2026 Kim Donghwan. Mol*, YAML and bundled dependencies retain their licenses and attributions; see [THIRD_PARTY.md](THIRD_PARTY.md) and the release's `THIRD_PARTY_LICENSES.txt`.

## Permissions and release provenance

Runtime filesystem operations read vault-contained sources or one explicitly registered external file. Registration grants no directory-wide access and resolved paths are checked again on use. AtomView does not write to structure sources. Settings are persisted through Obsidian's plugin API. The clipboard feature only writes a user-requested current-view block; it does not read clipboard contents. The directory may still display its broad filesystem and clipboard notices for these capabilities.

Releases from 0.1.4 on (latest: 0.2.0) are built and attested by the GitHub Actions workflow. It validates the exact tag/manifest/package versions, runs checks, builds and attests `main.js`, `manifest.json` and `styles.css`, then publishes only those assets. Required licenses are embedded in `main.js`. Verify a downloaded asset with `gh attestation verify main.js --repo dhwan0112/obsidian-atomview`. All three downloaded assets of 0.1.4, 0.1.6 and 0.2.0 passed attestation verification against this repository and workflow, with hashes equal to the local build; see VALIDATION.md for the runs and recorded results. The 0.1.5 tag exists but was never released: its workflow run was stopped by the dependency audit gate.