diff --git a/README.md b/README.md index 71fb70c..99540b6 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,19 @@ sensors/finger/ ## Prerequisites - Python 3.10+ -- Blender version pinned in `blender.lock.json` (install separately) +- Blender version pinned in `blender.lock.json` (install separately; see below) + +Install the CLI (editable): + +```powershell +cd D:\orisys_ws\orisys-sensor-design +python -m pip install -e . +``` + +The base install is stdlib + PyYAML. Feature extras are `dev`, `preview`, `optics`, +`viz` and `probe`; see `requirements.txt` for the flat list, which is what the full +test suite needs. Blender is only used by the in-scene commands, so `validate`, +`export`, `texture` and `manifest` run without it. No Git LFS is required — binaries are committed as ordinary files. @@ -66,13 +78,6 @@ Convenience launcher (auto-finds Blender for this process, then exports): ## Commands -Install the CLI (editable): - -```powershell -cd D:\orisys_ws\orisys-sensor-design -python -m pip install -e . -``` - Four commands for v1: ```powershell @@ -516,54 +521,20 @@ per-cell pattern does not. ### The noise floor was wrong, and it changed the answer -**Read [`docs/probe-findings.md`](docs/probe-findings.md) for the conclusions and -recommendations.** The short version is below. +**Read [`docs/probe-findings.md`](docs/probe-findings.md) for the conclusions, the tables and +the numbers; [method](docs/probe-method.md) for why.** The short version: -**This section replaces an earlier claim that nx=31 is the best pattern and that "the -marker cell must match the estimator's effective window". That claim is retracted.** It -was driven by the noise floor, and the floor was not a valid noise model. +An earlier claim here — that nx=31 is the best pattern and that "the marker cell must match +the estimator's effective window" — is **retracted**. It was driven by `floor_px`, which is a +render-seed antialiasing artefact, not sensor noise: its trend reverses under additive noise, +and it understates the real idle floor (0.2267 px p95 |flow| on `data/dd02-0703/190.mp4`) by +roughly 2–6x, understating the coarse patterns most. -`floor_px` is measured as `reference` vs a re-render at **seed + 1** — Cycles -antialiasing jitter. On this data it differs by ~5 grey levels RMS on half the pixels and -scales with edge contrast. It is not sensor noise, and three checks show it cannot rank -patterns: - -1. **Its trend reverses** under additive noise. p95 |flow| over the ROI, same DIS config: - - | pattern | render-seed | injected σ=2 | σ=4 | - |---|---|---|---| - | nx=80 | 0.0292 | **0.0161** | 0.0278 | - | nx=31 | 0.0376 | **0.0084** | 0.0182 | - | nx=56 | 0.0134 | 0.0102 | 0.0203 | - -2. **It understates the real floor.** Measured on idle dd02 footage - (`data/dd02-0703/190.mp4`, 1280x720) with the same estimator: - **0.2267 px** p95 |flow| over the ROI, dominant marker period **25.5 px**, i.e. - **0.0089 floor per period**. Short baseline (consecutive frames) equals long baseline - (vs frame 0) — ratio 0.98 — so this is frame-independent white noise, not drift, and - the clip is genuinely idle. Every simulated floor per cell is well below it, and the - **coarse patterns are understated most** (nx=56 by ~6x, nx=31 by ~4x, nx=80 by ~2x) — - exactly the bias that made nx=31 and nx=56 look best. - -3. **Signal is not noise-invariant either**, so gain must be quoted under a stated model. - At +0.10 mm on the x axis, retention is `gain(σ)/gain(clean)`: - - | pattern | σ=4 | σ=16 | - |---|---|---| - | nx=80 dm1 | **99%** | **84%** | - | nx=56 dm1 | 96% | 71% | - | nx=31 dm1 | 72% | 59% | - -**What the calibrated model supports:** at the render scale, `radius_mm=0.5`, `dis_mode=1`, -nx=80 has the **highest clean response on both axes** (x 9.10 vs 4.74 px/mm; y 11.69 vs -10.90) and the **best noise retention** (84–99% vs 59–73%), so on this evidence the -shipped 80x80 is competitive or better, not worse. What is *not* yet re-ranked: the -process (250x250) scale and the `radius_mm=1.5` block, where the score ordering differs. - -Every report now carries `noise_models` (per-axis gain, floor and `response_retention` per -σ, measured under one model) and `noise_calibration` (the real idle numbers above), and -`settings_response.png` has a retention panel so a pattern that looks strong but collapses -under noise is visible. +Under the calibrated model, the shipped **80x80 has the highest clean response on both axes +and the best noise retention** (84–99% vs 59–73%), so it is competitive or better, not worse. +Not yet re-ranked: the process (250x250) scale and the `radius_mm=1.5` block, where the score +ordering differs. Every report carries `noise_models` and `noise_calibration`, and +`settings_response.png` has a retention panel. ### What the bench measures diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..43c6e08 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,18 @@ +# python -m pip install -r requirements.txt +# python -m pip install -e . # the `orisys-design` entry point +# +# Flat instead of `-e .[dev,preview,optics,viz,probe]`, which needs network. + +PyYAML>=6.0 +pytest>=7.0 +numpy>=1.24 +PyQt5>=5.15 +PyOpenGL>=3.1 +matplotlib>=3.7 +opencv-python>=4.8 + +# tests/test_uv_map.py imports `orisys.unroll.geometry` with no importorskip guard, so the +# suite also needs the sibling repo: pip install -e ../orisys-sdk +# +# Blender is not a pip dependency: install the version in blender.lock.json, on PATH or via +# ORISYS_BLENDER. Only the in-scene commands need it.