MolVis

A visual workspace where people and agents inspect molecular data together

Documentation  ·  Quick start  ·  Ecosystem

MolVis renders molecules, simulation boxes, and trajectories in the browser, with one product surface shared across the web, VS Code, and Jupyter. Its bidirectional RPC layer lets an agent operate the live scene while the user inspects every result, selects the relevant atoms or bonds, and sends that precise visual context back to the agent.

Vision

Molecular visualization tools have long made you choose: a powerful desktop application that is hard to install and impossible to share, or a lightweight web viewer that cannot keep up once your work gets serious. MolVis exists to erase that trade-off — a single rendering stack that runs anywhere a browser does, with no compromise on what you can see or do.

We want looking at a structure to be frictionless. Drag a file onto a page, open it in your editor next to its input deck, or display it inline in a notebook cell — the viewport, the modes, and the shortcuts are identical everywhere, so the muscle memory you build transfers across every context you work in.

And we want visualization to be more than a picture. MolVis treats editing, measurement, pipeline transforms, and analysis as first-class, fully reversible operations on live molecular data — so the viewer becomes a place where you actually do the work, not just admire the result.

Human-in-the-loop agent workflow

MolVis is designed to be the visual boundary between an agent and molecular data:

1. An agent uses JSON-RPC commands to load data, move the camera, change the representation, select atoms, edit the scene, or run pipeline operations.
2. The user reviews the exact result in the shared viewer instead of auditing a textual description of it.
3. The user selects atoms or bonds that need attention. MolVis emits the selection, active frame, and interaction state back to the host.
4. The agent receives a structured subset with get_selected(), acts on the feedback, and presents the next visible result.

RPC requests and responses are structured and snapshots can capture the visible state, making the workflow straightforward for an agent host to record and audit. MolVis provides the observable interaction boundary; durable audit-log storage remains the responsibility of the host application.

See Agent workflows for a complete selection-feedback loop.

Packages

Package	Role
@molcrafts/molvis-stage	3D stage — Babylon.js rendering, commands, modes, pipeline, RPC
@molcrafts/molvis-sketch	2D sketch — Canvas structure editor
@molcrafts/molvis	Umbrella (repo root) — re-exports stage + sketch + plugin SDK
@molcrafts/molvis-plugin	Plugin authoring SDK (base class, contract, host-aligned UI)
@molcrafts/molvis-core	Shared molrs gateway + element catalog (transitive; not a product install)
page	React 19 product UI (ships inside Python / VS Code hosts)
VS Code extension	Custom editor for molecular formats
molcrafts-molvis (PyPI)	Python driver over WebSocket

Install

# both engines (root package)
npm install @molcrafts/molvis

# 3D only
npm install @molcrafts/molvis-stage

# 2D only
npm install @molcrafts/molvis-sketch

Requires Node.js 22+. The Python package (pip install molcrafts-molvis) needs Python 3.12+; the VS Code extension installs from the Marketplace.

Quick start

import { mountMolvis } from "@molcrafts/molvis-stage";
import { loadFileContent } from "@molcrafts/molvis-stage/io";

const container = document.getElementById("viewer");
if (!container) throw new Error("viewer container not found");

const app = mountMolvis(container);
await app.start();

const pdbText = await (await fetch("/structure.pdb")).text();
await loadFileContent(app, pdbText, "structure.pdb");

See the documentation for the web viewer, the VSCode extension, the Python API, and how to extend the engine.

Documentation

• Tutorial — frames, camera, representations, selection, pipeline, trajectories, export
• Agent workflows — RPC control, visual review, selection feedback, and audit records
• Interfaces — Web/TypeScript, Python/Jupyter, and VS Code guides
• Development — embed MolVis and write custom modifiers and commands
• API Reference — TypeScript library and Python package

MolCrafts ecosystem

Project	Role
molpy	Python toolkit — shared molecular data model & workflow layer
molrs	Rust core — molecular data structures & compute kernels (native + WASM)
molpack	Packmol-grade molecular packing (Rust + Python)
molvis — this repo	WebGL molecular visualization & editing
molexp	Workflow & experiment-management platform
molnex	Molecular machine-learning framework
molq	Unified job queue — local / SLURM / PBS / LSF
molcfg	Layered configuration library
mollog	Structured logging, stdlib-compatible
molhub	Molecular dataset hub
molmcp	MCP server for the ecosystem
molrec	Atomistic record specification

Contributing

Contributions are welcome — see the development guide.

License

BSD-3-Clause — see LICENSE.

---

_{Crafted with 💚 by MolCrafts}