AtomView

by Denny Kim
5
4
3
2
1
Score: 50/100

Description

Desktop Obsidian viewer for atomic structures and MD trajectories, powered by Mol*

Reviews

No reviews yet.

Stats

0
stars
79
downloads
0
forks
36
days
18
days
18
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
12
commits

Latest Version

18 days ago

Changelog

AtomView 0.2.0

Personal colors and display settings (Stage 1 of the roadmap). No parser change; coordinates, atom IDs and cell handling are untouched. Blocks without a display key load exactly as before.

  • New settings tab section "Colors": element palette (AtomView softened Jmol or Jmol), type palette (AtomView, Okabe-Ito, Tol bright, IBM), scalar palette (AtomView, Viridis, Magma, Cividis, Turbo, red-white-blue, greys) with optional reversal, below-/above-range colors, selected-atom color, per-element and per-type color overrides, and a live preview on the viewport and on a light background.
  • New settings tab section "Display": sphere scale (0.2–3), viewport background, cell wireframe color and width, and a reset to built-in defaults.
  • Settings are stored under display in the vault's plugin data.json; changing them redraws every open view immediately. Invalid stored values are dropped on load instead of failing the plugin.
  • Block schema 2: an optional display mapping with the same keys overrides the personal settings for that block only; schema 1 blocks load unchanged and copied blocks are written as schema 2.
  • Legend shows the active palette, marks a block override, and for fixed ranges lists how many atoms fall below and above the range together with the clip colors.
  • Type colors index the type palette by type number and never imply an element; element colors apply only to atoms with a known element or an explicit elementMap entry.
  • Release attachments remain main.js, manifest.json and styles.css only; license notices remain embedded in main.js.

Filesystem notices remain expected: registered external files are read-only and explicit. Clipboard access only writes the requested view block. Windows/macOS behavior is not verified by the maintainer.

AtomView 0.1.6

Housekeeping release; no parser, renderer, schema or settings change. The 0.1.5 tag was never published: its CI release run stopped at the npm audit --omit=dev gate on a newly published advisory for the transitive dependency body-parser (GHSA-27r3-jxmh-p828, reached through Mol* → express). body-parser is not part of the plugin bundle.

  • Adjust UI wording (input placeholders, one aria-label, one status message) so the official Obsidian lint reports zero errors and zero warnings; scientific acronyms are kept as-is.
  • Refresh README, VALIDATION, TEST_REPORT, KNOWN_ISSUES and ROADMAP: community-directory listing, verified in-app installation on Linux desktop Obsidian 1.14.5, and the reordered roadmap (personal color/display settings next).
  • Update package-lock.json so the production dependency audit is clean (body-parser 2.3.0 → 2.4.0; package.json unchanged; not bundled into main.js).
  • Release attachments remain main.js, manifest.json and styles.css only; license notices remain embedded in main.js.

Filesystem notices remain expected: registered external files are read-only and explicit. Clipboard access only writes the requested view block. Windows/macOS behavior is not verified by the maintainer.

README file from

Github

AtomView

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:

  1. Download the runtime files from 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.
  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 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.