ORCA Visualizer

Cross-platform ORCA post-processing and visualization software built with Python, Streamlit, ASE, and Plotly.

支持 macOS / Ubuntu / Windows 的 ORCA 结果处理与可视化软件，面向本地科研工作流，覆盖输出解析、结构显示、谱图、路径、cube、GBW 和后台驻留任务检测。

Important:

For pure viewing of existing .out / .log / .xyz / .cube files, ORCA itself is not required.
For GBW -> cube, local validation, and ORCA tool/environment checks, you should install ORCA on the same machine and make orca / orca_plot available.

Highlights

Parse .out, .log, .txt, .xyz, .cube, and .gbw
Visualize structures, frequencies, vibrational modes, TDDFT spectra, IRC / NEB / Scan paths, and atomic charges
Generate electron density, spin density, ESP, HOMO/LUMO, and custom MO cubes from GBW + orca_plot
Provide transition-state diagnostics and thermochemistry summaries
Support Chinese / English UI switching
Include a cross-platform background-process monitor for ORCA / Python / Streamlit jobs
Provide a card-based landing page and clearer upload-before/upload-after states
Ship unified figure styling and export presets for Paper / Presentation / Web
Provide separate 2D/3D export presets, faithful export, paper export, HTML export, and 3D view-aware export controls
Show persistent task status for GBW density scanning and cube generation
Offer an npm launcher so non-developer users can install and run the app more easily
Run on Windows, macOS, and Ubuntu/Linux with launch scripts and CI coverage

Platform Support

The repository is maintained for:

windows-latest
macos-latest
ubuntu-latest
Python 3.10, 3.11, 3.12

This matrix is verified in GitHub Actions: .github/workflows/ci.yml

Features

ORCA Output Analysis

Final energy and optimization energy trajectory
Frequencies, imaginary modes, and vibrational density broadening
Normal-mode animation
TDDFT / TDA absorption spectra
IRC / NEB / relaxed Scan pathway plots
Transition-state diagnosis, TS mode, active atoms, Hessian summary, and thermochemistry
Mulliken / Loewdin charges

3D Visualization

Ball-and-stick, space-filling, stick, and wireframe structure views
Direct atom picking for automatic distance / angle / dihedral measurements
Charge-colored 3D molecular views
Cube slice and isosurface rendering for density, ESP, and orbitals

GBW Workflow

Auto-detect orca_plot where possible
Detect sidecar files such as .densities, .densitiesinfo, .property.txt, .xyz
Generate:
- electron density
- spin density
- electrostatic potential
- HOMO / LUMO
- custom molecular orbitals

Utilities

Background process monitor for resident ORCA / Python / Streamlit tasks
High-resolution figure export with preset-based defaults
Bilingual UI

Export Presets

Paper: larger canvas, tighter typography, vector-friendly defaults
Presentation: 16:9 layout and larger labels for slide decks
Web: lighter canvas for browser previews and screenshots

Export modes:

Faithful Export: preserve the current figure as much as possible and only adjust size / scale / explicit toggles
Paper Export: keep the current 2D/3D view while normalizing typography, margins, and background for publication use

3D-specific export controls:

current view
fit molecule
fit surface
paper default
hide axes / legend / colorbar
tight crop / balanced margin

Supported export targets:

PNG
SVG
PDF
HTML for interactive 3D delivery

Screens and Data Types

Single-File Mode

Supported inputs:

.out
.log
.txt
.xyz
.cube
.gbw

Batch Mode

Use batch mode to compare multiple ORCA or cube files from:

multiple uploaded files
a local folder scanned recursively

Quick Start

1. Install from npm

npm install -g orca-visualizer
orca-visualizer
orca-visualizer doctor

Or run without a global install:

npx orca-visualizer

Notes:

The npm launcher expects local Python 3.10 / 3.11 / 3.12.
The npm package does not bundle ORCA itself.
To use GBW -> cube, orca_plot, or local ORCA validation workflows, install ORCA locally first.

2. Install from the Repository

If you prefer cloning the repository, or if you want a no-npm install path, use the bundled install scripts:

macOS: double-click install_app.command, then run_app.command
Ubuntu / Linux:

bash install_app.sh
bash run_app.sh

Windows PowerShell:

.\install_app.ps1
.\run_app.ps1

Windows CMD:

install_app.bat
run_app.bat

The install scripts:

create .venv automatically if needed
upgrade pip / setuptools / wheel
install the packaged app with pip install .
keep the launch path short for non-developer users

Before using GBW -> electron density / spin density / ESP / HOMO / LUMO workflows, install ORCA locally first. The app can read existing ORCA outputs without ORCA, but it cannot call orca_plot if ORCA is not installed on the machine.

3. Clone the Repository

git clone https://github.com/wuls968/orca-visualizer.git
cd orca-visualizer

4. Developer Install

For active development, use an editable install so source-code changes apply immediately.

macOS / Ubuntu:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements-dev.txt

Windows PowerShell:

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements-dev.txt

Windows CMD:

py -3 -m venv .venv
call .venv\Scripts\activate.bat
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements-dev.txt

Equivalent developer install command:

python -m pip install -e ".[dev]"

5. Run the App

Recommended:

orca-visualizer
orca-visualizer doctor

Developer-friendly:

python -m orca_viz.cli run

Compatibility entry:

python -m streamlit run app.py

The packaged launcher and npm wrapper both route through the same CLI entrypoint. app.py remains only as a thin compatibility wrapper.

Platform launchers:

macOS: run_app.command
Ubuntu / Linux: run_app.sh
Windows CMD: run_app.bat
Windows PowerShell: run_app.ps1

Environment Doctor and ORCA Tool Detection

The app now includes a dedicated Environment Doctor mode in the sidebar.

It checks:

Python runtime and package versions
ORCA_HOME
auto-detected ORCA version from installation paths
version probing from the orca executable when possible, with path-based fallback
whether key ORCA utilities are usable, including:
- orca
- orca_plot
- orca_2json
- orca_2mkl
- orca_mapspc
- orca_vib
- orca_pltvib
- orca_nmrspectrum

The same logic is available from the command line:

python -m orca_viz.cli doctor
python -m orca_viz.cli doctor --json

# after packaged install
orca-viz-doctor
orca-viz-doctor --json

When no manual path is provided, the detector searches:

current-process PATH
current-process ORCA_HOME
login-shell PATH and ORCA_HOME
common ORCA installation directories on Windows / macOS / Ubuntu

If ORCA is installed locally, this page is also the fastest way to confirm whether orca, orca_plot, and related tools are really callable by the app instead of only existing somewhere on disk.

Maintainer Note: Manual npm Publishing

This repository now uses manual local npm publishing instead of GitHub-triggered publication.

Recommended maintainer workflow:

npm version <new-version>
npm pack --dry-run
npm publish --access public

Then create and push the matching Git tag and GitHub release manually.

This keeps npm publication under explicit local control and avoids accidental release-triggered publishes from CI.

ORCA and GBW Notes

If you want GBW-derived density or orbital cubes, install ORCA and make sure orca_plot is available.

In practice this means:

install ORCA locally on the machine where ORCA Visualizer runs
ensure orca and orca_plot are reachable through ORCA_HOME or PATH
then use the Environment Doctor page to verify detection before starting GBW workflows

Recommended GBW sidecar files:

.densities
.densitiesinfo
.property.json
.property.txt
.xyz
.out or .log

The app tries to auto-detect orca_plot. If detection fails, provide the ORCA installation directory or executable path in the UI.

Export Notes

2D and 3D figures now use different default export sizes.
3D export keeps the current camera / scene by default instead of resetting to a generic view.
SVG / PDF export is still useful for 2D figures, but Plotly WebGL-based 3D layers are typically rasterized there.
For high-quality interactive 3D sharing or archival, prefer HTML.

Structure Viewer Notes

The structure viewer is bundled locally in the repository, so it does not depend on an external CDN to render molecules.
Direct picking works in the Overview and Structure tabs.
Measurement logic is automatic:
- select 2 atoms: distance
- select 3 atoms: angle
- select 4 atoms: dihedral
- click a selected atom again: unselect it

Testing

Run local verification with:

python -m compileall -q app.py orca_viz tests
.venv/bin/python -m unittest discover -s tests

Current CI covers:

Windows
macOS
Ubuntu
Python 3.10 / 3.11 / 3.12

Project Layout

app.py: thin compatibility wrapper for Streamlit launches from a source checkout
pyproject.toml: package metadata, runtime dependencies, and CLI entrypoints
orca_viz/parser.py: ORCA output parsing
orca_viz/cube.py: cube reading and sampling
orca_viz/gbw.py: GBW loading and orca_plot workflows
orca_viz/orca_runtime.py: ORCA runtime and utility detection
orca_viz/streamlit_app.py: packaged Streamlit app entrypoint used by the CLI launcher
orca_viz/cli.py: CLI launch and environment-doctor commands
orca_viz/visualization.py: figures, 3D viewers, animations
orca_viz/plots: split plotting modules for structure / spectra / cube / charges / pathways
orca_viz/plot_theme.py: shared scientific plot theme
orca_viz/exporting.py: preset-based export pipeline
orca_viz/ui: page layer, UI components, export controls, and data-loading helpers
orca_viz/process_monitor.py: cross-platform process monitor
tests: unit tests

Changelog

See:

CHANGELOG.md

License

This project is released under the MIT License.

See:

LICENSE

中文说明

适用平台

Windows
macOS
Ubuntu / Linux
Python 3.10 / 3.11 / 3.12

并通过 GitHub Actions 持续测试。

主要功能

ORCA 输出解析：总能量、优化曲线、频率、虚频、TDDFT、IRC / NEB / Scan、过渡态、热化学
结构 3D 可视化：球棍、空间填充、棒状、线框
直接点原子自动测量：键长、键角、二面角
电荷 2D / 3D 分布
cube 切片和等值面
GBW + orca_plot 波函数后处理
环境检测：自动检查 orca / orca_plot / orca_2json / orca_2mkl 等工具可用性
后台驻留进程检测
中英文界面切换

启动方法

推荐命令：

orca-visualizer
orca-visualizer doctor

兼容的源码运行方式：

python -m streamlit run app.py

也可以直接双击或执行：

GBW 注意事项

如果要从 .gbw 生成电子密度、ESP 或轨道 cube，请先在本机安装好 ORCA，并确保 orca / orca_plot 可以被软件检测到。建议同时准备同名：

.densities
.densitiesinfo
.property.txt
.xyz
.out/.log

结构测量说明

选 2 个原子：显示键长
选 3 个原子：显示键角
选 4 个原子：显示二面角
再点一次已选原子：取消选中

更新记录

详见：

CHANGELOG.md

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github/workflows		.github/workflows
npm		npm
orca_viz		orca_viz
sample_data		sample_data
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
app.py		app.py
install_app.bat		install_app.bat
install_app.command		install_app.command
install_app.ps1		install_app.ps1
install_app.sh		install_app.sh
package.json		package.json
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
run_app.bat		run_app.bat
run_app.command		run_app.command
run_app.ps1		run_app.ps1
run_app.sh		run_app.sh

Folders and files

Latest commit

History

Repository files navigation

ORCA Visualizer

Highlights

Platform Support

Features

ORCA Output Analysis

3D Visualization

GBW Workflow

Utilities

Export Presets

Screens and Data Types

Single-File Mode

Batch Mode

Quick Start

1. Install from npm

2. Install from the Repository

3. Clone the Repository

4. Developer Install

5. Run the App

Environment Doctor and ORCA Tool Detection

Maintainer Note: Manual npm Publishing

ORCA and GBW Notes

Export Notes

Structure Viewer Notes

Testing

Project Layout

Changelog

License

中文说明

适用平台

主要功能

启动方法

GBW 注意事项

结构测量说明

更新记录

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages