Quickstart

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

Prerequisites

Install the package (see Installation):

pip install moordiag

Step 1 — Create a mooring YAML

A minimal mooring configuration (my_mooring.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::

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

Step 2 — Generate the diagram

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 generate_diagrams.sh

See generate_diagrams.sh for per-mooring configuration.