🔬 CrystalCanvas

High-performance crystal structure modeling, volumetric visualization, and DFT/MD file preparation — in a native desktop app.

CrystalCanvas is an open-source desktop GUI application designed for computational materials science, condensed matter physics, and quantum chemistry. It breaks free from the limitations of traditional tools (VESTA, Materials Studio) by combining a native-first architecture with modern AI-powered workflows.

• 🖱️ Pixel-precise manual modeling — Hardware-accelerated 3D view with real-time atom selection, addition, deletion, and element substitution.
• 📊 Volumetric data visualization — Real-time isosurface extraction (GPU Marching Cubes) and volume raycasting for CHGCAR, Gaussian Cube, and XSF files. 10 scientific colormaps, dual-color signed isosurfaces, density cutoff control.
• ⚙️ Industrial-grade physics kernel — C++ engine with Spglib (space group analysis), Eigen (matrix transforms), and Gemmi (CIF/PDB parsing).
• 🧠 AI-powered workflow (experimental) — Natural language commands like "Generate a 3×3×3 silicon supercell and dope 5% phosphorus on the surface". Context-aware LLM acts as a semantic parameterizer and command orchestrator with strict physics validation (MIC overlap checks).
• 🔌 Seamless DFT/MD integration — Native high-fidelity export for VASP (POSCAR), LAMMPS (Data), Quantum ESPRESSO (Input with automatic K-point density and IUPAC 2021 masses).
• 🛡️ Memory-safe architecture — Rust logic layer eliminates crashes from dangling pointers and buffer overflows.

⚠️ Platform Support: Due to rendering engine (wgpu) backend differences, Windows and Linux builds may have rendering issues. Currently only macOS is fully tested and supported.

Since releases are not signed with an Apple Developer Certificate, macOS will prevent it from running with a "Developer cannot be verified" warning.

To run the app:

1. Move CrystalCanvas.app to your /Applications folder.
2. Right-click (or Control-click) the app icon and select Open.
3. Click Open again in the dialog box.

Alternatively, run the following command in Terminal:

sudo xattr -cr /Applications/CrystalCanvas.app

┌─────────────────────────────────────────────────────┐
│  React + TypeScript + TailwindCSS  (UI)             │
├─────────────────────────────────────────────────────┤
│  Rust / Tauri 2.0  (Application Logic / SSoT)       │
├─────────────────────────────────────────────────────┤
│  Rust / wgpu  (Impostor Sphere + Volume Raycast)    │
├─────────────────────────────────────────────────────┤
│  WGSL Compute  (GPU Marching Cubes / Raycasting)    │
├─────────────────────────────────────────────────────┤
│  C++ Physics Kernel  (Spglib / Gemmi / Eigen)       │
└─────────────────────────────────────────────────────┘

New to CrystalCanvas? Check out the User Manual (v0.1) for a comprehensive guide on modeling, AI workflows, and DFT exports.

CrystalCanvas utilizes a Zero-Global-Pollution strategy. All toolchains (Rust, Node) and dependencies are isolated within the project directory.

• Xcode Command Line Tools: xcode-select --install
• pnpm: npm install -g pnpm (the only global dependency required)

Clone the repository and initialize the local toolchains:

git clone https://github.com/XiaoJiang-Phy/CrystalCanvas.git
cd CrystalCanvas

# Initialize local Rustup and Cargo home
mkdir -p .rustup .cargo
source dev_env.sh

# Install Rust stable locally (if not present)
rustup toolchain install stable

# Install Node dependencies
pnpm install

CrystalCanvas handles C++/Rust/TS full-stack compilation in a unified flow.

Always source the environment script before starting development to ensure RUSTUP_HOME and CARGO_HOME point to the project-local folders:

source dev_env.sh

# This starts the Vite dev server and the Tauri native window
pnpm run tauri dev

To verify GPU/wgpu compatibility without the full React UI:

cd src-tauri
RUST_LOG=info cargo run --bin render_demo

Controls: Left-click drag to rotate, scroll to zoom.

Note: The C++ kernel (Spglib, Gemmi, Eigen) is compiled automatically via the Rust build.rs script using cxx-build. No manual CMake interaction is required.

• M1-M2: Infrastructure & Data Model — Rust/C++ bridge, CIF parsing.
• M3: High-Performance Rendering (wgpu) — Impostor spheres, ray-picking, orbital camera.
• M4-M6: UI Integration & Geometry Ops — Hybrid window, slab cleaving, supercells, atomic operations.
• M7-M8: DFT/MD Ecology & I/O Pipeline — Overlap detection (MIC), native exporters (VASP, QE, LAMMPS).
• M8.5: Persistent Settings & UI Polish — Local JSON caching, global rendering customization.
• M9: LLM Command Bus — Context-aware semantic AI agent for macro-scale geometry manipulation.
• M10: Structural Analysis & Phonons — Polyhedra identification, defect tracking, and imaginary frequency animation.
• M11: Volumetric Rendering — GPU Marching Cubes isosurfaces, volume raycasting, 10 colormaps, CHGCAR/Cube/XSF parsers.
• M12+: AI4Science Phase Space — High-throughput MLFF dataset perturbations, NEB playback, and Symmetry Subgroup extraction.

CrystalCanvas/
├── .github/            # GitHub Actions (CI/CD release workflows)
├── src-tauri/          # Rust backend (Tauri commands, state handling, wgpu orchestration)
│   ├── shaders/        # WGSL shaders (volume_raycast, marching_cubes, isosurface_render)
│   ├── src/
│   │   ├── io/         # File parsers (CIF, POSCAR, CHGCAR, Cube, XSF, QE)
│   │   ├── renderer/   # wgpu pipelines (atoms, bonds, isosurface, volume raycast)
│   │   └── ...         # State manager, command router, volumetric module
│   ├── build.rs        # Unified Rust + C++ build script (cmake/cxx bridge)
│   └── Cargo.toml
├── src/                # React frontend (TypeScript + TailwindCSS components)
│   ├── components/     # UI Panel components (RightSidebar: volumetric controls)
│   ├── hooks/          # Custom React hooks (tauri events, file-drop, 3D interaction)
│   └── types/          # Strict TS IPC mappings (e.g., CrystalState, CrystalCommand)
├── cpp/                # C++ physics kernel
│   ├── include/        # Public C-compatible headers (cxx bridge)
│   ├── src/            # Implementation code (Spglib, Gemmi, Eigen integrations)
│   └── CMakeLists.txt
├── docs/               # System documentation ([User Manual](docs/UserManual_v0.1.md), Development Notes)
├── tests/              # Integration tests & benchmark data (LFS-tracked volumetric files)
├── dev_env.sh          # Local toolchain environment activation script
├── CHANGELOG.md        # Release history and known issues
└── README.md

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

• Primary dev platform: macOS (Intel & Apple Silicon)
• Environment toolchains should be installed locally within the project directory when possible (see .gitignore for excluded paths).
• Documentation in docs/ and CHANGELOG.md is tracked for release transparency.

This project is dual-licensed under the MIT License and the Apache License 2.0. You may choose either license for your use.

• LICENSE-MIT
• LICENSE-APACHE

For third-party software licenses used in this project, please see THIRD_PARTY_LICENSES.md.

• Spglib — Crystal symmetry analysis
• Gemmi — CIF/PDB file parsing
• Eigen — Linear algebra
• Tauri — Desktop app framework
• wgpu — Cross-platform GPU API