From b7942bfb298a1fc5814f879657a59d348ac4cbcc Mon Sep 17 00:00:00 2001 From: ykcheungab Date: Sun, 4 Oct 2026 11:02:25 +0800 Subject: [PATCH] make the newcomer setup path work Prerequisites named only Python and Blender while the install step sat 29 lines below in Commands, so a new contributor hit a missing package before finding the command that installs it. Install now sits inside Prerequisites, with the extras, the flat requirements.txt list, and which commands actually need Blender. The duplicate install block left Commands. requirements.txt gives the flat dependency set in one file; pyproject extras stay the source of truth. Verified: README 3770 words against its frozen 3965 ceiling, the 238 words freed by moving the probe retraction's tables to the docs that already own them; doc_lint default and --all exit 0. --- README.md | 79 +++++++++++++++--------------------------------- requirements.txt | 18 +++++++++++ 2 files changed, 43 insertions(+), 54 deletions(-) create mode 100644 requirements.txt 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.