# Molecular Orbitals

Render MO lobes from `.cube` or `.cub` files with `--mo`. The cube file contains both geometry and the orbital grid — no separate XYZ file needed.

When auto-orientation is active (default), the molecule is tilted 45° around the x-axis after alignment so lobes above and below the molecular plane are clearly visible. Use `--no-orient` to render in raw cube coordinates, or `-I` to use the [v viewer](https://github.com/briling/v) for interactive orientation.

Cube files are typically generated by [ORCA](https://www.faccts.de/docs/orca/6.1/manual/contents/utilitiesvisualization/utilities.html?q=orca_plot&n=0#orca-plot) (`orca_plot`) or Gaussian (`cubegen`).

> **Python.** All `xyzrender` flags below map 1:1 to keyword arguments on `render()` (`--foo bar` → `foo="bar"`). The non-obvious shapes here are `--mo-colors POS NEG` → `mo_colors=("steelblue", "maroon")` (a tuple) and loading a cube once for repeated renders with `mol = load("homo.cube")`. See the [Python API guide](../python_api.md).

```python
from xyzrender import load, render

mol = load("caffeine_homo.cube")
render(mol, mo=True, output="caffeine_homo.svg")
render(mol, mo=True, iso=0.03, mo_colors=("maroon", "teal"), opacity=0.8)
render(mol, mo=True, surface_style="mesh")
```

| HOMO (default) | LUMO (opaque + outlined) |
|----------------|--------------------------|
| ![HOMO](../../../examples/images/caffeine_homo.svg) | ![LUMO](../../../examples/images/caffeine_lumo.svg) |

The HOMO uses the default translucent appearance. The LUMO pairs `--mo-outline-width` with a high `--opacity` — outlines look cleanest on opaque lobes; at the default translucency the stroke fades along with the fill.

| HOMO + H (iso 0.03) | HOMO rotation |
|--------------------|--------------|
| ![HOMO + H (iso 0.03)](../../../examples/images/caffeine_homo_iso_hy.svg) | ![HOMO rotation](../../../examples/images/caffeine_homo.gif) |

```bash
xyzrender caffeine_homo.cube --mo -o caffeine_homo.svg
xyzrender caffeine_lumo.cube --mo --mo-colors maroon teal --opacity 0.8 --mo-outline-width 5 -o caffeine_lumo.svg
xyzrender caffeine_homo.cube --mo --hy --iso 0.03 -o homo_iso_hy.svg
xyzrender caffeine_homo.cube --mo --gif-rot -go caffeine_homo.gif
```

## Surface styles

All contour-based surfaces (MO, density, NCI) support alternative rendering styles via `--surface-style`:

| Mesh | Contour | Dot |
|------|---------|-----|
| ![Mesh](../../../examples/images/caffeine_homo_mesh.svg) | ![Contour](../../../examples/images/caffeine_homo_contour.svg) | ![Dot](../../../examples/images/caffeine_homo_dot.svg) |

```bash
xyzrender caffeine_homo.cube --mo --surface-style mesh
xyzrender caffeine_homo.cube --mo --surface-style contour
xyzrender caffeine_homo.cube --mo --surface-style dot
```

| Style | Description |
|-------|-------------|
| `solid` (default) | Filled surfaces with depth cueing |
| `mesh` | Warped grid lines emulating a 3D wireframe |
| `contour` | Iso-value contour rings showing surface depth |
| `dot` | Stippled contour rings (dots denser toward centre) |

## MO flags

| Flag | Description |
|------|-------------|
| `--mo` | Enable MO lobe rendering (required for `.cube` or `.cub` input) |
| `--iso` | Isosurface threshold (default: 0.05 — smaller value = larger lobes) |
| `--opacity` | Surface opacity (default: 0.6 when `--mo` is active, otherwise 1.0) |
| `--surface-style STYLE` | Surface rendering style: `solid`, `mesh`, `contour`, `dot` |
| `--mo-colors POS NEG` | Lobe colors as hex or [named color](https://matplotlib.org/stable/gallery/color/named_colors.html) (default: `steelblue` `maroon`) |
| `--mo-outline-width PX` | Outline stroke per lobe (solid style only; pair with `--opacity 1.0` for crisp edges) |
| `--mo-outline-color COLOR` | Outline color (default: black) |
| `--flat-mo` | Disable depth-fog colour blend on MO lobes |
| `--mo-blur SIGMA` | Gaussian blur sigma for lobe smoothing (default: 0.8, ADVANCED) |
| `--mo-upsample N` | Upsample factor for contour resolution (default: 3, ADVANCED) |