# OrbVista


**OrbVista** is an advanced graphical suite for the interactive visualization and 
volumetric analysis of Molecular Orbitals (MO), Electrostatic Potentials (ESP), 
and Spin Densities. It serves as the visual bridge between computational chemistry 
results and publication-quality rendering.

## Key Features
- **Wide Format Support**: Load and visualize data from `.cube`, `.molden`, 
  and `.fchk` files (with automatic Bohr-to-Angstrom conversion).
- **Dynamic Property Mapping**: Project ESP or Spin Density onto electron density 
  isosurfaces with customizable colormaps and automatic v-min/v-max scaling.
- **Interactive UI**: 
  - Manage multiple files in a synchronized session supporting also open-shell systems.
  - Customize lobe colors and background settings via intuitive context menus.
  - Dedicated **Grid Settings** for on-the-fly volumetric calculations.
- **High-End Export**: 
  - **POV-Ray**: Generates detailed `.inc` files for ray-traced imagery 
    (including embedded scalebar logic).
  - **Blender**: Exports .glb scenes along with separate colorbar objects for mapping.
  - **Analysis**: Save calculated grids back to `.cube` format (including synchronized 
    `.xyz` for ChimeraX).

## Interface Overview
- **File List**: Manage your computational results. Double-click to remove, 
  single-click to focus.
- **Orbital Tabs**: Browse Alpha and Beta orbitals directly from Molden/FCHK outputs.
- **Property Controls**: Real-time adjustment of opacity, isolevels, and $v_{max}/v_{min}$ 
  scaling for mapping.
- **Grid Settings**: Fine-tune your calculation resolution ($n_x, n_y, n_z$) and 
  spatial padding.

## Workflow & Integration

### From QC to Visualization
1. **Load**: Import your `molden` or `fchk` file via `App -> Load`.
2. **Calculate**: Select the desired property (e.g., `Draw -> ESP molden`).
3. **Analyze**: Adjust the isosurface and colormap (e.g., `turbo`, `hsv`, `coolwarm`).
4. **Export**: Use `Export -> POV-Ray` or Èxport -> Blender' for professional rendering 
or `Export -> MO Cube` for further analysis.

## Project Structure

```text
.
├── main.py               # Main application entry point
├── requirements.txt      # Project dependencies
├── README.md             # Documentation
├── /examples             # examples
    ├── ex1               # orca example
    ├── ex2               # NWChem example
    ├── ex3               # Psi-4 example
├── /modules              # Core logic and UI components
│   ├── draw.py           # functions required for plotting
│   ├── export.py         # export routines
│   ├── gui_ui.py         # main GUI python file
│   ├── gui.ui            # main GUI raw ui file
│   ├── grid.ui           # grid settings window ui file
│   └── manual.html       # manual for help menu
├── /screenshots          # 
    ├── ...               # screenshots

## Examples & Tutorials

Ex1: Benzoic acid (B3LYP/6-31G)
ORCA:
F. Neese, "Software update: the ORCA program system — Version 6.0", Wiley Interdiscip. Rev.: Comput. Mol. Sci., 
15, e70019 (2025). doi: 10.1002/wcms.70019.

Ex2: Methylamine (B3LYP/6-31G)
NWChem:
E. Aprà, D. Mejía-Rodríguez, et al., "NWChem: Recent and Ongoing Developments", J. Chem. Theory Comput., 
19, 7077–7096 (2023). doi: 10.1021/acs.jctc.3c00421. 

Ex3: Allyl radical (UHF/cc-pVDZ)
PSI-4:
D. G. A. Smith, L. A. Burns, et al., "Psi4 1.4: Open-source software for high-throughput quantum chemistry", 
J. Chem. Phys., 152, 184108 (2020). doi: 10.1063/5.0006002.

# Rendering Software:
Blender Foundation (2026). Blender (Version 5.1): Cycles Rendering Engine [Computer software]. Retrieved from blender.org
POV-Ray Team (2013). Persistence of Vision Raytracer (Version 3.7) [Computer software]. GNU Affero General Public License. Retrieved from povray.org

## Installation

1. Clone the repository
    git clone https://github.com
    cd MolVista

2. Install dependencies (using a VENV is recommended)
    pip install -r requirements.txt

3. Requirements
    - Python 3.x
    - PySide6, or compatible Qt wrapper
    - Matplotlib, NumPy, SciPy
    - PySCF (for on-the-fly grid generation from Molden/FCHK)
    - Scikit-Image (Marching Cubes algorithm)
    - ...

## Usage

    python3 main.py

Note: Precompiled executable is available for macOS, for Linux arm64, and Linux x64 see 'MolSuite'

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file 
for details.