oceanarray 0.1.0__py3-none-any.whl

oceanarray/logsheet/_latex.py

@@ -0,0 +1,128 @@
+"""oceanarray.logsheet._latex
+============================
+LaTeX escaping, column-spec building, and row-rendering helpers.
+"""
+
+_TEX_SPECIAL: dict[str, str] = {
+    "&": r"\&",
+    "%": r"\%",
+    "$": r"\$",
+    "#": r"\#",
+    "_": r"\_",
+    "{": r"\{",
+    "}": r"\}",
+    "~": r"\textasciitilde{}",
+    "^": r"\^{}",
+    "\\": r"\textbackslash{}",
+}
+
+
+def tex_safe(s: str) -> str:
+    """Escape a plain string that contains no LaTeX commands."""
+    if s is None:
+        return ""
+    return "".join(_TEX_SPECIAL.get(ch, ch) for ch in str(s))
+
+
+def colspec_from_cols(cols: list[dict]) -> str:
+    """Build a LaTeX tabular column-spec string from a resolved column list.
+
+    Column ``width`` values are relative weights normalised to fill
+    ``\\linewidth``.
+    """
+    total = sum(c["width"] for c in cols)
+    parts = ["|"]
+    for col in cols:
+        frac = col["width"] / total
+        col_type = "p" if col.get("align") == "left" else "C"
+        parts.append(
+            f"{col_type}{{\\dimexpr {frac:.5f}\\linewidth-2\\tabcolsep\\relax}}|"
+        )
+    return "".join(parts)
+
+
+def header_row(cols: list[dict]) -> str:
+    """Build the grey, bold LaTeX header row."""
+    cells = []
+    for col in cols:
+        text = " ".join(col["header"].split("\n"))
+        text = (
+            text.replace("_", r"\_")
+            .replace("{", r"\{")
+            .replace("}", r"\}")
+            .replace("&", r"\&")
+            .replace("#", r"\#")
+        )
+        cells.append(r"\cellcolor{hdrgray}{\bfseries\small " + text + r"}")
+    return " & ".join(cells)
+
+
+def example_data_row(cols: list[dict]) -> str:
+    """Build the shaded example row from the ``example`` field on each column."""
+    cells = []
+    for col in cols:
+        ex = str(col.get("example", ""))
+        if not ex:
+            cells.append("")
+            continue
+        ex_tex = ex if ex.startswith("\\") else tex_safe(ex)
+        cells.append(r"\textit{\small " + ex_tex + r"}")
+    return " & ".join(cells)
+
+
+def data_row(
+    cols: list[dict],
+    sn: int | None = None,
+    prefills: dict | None = None,
+    extra_readonly: dict | None = None,
+    prefilled_extra: dict | None = None,
+) -> str:
+    """Build a single instrument data row.
+
+    Parameters
+    ----------
+    cols:
+        Resolved column dicts.
+    sn:
+        Serial number; rendered in ``readonly`` SN columns.
+        ``0`` or ``None`` renders a blank SN cell.
+    prefills:
+        ``{key: value}`` map for pre-filled dynamic values (e.g. ``"sint"``).
+    extra_readonly:
+        ``{col_index: text}`` to force-fill specific columns as readonly text.
+    prefilled_extra:
+        ``{col_index: text}`` to force-fill specific columns with ``\\pre{}``
+        styling (grey).  Takes priority over all other logic for the matched column.
+
+    """
+    cells = []
+    if prefills is None:
+        prefills = {}
+    if extra_readonly is None:
+        extra_readonly = {}
+    if prefilled_extra is None:
+        prefilled_extra = {}
+
+    for i, col in enumerate(cols):
+        inp = col.get("input", "free")
+        default = col.get("default")
+
+        if i in prefilled_extra:
+            cells.append(r"\pre{" + tex_safe(str(prefilled_extra[i])) + r"}")
+        elif i in extra_readonly:
+            cells.append(r"\small " + tex_safe(str(extra_readonly[i])))
+        elif inp == "readonly" and col["header"].strip().startswith("SN"):
+            cells.append(r"\small " + tex_safe(str(sn)) if sn else "")
+        elif inp == "readonly":
+            cells.append("")
+        elif inp == "tick":
+            cells.append("")
+        elif inp == "prefilled" and default:
+            cells.append(r"\pre{" + tex_safe(default) + r"}")
+        elif inp == "prefilled" and sn and "{sint}" in col["header"]:
+            val = prefills.get("sint", "")
+            cells.append(r"\pre{" + tex_safe(str(val)) + r"}")
+        else:
+            cells.append("")
+
+    return " & ".join(cells)

oceanarray/logsheet/_render.py

@@ -0,0 +1,126 @@
+"""oceanarray.logsheet._render
+==============================
+Jinja2 environment factory and PDF compilation helper.
+"""
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader
+
+
+def make_jinja_env(templates_dir: Path) -> Environment:
+    """Return a Jinja2 :class:`~jinja2.Environment` configured for LaTeX templates.
+
+    Uses custom delimiters to avoid clashing with LaTeX ``{}``:
+
+    - blocks:    ``(% … %)``
+    - variables: ``(( … ))``
+    - comments:  ``(# … #)``
+
+    Parameters
+    ----------
+    templates_dir:
+        Directory containing the ``.tex.j2`` template files.  Pass
+        ``cfg.templates_dir`` (which defaults to the bundled package data).
+
+    """
+    return Environment(
+        loader=FileSystemLoader(str(templates_dir)),
+        block_start_string="(%",
+        block_end_string="%)",
+        variable_start_string="((",
+        variable_end_string="))",
+        comment_start_string="(#",
+        comment_end_string="#)",
+        keep_trailing_newline=True,
+    )
+
+
+def compile_pdf(
+    tex_source: str,
+    out_pdf: Path,
+    out_tex: Path | None = None,
+) -> Path:
+    """Compile a LaTeX source string to PDF via ``pdflatex``.
+
+    Parameters
+    ----------
+    tex_source:
+        Complete LaTeX document source.
+    out_pdf:
+        Destination path for the compiled PDF.
+    out_tex:
+        If given, also write the ``.tex`` source alongside the PDF.
+
+    Raises
+    ------
+    RuntimeError
+        If ``pdflatex`` fails to produce a PDF.
+
+    """
+    if out_tex is not None:
+        out_tex.write_text(tex_source, encoding="utf-8")
+        print(f"  Written: {out_tex}")
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tex_file = Path(tmpdir) / "sheet.tex"
+        tex_file.write_text(tex_source, encoding="utf-8")
+        result = subprocess.run(
+            [
+                "pdflatex",
+                "-interaction=nonstopmode",
+                "-output-directory",
+                tmpdir,
+                str(tex_file),
+            ],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        pdf_tmp = Path(tmpdir) / "sheet.pdf"
+        if pdf_tmp.exists():
+            shutil.copy(pdf_tmp, out_pdf)
+            print(f"  Written: {out_pdf}")
+        else:
+            print("LaTeX compilation failed. Log:")
+            print(result.stdout[-3000:])
+            raise RuntimeError(f"pdflatex failed for {out_pdf.name}")
+
+    return out_pdf
+
+
+def render_sheet(
+    tex_source: str,
+    out_dir: Path,
+    stem: str,
+    fmt: str = "pdf",
+) -> Path:
+    """Write a rendered LaTeX sheet to ``out_dir`` in the requested format.
+
+    Parameters
+    ----------
+    tex_source:
+        Complete LaTeX document source.
+    out_dir:
+        Output directory (created by caller).
+    stem:
+        Filename stem (no extension), e.g. ``"castN1_setup"``.
+    fmt:
+        ``"pdf"`` — compile via pdflatex (also writes ``.tex`` alongside).
+        ``"tex"`` — write ``.tex`` only; skip pdflatex.
+
+    Raises
+    ------
+    RuntimeError
+        If ``fmt="pdf"`` and pdflatex fails.
+
+    """
+    if fmt == "tex":
+        out_path = out_dir / f"{stem}.tex"
+        out_path.write_text(tex_source, encoding="utf-8")
+        print(f"  Written: {out_path}")
+        return out_path
+    return compile_pdf(tex_source, out_dir / f"{stem}.pdf", out_dir / f"{stem}.tex")

oceanarray/logsheet/builders/__init__.py

@@ -0,0 +1,13 @@
+from .caldip_setup import build_caldip_setup
+from .caldip_download import build_caldip_download
+from .recovery import build_recovery
+from .mooring_download import build_mooring_download
+from .deployment_setup import build_deployment_setup
+
+__all__ = [
+    "build_caldip_setup",
+    "build_caldip_download",
+    "build_recovery",
+    "build_mooring_download",
+    "build_deployment_setup",
+]

oceanarray/logsheet/builders/caldip_download.py

@@ -0,0 +1,195 @@
+"""oceanarray.logsheet.builders.caldip_download
+===============================================
+Build caldip-download PDF logsheets.
+"""
+
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .._config import (
+    LogsheetsConfig,
+    load_yaml,
+    load_instruments,
+    sn_to_entry,
+)
+from .._firmware import fw_group, FW_GROUP_LABELS
+from .._latex import colspec_from_cols, header_row, data_row, example_data_row
+from .._columns import resolve_columns, format_data_path_note
+from .._render import make_jinja_env, render_sheet
+
+
+def build_caldip_download(
+    cast_id: str,
+    cfg: LogsheetsConfig,
+    fmt: str = "pdf",
+    caldip_yaml: "dict | None" = None,
+) -> Path:
+    """Build the caldip-download PDF for a given cast.
+
+    Parameters
+    ----------
+    cast_id:
+        File path string (used for the output filename fallback when
+        *caldip_yaml* is provided) or a cast key in a legacy
+        ``cruise_config.yaml → casts`` dict.
+    cfg:
+        Resolved logsheets configuration from :func:`~._config.resolve_config`.
+    fmt:
+        ``"pdf"`` or ``"tex"``.
+    caldip_yaml:
+        Pre-loaded caldip YAML dict.  The canonical format is a dict with a
+        top-level ``instruments:`` list; each entry has at minimum ``serial``
+        (int) and ``instrument`` (type string).  When provided, cast info is
+        taken directly from this dict.
+
+    """
+    col_defs = load_yaml(cfg.column_defs_path)
+    col_library = col_defs.get("column_library", {})
+    instruments = load_instruments(cfg)
+
+    # Global settings from logsheet_config.yaml (with safe fallback).
+    lsconf: dict = {}
+    if cfg.cruise_config_path.exists():
+        lsconf = load_yaml(cfg.cruise_config_path)
+
+    sentinel = lsconf.get("microcat_firmware_sentinel", "3.0d")
+    caldip_data = lsconf.get("paths", {}).get("caldip_data", "")
+
+    # Cast config: from explicit caldip_yaml, or looked up in legacy casts dict.
+    if caldip_yaml is not None:
+        cast_cfg = caldip_yaml
+    else:
+        cast_cfg = lsconf.get("casts", {}).get(cast_id)
+        if cast_cfg is None:
+            sys.exit(f"Cast {cast_id} not found in {cfg.cruise_config_path}")
+
+    # cruise may live in the caldip YAML itself or in logsheet_config.yaml.
+    cruise = cast_cfg.get("cruise") or lsconf.get("cruise", "")
+
+    # Label: try common key names, fall back to file stem.
+    cast_label = (
+        cast_cfg.get("label")
+        or cast_cfg.get("cast_label")
+        or cast_cfg.get("name")
+        or cast_cfg.get("cast")
+        or Path(cast_id).name.split(".")[0]
+    )
+
+    all_mcats_by_group: dict[str, list[dict]] = {
+        "old_seaterm": [],
+        "seaterm_v2": [],
+        "seaterm_v2_odo": [],
+    }
+    all_aquadopps: list[dict] = []
+    rbr_tr1050_entries: list[dict] = []
+    rbr_solot_entries: list[dict] = []
+    seapoint_entries: list[dict] = []
+    sheet_warnings: list[str] = []
+
+    # Canonical caldip YAML format: top-level instruments: list.
+    for item in cast_cfg.get("instruments", []):
+        sn = int(item["serial"])
+        try:
+            itype, entry = sn_to_entry(instruments, sn)
+        except KeyError:
+            sheet_warnings.append(f"SN {sn} not found in inventory -- skipped")
+            continue
+        if itype == "microcat":
+            all_mcats_by_group[fw_group(entry, sentinel)].append(entry)
+        elif itype == "aquadopp":
+            all_aquadopps.append(entry)
+        elif itype in ("rbrsolo", "rbrduet"):
+            rbr_solot_entries.append(entry)
+        elif itype == "tr1050":
+            rbr_tr1050_entries.append(entry)
+        elif itype == "seapoint":
+            seapoint_entries.append(entry)
+
+    sections = []
+
+    mcat_def = col_defs["microcat_download_caldip"]
+    mcat_note_raw = mcat_def.get("data_path_note", "")
+
+    for grp, entries in all_mcats_by_group.items():
+        if not entries:
+            continue
+        cols = resolve_columns(mcat_def[f"columns_{grp}"], col_library)
+        note_lines = format_data_path_note(
+            mcat_note_raw, caldip_data=caldip_data, cast_label=cast_label
+        )
+        sections.append(
+            {
+                "title": FW_GROUP_LABELS[grp],
+                "colspec": colspec_from_cols(cols),
+                "header_row": header_row(cols),
+                "example_row": example_data_row(cols),
+                "note_lines": note_lines,
+                "data_rows": [data_row(cols, sn=e["serial"]) for e in entries],
+                "ncols": len(cols),
+            }
+        )
+
+    if all_aquadopps:
+        aq_def = col_defs["aquadopp_download_caldip"]
+        cols = resolve_columns(aq_def["columns"], col_library)
+        sections.append(
+            {
+                "title": aq_def.get("section_title", "Aquadopp Cal Dip Download"),
+                "colspec": colspec_from_cols(cols),
+                "header_row": header_row(cols),
+                "example_row": example_data_row(cols),
+                "note_lines": format_data_path_note(
+                    aq_def.get("data_path_note", ""),
+                    caldip_data=caldip_data,
+                    cast_label=cast_label,
+                ),
+                "data_rows": [data_row(cols, sn=e["serial"]) for e in all_aquadopps],
+                "ncols": len(cols),
+            }
+        )
+
+    def _rbr_section(def_key: str, entries: list[dict]) -> dict:
+        defn = col_defs[def_key]
+        cols = resolve_columns(defn["columns"], col_library)
+        note_lines = format_data_path_note(
+            defn.get("data_path_note", ""),
+            caldip_data=caldip_data,
+            cast_label=cast_label,
+        )
+        return {
+            "title": defn.get("section_title", def_key),
+            "colspec": colspec_from_cols(cols),
+            "header_row": header_row(cols),
+            "example_row": example_data_row(cols),
+            "note_lines": note_lines,
+            "data_rows": [data_row(cols, sn=e["serial"]) for e in entries],
+            "ncols": len(cols),
+        }
+
+    if rbr_tr1050_entries:
+        sections.append(_rbr_section("rbr_tr1050_download_caldip", rbr_tr1050_entries))
+    if rbr_solot_entries:
+        sections.append(_rbr_section("rbr_solot_download_caldip", rbr_solot_entries))
+    if seapoint_entries:
+        sections.append(_rbr_section("rbr_solot_download_caldip", seapoint_entries))
+
+    tex_source = (
+        make_jinja_env(cfg.templates_dir)
+        .get_template("caldip_download.tex.j2")
+        .render(
+            cruise=cruise,
+            cast_label=cast_label,
+            sections=sections,
+            sheet_warnings=sheet_warnings,
+            timestamp=datetime.now().strftime("%Y-%m-%d %H:%M"),
+        )
+    )
+
+    out_dir = cfg.output_dir / "caldip-download"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    stem = f"{cast_label}_download"
+    try:
+        return render_sheet(tex_source, out_dir, stem, fmt)
+    except RuntimeError:
+        sys.exit(1)

oceanarray/logsheet/builders/caldip_setup.py

@@ -0,0 +1,188 @@
+"""oceanarray.logsheet.builders.caldip_setup
+============================================
+Build caldip-setup PDF logsheets.
+"""
+
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .._config import (
+    LogsheetsConfig,
+    load_yaml,
+    load_instruments,
+    sn_to_entry,
+)
+from .._firmware import fw_group, FW_GROUP_LABELS
+from .._latex import colspec_from_cols, header_row, data_row, example_data_row
+from .._columns import resolve_columns
+from .._render import make_jinja_env, render_sheet
+
+
+def build_caldip_setup(
+    cast_id: str,
+    cfg: LogsheetsConfig,
+    fmt: str = "pdf",
+    caldip_yaml: "dict | None" = None,
+) -> Path:
+    """Build the caldip-setup PDF for a given cast.
+
+    Parameters
+    ----------
+    cast_id:
+        File path string (used for the output filename fallback when
+        *caldip_yaml* is provided) or a cast key in a legacy
+        ``cruise_config.yaml → casts`` dict.
+    cfg:
+        Resolved logsheets configuration from :func:`~._config.resolve_config`.
+    fmt:
+        ``"pdf"`` or ``"tex"``.
+    caldip_yaml:
+        Pre-loaded caldip YAML dict.  The canonical format is a dict with a
+        top-level ``instruments:`` list; each entry has at minimum ``serial``
+        (int) and ``instrument`` (type string).  When provided, cast info is
+        taken directly from this dict.
+
+    """
+    col_defs = load_yaml(cfg.column_defs_path)
+    col_library = col_defs.get("column_library", {})
+    instruments = load_instruments(cfg)
+
+    # Global settings from logsheet_config.yaml (with safe fallback).
+    lsconf: dict = {}
+    if cfg.cruise_config_path.exists():
+        lsconf = load_yaml(cfg.cruise_config_path)
+
+    sentinel = lsconf.get("microcat_firmware_sentinel", "3.0d")
+    caldip_data = lsconf.get("paths", {}).get("caldip_data", "")
+
+    # Cast config: from explicit caldip_yaml, or looked up in legacy casts dict.
+    if caldip_yaml is not None:
+        cast_cfg = caldip_yaml
+    else:
+        cast_cfg = lsconf.get("casts", {}).get(cast_id)
+        if cast_cfg is None:
+            sys.exit(f"Cast {cast_id} not found in {cfg.cruise_config_path}")
+
+    # cruise may live in the caldip YAML itself or in logsheet_config.yaml.
+    cruise = cast_cfg.get("cruise") or lsconf.get("cruise", "")
+
+    # Label: try common key names, fall back to file stem.
+    cast_label = (
+        cast_cfg.get("label")
+        or cast_cfg.get("cast_label")
+        or cast_cfg.get("name")
+        or cast_cfg.get("cast")
+        or Path(cast_id).name.split(".")[0]
+    )
+    post_dep = cast_cfg.get("post_deployment", False)
+
+    all_mcats_by_group: dict[str, list[dict]] = {
+        "old_seaterm": [],
+        "seaterm_v2": [],
+        "seaterm_v2_odo": [],
+    }
+    all_aquadopps: list[dict] = []
+    rbr_tr1050_entries: list[dict] = []
+    rbr_solot_entries: list[dict] = []
+    seapoint_entries: list[dict] = []
+    sheet_warnings: list[str] = []
+
+    # Canonical caldip YAML format: top-level instruments: list.
+    # Each entry has serial (int) and instrument (type string).
+    # Classify each entry by looking up the serial in the inventory.
+    for item in cast_cfg.get("instruments", []):
+        sn = int(item["serial"])
+        try:
+            itype, entry = sn_to_entry(instruments, sn)
+        except KeyError:
+            sheet_warnings.append(f"SN {sn} not found in inventory -- skipped")
+            continue
+        if itype == "microcat":
+            all_mcats_by_group[fw_group(entry, sentinel)].append(entry)
+        elif itype == "aquadopp":
+            all_aquadopps.append(entry)
+        elif itype in ("rbrsolo", "rbrduet"):
+            rbr_solot_entries.append(entry)
+        elif itype == "tr1050":
+            rbr_tr1050_entries.append(entry)
+        elif itype == "seapoint":
+            seapoint_entries.append(entry)
+
+    sections = []
+
+    mcat_def = col_defs["microcat_setup_caldip"]
+    for grp, entries in all_mcats_by_group.items():
+        if not entries:
+            continue
+        cols = resolve_columns(mcat_def[f"columns_{grp}"], col_library)
+        sections.append(
+            {
+                "title": FW_GROUP_LABELS[grp],
+                "colspec": colspec_from_cols(cols),
+                "header_row": header_row(cols),
+                "example_row": example_data_row(cols),
+                "data_rows": [data_row(cols, sn=e["serial"]) for e in entries],
+                "post_deployment": post_dep,
+                "ncols": len(cols),
+            }
+        )
+
+    if all_aquadopps:
+        cols = resolve_columns(
+            col_defs["aquadopp_setup_caldip"]["columns"], col_library
+        )
+        sections.append(
+            {
+                "title": "Aquadopp",
+                "colspec": colspec_from_cols(cols),
+                "header_row": header_row(cols),
+                "example_row": example_data_row(cols),
+                "data_rows": [data_row(cols, sn=e["serial"]) for e in all_aquadopps],
+                "post_deployment": False,
+                "ncols": len(cols),
+            }
+        )
+
+    def _rbr_section(entries: list[dict], title: str) -> dict:
+        cols = resolve_columns(col_defs["rbr_setup_caldip"]["columns"], col_library)
+        return {
+            "title": title,
+            "colspec": colspec_from_cols(cols),
+            "header_row": header_row(cols),
+            "example_row": example_data_row(cols),
+            "data_rows": [data_row(cols, sn=e["serial"]) for e in entries],
+            "post_deployment": False,
+            "ncols": len(cols),
+        }
+
+    if rbr_tr1050_entries:
+        sections.append(_rbr_section(rbr_tr1050_entries, "RBR TR-1050 Thermistors"))
+    if rbr_solot_entries:
+        sections.append(_rbr_section(rbr_solot_entries, "RBR soloT Thermistors"))
+    if seapoint_entries:
+        sections.append(_rbr_section(seapoint_entries, "Seapoint Turbidity"))
+
+    caldip_data_tex = caldip_data.replace("~", r"\textasciitilde{}").replace("_", r"\_")
+
+    tex_source = (
+        make_jinja_env(cfg.templates_dir)
+        .get_template("caldip_setup.tex.j2")
+        .render(
+            cruise=cruise,
+            cast_label=cast_label,
+            moorings_str="",
+            caldip_data=caldip_data_tex,
+            sections=sections,
+            sheet_warnings=sheet_warnings,
+            timestamp=datetime.now().strftime("%Y-%m-%d %H:%M"),
+        )
+    )
+
+    out_dir = cfg.output_dir / "caldip-setup"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    stem = f"{cast_label}_setup"
+    try:
+        return render_sheet(tex_source, out_dir, stem, fmt)
+    except RuntimeError:
+        sys.exit(1)