# Molecule2D and Molecule

> Molecule2D draws a skeletal formula from a Structure: atoms with positions in bond lengths (y up) and bonds between them.

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

`Molecule2D` draws a skeletal formula from a `Structure`: atoms with positions in bond
lengths (`y` up) and bonds between them. It draws the bonds `bond_length` pixels long:

- single, double and triple bonds;
- a solid `Wedge` out of the page and a hashed `Dash` behind it, both wide at the second atom;
- in a ring, the second line of a double bond inside the ring;
- with the same number of neighbours on both sides (a carbonyl), the two lines centred.

Carbons are left out. Other atoms are labelled with their hydrogens (on the side away from
their bonds) and their charge, and with `color_atoms` oxygen, nitrogen, sulfur, phosphorus
and the halogens get their own colours. With `Create` as `enter` the bonds draw on one after
the other. Gallery scene: `Molecule2D` (a stereocentre with a wedge and a dash).

Gallery clip of `Molecule2D`: https://fframes-kit.pages.dev/media/scenes/Molecule2D-65056ef5.mp4

`Molecule` takes a SMILES string instead. `Structure::from_smiles` reads it with `chematic`,
which lays it out in 2D. Aromatic rings become alternating single and double bonds. The
layout is computed once per string and kept for the rest of the process. An invalid string
draws nothing, so check new strings with `Structure::from_smiles`, which returns a
`SmilesError`. Gallery scene: `Molecule` (aspirin and caffeine).

Gallery clip of `Molecule`: https://fframes-kit.pages.dev/media/scenes/Molecule-8a0c6a67.mp4

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

fn water() -> Structure {
    Structure::new(
        vec![
            ChemAtom::new("O", 0.0, 0.0),
            ChemAtom::new("H", -0.8, -0.6),
            ChemAtom::new("H", 0.8, -0.6),
        ],
        vec![
            ChemBond::new(0, 1, BondKind::Single),
            ChemBond::new(0, 2, BondKind::Single),
        ],
    )
}

fn figures<'a>(ui: &mut Ui<'a, '_, '_>, water: &'a Structure) -> Svgr<'a> {
    let water = ui.show(Molecule2D {
        structure: Some(water),
        center: (-4.0, 0.0),
        bond_length: 90.0,
        ..ui.defaults()
    });
    let aspirin = ui.show(Molecule {
        smiles: "CC(=O)Oc1ccccc1C(=O)O".into(),
        center: (2.5, 0.0),
        enter: Some(Create::default().into()),
        ..ui.defaults()
    });
    svgr!(<g>{water}{aspirin}</g>)
}
```

## 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`).

### Molecule2D

A skeletal formula: the bonds of `structure` `bond_length` pixels long around `center` (units of `ui.space`), double bonds in rings drawn inside the ring, and the labels of the atoms that are not carbons, with their hydrogens and charges (`show_hydrogens`). The bonds draw on in order with `enter` (`Create` draws them one after the other), the labels with `parts_enter`. With `color_atoms` oxygen, nitrogen, sulfur, phosphorus and the halogens get their own colours. Without `structure` nothing is drawn.

| 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` | `70.0` | Pixels per bond length of the structure's coordinates. |
| `show_hydrogens` | `bool` | `true` | Writes the hydrogens and charge after a heteroatom's symbol (`OH`, `NH2`); `false` writes the symbol alone. |
| `color_atoms` | `bool` | `true` | Colours the labels of oxygen, nitrogen, sulfur, phosphorus and the halogens; `false` uses `bond_color` for all. |
| `bond_color` | `Color` | `theme.colors.text` | Colour of the bonds, and of the labels of carbon and of every atom when `color_atoms` is `false`. |
| `stroke_width` | `f32` | `theme.stroke.regular` | Width in pixels of the bond lines. |
| `enter` | `Option<EnterAnim>` | `None` | How the bonds draw on; `None` shows them from the start. |
| `exit` | `Option<ExitAnim>` | `None` | How the bonds leave at the end of the container; `None` stays. |
| `parts_enter` | `Option<FadeIn>` | `None` | Fade in of the atom labels; `None` for none. |
| `parts_exit` | `Option<FadeOut>` | `None` | Fade out of the atom labels before the end; `None` for none. |

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

### Molecule

A skeletal formula from a SMILES string (`"CC(=O)O"`), laid out by `chematic` and drawn like `Molecule2D`. The layout is computed once per string and kept for the rest of the process; an invalid string draws nothing (check it with `Structure::from_smiles`).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `smiles` | `Cow<str>` | `Cow::Borrowed("c1ccccc1")` | The molecule as a SMILES string (`"CC(=O)O"`); an invalid string draws nothing. |
| `center` | `(f64, f64)` | `m.center` | The middle of the molecule's coordinates, in units of `ui.space`. |
| `bond_length` | `f32` | `m.bond_length` | Pixels per bond length of the laid-out structure. |
| `show_hydrogens` | `bool` | `m.show_hydrogens` | Writes the hydrogens and charge after a heteroatom's symbol (`OH`, `NH2`); `false` writes the symbol alone. |
| `color_atoms` | `bool` | `m.color_atoms` | Colours the labels of oxygen, nitrogen, sulfur, phosphorus and the halogens; `false` uses `bond_color` for all. |
| `bond_color` | `Color` | `m.bond_color` | Colour of the bonds, and of the labels of carbon and of every atom when `color_atoms` is `false`. |
| `stroke_width` | `f32` | `m.stroke_width` | Width in pixels of the bond lines. |
| `enter` | `Option<EnterAnim>` | `None` | How the bonds draw on; `None` shows them from the start. |
| `exit` | `Option<ExitAnim>` | `None` | How the bonds leave at the end of the container; `None` stays. |
| `parts_enter` | `Option<FadeIn>` | `None` | Fade in of the atom labels; `None` for none. |
| `parts_exit` | `Option<FadeOut>` | `None` | Fade out of the atom labels before the end; `None` for none. |

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