orisys-tech/orisys-sensor-design
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

make the newcomer setup path work

Browse Source 
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.
This commit is contained in:
ykcheungab
2026-10-04 11:02:25 +08:00
parent 30a903a299
commit b7942bfb29
2 changed files with 43 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+25 -54
View File
@@ -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