Drive PIV Desk from your own code

{
  "settings": {
    "openpiv_version": "0.25.4",
    "source": "synthetic pair generated by the page",
    "frame_a": {"file": "frame_a.png", "format": "png", "width": 320, "height": 320, "bit_depth": 8,
                "openpiv_reads_as": "2-D grey array", "grey_min": 0, "grey_max": 255,
                "grey_mean": 16.47, "grey_std": 20.22, "saturated_fraction": 0.0000293},
    "frame_b": {"file": "frame_b.png", "...": "as frame_a"},
    "window_size": 32, "overlap": 12, "search_area_size": 38,
    "correlation_method": "linear", "correlation_setting": "auto",
    "subpixel_method": "gaussian", "sig2noise_method": "peak2peak", "width": 2,
    "sig2noise_threshold": 1.05, "dt_s": 0.01, "scaling_px_per_unit": 20, "unit": "mm",
    "validators": ["sig2noise_val"],
    "replace_outliers": {"method": "localmean", "max_iter": 3, "kernel_size": 2, "tol": 0.001},
    "drop_invalid": false,
    "grid": {"rows": 11, "cols": 11, "step_px": 26, "first_label_px": [30, 30],
             "coordinate_offset_px": [11, 11], "spacing": 1.3},
    "correlation_plane": {"shape": [38, 38], "zero_padded_to": 127},
    "normalized_windows": true,
    "runner_equivalent": true,
    "synthetic": {"description": "synthetic 320 x 320, Lamb-Oseen vortex, peak 3 px/frame at r = 70 px, ...",
                  "field": "vortex", "seed": 11, "particle_density_per_px": 0.02,
                  "particle_diameter_px": 2.6, "noise_grey_levels": 3}
  },
  "metrics": [
    {"id": "M1", "metric": "vectors", "value": 121,
     "basis": "11 rows x 11 columns of 38 px search windows every 26 px"},
    {"id": "M2", "metric": "flagged_vectors", "value": 0, "basis": "sig2noise_val(s2n < 1.05); s2n 0", "fraction": 0},
    {"id": "M3", "metric": "median_s2n", "value": 4.021, "basis": "peak2peak over all 121 vectors ...", "p10": 3.076},
    {"id": "M4", "metric": "max_displacement_px", "value": 2.997,
     "basis": "largest |displacement| of a valid vector, px per frame; the quarter-window guide is 8 px"},
    "... M5 median_displacement_px 2.341, M6 quarter_rule_exceeded 0, M7 peak_locking_near_integer 0.2107,
     M8 border_peaks 0, M9 replaced_vectors 0 ...",
    {"id": "M10", "metric": "mean_velocity", "value": [-0.59864, -0.61434],
     "basis": "u_mean, v_mean in mm/s after scaling, y up (analyze.py)"},
    {"id": "M11", "metric": "rms_velocity", "value": [8.3309, 8.3922], "basis": "...", "tke": 69.916},
    {"id": "M12", "metric": "vorticity_range", "value": [-0.5193, 12.31],
     "basis": "min, max of dv/dx - du/dy in 1/s on the 1.30000 mm grid (analyze.py)"},
    "... M13 particles_per_window 18.4, M14 saturated_pixels 0.0000293 ...",
    {"id": "M15", "metric": "truth_rms_error_px", "value": 0.127, "basis": "synthetic pair: ...",
     "bias_u_v": [0.003859, -0.0007199], "rms_after_replacement": 0.127, "rms_at_labels": 0.4493},
    {"id": "M16", "metric": "coordinate_offset_px", "value": [11, 11], "basis": "..."}
  ],
  "flags": [
    {"id": "F1", "severity": "low", "category": "saturation",
     "message": "Some pixels (0%) are at full scale.", "refs": ["M14"]},
    {"id": "F2", "severity": "low", "category": "coordinate_offset",
     "message": "openpiv labels each vector 11 px right and 11 px down of its window's centre ...", "refs": ["M16"]},
    {"id": "F3", "severity": "low", "category": "single_pair_statistics",
     "message": "The mean and RMS velocities come from one image pair: ...", "refs": ["M10", "M11"]}
  ],
  "regions": [
    {"region": "top left", "vectors": 9, "flagged": 0, "median_s2n": 4.498, "median_displacement_px": 1.774},
    "... 8 more, top centre to bottom right ..."
  ],
  "flagged_vectors": [],
  "flagged_vectors_total": 0,
  "browser_verdict": "sound",
  "expected": {
    "n_rows": 11, "n_cols": 11, "flagged_count": 0,
    "u_px__r5c5": -0.688174, "v_px__r5c5": 0.509149, "s2n__r5c5": 2.588528,
    "u_px__r2c2": -1.574056, "v_px__r2c2": 1.717378, "s2n__r2c2": 3.148825,
    "...": "r2c8, r8c2 and r8c8 the same way"
  },
  "expected_count": 18,
  "clipped": []
}

// make-body.js - build the exact body the page sends, with the page's own code.
// Save https://piv-desk.skillsafe.ai/piv.js, pivkit.js and imgio.js next to this file (Node 18+), then:
//   node make-body.js frame_a.png frame_b.png review "Vortex check" "notes" "question" > body.json
// Frames are PNG (8/16-bit) or uncompressed TIFF. Settings come from settings.json if present
// (the page's "Save settings .json" file, or {"params": {...}, "unit": "mm"}); otherwise the page defaults.
const fs = require("fs");
const path = require("path");
const PIV = require("./piv.js");
const K = require("./pivkit.js");
const IO = require("./imgio.js");
const [fa, fb, lane = "review", title = "", context = "", question = "", decision = ""] = process.argv.slice(2);

async function frame(file) {
  const bytes = new Uint8Array(fs.readFileSync(file));
  const fmt = IO.sniff(bytes);
  const img = fmt === "png" ? await IO.decodePng(bytes) : fmt === "tiff" ? IO.decodeTiff(bytes) : null;
  if (!img) throw new Error(file + ": only PNG and uncompressed TIFF decode outside a browser");
  const gray = IO.toOpenpivGray(img);
  return { name: path.basename(file), format: img.format, decoder: img.decoder, w: img.w, h: img.h, depth: img.depth,
    layout: img.layout, multipage: !!img.multipage, gray, stats: IO.stats(gray, img.w, img.h, img.depth) };
}

(async () => {
  const saved = fs.existsSync("settings.json") ? JSON.parse(fs.readFileSync("settings.json", "utf8")) : {};
  const params = Object.assign({}, PIV.DEFAULTS, saved.params || {});
  const unit = saved.unit || "mm";
  const a = await frame(fa), b = await frame(fb);
  const res = PIV.runSync(a.gray, b.gray, a.h, a.w, params);
  const X = K.analyze(res, { a, b }, null, { title, unit });
  const body = K.mustBeObject(K.buildInput(X, { lane, title, context, question, decision }));
  fs.writeFileSync("vectors.txt", PIV.vectorsTxt(X.res));     // openpiv's tools.save format
  console.error("browser verdict:", X.hint, "| vectors:", X.n, "| flagged:", X.nFlag, "| flags:", X.flags.map(f => f.id + " " + f.category).join(", "));
  console.error("idempotency key: piv-desk:" + body.task + ":" + K.hashInput(body) + ":a1");
  process.stdout.write(JSON.stringify(body));
})().catch(e => { console.error(e.message); process.exit(1); });

# Or build the body in any language from a facts object you already hold, for example the
# "facts" key of the page's "Report .json" download. facts must go in as a STRING.
import json

report = json.load(open("piv-desk-vortex-check-before-the-tunnel-run-report.json"))   # the page's download
facts = report["facts"]
body = {
    "task": "review",
    "title": "Vortex check before the tunnel run",
    "context": "Synthetic check of our processing chain before the water-tunnel campaign. ...",
    "question": "Is a 32 px window fine enough for this vortex?",
    "facts": json.dumps(facts, separators=(",", ":")),
}
json.dump(body, open("body.json", "w"))

{"ok": true, "data": {"job_id": "job_...", "status": "queued"}}
{"ok": false, "error": {"code": "payment_required", "message": "..."}}

# Every call is the same three things: the base URL, your bearer token,
# and a JSON body. Keep the token in a shell variable.
BASE="https://api.skillsafe.ai/v1/app-api"
SLUG="piv-desk"
TOKEN="$SKILLSAFE_TOKEN"   # from https://piv-desk.skillsafe.ai/tokens.html

call() {                  # call <path> [json-body]
  if [ -n "$2" ]; then
    curl -sS -X POST "$BASE/$1" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d "$2"
  else
    curl -sS "$BASE/$1" -H "Authorization: Bearer $TOKEN"
  fi
}

# The token page is the shortest path. It shows the token this browser holds and
# hands you a ready-made shell export:
#
#   https://piv-desk.skillsafe.ai/tokens.html
#   export SKILLSAFE_TOKEN="..."
#
# To mint a guest token from the command line instead. A guest token is enough
# for /me and /estimate; a run needs a personal token from signing in.
curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/guest" \
  -H "Content-Type: application/json" -d '{"slug":"piv-desk"}'
# {"ok":true,"data":{"token":"...","subject_type":"guest"}}

call me
# {"ok":true,"data":{"subject_type":"user","username":"you","credits":51234}}

# body.json is the input object itself - no {"input": ...} wrapper. Build it with
# make-body.js above, or by hand. estimate does not validate it, so check the shape first:
python3 -c 'import json;b=json.load(open("body.json"));assert isinstance(b,dict) and b.get("task") in ("review","script") and all(isinstance(v,str) for v in b.values()) and all(b.get(k,"").strip() for k in ("facts",)) and isinstance(json.loads(b["facts"]),dict)'
INPUT=$(cat body.json)

call estimate "$INPUT"
# {"ok":true,"data":{"model":"...","model_alias":"gpt-terra",
#   "markup_bps":1000,"hold_credits":...,"min_credits":...,"sponsor_enabled":false,
#   "warnings":[]}}
#
# estimate creates no job and charges nothing. hold_credits is RESERVED, not the
# price; charged_credits after the run is the actual cost, usually far lower.

# Always send an Idempotency-Key derived from the input. A retried request with
# the same key returns the SAME job instead of billing a second run.
LANE=$(printf '%s' "$INPUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["task"])')   # review or script
KEY="piv-desk:$LANE:$(printf '%s' "$INPUT" | shasum -a 256 | cut -c1-16):a1"

JOB=$(curl -sS -X POST "$BASE/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d "$INPUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["job_id"])')

while :; do
  OUT=$(call "jobs/$JOB")
  STATUS=$(printf '%s' "$OUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["status"])')
  [ "$STATUS" = "succeeded" ] && break
  [ "$STATUS" = "failed" ] && echo "$OUT" && exit 1
  sleep 2
done

# {"ok":true,"data":{"job_id":"job_...","status":"succeeded",
#   "output":{"output":"{\"lane\":\"review\",\"verdict\":\"caveated\",\"headline\":\"...\", ...}"},
#   "charged_credits":...,"truncated":false}}
printf '%s' "$OUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["output"]["output"])' > reply.json

# Server-sent events. `delta` events carry chunks of the reply; `done` carries the
# status, charged_credits and the truncated flag. Ignore `tick` heartbeats.
curl -N -X POST "$BASE/run-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -H "Accept: text/event-stream" \
  -d "$INPUT"

# event: job    {"job_id":"job_..."}
# event: delta  {"text":"{\"lane\":\"review\",\"verdict\":\"caveated\",\"headline\":\"The"}
# event: done   {"status":"succeeded","charged_credits":...,"truncated":false}

# The reply is a JSON string inside data.output.output. Pull it out and parse it:
printf '%s' "$JOB" | python3 -c 'import sys,json;r=json.loads(json.load(sys.stdin)["output"]["output"]);print(r["verdict"],r["headline"])'

{
 "task": "review",
 "title": "Vortex check before the tunnel run",
 "context": "Synthetic check of our processing chain before the water-tunnel campaign. I want to say these settings resolve the vortex and its peak displacement of about 3 px per frame.",
 "facts": "{\"settings\":{\"openpiv_version\":\"0.25.4\",\"source\":\"synthetic pair generated by the page\",\"frame_a\":{\"file\":\"frame_a.png\",\"format\":\"png\",\"width\":320,\"height\":320,\"bit_depth\":8,\"...\":\"more\"},\"...\":\"more settings\"},\"metrics\":[{\"id\":\"M1\",\"metric\":\"vectors\",\"value\":121,\"...\":\"...\"},\"... M2 to M16 ...\"],\"flags\":[{\"id\":\"F1\",\"severity\":\"low\",\"category\":\"saturation\",\"...\":\"...\"},{\"id\":\"F2\",\"severity\":\"low\",\"category\":\"coordinate_offset\",\"...\":\"...\"},{\"id\":\"F3\",\"severity\":\"low\",\"category\":\"single_pair_statistics\",\"...\":\"...\"}],\"regions\":[...],\"flagged_vectors\":[],\"flagged_vectors_total\":0,\"browser_verdict\":\"sound\",\"expected\":{\"n_rows\":11,\"n_cols\":11,\"flagged_count\":0,\"...\":\"15 more\"},\"expected_count\":18,\"clipped\":[]}",
 "question": "Is a 32 px window fine enough for this vortex?"
}

{
  "lane": "review",
  "verdict": "sound",
  "headline": "The measured field of this synthetic vortex is fully valid: all 121 vectors pass sig2noise_val and none are replaced.",
  "tldr": [
    "0 of 121 vectors are flagged (M2) and 0 are replaced (M9), so every vector is a measurement.",
    "The synthetic truth check gives an RMS error of 0.127 px per frame at the window centres (M15).",
    "Answer: on this pair the 32 px window keeps every displacement well inside the 8 px quarter-window guide (M4: 2.997 px, M6: 0), but one window spans 32 px, so finer vortex structure is not resolved."
  ],
  "metrics": [
    {"id": "M1", "reading": "121 vectors on an 11 x 11 grid of 38 px search windows every 26 px."},
    {"id": "M2", "reading": "No vector falls below the 1.05 signal-to-noise threshold (0%)."},
    "... one reading for each of M3 to M16, in order ..."
  ],
  "field": [
    "No region has a flagged vector; region median displacements run from 1.774 px (top left) to 2.729 px (bottom centre).",
    "The vorticity ranges from -0.519 to 12.3 1/s (M12) on the 1.3 mm grid.",
    "..."
  ],
  "parameters": [
    {"change": "Test window_size 16 with a matching overlap and search_area_size, as a suggestion.", "why": "Displacements are far below the quarter-window guide, so a smaller window may resolve the core more finely.", "refs": ""}
  ],
  "claims": [
    {"claim": "These settings resolve the vortex and its peak displacement of about 3 px per frame.", "support": "partly", "why": "The largest measured displacement is 2.997 px per frame (M4) and the truth error is 0.127 px (M15), but the spatial resolution is one 32 px window."}
  ],
  "methods": "Vectors were computed with openpiv 0.25.4 extended_search_area_piv using a 32 px window, 12 px overlap and 38 px search area, linear correlation, a gaussian sub-pixel fit and peak2peak signal-to-noise; vectors below 1.05 were flagged with sig2noise_val and replaced by localmean replace_outliers (max_iter 3, kernel_size 2); dt 0.01 s, 20 px/mm. ...",
  "cautions": [
    "One image pair gives spatial spread, not turbulence statistics (F3).",
    "Out-of-plane motion is not measured by a single-camera pair.",
    "..."
  ],
  "next_steps": ["Repeat the synthetic check at the displacements expected in the tunnel.", "..."],
  "prescan_responses": [
    {"ref": "F1", "verdict": "confirmed", "note": "A share of 0.0000293 of the pixels is at full scale; too small to affect the field."},
    {"ref": "F2", "verdict": "confirmed", "note": "Labels sit 11 px right and down of the window centres (M16)."},
    {"ref": "F3", "verdict": "confirmed", "note": "M10 and M11 describe this one pair only."}
  ]
}

{
 "task": "script",
 "title": "Vortex check before the tunnel run",
 "context": "Synthetic check of our processing chain before the water-tunnel campaign. I want a script that reproduces this field and then tries a finer window.",
 "facts": "{\"settings\":{\"openpiv_version\":\"0.25.4\",\"...\":\"as in the review example\"},\"...\":\"...\",\"browser_verdict\":\"sound\",\"expected\":{\"n_rows\":11,\"n_cols\":11,\"flagged_count\":0,\"u_px__r5c5\":-0.688174,\"v_px__r5c5\":0.509149,\"s2n__r5c5\":2.588528,\"...\":\"12 more\"},\"expected_count\":18,\"clipped\":[]}",
 "decision": "Verdict: sound.\nThe 32 px window fully resolves this synthetic vortex - every one of 121 vectors is valid and unreplaced with a 0.127 px truth error - though its labels sit 11 px off the window centres.\n- All 121 vectors across all nine regions are unflagged and unreplaced (M2, M9), ...\n...\n- Try: Test a smaller window_size such as 16 px, with a matched search_area_size, as a suggestion to test. (...)\n...\nNext steps:\n- ..."
}

{
  "lane": "script",
  "verdict": "sound",
  "headline": "The script reproduces the 121-vector field from frame_a.png and frame_b.png, checks all 18 expected values, then reruns with a 16 px window.",
  "tldr": ["The reproduction check covers the grid shape, the flagged count and u, v and s2n at five vectors.", "..."],
  "fixes": [
    {"fix": "Rerun extended_search_area_piv with window_size 16, overlap 8 and search_area_size 20 and print the flagged count.", "why": "The review suggested a finer window; the flagged count shows what it costs.", "refs": ""},
    {"fix": "Add local_median_val with a 2 px per frame threshold applied in px/s and print the flagged count.", "why": "A second, spatial validator before the real tunnel pairs.", "refs": ""},
    {"fix": "Save vectors.txt with tools.save.", "why": "The same file the page exports, for comparison.", "refs": ""}
  ],
  "script": "import json\nimport math\nfrom pathlib import Path\n\nimport numpy as np\n...",
  "assumptions": ["frame_a.png and frame_b.png are the frames the page generated.", "openpiv 0.25.4 is installed.", "dt 0.01 s and 20 px/mm are the experiment's own values."],
  "checks": ["The reproduction prints no MISMATCH line.", "How the flagged count moves with the 16 px window and with local_median_val."],
  "next_steps": ["Save both frames from the page next to piv_check.py and run python piv_check.py.", "..."],
  "prescan_responses": [
    {"ref": "F1", "verdict": "confirmed", "note": "A negligible share of saturated pixels; the script does not change it."},
    {"ref": "F2", "verdict": "confirmed", "note": "The script keeps openpiv's labels from get_coordinates."},
    {"ref": "F3", "verdict": "confirmed", "note": "One pair; the script does not build an ensemble."}
  ]
}

# piv_check.py - reproduce the browser's PIV field with openpiv 0.25.4 (abbreviated reply script)
import json
import math
from pathlib import Path

import numpy as np
from openpiv import filters, pyprocess, scaling, tools, validation

FRAME_A = "frame_a.png"
FRAME_B = "frame_b.png"
DT = 0.01
SCALING = 20

EXPECTED = {
    "n_rows": 11, "n_cols": 11, "flagged_count": 0,
    "u_px__r5c5": -0.688174, "v_px__r5c5": 0.509149, "s2n__r5c5": 2.588528,
    "u_px__r2c2": -1.574056, "v_px__r2c2": 1.717378, "s2n__r2c2": 3.148825,
    "u_px__r2c8": -1.934253, "v_px__r2c8": -1.476777, "s2n__r2c8": 3.224506,
    "u_px__r8c2": 1.528143, "v_px__r8c2": 1.970747, "s2n__r8c2": 4.264483,
    "u_px__r8c8": 2.015346, "v_px__r8c8": -1.944011, "s2n__r8c8": 4.319056,
}


def check(u, v, s2n, flags):
    bad = []
    if (EXPECTED["n_rows"], EXPECTED["n_cols"]) != u.shape:
        bad.append(f"shape {u.shape}")
    if abs(int(flags.sum()) - EXPECTED["flagged_count"]) > 1:
        bad.append(f"flagged_count {int(flags.sum())}")
    for key, want in EXPECTED.items():
        if "__r" not in key:
            continue
        name, tag = key.split("__")
        r, c = (int(t) for t in tag[1:].split("c"))
        if name == "s2n":
            got, ok = float(s2n[r, c]), math.isclose(float(s2n[r, c]), want, rel_tol=1e-3, abs_tol=1e-3)
        else:
            got = float((u if name == "u_px" else v)[r, c] * DT)
            ok = math.isclose(got, want, abs_tol=2e-3)
        if not ok:
            bad.append(f"{key}: got {got!r}, expected {want!r}")
    for b in bad:
        print("MISMATCH", b)
    print("reproduction:", "OK" if not bad else f"{len(bad)} mismatch(es)")


def main():
    for name in (FRAME_A, FRAME_B):
        if not Path(name).is_file():
            raise SystemExit(f"{name} not found: save both frames from the PIV Desk page first")
    frame_a = tools.imread(FRAME_A).astype(np.int32)
    frame_b = tools.imread(FRAME_B).astype(np.int32)

    u, v, s2n = pyprocess.extended_search_area_piv(
        frame_a, frame_b, window_size=32, overlap=12, dt=DT, search_area_size=38,
        correlation_method="linear", subpixel_method="gaussian", sig2noise_method="peak2peak", width=2)
    x, y = pyprocess.get_coordinates(image_size=frame_a.shape, search_area_size=38, overlap=12)
    flags = validation.sig2noise_val(s2n, threshold=1.05)
    check(u, v, s2n, flags)

    u, v = filters.replace_outliers(u, v, flags, method="localmean", max_iter=3, kernel_size=2)
    x, y, u, v = scaling.uniform(x, y, u, v, scaling_factor=SCALING)
    x, y, u, v = tools.transform_coordinates(x, y, u, v)

    # Fix 1: a finer window (a suggestion to test).
    u16, v16, s16 = pyprocess.extended_search_area_piv(
        frame_a, frame_b, window_size=16, overlap=8, dt=DT, search_area_size=20,
        correlation_method="linear", subpixel_method="gaussian", sig2noise_method="peak2peak", width=2)
    print("16 px window: flagged", int(validation.sig2noise_val(s16, threshold=1.05).sum()), "of", u16.size)
    # Fix 2 ... Fix 3: tools.save("vectors.txt", x, y, u, v, flags)


if __name__ == "__main__":
    main()

{
  "lane": "review" | "script",
  "verdict": "sound" | "caveated" | "unreliable",
  "headline": "one sentence",
  "tldr": ["2-5 bullets; one starts \"Answer:\" when a question was asked"],
  ...lane body...,
  "next_steps": ["1-5 concrete actions, most useful first"],
  "prescan_responses": [{"ref": "F1", "verdict": "confirmed|dismissed", "note": "..."}]  // every flag once
}

{
  "metrics": [{"id": "M1", "reading": "..."}],            // one per facts.metrics item, same order
  "field": ["1-5 strings: where vectors failed or were replaced, largest displacements, vorticity, mean velocity"],
  "parameters": [{"change": "...", "why": "...", "refs": "F2"}],   // 0-4; refs "" when no flag
  "claims": [{"claim": "...", "support": "supported|partly|not_supported", "why": "..."}],
  "methods": "one methods-section paragraph stating exactly the processing in settings",
  "cautions": ["1-4 strings on what this field cannot show"]
}

{
  "fixes": [{"fix": "...", "why": "...", "refs": "F1"}],  // 1-6; refs "" for a plain step
  "script": "import json\nimport math\n...",              // one complete Python script, under 9000 characters
  "assumptions": ["1-4 strings"],
  "checks": ["1-4 strings"]
}