# Quickstart

This guide walks through generating a mooring diagram from a YAML configuration file.

## Prerequisites

Install the package (see [Installation](installation.md)):

```bash
pip install moordiag
```

## Step 1 — Create a mooring YAML

A minimal mooring configuration (`my_mooring.yaml`):

```yaml
name: my_mooring_2026
year: 2026
status: planned        # deployed | planned | recovered  (any string is accepted)
waterdepth: 700
cruise: MSM142
ship: Merian
deployment_time: '2026-05-05T00:00:00'
recovery_time: '2027-05-05T00:00:00'
planned_latitude: 65.594
planned_longitude: -29.467
inline:
  - position: '1'
    serial: 'n/a'
    label: 'Recovery float'
    image: top_float.png
    hab: 500
  - position: '2'
    serial: '0001 + 0002'
    label: '2 Releases'
    image: release_pair.png
    hab: 10
  - position: '3'
    serial: 'n/a'
    label: 'Anchor'
    image: anchor_wheel.png
    hab: 0
```

Elements require either `hab` (height above bottom in metres) or `depth`
(negative metres below surface). If both are given, `hab` takes priority.

The `name` field is used in diagram titles and in output filenames, so it
should be unique and descriptive.  The filename itself does not need to match
the `name` value and does not need to contain the year.

### Instrument serials

The `serial` field controls what is shown next to each instrument label:

| `serial` value | Displayed as |
|---|---|
| `null` (YAML null) | nothing — serial is omitted |
| `'n/a'` | nothing — serial is omitted |
| `'0000'` | `_______` — blank placeholder (serial not yet assigned) |
| any other string | shown as-is after the label |

Use `serial: null` or `serial: 'n/a'` for hardware items (anchors, floats,
shackles) that do not have serial numbers.  Use `serial: '0000'` for
instruments whose serial you plan to fill in later — the underscores serve
as a visible reminder that the field is incomplete.

### Clamp-on instruments

Instruments clamped to the mooring wire (e.g. RBR or SBE37 microcats) go in
a separate `clamp:` section rather than `inline:`:

```yaml
clamp:
  - clamp_id: '1'
    serial: 'SBE37-12345'
    label: 'SBE37 microcat'
    image: microcat.png
    hab: 450
```

## Step 2 — Generate the diagram

```bash
moordiag single my_mooring.yaml
```

This produces a diagram in the `diagrams/` directory.

## Step 3 — Multi-mooring batch generation

To generate all diagram types for a cruise, run:

```bash
bash generate_diagrams.sh
```

See `generate_diagrams.sh` for per-mooring configuration.