CrystalCanvas

sudo xattr -cr /Applications/CrystalCanvas.app

• Pixel-precise manual modeling — Hardware-accelerated 3D viewport with real-time atom selection, addition, deletion, element substitution, and multi-atom drag translation.
• Cell standardization — Niggli reduction, Delaunay reduction, Primitive ↔ Conventional cell transforms via Spglib.
• Slab cleaving — Rigorous $(h,k,l)$ surface cutting via Extended Euclidean Algorithm (Diophantine solver), not heuristic templates. Adjustable layer count, vacuum thickness, and termination selection.
• Supercell generator — Arbitrary $3\times3$ integer transformation matrices with automatic coordinate remapping and boundary deduplication.

• Brillouin Zone visualization — 3D Wigner-Seitz cell construction (all 14 Bravais lattice types) and 2D BZ support (5 wallpaper group types) with high-symmetry $\mathbf{k}$-point labeling. One-click band path export for Quantum ESPRESSO and VASP.
• Tight-Binding (Wannier) visualizer — Parse wannier90_hr.dat hopping Hamiltonians $H = \sum_{\mathbf{R}} t_{ij}(\mathbf{R}) c^\dagger_{i,\mathbf{0}} c_{j,\mathbf{R}}$ and render as 3D network overlays with per-orbital color coding (10-color Material palette), $\mathbf{R}$-shell/orbital selection, magnitude filtering, and ghost atom rendering for neighboring cells.

• GPU isosurface extraction — Real-time Marching Cubes (GPU compute shader) for CHGCAR, Gaussian Cube, and XSF files.
• Volume raycasting — Depth-aware front-to-back compositing with Blinn-Phong shading. Nyquist-compliant step size eliminates Moiré banding.
• Dual-color signed isosurfaces — Positive/negative lobes in distinct colormap-derived colors for Wannier functions and $\Delta\rho$. 10 scientific colormaps (Viridis, Coolwarm, RdYlBu, etc.).

• Seamless DFT/MD export — Native high-fidelity export for VASP (POSCAR), LAMMPS (Data), Quantum ESPRESSO (Input with automatic K-point density and IUPAC 2021 masses).
• 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 agent with strict physics validation (MIC overlap checks).
• Memory-safe architecture — Rust logic layer eliminates crashes from dangling pointers and buffer overflows. All crystal state managed via SSoT (Single Source of Truth) with f64 physics / f32 GPU precision separation.

For the full roadmap, see ROADMAP.md.

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.

┌─────────────────────────────────────────────────────────┐
│  L4: React + TypeScript + TailwindCSS  (Presentation)   │
│      WebView / Tauri IPC (invoke / events)              │
├─────────────────────────────────────────────────────────┤
│  L3: Rust / Tauri 2.0  (Application Logic / SSoT)       │
│      State Manager • Command Router • Undo Stack        │
├─────────────────────────────────────────────────────────┤
│  L2: Rust / wgpu  (Rendering Engine)                    │
│      Impostor Spheres • Bond Cylinders • BZ Wireframe   │
│      Volume Raycast • GPU Marching Cubes • Wannier Net  │
├─────────────────────────────────────────────────────────┤
│  L1: C++ Physics Kernel  (Spglib / Gemmi / Eigen)       │
│      Symmetry • Slab • Supercell • Overlap Detection    │
└─────────────────────────────────────────────────────────┘

Key Design Decisions:

• Dual-precision: f64 for crystallographic calculations, f32 for GPU rendering
• ColMajor enforcement: All lattice matrices follow Fortran column-major order throughout the stack
• Full GPU reconstruction: Instance buffer rebuilt on every state change (~16 KB for 500 atoms, < 0.1 ms)
• Three-layer LLM safety: Schema validation → physics sandbox → undo snapshot before every AI-generated command

New to CrystalCanvas? Check out the User Manual for a comprehensive guide.

For more in-depth documentation, see the Documentation section below.

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

Always source the environment script before starting development:

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.

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, wannier90_hr)
│   │   ├── renderer/   # wgpu pipelines (atoms, bonds, hopping, isosurface, volume, BZ)
│   │   └── ...         # State manager, command router, volumetric, wannier, BZ modules
│   ├── build.rs        # Unified Rust + C++ build script (cmake/cxx bridge)
│   └── Cargo.toml
├── src/                # React frontend (TypeScript + TailwindCSS components)
│   ├── components/     # UI components (icon toolbar, panels, chat)
│   ├── hooks/          # Custom React hooks (tauri events, file-drop, 3D interaction)
│   └── types/          # Strict TS IPC type mappings
├── cpp/                # C++ physics kernel
│   ├── include/        # Public C-compatible headers (cxx bridge)
│   ├── src/            # Spglib, Gemmi, Eigen integrations
│   └── CMakeLists.txt
├── doc/                # Internal technical docs (TDD, Roadmap, Feature Assessment)
├── docs/               # Public documentation
│   ├── UserManual.md       # End-user guide
│   ├── DeveloperGuide.md   # Architecture & contribution guide
│   ├── Algorithms.md       # Core algorithm specifications
│   ├── IPC_Commands.md     # Complete Tauri IPC command reference
│   ├── Shader_Reference.md # WGSL shader bind groups & pipelines
│   ├── TestingGuide.md     # Node TDD process & test inventory
│   └── FAQ.md              # Troubleshooting & common issues
├── tests/              # Integration tests & benchmark data (LFS-tracked volumetric files)
├── dev_env.sh          # Local toolchain environment activation script
├── CHANGELOG.md        # Release history
└── README.md

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

• Primary dev platform: macOS (Intel & Apple Silicon)
• Environment: Always source dev_env.sh before building. API keys stored in OS Keychain — never in code or logs.
• Code conventions: snake_case for variables/functions, PascalCase for types, physics symbol fidelity preserved (e.g., sigma_k ≠ Sigma_K). See CONTRIBUTING.md for full guidelines.
• Documentation: Internal docs in doc/, public docs in docs/. Changes tracked in CHANGELOG.md.

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