seismo-relay/sfm/report_pdf.py

"""
sfm/report_pdf.py — generate Instantel-style Event Report PDFs.

Stub layout for v0.20.0 — the exact visual is iterated against actual
Blastware reference PDFs (uploaded to docs/reference/instantel/).
Current output captures all the data fields a real BW Event Report
contains, but the visual hierarchy / spacing is still approximate.

Architecture
────────────
1. ``gather_report_data(event_id)`` — assembles a flat dict from three
   sources: the SeismoDb events row, the .sfm.json sidecar (bw_report
   block), and the .h5 waveform samples.  Returns ``None`` when the
   event doesn't exist or has no waveform data on disk.

2. ``render_event_report_pdf(data)`` — takes that dict and produces a
   single-page letter-sized PDF as bytes, using matplotlib's PDF
   backend (vector output, no rasterization, prints cleanly).

3. The HTTP endpoint at ``/db/events/{id}/report.pdf`` wires them
   together: fetch event → gather → render → stream bytes back with
   ``Content-Type: application/pdf``.

What's in the report (every field BW's printout includes):

  Header (left):  Date/Time, Trigger Source, Range, Sample Rate, Notes,
                  Project, Client, User Name, Seis. Loc
  Header (right): Serial + firmware, Battery, Calibration, File Name,
                  Post Event Notes
  Mic block:      PSPL (dBL + psi), ZC Freq, Channel Test result
  Stats table:    per-channel PPV / ZC Freq / Time of Peak /
                  Peak Acceleration / Peak Displacement / Sensor Check
  Peak Vector Sum
  Waveform plot:  4 channels stacked (MicL/Long/Vert/Tran), shared
                  time axis, trigger marker, peak markers
  USBM RI8507/OSMRE compliance chart:  STUBBED — separate work item

Histogram events: the layout differs (Number of Intervals header
field, no trigger marker, per-interval bar chart instead of waveform).
Handled via a record_type branch in ``render_event_report_pdf``.
"""

from __future__ import annotations

import io
import json
import logging
import math
from dataclasses import dataclass, field
from pathlib import Path
from typing import Optional

import matplotlib
matplotlib.use("Agg")   # headless — no display required
import matplotlib.pyplot as plt
import numpy as np
from matplotlib.backends.backend_pdf import PdfPages

log = logging.getLogger(__name__)


# Reference pressure for dB(L) conversion: 20 µPa expressed in psi.
DBL_REF_PSI = 2.9e-9


# ── Data assembly ────────────────────────────────────────────────────────────


@dataclass
class ReportData:
    """All fields needed to render an Instantel-style Event Report.

    Most fields are Optional — BW's printout shows '—' or just omits
    sections when source data is missing.  The renderer mirrors that.
    """
    # Header — left column
    event_datetime_str: Optional[str] = None
    trigger_source:     Optional[str] = None
    geo_range_str:      Optional[str] = None
    sample_rate_str:    Optional[str] = None
    notes:              Optional[str] = None
    project:            Optional[str] = None
    client:             Optional[str] = None
    operator:           Optional[str] = None
    sensor_location:    Optional[str] = None

    # Header — right column
    serial:                 Optional[str] = None
    firmware:               Optional[str] = None
    battery_volts:          Optional[float] = None
    calibration_date:       Optional[str] = None
    calibration_by:         Optional[str] = None
    file_name:              Optional[str] = None
    post_event_notes:       Optional[str] = None

    # Microphone block
    mic_pspl_dbl:           Optional[float] = None
    mic_pspl_psi:           Optional[float] = None
    mic_pspl_time_s:        Optional[float] = None
    mic_zc_freq_hz:         Optional[float] = None
    mic_channel_test_result: Optional[str] = None
    mic_channel_test_freq_hz: Optional[float] = None
    mic_channel_test_amp_mv: Optional[float] = None

    # Per-channel stats — list of dicts (one per channel)
    # Keys: name, ppv_ips, zc_freq_hz, time_of_peak_s,
    #       peak_accel_g, peak_disp_in, sensor_check
    channel_stats:          list[dict] = field(default_factory=list)

    # Peak Vector Sum
    peak_vector_sum_ips:    Optional[float] = None
    peak_vector_sum_time_s: Optional[float] = None

    # Waveform samples — channels[ch] = list of floats in physical units
    # Time axis derived from sample_rate + pretrig_samples
    channels:               dict = field(default_factory=dict)
    sample_rate_sps:        Optional[int] = None
    pretrig_samples:        Optional[int] = None
    t0_ms:                  Optional[float] = None
    dt_ms:                  Optional[float] = None

    # Record-type discriminator
    record_type:            Optional[str] = None
    is_histogram:           bool = False

    # Bookkeeping
    event_id:               Optional[str] = None
    server_received_at:     Optional[str] = None
    bw_pc_sw_version:       Optional[str] = None


def gather_report_data(
    db,
    store,
    event_id: str,
) -> Optional[ReportData]:
    """Collect every field needed to render an event report.

    Returns ``None`` if the event is unknown or has no waveform data
    on disk (no .h5, no .a5.pkl — same condition the waveform.json
    endpoint 404s on).
    """
    row = db.get_event(event_id)
    if row is None:
        return None
    serial   = row.get("serial")
    filename = row.get("blastware_filename")
    if not serial or not filename:
        return None

    rd = ReportData(
        event_id=event_id,
        serial=serial,
        file_name=filename,
        record_type=row.get("record_type"),
        is_histogram=str(row.get("record_type", "")).lower().startswith("hist"),
        event_datetime_str=row.get("timestamp"),
        sample_rate_sps=row.get("sample_rate"),
        project=row.get("project"),
        client=row.get("client"),
        operator=row.get("operator"),
        sensor_location=row.get("sensor_location"),
        server_received_at=row.get("created_at"),
    )

    # ── Sidecar bw_report — the rich BW-derived fields ──
    sidecar_path = store.sidecar_path_for(serial, filename)
    if sidecar_path.exists():
        try:
            sc = json.loads(sidecar_path.read_text())
        except Exception as exc:
            log.warning("gather_report_data: sidecar read failed: %s", exc)
            sc = {}
        bw = sc.get("bw_report") or {}

        # Trigger / range / sample-rate display
        trig = bw.get("trigger") or {}
        rd.trigger_source = (
            f"{trig.get('channel','')}: {trig.get('geo_level_ips')} in/s"
            if trig.get("channel") or trig.get("geo_level_ips") is not None
            else None
        )
        rec = bw.get("recording") or {}
        rd.geo_range_str = (
            f"Geo: {rec.get('geo_range_ips')} in/s"
            if rec.get("geo_range_ips") is not None else None
        )
        rt = rec.get("record_time_s")
        if rt is not None and rd.sample_rate_sps:
            rd.sample_rate_str = f"{rt:.1f} sec At {rd.sample_rate_sps} Sps"

        # Device block
        dev = bw.get("device") or {}
        rd.battery_volts    = dev.get("battery_volts")
        rd.calibration_date = dev.get("calibration_date")
        rd.calibration_by   = dev.get("calibration_by")
        rd.firmware         = bw.get("version")
        rd.bw_pc_sw_version = bw.get("pc_sw_version")

        # Microphone block
        mic = bw.get("mic") or {}
        rd.mic_pspl_dbl    = mic.get("pspl_dbl")
        if rd.mic_pspl_dbl is not None and rd.mic_pspl_dbl > 0:
            # Inverse of the dBL formula → psi.  Mirrors waveform_codec convention.
            rd.mic_pspl_psi = DBL_REF_PSI * (10 ** (rd.mic_pspl_dbl / 20))
        rd.mic_pspl_time_s = mic.get("time_of_peak_s")
        rd.mic_zc_freq_hz  = mic.get("zc_freq_hz")
        sc_mic = (bw.get("sensor_check") or {}).get("mic") or {}
        rd.mic_channel_test_result   = sc_mic.get("result")
        rd.mic_channel_test_freq_hz  = sc_mic.get("freq_hz")
        rd.mic_channel_test_amp_mv   = sc_mic.get("amplitude_mv")

        # Per-channel stats (Tran / Vert / Long)
        peaks = bw.get("peaks") or {}
        sc_block = bw.get("sensor_check") or {}
        for ch_lc, ch_label in (("tran", "Tran"), ("vert", "Vert"), ("long", "Long")):
            ch = peaks.get(ch_lc) or {}
            sc_ch = sc_block.get(ch_lc) or {}
            rd.channel_stats.append({
                "name":          ch_label,
                "ppv_ips":       ch.get("ppv_ips"),
                "zc_freq_hz":    ch.get("zc_freq_hz"),
                "time_of_peak_s": ch.get("time_of_peak_s"),
                "peak_accel_g":  ch.get("peak_accel_g"),
                "peak_disp_in":  ch.get("peak_disp_in"),
                "sensor_check":  sc_ch.get("result"),
            })

        # Peak Vector Sum
        vs = peaks.get("vector_sum") or {}
        rd.peak_vector_sum_ips    = vs.get("ips")
        rd.peak_vector_sum_time_s = vs.get("time_s")

    # ── Waveform samples — from the .h5 via the existing helper ──
    from sfm import event_hdf5
    h5_path = store.hdf5_path_for(serial, filename)
    if h5_path.exists():
        try:
            wf = event_hdf5.plot_json_from_hdf5(h5_path, event_id=event_id)
            rd.channels = {
                ch: (chd.get("values") or [])
                for ch, chd in (wf.get("channels") or {}).items()
            }
            ta = wf.get("time_axis") or {}
            rd.sample_rate_sps  = rd.sample_rate_sps or ta.get("sample_rate")
            rd.pretrig_samples  = ta.get("pretrig_samples")
            rd.t0_ms            = ta.get("t0_ms")
            rd.dt_ms            = ta.get("dt_ms")
        except Exception as exc:
            log.warning("gather_report_data: hdf5 read failed: %s", exc)

    return rd


# ── PDF rendering ────────────────────────────────────────────────────────────


def render_event_report_pdf(rd: ReportData) -> bytes:
    """Render an event report dict to a single-page letter PDF.

    Returns the raw PDF bytes — caller streams them back via FastAPI.

    NOTE: this is a v0.20.0 stub layout.  The visual hierarchy will be
    refined once reference PDFs land at docs/reference/instantel/.  All
    fields the printout includes are surfaced; spacing and typography
    are approximate.
    """
    # Letter portrait — 8.5"×11"
    fig = plt.figure(figsize=(8.5, 11), dpi=100)
    fig.patch.set_facecolor("white")

    # Grid: header rows on top, stats in the middle, waveform plot at bottom
    # height_ratios sum doesn't matter, only the relative proportions
    gs = fig.add_gridspec(
        nrows=4, ncols=1,
        left=0.07, right=0.96, top=0.96, bottom=0.04,
        height_ratios=[2.2, 1.0, 1.4, 5.0],
        hspace=0.35,
    )

    # ── Header area (top) ──
    ax_header = fig.add_subplot(gs[0])
    ax_header.axis("off")
    _draw_header(ax_header, rd)

    # ── Mic block (left) + USBM chart placeholder (right) ──
    ax_mic = fig.add_subplot(gs[1])
    ax_mic.axis("off")
    _draw_mic_block(ax_mic, rd)

    # ── Per-channel stats table + Peak Vector Sum ──
    ax_stats = fig.add_subplot(gs[2])
    ax_stats.axis("off")
    _draw_channel_stats(ax_stats, rd)

    # ── Waveform / histogram plot ──
    if rd.is_histogram:
        _draw_histogram_subplot(fig, gs[3], rd)
    else:
        _draw_waveform_subplot(fig, gs[3], rd)

    # Footer
    fig.text(
        0.07, 0.015,
        f"Generated by seismo-relay  •  event_id={rd.event_id or '—'}",
        fontsize=7, color="#888", ha="left",
    )

    buf = io.BytesIO()
    fig.savefig(buf, format="pdf")
    plt.close(fig)
    return buf.getvalue()


def _kv(ax, x, y, label, value, *, label_w=0.18):
    """Render a 'Label  Value' row at axes-coordinates (x, y)."""
    ax.text(x, y, label, fontsize=8, color="#555", ha="left", va="top",
            transform=ax.transAxes)
    ax.text(x + label_w, y, _fmt(value), fontsize=8, ha="left", va="top",
            transform=ax.transAxes, family="monospace")


def _fmt(v):
    """Format any field for display — '—' for None, str otherwise."""
    if v is None:
        return "—"
    if isinstance(v, float):
        return f"{v:.4f}".rstrip("0").rstrip(".")
    return str(v)


def _draw_header(ax, rd: ReportData) -> None:
    """Two-column metadata header — matches BW printout layout."""
    # Left column
    rows_left = [
        ("Date/Time",      rd.event_datetime_str),
        ("Trigger Source", rd.trigger_source),
        ("Range",          rd.geo_range_str),
        ("Sample Rate",    rd.sample_rate_str),
        ("Notes",          rd.notes),
        ("Project:",       rd.project),
        ("Client:",        rd.client),
        ("User Name:",     rd.operator),
        ("Seis. Loc:",     rd.sensor_location),
    ]
    rows_right = [
        ("Serial Number",   f"{rd.serial or '—'}"
                            + (f"  {rd.firmware}" if rd.firmware else "")),
        ("Battery Level",  f"{rd.battery_volts:.1f} Volts" if rd.battery_volts is not None else None),
        ("Unit Calibration", (f"{rd.calibration_date}"
                              + (f" by {rd.calibration_by}" if rd.calibration_by else ""))
                              if rd.calibration_date else None),
        ("File Name",      rd.file_name),
        ("Post Event Notes", rd.post_event_notes),
    ]
    y = 0.95
    dy = 0.10
    for label, value in rows_left:
        _kv(ax, 0.0, y, label, value, label_w=0.18)
        y -= dy
    y = 0.95
    for label, value in rows_right:
        _kv(ax, 0.55, y, label, value, label_w=0.20)
        y -= dy


def _draw_mic_block(ax, rd: ReportData) -> None:
    """Microphone block — PSPL, ZC Freq, Channel Test.  USBM chart
    placeholder on the right (filled in a separate work item)."""
    ax.text(0.0, 0.95, "Microphone   Linear Weighting", fontsize=8, color="#555",
            transform=ax.transAxes, va="top")
    rows = []
    if rd.mic_pspl_dbl is not None:
        line = f"{rd.mic_pspl_dbl:.1f} dB(L)"
        if rd.mic_pspl_time_s is not None:
            line += f" at {rd.mic_pspl_time_s:.3f} sec."
        rows.append(("PSPL", line))
    if rd.mic_zc_freq_hz is not None:
        rows.append(("ZC Freq", f"{rd.mic_zc_freq_hz:.0f} Hz"))
    if rd.mic_channel_test_result:
        line = rd.mic_channel_test_result
        if rd.mic_channel_test_freq_hz is not None and rd.mic_channel_test_amp_mv is not None:
            line += (f" (Freq = {rd.mic_channel_test_freq_hz:.1f} Hz, "
                     f"Amp = {rd.mic_channel_test_amp_mv:.0f} mv)")
        rows.append(("Channel Test", line))

    y = 0.70
    for label, value in rows:
        _kv(ax, 0.0, y, label, value, label_w=0.18)
        y -= 0.22

    # USBM chart placeholder — upper-right of this row
    ax.text(0.75, 0.95, "USBM RI8507 / OSMRE",
            fontsize=8, color="#555", ha="center", va="top",
            transform=ax.transAxes)
    ax.text(0.75, 0.45, "[compliance chart\nrenders here]",
            fontsize=8, color="#bbb", ha="center", va="center",
            transform=ax.transAxes, style="italic")


def _draw_channel_stats(ax, rd: ReportData) -> None:
    """Per-channel stats table + Peak Vector Sum row."""
    # Build a 2-D array of strings: header row + 3 channel rows
    headers = ["", "Tran", "Vert", "Long", ""]
    rows = [
        ["PPV",                "ppv_ips",        "in/s"],
        ["ZC Freq",            "zc_freq_hz",     "Hz"],
        ["Time (Rel. to Trig)", "time_of_peak_s", "sec"],
        ["Peak Acceleration",   "peak_accel_g",   "g"],
        ["Peak Displacement",   "peak_disp_in",   "in"],
        ["Sensor Check",        "sensor_check",   ""],
    ]
    ch_lookup = {c["name"]: c for c in rd.channel_stats}

    def _cell(field, ch_name):
        val = ch_lookup.get(ch_name, {}).get(field)
        if val is None:
            return "—"
        if field == "sensor_check":
            return str(val)
        if isinstance(val, float):
            return f"{val:.3f}"
        return str(val)

    table_data = [headers]
    for label, field_name, unit in rows:
        table_data.append([
            label,
            _cell(field_name, "Tran"),
            _cell(field_name, "Vert"),
            _cell(field_name, "Long"),
            unit,
        ])

    tbl = ax.table(
        cellText=table_data, loc="upper left",
        colWidths=[0.30, 0.13, 0.13, 0.13, 0.10],
        cellLoc="left", edges="open",
    )
    tbl.auto_set_font_size(False)
    tbl.set_fontsize(8)
    tbl.scale(1, 1.4)
    # Header row styling
    for j in range(5):
        cell = tbl[(0, j)]
        cell.set_text_props(weight="bold", color="#555")

    # Peak Vector Sum
    if rd.peak_vector_sum_ips is not None:
        line = f"Peak Vector Sum   {rd.peak_vector_sum_ips:.3f} in/s"
        if rd.peak_vector_sum_time_s is not None:
            line += f" At {rd.peak_vector_sum_time_s:.3f} sec."
        ax.text(0.0, -0.05, line, fontsize=9, weight="bold",
                ha="left", va="top", transform=ax.transAxes)


def _channel_axis_color(ch: str) -> str:
    return {"MicL": "#cc00cc", "Long": "#0066ff", "Vert": "#009933", "Tran": "#cc0000"}.get(ch, "#444")


def _draw_waveform_subplot(fig, gridspec_cell, rd: ReportData) -> None:
    """4-channel stacked waveform plot — Instantel printout order
    (MicL on top, Tran on bottom), shared x-axis."""
    inner = gridspec_cell.subgridspec(4, 1, hspace=0.0)
    order = ["MicL", "Long", "Vert", "Tran"]
    sr = rd.sample_rate_sps or 1024
    dt_ms = rd.dt_ms or (1000.0 / sr)
    t0_ms = rd.t0_ms if rd.t0_ms is not None else 0.0

    last_idx = len(order) - 1
    for i, ch in enumerate(order):
        ax = fig.add_subplot(inner[i])
        values = rd.channels.get(ch) or []
        times = [t0_ms + j * dt_ms for j in range(len(values))]

        if values:
            color = _channel_axis_color(ch)
            ax.plot(times, values, color=color, linewidth=0.6)
            # Symmetric y-axis for geo; zero-anchored for mic
            if ch != "MicL":
                amax = max((abs(v) for v in values), default=0.001)
                ax.set_ylim(-amax * 1.1, amax * 1.1)
        # Channel label on left
        ax.set_ylabel(ch, fontsize=8, rotation=0, ha="right", va="center",
                      color=_channel_axis_color(ch), weight="bold", labelpad=14)
        ax.grid(True, linestyle=":", linewidth=0.4, alpha=0.5)
        # Dashed trigger line at t=0
        ax.axvline(0.0, color="#cc0000", linestyle="--", linewidth=0.8, alpha=0.7)
        # Zero baseline
        ax.axhline(0.0, color="#888", linestyle="-", linewidth=0.4, alpha=0.5)

        if i != last_idx:
            ax.set_xticklabels([])
        else:
            ax.set_xlabel("Time (ms)", fontsize=8)
        ax.tick_params(axis="both", labelsize=7)


def _draw_histogram_subplot(fig, gridspec_cell, rd: ReportData) -> None:
    """4-channel stacked histogram bar chart — per-interval peaks."""
    inner = gridspec_cell.subgridspec(4, 1, hspace=0.0)
    order = ["MicL", "Long", "Vert", "Tran"]
    last_idx = len(order) - 1
    for i, ch in enumerate(order):
        ax = fig.add_subplot(inner[i])
        values = rd.channels.get(ch) or []
        if values:
            xs = np.arange(1, len(values) + 1)
            color = _channel_axis_color(ch)
            ax.bar(xs, values, color=color, width=1.0, linewidth=0)
        ax.set_ylabel(ch, fontsize=8, rotation=0, ha="right", va="center",
                      color=_channel_axis_color(ch), weight="bold", labelpad=14)
        ax.grid(True, axis="y", linestyle=":", linewidth=0.4, alpha=0.5)
        if i != last_idx:
            ax.set_xticklabels([])
        else:
            ax.set_xlabel("Interval", fontsize=8)
        ax.tick_params(axis="both", labelsize=7)