quantized-lab 0.8.0__py3-none-any.whl

quantized/io/origin_project/opju_figure_text.py

@@ -0,0 +1,245 @@
+"""``.opju`` (CPYUA) graph text-object recovery — axis titles / legend / annotations.
+
+Solved 2026-07-05 (previously a documented limitation: ``figures_opju`` dumped
+every recovered string into one flat ``annotations`` list). CPYUA graph pages
+carry the SAME named child objects the ``.opj`` container has (``YL``/``XB``/
+``YR``/``XT`` axis titles, ``Legend``, ``Text``/``TextN`` floating
+annotations, ``__FRAMESRCDATAINFOS`` internals …), just in a different
+framing. Two byte-level structures, validated across every graph page of the
+5-file real ``.opju`` corpus (323 name→text pairs, 0 orphan texts, and — the
+strongest check — every shared graph's routed titles equal to the
+``hc2convert.opj`` Save-As conversion's independently decoded titles):
+
+**Object-name header** — a tagged field whose payload opens ``0x10``,
+immediately followed by the name field::
+
+    <tag 80-9f> 04 10 00 00 <xx> <ntag> <nlen> <name>     (axis-title shape)
+    <tag 80-9f> 01 10 <ntag> <nlen> <name>                (Legend/Text shape)
+
+``tag`` varies (``8a``/``84``/``92`` observed), ``<xx>`` varies (``02``/
+``04``/``82``/``84`` — uninterpreted), ``ntag`` is ``0x80`` or ``0x83``, and
+``name`` is plain ASCII (min 2 chars — a 1-char floor admitted junk
+single-letter "names" in trailing storage sections).
+
+**Text content** — a 1-byte ``0x80`` field then a length-prefixed string::
+
+    <tag> 01 80 <tlen> <text … 00>
+
+``tag`` is ``0x86`` or ``0xa8`` (both observed; a corpus scan accepting ANY
+tag byte found zero additional matches that survive validation, so the
+``0x80-0xbf`` tag range accepted here is not load-bearing — the validation
+is: ``tlen`` exact, NUL terminator present, strict UTF-8, no control bytes
+beyond CR/LF/TAB). Text is UTF-8 (e.g. Hc2's ``H\\-(c2⊥) (T)`` title and
+``∥``/``⊥`` legend labels are raw multi-byte characters here, where the
+ANSI ``.opj`` container stores ``\\(x22A5)`` escapes instead).
+
+**Pairing** — objects are sequential: name header, a short style/format
+field run (name→text distance 49-66 bytes across the whole corpus; bounded
+at ``_MAX_NAME_TO_TEXT`` = 512 to allow longer style runs while still
+failing closed), then the object's single text. Each text run therefore
+pairs with the nearest preceding *unconsumed* header; a text with no such
+header defaults to ``annotations`` (the same degrade ``.opj``'s
+``_build_layer`` uses for text before its first resolvable header) — so a
+regex-missed header can only ever yield a missing/annotation-demoted title,
+never a WRONG one. Routing reuses ``figures.py``'s ``_object_bucket`` table
+verbatim, and the title/legend/annotation cleanup runs through the exact
+same pipeline (``_first_title``/``_parse_legend_labels``/
+``_clean_annotations`` + ``clean_richtext``) so both containers' outputs
+match character-for-character.
+
+Undecoded/known negatives: an object holding MORE than one framed text run
+would send its second run to ``annotations`` (never observed in the
+corpus); a text longer than 255 bytes presumably uses a wider length
+encoding never observed — such a run fails the NUL check and is dropped,
+not truncated.
+
+Pure library: bytes in → strings out. No fastapi/pydantic/routes imports.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, NamedTuple
+
+from quantized.io.origin_project.annotation_marks import (
+    _AUTO_TITLE,
+    _clean_annotations,
+    build_mark,
+    frac_to_data,
+    opju_text_fractions,
+)
+from quantized.io.origin_project.figure_text import (
+    _first_title,
+    _object_bucket,
+    _parse_legend_labels,
+)
+from quantized.io.origin_project.origin_richtext import clean_richtext
+
+__all__ = ["FigureText", "routed_figure_text"]
+
+# Object-name header: <tag> <plen 01|04> <payload[0]=0x10 ...> (module docstring).
+_HDR_RE = re.compile(rb"[\x80-\x9f]([\x01\x04])\x10", re.DOTALL)
+_NAME_TAGS = (0x80, 0x83)
+_NAME_RE = re.compile(rb"[A-Za-z_][A-Za-z0-9_]{1,23}\Z")  # >= 2 chars (docstring)
+
+# Text content field: <tag> 01 80 <tlen> <text ... 00> (module docstring).
+_TEXT_RE = re.compile(rb"[\x80-\xbf]\x01\x80", re.DOTALL)
+
+# Upper bound on the style/format run between an object's name header and its
+# own text (measured max 66 bytes corpus-wide; generous margin, still local).
+_MAX_NAME_TO_TEXT = 512
+
+
+class FigureText(NamedTuple):
+    """One graph layer's routed text, shaped exactly like the ``.opj`` fields."""
+
+    x_title: str
+    y_title: str
+    y2_title: str
+    legend_labels: list[str]
+    annotations: list[str]
+    # Positioned floating text ({"text", "x", "y"} in data coords, one per
+    # Text object, multi-line preserved) — see annotation_marks.py. Empty
+    # when the caller supplied no axis range or no position field decoded.
+    annotation_marks: list[dict[str, Any]]
+    # The Legend object's box top-left in data coords ({"x", "y"}) — the
+    # SAME position field every text object carries (§13.2 #3, 2026-07-06),
+    # read from the Legend name header. None when no legend, no axes, or
+    # the position field didn't decode (omitted, never guessed).
+    legend_pos: dict[str, float] | None
+
+
+def _object_headers(b: bytes, start: int, end: int) -> list[tuple[int, str]]:
+    """Every object-name header in ``b[start:end)`` as ``(position, name)``."""
+    out: list[tuple[int, str]] = []
+    for m in _HDR_RE.finditer(b, start, end):
+        plen = m.group(1)[0]
+        if plen == 4 and b[m.start() + 3 : m.start() + 5] != b"\x00\x00":
+            continue  # axis-title shape's payload is always 10 00 00 <xx>
+        p = m.start() + 2 + plen  # the name field, right after the payload
+        if p + 2 > end or b[p] not in _NAME_TAGS:
+            continue
+        nlen = b[p + 1]
+        name = b[p + 2 : p + 2 + nlen]
+        if len(name) != nlen or not _NAME_RE.match(name):
+            continue
+        out.append((m.start(), name.decode("ascii")))
+    return out
+
+
+def _text_runs(b: bytes, start: int, end: int) -> list[tuple[int, str]]:
+    """Every framed text run in ``b[start:end)`` as ``(position, text)``.
+
+    Validation is what carries the safety here (see module docstring): the
+    length byte must fit, the run must be NUL-terminated, decode as strict
+    UTF-8, and contain no control characters beyond CR/LF/TAB — anything
+    else is dropped, never repaired.
+    """
+    out: list[tuple[int, str]] = []
+    for m in _TEXT_RE.finditer(b, start, end):
+        p = m.end()
+        if p >= end:
+            continue
+        tlen = b[p]
+        raw = b[p + 1 : p + 1 + tlen]
+        if len(raw) != tlen or tlen < 2 or raw[-1] != 0:
+            continue
+        try:
+            body = raw[:-1].decode("utf-8")
+        except UnicodeDecodeError:
+            continue
+        if any(ord(c) < 0x20 and c not in "\r\n\t" for c in body):
+            continue
+        out.append((m.start(), body))
+    return out
+
+
+def routed_figure_text(
+    b: bytes,
+    start: int,
+    end: int,
+    axes: tuple[float, float, float, float] | None = None,
+    x_log: bool = False,
+    y_log: bool = False,
+) -> FigureText | None:
+    """Route one figure window's text objects into the ``.opj``-shaped buckets.
+
+    Returns ``None`` when the window holds no framed text run at all (legacy/
+    synthetic streams without CPYUA text objects) so the caller can degrade
+    to its historical flat-scrape ``annotations``. Otherwise: each text run
+    pairs with the nearest preceding unconsumed name header within
+    ``_MAX_NAME_TO_TEXT`` bytes and routes via ``figures._object_bucket``
+    (``YL``→``y_title``, ``XB``→``x_title``, ``YR``→``y2_title``,
+    ``Legend``→legend, ``Text*``/``Line*``→annotations, anything else →
+    dropped); an unpaired text defaults to ``annotations``. Multi-line runs
+    (CPYUA stores a whole legend/textbox as ONE ``\\r\\n``-joined string,
+    where ``.opj``'s byte scan naturally splits at the control bytes) are
+    split into lines first, so both containers feed identical strings into
+    the shared cleanup pipeline.
+
+    ``axes`` is the layer's ``(x_from, x_to, y_from, y_to)``; when given,
+    every annotation-bucket text whose own name header carries the
+    fixed-distance position field (``annotation_marks.opju_text_fractions``)
+    also emits a positioned ``annotation_marks`` entry — the whole
+    multi-line object as ONE mark. Objects without the field (or an
+    unpaired text, which has no header to read from) stay text-only.
+    """
+    texts = _text_runs(b, start, end)
+    if not texts:
+        return None
+    headers = _object_headers(b, start, end)
+    buckets: dict[str, list[str]] = {
+        "x_title": [],
+        "y_title": [],
+        "y2_title": [],
+        "legend": [],
+        "annotations": [],
+    }
+    marks: list[dict[str, Any]] = []
+    legend_pos: dict[str, float] | None = None
+    events = sorted(
+        [(pos, 0, name) for pos, name in headers] + [(pos, 1, text) for pos, text in texts]
+    )
+    pending: tuple[int, str] | None = None
+    for pos, kind, value in events:
+        if kind == 0:  # a name header: becomes the pending object (one text each)
+            pending = (pos, value)
+            continue
+        header_pos: int | None = None
+        if pending is not None and pos - pending[0] <= _MAX_NAME_TO_TEXT:
+            bucket = _object_bucket(pending[1])
+            header_pos = pending[0]
+        else:
+            bucket = "annotations"  # unpaired text: same default bucket .opj uses
+        pending = None
+        if bucket not in buckets:
+            continue
+        lines = [line for line in re.split(r"\r\n|[\r\n]", value) if line.strip()]
+        buckets[bucket].extend(lines)
+        if bucket == "annotations" and header_pos is not None and axes is not None:
+            mark = build_mark(
+                opju_text_fractions(b, header_pos), lines, *axes, x_log, y_log
+            )
+            if mark is not None:
+                marks.append(mark)
+        if bucket == "legend" and header_pos is not None and axes is not None:
+            fracs = opju_text_fractions(b, header_pos)
+            if fracs is not None and legend_pos is None:
+                lx, ly = frac_to_data(fracs[0], fracs[1], *axes, x_log, y_log)
+                legend_pos = {"x": lx, "y": ly}
+
+    def _title(lines: list[str]) -> str:
+        # .opj's _texts_in drops the %(?X)/%(?Y) auto-templates via its letter
+        # filter; the framed extraction sees them verbatim, so filter here.
+        return _first_title([t for t in lines if not _AUTO_TITLE.match(t)])
+
+    notes = [t for t in buckets["annotations"] if not _AUTO_TITLE.match(t) and "\\l(" not in t]
+    return FigureText(
+        x_title=_title(buckets["x_title"]),
+        y_title=_title(buckets["y_title"]),
+        y2_title=_title(buckets["y2_title"]),
+        legend_labels=_parse_legend_labels(buckets["legend"]),
+        annotations=[clean_richtext(a) for a in _clean_annotations(notes)[:12]],
+        annotation_marks=marks,
+        legend_pos=legend_pos,
+    )

quantized/io/origin_project/opju_reports.py

@@ -0,0 +1,129 @@
+"""Origin auto-generated report-sheet columns for ``.opju`` (CPYUA) — plan
+item 4's report-sheet residue, the ``.opju`` sibling of ``opj.py``'s
+``decode_report_strings`` (``container.py``).
+
+Origin's FitLinear/NLFit X-Functions auto-generate report sheets ("FitNL1",
+"FitLinearCurve1", …) whose cells hold a variable-length
+``cell://<Section>.<Row>.<Field>`` reference string (e.g.
+``"cell://Parameters.Slope.Value"``, naming *which* fit statistic that cell
+represents) rather than a plain float64. ``.opj``'s version of this family
+overflows a fixed 8-byte value area (``container.decode_inline_text`` has to
+drop it); ``.opju`` stores the SAME conceptual content in its own record
+framing, sharing ``opju_codec``'s ``0a 05 <…> ff ff <…>`` marker but taking a
+completely different branch after it.
+
+**The grammar** (pinned against ``specimens/fitreport2.opju`` — a known
+linear fit, x=1..8, slope -1.5, intercept 9.5 — whose ``FitNL1`` report sheet
+has 28 columns, ``FitNLCurve1`` has 11): a normal numeric record is ``ff ff
+<varint> 00 <ZigZag-varint segments>`` (``opju_codec``'s grammar: the byte
+right after the row-count varint is ``0x00``, then the segment list decodes
+straight to float64s). A REPORT column instead has ``0x01`` at that exact
+position — the discriminator, checked at the same byte offset the numeric
+codec already tests. What follows is *not* ``opju_codec``'s FPC/repeat
+segment grammar at all: a single ZigZag-varint segment count, then, if
+negative (``-m``), ``m`` consecutive ``<len:u8><ASCII bytes>`` strings
+(``len=0`` is a valid, blank report cell — most report columns hold only a
+handful of populated rows out of the segment's ``m``). A positive segment
+count was observed on 2 of ``FitNL1``'s 28 columns (its first two, with no
+``cell://`` content at all) and its shape is not understood — those columns
+are honestly dropped, never guessed at.
+
+**Validation:** every one of ``FitNL1``'s 26 populated columns decodes
+cleanly (the reference strings match exactly what
+``tools/origin_trial/generate_specimens3.py``'s ``fitreport2`` generator
+produced — ``Notes.*`` metadata, ``Input.R1/R2.C1..C4``,
+``Parameters.A/B/xintercept.{Value,Error,tValue,Prob,Dependency}``,
+``RegStats.C1.*``, ``Summary.R1.*``, ``ANOVAs.*``); the 2 non-text columns
+are honestly dropped. **What this does NOT recover:** the fit's actual
+computed numbers (e.g. Slope = -1.5) are not present as a plain float64
+anywhere near these records (checked directly: neither raw nor FPC-compact
+encodings of 9.5/-1.5 appear in the report-sheet byte range) — Origin
+appears to cache them in a separate internal structure this module does not
+decode. See ``docs/origin_project_format.md`` "Non-double column values" for
+the full writeup and the byte-level trail.
+"""
+
+from __future__ import annotations
+
+from quantized.io.origin_project.opju_codec import (
+    _NAME,
+    CodecError,
+    _read_varint,
+    _records,
+    _zigzag,
+)
+
+__all__ = ["scan_report_columns"]
+
+_PRINTABLE = frozenset(range(0x20, 0x7F))
+_MAX_ROWS = 500  # generous ceiling for a report sheet's row count (real corpus: <= 11)
+_MAX_STRLEN = 200  # generous ceiling for one reference string (real corpus: <= 34 chars)
+
+
+def _decode_report_record(b: bytes, marker: int) -> list[str] | None:
+    """Decode one report-column record at a ``ff ff`` marker (``marker`` is
+    the byte offset of the first ``0xff``), or ``None`` if it isn't this
+    shape or fails validation.
+
+    Shares the row-count varint read with ``opju_codec._decode_record`` but
+    diverges the instant the following byte is ``0x01`` instead of ``0x00``
+    — the two codecs are mutually exclusive by construction (gated on the
+    same byte), so this never intercepts a record ``opju_codec.scan_columns``
+    would otherwise decode.
+    """
+    try:
+        _row_count, p = _read_varint(b, marker + 2)
+    except CodecError:
+        return None
+    if p >= len(b) or b[p] != 0x01:  # 0x00 = a plain numeric record, not ours
+        return None
+    p += 1
+    try:
+        raw, p = _read_varint(b, p)
+    except CodecError:
+        return None
+    count = _zigzag(raw)
+    if count >= 0:
+        return None  # a positive/blank-fill segment -- shape not understood, honest drop
+    m = -count
+    if not 1 <= m <= _MAX_ROWS:
+        return None
+    rows: list[str] = []
+    for _ in range(m):
+        if p >= len(b):
+            return None
+        length = b[p]
+        p += 1
+        if length > _MAX_STRLEN or p + length > len(b):
+            return None
+        raw_bytes = b[p : p + length]
+        p += length
+        if not all(c in _PRINTABLE for c in raw_bytes):
+            return None
+        rows.append(raw_bytes.decode("latin1"))
+    return rows
+
+
+def scan_report_columns(b: bytes) -> list[tuple[str, list[str]]]:
+    """Every ``<Book>_<Col>[@sheet]`` report-sheet column in a CPYUA file.
+
+    Reuses ``opju_codec``'s record-marker scan (``_records``) and the same
+    "nearest preceding length-prefixed dataset name" anchoring rule
+    ``scan_columns`` uses; the two functions never compete for the same
+    marker (see ``_decode_report_record``'s docstring), so this can run as an
+    entirely independent second pass with no cursor coordination needed.
+    """
+    names = [
+        (m.start(), m.group(0).decode("latin1"))
+        for m in _NAME.finditer(b)
+        if m.start() > 0 and b[m.start() - 1] == len(m.group(0))
+    ]
+    out: list[tuple[str, list[str]]] = []
+    for marker in _records(b):
+        rows = _decode_report_record(b, marker)
+        if rows is None:
+            continue
+        prev = [name for pos, name in names if pos < marker]
+        if prev:
+            out.append((prev[-1], rows))
+    return out

quantized/io/origin_project/origin_richtext.py

@@ -0,0 +1,145 @@
+"""Origin LabTalk rich-text (escape-code) → plain display text.
+
+Origin stores axis titles, legend labels, and text annotations with inline
+formatting escapes (LabTalk "text object" syntax). Extracting the raw bytes
+(``figures.py``) recovers the string *with* those escapes, e.g. an XRD x-axis
+title comes back as ``2\\g(q \\(40))degrees)`` — which, shown verbatim, reads
+as literal backslash noise rather than "2θ (degrees)". This module decodes the
+display-affecting escapes so a recreated plot's labels match Origin.
+
+Handled escapes:
+  ``\\g(...)``            Symbol-font run → Greek letters (q→θ, a→α, m→μ, …)
+  ``\\(NNN)``             insert the character with decimal code NNN
+  ``\\(xHHHH)``           insert the character with hex code HHHH — Origin's
+                         Unicode form (how a ``.opj``-container Save-As stores
+                         non-ANSI characters, e.g. ``\\(x2225)`` → ∥; observed
+                         live in hc2convert.opj's converted axis titles)
+  ``\\+(...)`` / ``\\-(...)``  super-/sub-script → Unicode super/subscripts
+  ``\\b(...)`` ``\\i(...)`` ``\\u(...)`` ``\\f:Font(...)`` ``\\c<n>(...)``
+                         bold/italic/underline/font/colour → keep inner text
+
+Left untouched: ``%(...)`` data-reference substitutions (e.g. a legend's
+auto-label ``%(2)`` means "dataset 2's name" — a reference, not display text)
+and any shape we don't recognise (we degrade to the raw string, never worse).
+
+Pure library: str in → str out. No project imports.
+"""
+
+from __future__ import annotations
+
+# Adobe/Origin "Symbol" font: Latin code point → the Greek glyph it displays.
+_SYMBOL_GREEK: dict[str, str] = {
+    "a": "α", "b": "β", "g": "γ", "d": "δ", "e": "ε", "z": "ζ", "h": "η",
+    "q": "θ", "i": "ι", "k": "κ", "l": "λ", "m": "μ", "n": "ν", "x": "ξ",
+    "o": "ο", "p": "π", "r": "ρ", "s": "σ", "t": "τ", "u": "υ", "f": "φ",
+    "c": "χ", "y": "ψ", "w": "ω", "v": "ς", "j": "ϕ",
+    "A": "Α", "B": "Β", "G": "Γ", "D": "Δ", "E": "Ε", "Z": "Ζ", "H": "Η",
+    "Q": "Θ", "I": "Ι", "K": "Κ", "L": "Λ", "M": "Μ", "N": "Ν", "X": "Ξ",
+    "O": "Ο", "P": "Π", "R": "Ρ", "S": "Σ", "T": "Τ", "U": "Υ", "F": "Φ",
+    "C": "Χ", "Y": "Ψ", "W": "Ω",
+}  # fmt: skip
+_GREEK_TABLE = {ord(k): v for k, v in _SYMBOL_GREEK.items()}
+_SUP = str.maketrans("0123456789+-=()n", "⁰¹²³⁴⁵⁶⁷⁸⁹⁺⁻⁼⁽⁾ⁿ")
+_SUB = str.maketrans("0123456789+-=()", "₀₁₂₃₄₅₆₇₈₉₊₋₌₍₎")
+
+
+def _codepoint(code: str) -> int | None:
+    """The character code of a ``\\(...)`` escape body: decimal (``40``) or
+    hex with an ``x`` prefix (``x2225`` — Origin's Unicode form, see the
+    module docstring). ``None`` when the body is neither shape, or falls
+    outside Unicode's assignable range (malformed → literal-paren fallback).
+    """
+    if code.isdigit():
+        value = int(code)
+    elif code[:1] in ("x", "X") and len(code) > 1:
+        try:
+            value = int(code[1:], 16)
+        except ValueError:
+            return None
+    else:
+        return None
+    return value if 0 <= value <= 0x10FFFF and not 0xD800 <= value <= 0xDFFF else None
+
+
+def _apply_run(control: str, inner: str) -> str:
+    """Render a ``\\<control>(inner)`` run's already-decoded inner text."""
+    if control == "g":
+        return inner.translate(_GREEK_TABLE)
+    if control == "+":
+        return inner.translate(_SUP)
+    if control == "-":
+        return inner.translate(_SUB)
+    # b / i / u / f:Font / c<n> / anything else: drop the styling, keep text.
+    return inner
+
+
+def _render(s: str) -> str:
+    out: list[str] = []
+    i, n = 0, len(s)
+    while i < n:
+        c = s[i]
+        if c != "\\":
+            out.append(c)
+            i += 1
+            continue
+        # \(NNN) / \(xHHHH) — a character-code escape (atomic: its own parens).
+        if i + 1 < n and s[i + 1] == "(":
+            close = s.find(")", i + 2)
+            code = s[i + 2 : close] if close != -1 else ""
+            cp = _codepoint(code) if close != -1 else None
+            if cp is not None:
+                out.append(chr(cp))
+                i = close + 1
+            else:
+                out.append("(")  # malformed — treat as a literal paren
+                i += 2
+            continue
+        # \<control>(...) — a formatting run; control is the text up to '('.
+        k = s.find("(", i + 1)
+        if k == -1:  # dangling backslash-escape (e.g. a lone "\n"): drop the "\"
+            out.append(s[i + 1] if i + 1 < n else "")
+            i += 2
+            continue
+        control = s[i + 1 : k]
+        j, depth = k + 1, 1  # find the matching ')' of the run's opening '('
+        while j < n and depth:
+            if s[j] == "\\" and j + 1 < n:
+                if s[j + 1] == "(":  # nested \(NNN) — skip the whole atom
+                    inner_close = s.find(")", j + 2)
+                    j = inner_close + 1 if inner_close != -1 else j + 2
+                    continue
+                j += 2  # other escaped char
+                continue
+            if s[j] == "(":
+                depth += 1
+            elif s[j] == ")":
+                depth -= 1
+                if depth == 0:
+                    break
+            j += 1
+        if depth != 0:
+            # Unterminated run — malformed; bail so clean_richtext() returns the
+            # raw string unchanged rather than Symbol-mapping the rest of the line.
+            raise ValueError("unterminated Origin rich-text run")
+        out.append(_apply_run(control, _render(s[k + 1 : j])))
+        i = j + 1
+    return "".join(out)
+
+
+def clean_richtext(s: str) -> str:
+    """Decode Origin rich-text escapes in ``s`` to plain display text.
+
+    Idempotent-ish and total: strings with no ``\\`` escapes return unchanged,
+    and any parse error degrades to the raw input (never makes it worse).
+
+    >>> clean_richtext("2\\\\g(q \\\\(40))degrees)")
+    '2θ (degrees)'
+    >>> clean_richtext("Intensity (arb. units)")
+    'Intensity (arb. units)'
+    """
+    if "\\" not in s:
+        return s
+    try:
+        return _render(s)
+    except Exception:
+        return s

quantized/io/origin_project/preview.py

@@ -0,0 +1,132 @@
+"""Row-decimated preview ``DataStruct`` for the lazy per-book import transport
+(``ORIGIN_FILE_DECODE_PLAN`` #38).
+
+Mirrors the frontend's min/max-per-bucket envelope-preserving downsample
+(``frontend/src/lib/downsample.ts``, used for Library sparklines) but picks
+whole ROWS -- every channel moves together -- instead of decimating one
+channel's points independently. The result is a genuine (just smaller)
+``DataStruct``: any consumer that only reads ``.time``/``.values``/``.labels``/
+``.units``/``.metadata`` keeps working on it unchanged, which is the whole
+point of the "pending dataset carries a real but preview-sized `data`" design
+(see ``routes/parsers.py``'s ``_book_preview_payload``).
+
+Pure layer -- no fastapi/pydantic imports (enforced by test_repo_integrity).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from quantized.datastruct import DataStruct
+
+__all__ = ["decimate_datastruct"]
+
+
+def _trim_trailing_padding(ds: DataStruct) -> DataStruct:
+    """Drop trailing rows that carry no real data, mirroring the frontend's
+    ``dropTrailingEmptyRows`` (``frontend/src/lib/plotdata.ts``). Origin's
+    over-allocated worksheet storage leaves "allocated but unfilled" rows at
+    the END of a book (verified byte-for-byte across ~10 PNR-corpus books,
+    e.g. Book15: 19 of 180 rows), in two shapes:
+
+      - not plottable at all -- ``.time`` is non-finite, or (when there are
+        value channels) every value in the row is also non-finite, or
+      - over-allocated-storage padding -- ``.time`` AND every value in the
+        row read exactly finite ``0.0`` simultaneously. This is a "point", not
+        a gap, so the rule above doesn't catch it, and left in, it resets the
+        independent axis back to 0 at the tail (breaking x-ascending) and
+        collapses a sparkline/preview built from the raw row order.
+
+    Only trims a contiguous run off the END; interior gaps are left in place.
+    Returns ``ds`` unchanged (same object) when there is no prunable tail.
+    """
+    n = ds.n_points
+    if n == 0:
+        return ds
+    time = ds.time
+    values = ds.values
+    has_y = ds.n_channels > 0
+
+    def plottable(i: int) -> bool:
+        if not np.isfinite(time[i]):
+            return False
+        if not has_y:
+            return True
+        return bool(np.any(np.isfinite(values[i, :])))
+
+    def all_zero_row(i: int) -> bool:
+        if not has_y:
+            return False
+        if time[i] != 0:
+            return False
+        return bool(np.all(values[i, :] == 0))
+
+    end = n
+    while end > 0 and (not plottable(end - 1) or all_zero_row(end - 1)):
+        end -= 1
+    if end == n:
+        return ds
+    return DataStruct(
+        time=ds.time[:end],
+        values=ds.values[:end, :],
+        labels=ds.labels,
+        units=ds.units,
+        metadata=ds.metadata,
+    )
+
+
+def decimate_datastruct(ds: DataStruct, target_points: int = 200) -> DataStruct:
+    """Row-decimate ``ds`` to about ``target_points`` rows.
+
+    First prunes a trailing "allocated but unfilled" padding run (see
+    :func:`_trim_trailing_padding`) so a pending dataset's preview never
+    carries the padding into the thumbnail -- the fix for a preview whose
+    sparkline collapsed toward (0, 0) instead of tracing the real curve.
+
+    Then buckets the (pruned) row range into ``target_points // 2``
+    contiguous spans and keeps, from each span, the row holding the MINIMUM
+    and the row holding the MAXIMUM value of the densest channel (most finite
+    values) -- so a sparkline built from the result still shows real
+    spikes/dips a plain stride sample would step over. Every retained row
+    keeps ALL of its channels (they were picked together), so the output is a
+    normal, if smaller, ``DataStruct``.
+
+    Returns the (possibly padding-trimmed) ``ds`` unchanged when it already
+    has at most ``target_points`` rows or has no channels at all (an
+    empty-data pseudo-book -- nothing to pick extrema from, and nothing to
+    save by decimating zero columns).
+    """
+    ds = _trim_trailing_padding(ds)
+    n = ds.n_points
+    if n <= target_points or ds.n_channels == 0:
+        return ds
+
+    finite_counts = np.count_nonzero(np.isfinite(ds.values), axis=0)
+    densest = int(np.argmax(finite_counts))
+    y = ds.values[:, densest]
+
+    bucket_count = max(1, target_points // 2)
+    edges = np.linspace(0, n, bucket_count + 1)
+    keep: set[int] = set()
+    for b in range(bucket_count):
+        start, end = int(edges[b]), int(edges[b + 1])
+        if start >= end:
+            continue
+        seg = y[start:end]
+        finite = np.isfinite(seg)
+        if not finite.any():
+            keep.add(start)  # nothing finite in this span -> keep a placeholder row
+            continue
+        local = np.flatnonzero(finite)
+        seg_finite = seg[local]
+        keep.add(start + int(local[int(np.argmin(seg_finite))]))
+        keep.add(start + int(local[int(np.argmax(seg_finite))]))
+
+    idx = np.fromiter(sorted(keep), dtype=np.int64)
+    return DataStruct(
+        time=ds.time[idx],
+        values=ds.values[idx, :],
+        labels=ds.labels,
+        units=ds.units,
+        metadata=ds.metadata,
+    )