pi-exr-reader 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Richardson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# pi-exr-reader
+
+Pi extension that lets any pi session read `.exr` files — something pi's
+`read` tool can't do.
+
+The `exr_read` tool reports:
+
+- **Part metadata** — size, data window, storage, line order, compression,
+  for every part of a multilayer EXR
+- **Per-channel statistics** — min / max / mean / nonzero fraction, per
+  component (`UV_Box.R`, `st.G`, ...)
+- **Exact float pixel values** at a point, full precision
+- **Rect statistics** over an inclusive region
+- **PNG preview** — 8-bit linear-mapped (or viewer-look tone-mapped) image
+  attached to the tool result when the active model accepts image input
+
+Built for Arnold multi-AOV renders and UV/ST map inspection, but works on
+any EXR: scanline or tiled, any compression, multilayer or single-layer.
+
+## Install
+
+```
+pi install npm:pi-exr-reader
+```
+
+or from a local clone:
+
+```
+pi install /path/to/this/folder
+```
+
+## Requirements
+
+The extension shells out to a Python probe
+(`exr_reader/exr_probe.py`) using OpenEXR 3.x, numpy, and Pillow:
+
+```
+pip install OpenEXR numpy Pillow
+```
+
+The extension probes `python` / `python3` and fails with an install hint
+if the packages are missing.
+
+## Usage
+
+Ask your model to inspect an EXR, e.g. *"what are the UV values at pixel
+(540, 540) in render.exr"*. Coordinates are `(x, y)` with origin at the
+top-left of the data window, y increasing down — matching the preview
+PNG orientation.
+
+Channel names are case-insensitive; a group name selects all its
+components (`"uv_box"` → `UV_Box.R/.G/.B`).
+
+## Development
+
+Source lives in `exr_reader/` (`index.ts` + `exr_probe.py`). No build
+step — pi loads the TypeScript directly. The production global install on
+the author's machine is a copy at `~/.pi/agent/extensions/exr_reader/`;
+re-copy after changes (or `pi -e <this folder>` to test from source).

package/exr_reader/exr_probe.py

@@ -0,0 +1,457 @@
+#!/usr/bin/env python3
+"""exr_probe.py — EXR file reader for the pi `exr_read` tool.
+
+Reads an EXR file (any compression, scanline or tiled, multi-part,
+half/float/int channels) via the OpenEXR 3.x Python API and prints a
+single JSON object to stdout. Exit code 0 on success (including
+"ok": false results), non-zero on hard failure.
+
+Coordinate convention (matches the preview PNG orientation):
+  (x, y) = pixel coordinates with origin at the TOP-LEFT of the part's
+  data window, x increasing to the right, y increasing DOWN.
+  Array index is [y, x]. Preview PNG top row = array row 0 = y=0.
+
+Usage:
+  python exr_probe.py FILE.exr [--pixel X Y] [--rect X0 Y0 X1 Y1]
+                               [--channel NAME] [--preview-out PATH]
+                               [--max-preview N] [--tone-map MODE] [--no-preview]
+
+--tone-map MODE selects the preview mapping per component: "auto" (default),
+"linear", or "tonemap".
+  linear  = full [min,max] -> full range (any data; UV/ST maps, P/Z AOVs)
+  tonemap = viewer look: 1.0 = white, sRGB gamma, clip above (what Nuke/
+            Photoshop/AE show for an EXR)
+  auto    = linear when the data fits ~[0, 1.05] (maps/LDR), tonemap for
+            image-like HDR (min ~>= 0, max > 1.05), linear full-range for
+            data with a large negative span (P/Z-like). The per-component
+            mapping used is reported in the preview JSON.
+
+--channel NAME selects which channels get pixel values / rect stats /
+the preview. Matches a channel name case-insensitively (e.g. "R", "U",
+"st"); a GROUP name also selects all its components ("uv" matches
+"uv.R", "uv.G", "uv.B"), and an exact component name ("uv.r") still
+works. May be given multiple times. A filter that matches nothing is
+an error that lists the available channel names. Omitted: stats cover
+every channel; pixel queries report every channel; preview composes
+the first R,G,B channels (or the first up-to-3 channels if no R/G/B
+names exist).
+"""
+
+import argparse
+import json
+import math
+import os
+import re
+import sys
+import tempfile
+
+try:
+    import numpy as np
+    import OpenEXR
+except ImportError as _e:  # surfaced via fail() in main()
+    np = None  # type: ignore[assignment]
+    OpenEXR = None  # type: ignore[assignment]
+    _IMPORT_ERROR = _e
+else:
+    _IMPORT_ERROR = None
+
+
+def fail(msg, **extra):
+    out = {"ok": False, "error": msg}
+    out.update(extra)
+    print(json.dumps(sanitize(out)))
+    sys.exit(0)
+
+
+def sanitize(o):
+    """Replace non-finite floats with strings so the output is strict JSON."""
+    if isinstance(o, float):
+        if math.isnan(o):
+            return "NaN"
+        if math.isinf(o):
+            return "inf" if o > 0 else "-inf"
+        return o
+    if isinstance(o, dict):
+        return {k: sanitize(v) for k, v in o.items()}
+    if isinstance(o, (list, tuple)):
+        return [sanitize(v) for v in o]
+    return o
+
+
+def call_or_val(v):
+    """The OpenEXR 3.x Part API mixes methods (name/width/height/type/
+    compression) and dict properties (channels/header) — normalise both."""
+    return v() if callable(v) else v
+
+
+def preview_default_name(path, selected_args):
+    """Stable preview filename: <stem>[_<channel-tag>].png, always .png
+    (the probe only ever writes PNG). The channel tag keeps previews of
+    different channel selections of the same file from overwriting each
+    other (e.g. Box-on-alpha_uv_aovs_UV_Box_preview.png)."""
+    stem = os.path.splitext(os.path.basename(path))[0]
+    if selected_args:
+        tag = "_".join(
+            re.sub(r"[^a-z0-9]+", "_", s.lower()).strip("_") for s in selected_args
+        )
+        if tag:
+            stem += "_" + tag
+    return stem + "_preview.png"
+
+
+def comp_name(ch_name, arr, i):
+    """Component label: bare channel name for 2-D, 'name.0'/'name.1' for n-D."""
+    if arr.ndim == 3:
+        return f"{ch_name}.{i}"
+    return ch_name
+
+
+def _auto_mode(lo, hi):
+    """auto decision for one component:
+    - ~[0, 1.05] data -> linear min->max (maps/LDR: honest full-range view)
+    - image-like HDR (min ~>= 0, max > 1.05) -> tonemap (the viewer look)
+    - large negative span (P/Z-like) -> linear full-range (show everything)
+    """
+    if hi <= 1.05 and lo >= -0.01:
+        return "linear"
+    if lo >= -0.01:
+        return "tonemap"
+    return "linear"
+
+
+def _srgb_gamma(y):
+    y = np.clip(y, 0.0, 1.0)
+    return np.where(y <= 0.0031308, 12.92 * y, 1.055 * np.power(y, 1.0 / 2.4) - 0.055)
+
+
+def map_component(a, lo, hi, mode):
+    """Map one component (finite min lo, max hi) to [0, 65535] as float32.
+    linear:  full [lo, hi] -> [0, 65535] (any data range)
+    tonemap: viewer look — 1.0 = white, sRGB gamma, clip above 1 / below 0.
+             This is what EXR viewers (Nuke/Photoshop/AE) show, so a vision
+             model sees a display-referred image it was trained on."""
+    if mode == "linear":
+        a = a - lo
+        return a / (hi - lo) * 65535.0
+    return _srgb_gamma(a) * 65535.0
+
+
+def channel_matches(cname, selected):
+    """Case-insensitive match of a channel name against the --channel set.
+    An exact name match works ("uv", "uv.r"); a GROUP name also selects
+    all of a multi-component channel's components ("uv" matches
+    "uv.R", "uv.G", "uv.B"). The dot-anchored prefix prevents "uv" from
+    matching an unrelated channel named "uvbox"."""
+    cl = cname.lower()
+    if cl in selected:
+        return True
+    return any(cl.startswith(s + ".") for s in selected)
+
+
+def stats_of(a):
+    a = a.astype("float32")
+    finite = a[np.isfinite(a)]
+    if finite.size == 0:
+        mn = mx = None
+        mean = "NaN"
+    else:
+        mn, mx = float(finite.min()), float(finite.max())
+        mean = float(a.mean()) if a.size else "NaN"
+    nz = float(np.count_nonzero(a)) / a.size if a.size else 0.0
+    return {"min": mn, "max": mx, "mean": mean, "nonzero_frac": round(nz, 6)}
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("path")
+    ap.add_argument("--pixel", nargs=2, type=int, metavar=("X", "Y"))
+    ap.add_argument("--rect", nargs=4, type=int, metavar=("X0", "Y0", "X1", "Y1"))
+    ap.add_argument(
+        "--channel",
+        action="append",
+        default=None,
+        metavar="NAME",
+        help="channel name (case-insensitive); a group name like 'uv' also "
+        "selects its components ('uv.R','uv.G','uv.B'); may be repeated",
+    )
+    ap.add_argument("--preview-out", default=None)
+    ap.add_argument("--max-preview", type=int, default=1024)
+    ap.add_argument(
+        "--tone-map",
+        choices=["auto", "linear", "tonemap"],
+        default="auto",
+        help="preview mapping per component (default auto: linear for ~[0,1] data, "
+        "Reinhard+sRGB for HDR/negative data)",
+    )
+    ap.add_argument("--no-preview", action="store_true")
+    args = ap.parse_args()
+
+    path = os.path.abspath(args.path)
+    if not os.path.isfile(path):
+        fail(f"file not found: {path}")
+
+    if OpenEXR is None:
+        fail(f"missing python dependency: {_IMPORT_ERROR!r}. Install with: pip install OpenEXR")
+
+    try:
+        exr = OpenEXR.File(path, separate_channels=True)
+    except Exception as e:
+        fail(f"cannot open EXR: {e!r}")
+
+    selected = {c.lower() for c in args.channel} if args.channel else None
+
+    # ---------- parts + per-channel stats ----------
+    parts_out = []
+    all_channel_names = set()
+    for pi, part in enumerate(exr.parts):
+        chdict = call_or_val(part.channels)
+        all_channel_names.update(chdict.keys())
+        if not chdict:
+            fail(f"part {pi} has no channels", parts=parts_out)
+        dw = call_or_val(part.header).get("dataWindow")
+        dw_out = None
+        if dw is not None:
+            try:
+                lo, hi = dw
+                dw_out = [[int(lo[0]), int(lo[1])], [int(hi[0]), int(hi[1])]]
+            except Exception:
+                dw_out = str(dw)
+        channels_out = {}
+        for cname, ch in chdict.items():
+            arr = np.array(ch.pixels)
+            if selected is not None and not channel_matches(cname, selected):
+                continue
+            comps = {}
+            n = arr.shape[2] if arr.ndim == 3 else 1
+            for i in range(n):
+                a = arr[..., i] if arr.ndim == 3 else arr
+                comps[comp_name(cname, arr, i)] = {
+                    "shape": list(a.shape),
+                    **stats_of(a),
+                }
+            channels_out[cname] = comps
+        parts_out.append({
+            "index": pi,
+            "name": str(call_or_val(part.name)),
+            "width": int(call_or_val(part.width)),
+            "height": int(call_or_val(part.height)),
+            "dataWindow": dw_out,
+            "storage": str(call_or_val(part.type)),
+            "lineOrder": str(call_or_val(part.header).get("lineOrder")),
+            "compression": str(call_or_val(part.compression)),
+            "channels": channels_out,
+        })
+
+    result = {
+        "ok": True,
+        "path": path,
+        "bytes": os.path.getsize(path),
+        "numParts": len(parts_out),
+        "coordinateConvention": "origin top-left of data window, x right, y down; array index [y, x]",
+        "parts": parts_out,
+    }
+
+    # ---------- channel filter: honest no-match error ----------
+    # Runs BEFORE pixel/rect/preview: without it, a filter that matches
+    # nothing (a typo, or an old call that assumed exact-match semantics)
+    # produced empty results and, worse, a misleading "outside data
+    # window" error from the pixel path — verified on a real Arnold AOV
+    # file 2026-08-25.
+    if selected is not None:
+        if not any(channel_matches(c, selected) for c in all_channel_names):
+            avail = sorted(all_channel_names)
+            fail(
+                f"no channel matches {sorted(selected)!r} — available channel names: {avail!r} "
+                "(a group name like 'uv' selects its components 'uv.R'/'uv.G'/'uv.B'; "
+                "an exact component name also works)",
+                available=avail,
+            )
+
+    # ---------- pixel query ----------
+    if args.pixel:
+        x, y = args.pixel
+        pixel_out = {"x": x, "y": y, "parts": {}}
+        found = False
+        for p in parts_out:
+            if x < 0 or x >= p["width"] or y < 0 or y >= p["height"]:
+                continue
+            part = exr.parts[p["index"]]
+            chdict = call_or_val(part.channels)
+            vals = {}
+            for cname, ch in chdict.items():
+                if selected is not None and not channel_matches(cname, selected):
+                    continue
+                arr = np.array(ch.pixels)
+                if arr.ndim == 3:
+                    for i in range(arr.shape[2]):
+                        vals[comp_name(cname, arr, i)] = float(arr[y, x, i])
+                else:
+                    vals[cname] = float(arr[y, x])
+            if vals:
+                pixel_out["parts"][str(p["index"])] = vals
+                found = True
+        if not found:
+            dw = parts_out[0]["dataWindow"]
+            fail(
+                f"pixel ({x},{y}) outside data window(s) of all parts",
+                part0_dataWindow=dw,
+                part0_size=[parts_out[0]["width"], parts_out[0]["height"]],
+            )
+        result["pixel"] = pixel_out
+
+    # ---------- rect stats ----------
+    if args.rect:
+        x0, y0, x1, y1 = args.rect
+        if x0 > x1 or y0 > y1:
+            fail("invalid rect: x0>x1 or y0>y1")
+        p0 = parts_out[0]
+        part = exr.parts[0]
+        chdict = call_or_val(part.channels)
+        rect_out = {"x0": x0, "y0": y0, "x1": x1, "y1": y1, "size": [x1 - x0 + 1, y1 - y0 + 1], "channels": {}}
+        if x0 < 0 or y0 < 0 or x1 >= p0["width"] or y1 >= p0["height"]:
+            fail(
+                f"rect ({x0},{y0})-({x1},{y1}) outside part 0 data window "
+                f"(0,0)-({p0['width']-1},{p0['height']-1})"
+            )
+        for cname, ch in chdict.items():
+            if selected is not None and not channel_matches(cname, selected):
+                continue
+            arr = np.array(ch.pixels)[y0 : y1 + 1, x0 : x1 + 1]
+            n = arr.shape[2] if arr.ndim == 3 else 1
+            rect_out["channels"][cname] = {}
+            for i in range(n):
+                a = arr[..., i] if arr.ndim == 3 else arr
+                rect_out["channels"][cname][comp_name(cname, arr, i)] = stats_of(a)
+        result["rect"] = rect_out
+
+    # ---------- preview ----------
+    if not args.no_preview:
+        try:
+            from PIL import Image
+        except ImportError:
+            result["preview"] = {
+                "skipped": "PIL not installed (pip install Pillow); no preview produced"
+            }
+        else:
+            p0 = parts_out[0]
+            part = exr.parts[0]
+            chdict = call_or_val(part.channels)
+            if selected is not None:
+                names = [c for c in chdict if channel_matches(c, selected)]
+            else:
+                # Named R/G/B channels first; file order is NOT a safe
+                # default (this Arnold file lists A, B, G, R), otherwise
+                # fall back to the first up-to-3 channels.
+                rgb = [c for c in chdict if c.lower() in ("r", "g", "b")]
+                names = rgb if rgb else list(chdict.keys())[:3]
+            # R,G,B-aware slot ordering for whatever was picked: a channel
+            # whose name (or .suffix) is r/g/b goes to the matching color
+            # slot in R,G,B order regardless of file channel order — file
+            # order put B in the red slot for a group-selected UV AOV, the
+            # same swap as the 2026-08-25 preview bug. Non-RGB channels
+            # keep file order (stable). This is what makes a UV AOV preview
+            # read U->red, V->green.
+            _order = {c: i for i, c in enumerate(chdict.keys())}
+
+            def _slot_key(c):
+                lc = c.lower()
+                for i, s in enumerate(("r", "g", "b")):
+                    if lc == s or lc.endswith("." + s):
+                        return (0, i, 0)
+                return (1, 0, _order[c])
+
+            names.sort(key=_slot_key)
+            if not names:
+                result["preview"] = {"skipped": "no channels available for preview"}
+            else:
+                out_path = (
+                    os.path.abspath(args.preview_out)
+                    if args.preview_out
+                    else os.path.join(os.getcwd(), "images", "previews", preview_default_name(path, args.channel))
+                )
+                os.makedirs(os.path.dirname(out_path), exist_ok=True)
+                arrs = {c: np.array(chdict[c].pixels).astype("float32") for c in names}
+                w, h = arrs[names[0]].shape[1], arrs[names[0]].shape[0]
+                scales = {}
+                modes = {}
+
+                def _mode_for(lo, hi):
+                    return args.tone_map if args.tone_map != "auto" else _auto_mode(lo, hi)
+
+                if names[0] in arrs and arrs[names[0]].ndim == 3:
+                    # one multi-component channel: comp i -> channel i of RGB
+                    comp_arrays, labels = [], []
+                    for i in range(min(3, arrs[names[0]].shape[2])):
+                        a = arrs[names[0]][..., i]
+                        f = a[np.isfinite(a)]
+                        lo, hi = (float(f.min()), float(f.max())) if f.size else (0.0, 1.0)
+                        if hi <= lo:
+                            hi = lo + 1.0
+                        m = _mode_for(lo, hi)
+                        scales[f"{names[0]}.{i}"] = [lo, hi]
+                        modes[f"{names[0]}.{i}"] = m
+                        comp_arrays.append(map_component(a, lo, hi, m))
+                        labels.append(f"{names[0]}.{i}")
+                    rgb = np.stack(
+                        [np.clip(comp_arrays[0], 0, 65535)]
+                        + ([np.clip(comp_arrays[1], 0, 65535)] if len(comp_arrays) > 1 else [np.zeros_like(comp_arrays[0])])
+                        + ([np.clip(comp_arrays[2], 0, 65535)] if len(comp_arrays) > 2 else [np.zeros_like(comp_arrays[0])]),
+                        axis=-1,
+                    )  # keep float in [0, 65535]; 8-bit conversion happens below
+                else:
+                    comp_arrays, labels = [], []
+                    for c in names[:3]:
+                        a = arrs[c] if arrs[c].ndim == 2 else arrs[c][..., 0]
+                        f = a[np.isfinite(a)]
+                        lo, hi = (float(f.min()), float(f.max())) if f.size else (0.0, 1.0)
+                        if hi <= lo:
+                            hi = lo + 1.0
+                        m = _mode_for(lo, hi)
+                        scales[c] = [lo, hi]
+                        modes[c] = m
+                        comp_arrays.append(map_component(a, lo, hi, m))
+                        labels.append(c)
+                    rgb = np.stack(
+                        comp_arrays[0:1]
+                        + (comp_arrays[1:2] if len(comp_arrays) > 1 else [np.zeros_like(comp_arrays[0])])
+                        + (comp_arrays[2:3] if len(comp_arrays) > 2 else [np.zeros_like(comp_arrays[0])]),
+                        axis=-1,
+                    )  # keep float in [0, 65535]; 8-bit conversion happens below
+                # Convert to 8-bit HERE, explicitly. Pillow cannot encode 16-bit
+                # RGB PNGs, and Image.fromarray(uint16_array, "RGB") does NOT
+                # downscale — it reinterprets the raw 2-byte values as 8-bit
+                # byte pairs (verified 2026-08-25: produced a scrambled image).
+                rgb = (rgb / 257.0).round().clip(0, 255).astype("uint8")
+                im = Image.fromarray(rgb, mode="RGB")
+                max_edge = max(args.max_preview, 2)
+                if max(h, w) > max_edge:
+                    scale = max_edge / float(max(h, w))
+                    im = im.resize((max(2, int(w * scale)), max(2, int(h * scale))), Image.LANCZOS)
+                im.save(out_path, "PNG")
+                result["preview"] = {
+                    "path": out_path,
+                    "size": [im.width, im.height],
+                    "bitDepth": "8-bit RGB",
+                    "slots": {s: labels[i] for i, s in enumerate(("R", "G", "B")) if i < len(labels)},
+                    "mapping": {k: modes.get(k, "linear") for k in scales},
+                    "componentScales": {
+                        k: {"from": v, "to": [0, 255]} for k, v in scales.items()
+                    },
+                    "note": (
+                        "per-component mapping: 'linear' = full [min,max] -> full range (LDR/maps); "
+                        "'tonemap' = shift+Reinhard+sRGB gamma (HDR/negative data, for viewing). "
+                        "Structure shown, absolute values NOT — use --pixel/--rect for values. "
+                        f"(requested --tone-map: {args.tone_map})"
+                    ),
+                }
+
+    print(json.dumps(sanitize(result)))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except SystemExit:
+        raise
+    except Exception as e:
+        fail(f"unexpected error: {e!r}")

package/exr_reader/index.ts

@@ -0,0 +1,284 @@
+/**
+ * exr_read — EXR inspection tool for pi.
+ *
+ * Loads .exr files (Arnold/RenderMan/Blender/USD renders, UV/ST maps,
+ * AOVs, multilayer EXRs) and reports them to the LLM as:
+ *   - part metadata (size, data window, storage, compression, line order)
+ *   - per-channel statistics (min/max/mean/nonzero fraction, per component)
+ *   - exact float pixel values at a point
+ *   - per-channel statistics over a rect
+ *   - an 8-bit linear-mapped PNG preview (attached to the tool result,
+ *     so a vision model can see the structure)
+ *
+ * The heavy lifting is done by exr_reader/exr_probe.py (OpenEXR 3.x
+ * Python API + numpy + Pillow). This extension only: locates the script,
+ * builds the command, runs it, and packages JSON + preview image.
+ *
+ * Coordinate convention: (x, y) with origin at the TOP-LEFT of the part's
+ * data window, x right, y DOWN — matching how the preview PNG is oriented.
+ *
+ * Project-local install: <project>/.pi/extensions/exr_read/index.ts
+ *   (add { "extensions": ["../../<abs path>/exr_reader/index.ts"] } to
+ *    <project>/.pi/settings.json if you keep the code elsewhere)
+ * Global install: copy to ~/.pi/agent/extensions/exr_read/index.ts
+ */
+
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { execFile, spawnSync } from "node:child_process";
+
+const SCRIPT_DIR = __dirname;
+const SCRIPT = join(SCRIPT_DIR, "exr_probe.py");
+const MAX_PREVIEW_PX = 2048; // 1080² originals pass through unresized; cap guards huge renders
+const MAX_TEXT_CHARS = 12000;
+
+// Mirrors preview_default_name() in exr_probe.py (kept in sync on purpose):
+// <stem>[_<channel-tag>]_preview.png — the channel tag keeps previews of
+// different channel selections of the same file from overwriting each
+// other. The extension always passes --preview-out explicitly (user value
+// or this default) so it knows the exact path for the mutation queue.
+function previewDefaultName(exrPath: string, channels: string[] | undefined): string {
+  let stem = basename(exrPath).replace(/\.[^.]*$/, "");
+  if (channels?.length) {
+    const tag = channels
+      .map((s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, ""))
+      .join("_");
+    if (tag) stem += "_" + tag;
+  }
+  return stem + "_preview.png";
+}
+
+function findPython(): string | null {
+  const candidates = process.platform === "win32" ? ["python", "python3"] : ["python3", "python"];
+  for (const c of candidates) {
+    try {
+      const r = spawnSync(c, ["-c", "import OpenEXR, numpy; print(OpenEXR.__version__)"], {
+        timeout: 15000,
+        encoding: "utf8",
+        windowsHide: true,
+      });
+      if (r.status === 0 && (r.stdout ?? "").trim()) return c;
+    } catch {
+      /* try next */
+    }
+  }
+  return null;
+}
+
+const exrReadSchema = Type.Object({
+  path: Type.String({ description: "Path to the .exr file (absolute or relative to the session cwd)." }),
+  pixel: Type.Optional(
+    Type.Tuple([Type.Number(), Type.Number()], {
+      description:
+        "Optional: query exact values at pixel (x, y). Origin is TOP-LEFT of the part's data window, x right, y DOWN (preview PNG orientation).",
+    })
+  ),
+  rect: Type.Optional(
+    Type.Tuple([Type.Number(), Type.Number(), Type.Number(), Type.Number()], {
+      description: "Optional: per-channel stats over rect (x0, y0, x1, y1), inclusive corners.",
+    })
+  ),
+  channel: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        'Optional: restrict values/stats/preview to these channels (case-insensitive). A group name selects all its components ("uv" matches "uv.R","uv.G","uv.B"; "UV_Box" matches "UV_Box.R/.G/.B"); an exact component name also works. Omitted = all channels for stats, RGB-like composition for preview. A filter that matches nothing is an error listing the available channel names.',
+    })
+  ),
+  preview: Type.Optional(
+    Type.Boolean({ description: "Optional: set false to skip the PNG preview (default true)." })
+  ),
+  previewToneMap: Type.Optional(
+    Type.Union([Type.Literal("auto"), Type.Literal("linear"), Type.Literal("tonemap")], {
+      description:
+        "Optional: preview mapping per component (default 'auto'). 'linear' = min->max full-range remap; 'tonemap' = the viewer look (1.0 = white, sRGB gamma, clip above — what Nuke/Photoshop/AE show for an EXR); 'auto' = linear for map/LDR-like data (~[0,1]) and for data with large negatives (P/Z), tonemap for image-like HDR.",
+    })
+  ),
+  previewOut: Type.Optional(
+    Type.String({
+      description:
+        "Optional: where to save the preview PNG. Default: <cwd>/images/previews/<filename>[_<channels>]_preview.png (project-local, stable names, re-runs refresh the same file).",
+    })
+  ),
+});
+
+export type ExrReadInput = {
+  path: string;
+  pixel?: [number, number];
+  rect?: [number, number, number, number];
+  channel?: string[];
+  preview?: boolean;
+  previewToneMap?: "auto" | "linear" | "tonemap";
+  previewOut?: string;
+};
+
+function previewNote(hasVision: boolean, mapping: Record<string, string> | undefined): string {
+  const coord =
+    "Coordinates: (x, y) with origin at the TOP-LEFT of the part's data window, x increasing right, y increasing DOWN — the preview PNG is oriented the same way, so a point you see at (px, py) in the preview is queryable as pixel [px, py] (scale by preview.size / part size first if the preview was downscaled).";
+  const map = mapping && Object.values(mapping).length
+    ? ` Mapping per component (see 'mapping' in JSON): ${JSON.stringify(mapping)} — 'tonemap' components are Reinhard+sRGB, for viewing only.`
+    : "";
+  return hasVision
+    ? `Preview PNG: an 8-bit view of the image structure (LDR/map components are a linear min->max remap, HDR components are tone-mapped${map}) — structure is shown, absolute values are NOT; use pixel/rect for values. ${coord}`
+    : `Preview: the current model has no image input, so no preview was attached — the JSON below is the full data (the preview PNG is still written for you). ${coord}`;
+}
+
+export default function (pi: any) {
+  let pythonCache: string | null | undefined;
+
+  pi.registerTool({
+    name: "exr_read",
+    label: "EXR Read",
+    description:
+      "Read an .exr image file (render passes, UV/ST maps, Arnold AOVs such as UV/P/Z/TextureGrid, multilayer EXR). Returns part metadata + per-channel float stats, exact pixel values at a point, per-channel stats over a rect, and a linear-mapped PNG preview. Use it whenever the user mentions or references an .exr file. AOVs: pass the group name (e.g. \"UV_Box\") as channel; pixel queries report every part of a multilayer file.",
+    promptSnippet: "exr_read(path, pixel?, rect?, channel?, preview?) — inspect .exr files: metadata, per-channel stats, exact pixel values, rect stats, PNG preview",
+    promptGuidelines: [
+      "Use exr_read (not read/bash) for .exr files; it reports full-precision channel values.",
+      "exr_read coordinates: origin top-left, y down — same orientation as its preview PNG.",
+      "exr_read channel filter: a group name (e.g. 'uv_box') selects its components; a non-matching filter is an error that lists the available names.",
+    ],
+    parameters: exrReadSchema,
+    async execute(
+      _toolCallId: string,
+      params: ExrReadInput,
+      signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      ctx: any
+    ) {
+      if (pythonCache === undefined) pythonCache = findPython();
+      const python = pythonCache;
+      if (!python) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "exr_read unavailable: no python with OpenEXR + numpy found on PATH. Install with:  pip install OpenEXR numpy Pillow",
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const script = SCRIPT;
+      if (!existsSync(script)) {
+        return {
+          content: [{ type: "text" as const, text: `exr_read: script missing: ${script}` }],
+          isError: true,
+        };
+      }
+
+      const absPath = resolve(ctx.cwd, params.path);
+      if (!existsSync(absPath)) {
+        return {
+          content: [{ type: "text" as const, text: `exr_read: file not found: ${absPath}` }],
+          isError: true,
+        };
+      }
+      const args: string[] = [script, absPath];
+      if (params.pixel) args.push("--pixel", String(params.pixel[0]), String(params.pixel[1]));
+      if (params.rect)
+        args.push(
+          "--rect",
+          String(params.rect[0]),
+          String(params.rect[1]),
+          String(params.rect[2]),
+          String(params.rect[3])
+        );
+      if (params.channel) for (const c of params.channel) args.push("--channel", c);
+      const wantPreview = params.preview !== false;
+      let previewPath: string | undefined;
+      if (!wantPreview) {
+        args.push("--no-preview");
+      } else {
+        previewPath = params.previewOut
+          ? resolve(ctx.cwd, params.previewOut)
+          : join(ctx.cwd, "images", "previews", previewDefaultName(absPath, params.channel));
+        args.push(
+          "--preview-out", previewPath,
+          "--max-preview", String(MAX_PREVIEW_PX),
+          "--tone-map", params.previewToneMap ?? "auto"
+        );
+      }
+
+      // The probe writes previewPath. Queue it per the extension docs so
+      // parallel exr_read calls on the same file (same default preview
+      // path) can't interleave their writes.
+      const run = () => new Promise<{ stdout: string; stderr: string; code: number; spawnErr?: string }>((resolveP) => {
+        execFile(
+          python,
+          args,
+          {
+            cwd: ctx.cwd,
+            timeout: 300000,
+            maxBuffer: 16 * 1024 * 1024,
+            windowsHide: true,
+            signal,
+          },
+          (error, stdout, stderr) => {
+            let code = 0;
+            let spawnErr: string | undefined;
+            if (error) {
+              if (typeof (error as any).code === "number") code = (error as any).code;
+              else spawnErr = (error as any).code ?? String(error);
+            }
+            resolveP({ stdout: String(stdout ?? ""), stderr: String(stderr ?? ""), code, spawnErr });
+          }
+        );
+      });
+
+      const res = previewPath ? await withFileMutationQueue(previewPath, run) : await run();
+
+      if (res.spawnErr) {
+        return {
+          content: [{ type: "text" as const, text: `exr_read: python spawn failed (${res.spawnErr})` }],
+          isError: true,
+        };
+      }
+      if (res.code !== 0 && !res.stdout.trim()) {
+        return {
+          content: [{ type: "text" as const, text: `exr_read failed (exit ${res.code}):\n${res.stderr}` }],
+          isError: true,
+        };
+      }
+
+      let json: any = null;
+      try {
+        json = JSON.parse(res.stdout.trim().split("\n").pop() ?? "");
+      } catch (e: any) {
+        return {
+          content: [{ type: "text" as const, text: `exr_read: could not parse probe output: ${e?.message}\n${res.stdout.slice(0, 2000)}` }],
+          isError: true,
+        };
+      }
+
+      if (!json.ok) {
+        return {
+          content: [{ type: "text" as const, text: `exr_read: ${json.error}${json.part0_dataWindow ? ` (part 0 data window ${JSON.stringify(json.part0_dataWindow)}, size ${JSON.stringify(json.part0_size)})` : ""}` }],
+          isError: true,
+        };
+      }
+
+      const model: any = ctx.model;
+      const hasVision = Array.isArray(model?.input) && model.input.includes("image");
+
+      const content: Array<{ type: "text" | "image"; text?: string; data?: string; mimeType?: string }> = [];
+      let text = JSON.stringify(json, null, 1);
+      if (text.length > MAX_TEXT_CHARS) {
+        text =
+          text.slice(0, MAX_TEXT_CHARS) +
+          `\n…[truncated ${text.length - MAX_TEXT_CHARS} chars — re-query with channel/pixel/rect to narrow]`;
+      }
+      if (hasVision && json.preview?.path && existsSync(json.preview.path) && statSync(json.preview.path).size > 0) {
+        content.push({
+          type: "image",
+          data: readFileSync(json.preview.path).toString("base64"),
+          mimeType: "image/png",
+        });
+      }
+      content.push({ type: "text", text: text + "\n\n" + previewNote(hasVision, json.preview?.mapping) });
+
+      return { content, details: { previewPath: json.preview?.path } };
+    },
+  });
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "pi-exr-reader",
+  "version": "0.1.0",
+  "description": "Pi extension: read .exr files — exact full-precision channel stats, pixel values, rect stats, and a PNG preview. Works on Arnold/RenderMan/Blender AOVs, UV/ST maps, and multilayer EXRs.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "exr",
+    "openexr",
+    "aov",
+    "arnold",
+    "uv-map",
+    "render",
+    "pixel-inspection"
+  ],
+  "license": "MIT",
+  "author": "Luke Richardson",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lrich0/pi-exr-reader.git"
+  },
+  "files": [
+    "exr_reader/",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./exr_reader"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@types/node": "^25.9.1",
+    "typebox": "*",
+    "typescript": "^6.0.3"
+  }
+}