SectionCheck synthetic prototype

A runnable CPU experiment for reviewing one 2D affine transform. The CLI validates a neutral manifest and image hashes, checks coordinate frames and explicit policy bounds, and produces a self-contained HTML report. Version 0.2.1.dev0 supports annotation review, explicit decisions, approval-bound export and local re-import verification. Only authored synthetic data is accepted in this version. No researcher requirement or usefulness has been confirmed. This is an independent engineering prototype with no affiliation to Neuralink, VALIS or QuPath.

Live synthetic report · Releases · Contribution evidence

Explore in 3D · Watch the 30-second film · Download the illustrative GLB model · Media sources and reproduction. The scene uses the original synthetic images and ROI coordinates with depth added for explanation. The saved review still requires a decision.

The implementation was developed with AI assistance. The recorded validation covers synthetic geometry and software behavior; researcher usefulness and external-viewer interoperability remain unconfirmed.

The 0.2.1 review fixes reject non-regular image inputs, handle calibration overflow, require exact affine matrix rows, and disclose ROIs that cannot be fully seen in a preview crop. Updating requires a new report and decision because the tool version and source hashes are bound to approval.

uv venv --python 3.12 .venv
uv pip sync --python .venv/bin/python --require-hashes requirements.lock
uv pip install --python .venv/bin/python --no-deps -e .
.venv/bin/python examples/generate_synthetic.py
.venv/bin/sectioncheck check examples/synthetic/manifest.json
.venv/bin/sectioncheck report examples/synthetic/manifest.json --out my-report
.venv/bin/python -m pytest

For the new annotation workflow, start with:

.venv/bin/sectioncheck review examples/synthetic/manifest.json --annotations examples/synthetic/annotations.json --out roi-review

Open roi-review/report.html, inspect the six image/ROI panels and checks, and follow WORKFLOW.md to record a decision and export. Review reports never approve their own inputs. The full automated synthetic protocol exercise is also reproducible:

.venv/bin/python examples/exercise_synthetic_workflow.py --fixtures examples/synthetic --out synthetic-exercise

That script labels its decision automated-synthetic-exercise. It demonstrates the protocol and known geometric expectations; it is not a person's acceptance.

Open my-report/report.html locally. --out must name a new directory so existing reports and original images are preserved. A successful CLI exit means the engineering checks ran; it does not mean a transform was approved. Hard-invalid input returns exit 2 and creates no report. Warning and not-evaluated results are explicit. The initial version's transform-only report is preserved in examples/report/report.html; the current annotation example is in examples/workflow/report.html.

Coordinate contract

The packaged schema is strict and versioned. Affine matrices require the exact last row [0, 0, 1]; nonzero projective terms are rejected even when small. Declared calibration values must fit finite, positive floating-point values. H maps source level-0 integer pixel centers into target level-0 integer pixel centers, with column vectors [x,y,1], x right and y down. Each local preview has its own downsample/crop mapping C. Source-local to target-local mapping is:

inverse(C_target) @ H @ C_source

Local frames support positive independent x/y scales and crop translations. For full pyramidal downsampling by d, center alignment usually requires offset (d - 1) / 2; a backend adapter must establish its actual convention. Local footprints must fit their declared level-0 images. Physical checks use D_target @ H[:2,:2] @ inverse(D_source), using both xy calibrations. Missing calibration makes physical checks not evaluated.

Rotation is from polar decomposition A = R S. Positive rotation is clockwise on the displayed y-down image. Principal scales are singular values; the shear diagnostic is abs(S[0,1]) / sqrt(S[0,0] * S[1,1]). Reflections are flagged and have no proper-rotation angle. Transforms are never clamped. The numerical envelope rejects singular values below 1e-12, coefficients above 1e12, and condition numbers above 1e12.

Independent, asymmetric correspondences test direction, axis order, anisotropic pyramids, crop offsets and pixel-center resampling. A wrong invertible transform can pass a forward/inverse round trip; that is not sufficient evidence. The fixture has three authored landmarks and no fitted transform or tissue samples.

Scope and resource limits

Input JSON: at most 1 MB. Each image: at most 20 MB and 4096 × 4096 pixels, single-frame PNG or JPEG, with an exact hash and declared dimensions. Image files must be beside the manifest; path traversal and symlinks are rejected. Preview panels are limited to 512 pixels per side. The synthetic source pair is 512 × 512. These are bounded raster copies, not whole-slide loaders. Pillow resampling receives the inverse mapping with the appropriate half-pixel basis changes. File type and size are checked on the opened descriptor, and the read itself is bounded. Named pipes and other non-regular files are rejected without reading.

Reports escape labels, contain only embedded raster images and inline CSS, and have a restrictive content-security policy. They do not embed absolute input paths or load remote resources. They show slide content supplied by the caller; do not share a report containing unauthorized content.

The report fingerprint binds the manifest, declared image hashes, policy, tool version and schema. The separate annotation review fingerprint also binds exact input JSON bytes, packaged Python source hashes, ROI/decision schemas and geometry engine versions. Decisions prevent accidental stale export; they are not authentication or a tamper-proof audit. Clinical accuracy, researcher utility and population performance have not been evaluated. A clean second venv is environment reproduction on the same host.

Next research gate

The VALIS request asks for optimizer constraints. This prototype only reviews a proposed output. Researcher acceptance of that distinction, an authorized pair, an agreed transform/ROI contract and a measurable task must precede expansion. VALIS integration is a separate pinned environment and remains NOT RUN. The new local decision/export commands support only the documented synthetic pixel ROI profile. Researcher/QuPath acceptance and external viewer re-import remain NOT RUN. No pickle loading, viewer platform, GPU dependency, or clinical deployment is provided.

Geometry and image-library references: NumPy SVD, Pillow affine transform, Pillow coordinates.

Original code and synthetic shapes use Apache-2.0. Third-party dependencies retain their own licenses; their exact tested versions are recorded in requirements.lock.