README file from
GithubAtomView
An experimental desktop Obsidian plugin for viewing local atomic structures and molecular-dynamics trajectories with Mol*. Maintained by Kim Donghwan.
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:
- Download the runtime files from Releases:
main.js,manifest.jsonandstyles.css. These are the only release attachments; bundled dependency license notices are embedded at the top ofmain.jsand listed in THIRD_PARTY_LICENSES.txt. - Place them in
<your-vault>/.obsidian/plugins/atomview/. For a custom config directory, use itsplugins/atomview/folder instead. Do not nest anotheratomviewfolder inside it. - 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 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:
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:
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.
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, VALIDATION.md, ARCHITECTURE.md and 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.
License
MIT — Copyright (c) 2026 Kim Donghwan. Mol*, YAML and bundled dependencies retain their licenses and attributions; see 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.