# GraphMolecule

> GraphMolecule is manim-chemistry's GraphMolecule with the animations of its GMAnimationBuilder.

Page: https://fframes-kit.pages.dev/docs/chemistry/graph-molecule/
Cargo feature: `chemistry` (`fframes-kit = { version = "..", features = ["chemistry"] }`)

`GraphMolecule` is manim-chemistry's `GraphMolecule` with the animations of its
`GMAnimationBuilder`. It draws every atom of a `Structure` as a ring with its symbol,
carbons too, and the bonds as lines, two for a double bond and three for a triple bond,
`bond_length` pixels long. Three lists animate it on the figure's own seconds, each entry
with a `start` and a `duration`:

- `rotations`: a `BondRotation` turns the part of the molecule on the far side of bond
  `bond` (the atoms reached from its second atom) by `degrees` about the bond, as about a
  shaft. The figure is seen from `elevation` degrees above the page (15 by default), and
  atoms nearer the viewer are drawn larger and on top. A bond in a ring turns nothing.
- `recolors`: a `Recolor` blends the atoms and bonds in `parts` (`MoleculePart::Atom(i)`,
  `MoleculePart::Bond(i)`) to `color`.
- `highlights`: a `GroupHighlight` fades in a band of `color` behind `atoms` and the bonds
  between them.

`functional_groups(&structure, FunctionalGroup::Carboxyl)` finds the atoms of each group in
a structure: hydroxyls, carbonyls, carboxyls, esters, amides, amines and ethers, each list
starting with the group's central atom. Gallery scenes: `GraphMolecule` (acetic acid with its
carboxyl group highlighted) and `BondRotation` (hexan-1-ol, its hydroxyl lit while the end of
the chain turns).

Gallery clip of `GraphMolecule`: https://fframes-kit.pages.dev/media/scenes/GraphMolecule-dc325d74.mp4

Gallery clip of `BondRotation`: https://fframes-kit.pages.dev/media/scenes/BondRotation-bdb86327.mp4

```rust
use fframes_kit::prelude::*;

// Prepare the structure once, outside the frame render.
let acid = Structure::from_smiles("CC(=O)O")?;
let carboxyl = functional_groups(&acid, FunctionalGroup::Carboxyl);

fn figure<'a>(ui: &mut Ui<'a, '_, '_>, acid: &'a Structure, carboxyl: &[Vec<usize>]) -> Svgr<'a> {
    let accent = ui.theme.colors.accent;
    ui.show(GraphMolecule {
        structure: Some(acid),
        rotations: vec![BondRotation { bond: 0, degrees: 180.0, start: 1.0, duration: 2.0 }],
        highlights: carboxyl
            .iter()
            .cloned()
            .map(|atoms| GroupHighlight { atoms, color: accent, start: 0.3, duration: 0.5 })
            .collect(),
        ..ui.defaults()
    })
}
```

## API

Components are plain structs. Set the fields you need and fill the rest with `..ui.defaults()`: the defaults below come from the current theme (`theme.` values are fields of `Theme`).

### GraphMolecule

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `structure` | `Option<&Structure>` | `None` | The molecule to draw (from SMILES, a molfile or built by hand); `None` draws nothing. |
| `center` | `(f64, f64)` | `(0.0, 0.0)` | The middle of the molecule's coordinates, in units of `ui.space`. |
| `bond_length` | `f32` | `110.0` | Pixels per bond length of the structure's coordinates. |
| `atom_radius` | `f32` | `24.0` | Radius in pixels of an atom ring, before the depth scaling of a turn. |
| `elevation` | `f32` | `15.0` | Degrees the view looks down from above the page: 0 is straight on, where atoms in line hide each other. |
| `rotations` | `Vec<BondRotation>` | `Vec::new()` | Turns of the part of the molecule beyond a bond; empty for none. |
| `recolors` | `Vec<Recolor>` | `Vec::new()` | Colour changes of atoms and bonds over time; empty for none. |
| `highlights` | `Vec<GroupHighlight>` | `Vec::new()` | Soft colour bands behind groups of atoms, fading in over time; empty for none. |
| `color_atoms` | `bool` | `true` | Colours each ring and symbol by its element; `false` uses `bond_color` for all. |
| `bond_color` | `Color` | `theme.colors.text` | Colour of the bonds, and of the atoms when `color_atoms` is `false`. |
| `atom_fill` | `Color` | `theme.colors.surface` | Fill colour inside the atom rings. |
| `stroke_width` | `f32` | `theme.stroke.regular` | Width in pixels of the bonds and atom rings. |
| `enter` | `Option<FadeIn>` | `None` | Fade in at the start; `None` for none. |
| `exit` | `Option<FadeOut>` | `None` | Fade out before the end; `None` for none. |

Feature `chemistry` · [Source](https://github.com/khanhthanhdev/fframes-kit/blob/main/fframes-kit/src/kits/chemistry/graph_anim.rs#L247)