Skip to content

WORKFLOW.md

Latest commit

 

History

History
124 lines (101 loc) · 7.1 KB

WORKFLOW.md

File metadata and controls

124 lines (101 loc) · 7.1 KB
Raw

Synthetic annotation decision and export workflow

Version 0.2.1.dev0 extends the original CPU report with one bounded pixel ROI format. The motivating researcher task, VALIS extraction, and an external viewer handoff are still unconfirmed. These commands exercise a local engineering protocol; an approve record is not researcher acceptance or authentication.

flowchart LR
  Inputs[Images, manifest and source ROIs] --> Review[Validate and review report]
  Review --> Decision{Explicit decision}
  Decision -->|Reject| Stop[Export blocked]
  Decision -->|Approve with acknowledgments| Export[Revalidate inputs and export]
  Export --> Verify[Read output and verify geometry and receipt]
  Changed[Any changed bound input or tool] --> Stop
Loading

Coordinate and geometry contract

annotations.schema.json defines sectioncheck-pixel-rois version 0.1.0. It uses a FeatureCollection-shaped JSON representation with explicit image ID, level-0 frame, x-right/y-down axes, pixel units, integer-center origin, and synthetic domain. Vertices may have fractional coordinates. The supported image extent is [-0.5, width-0.5] × [-0.5, height-0.5] in that basis.

The RFC GeoJSON specification uses geographic WGS84 coordinates, so this pixel profile is not advertised as RFC 7946 geographic data. RFC 7946 QuPath exports image ROIs in full-resolution pixel coordinates relative to the top-left origin. A future adapter must establish the precise basis conversion and supported properties and test them in QuPath; adding a .geojson suffix does not establish compatibility. QuPath annotation documentation

Supported shapes are two-dimensional Polygon and MultiPolygon, including holes. Rings must be explicitly closed. Empty/zero-area polygons, self-intersections, holes outside shells, invalid multipart topology, Z/M coordinates, curves, points, lines, unknown properties and duplicate IDs are rejected. Shapely/GEOS checks planar topology; no automatic geometry repair is performed. Shapely manual

Limits: 1 MB per JSON input and serialized annotation export, 100 features, 10,000 total vertices including ring closures, 4,097 vertices per ring, 32 rings per polygon and 32 polygons per multipart feature. Images retain the core 20 MB/4096×4096 limits. The transformation is H in level-0 coordinates; preview crop/downsample frames affect display only. Every mapped vertex must remain in the target image. Out-of-bounds geometry blocks approval/export and is never clipped. IDs, labels, part/ring order and original files are preserved.

Review and decide

After the README installation and fixture generation, run:

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

The report shows source, target, resampled source, overlay, source ROI boundaries, and proposed target ROI boundaries. review.json records checks, part/hole counts, bounds, areas, required acknowledgments and the review fingerprint. It contains no approval. Inspect both the image boundaries and the check explanations.

The source_roi_preview and target_roi_preview checks warn when any ROI is partly clipped or completely outside the supplied crop. The review record names the affected ROI IDs. A covering preview is needed to inspect the complete ROI against the image. These warnings require their own explicit acknowledgments; acknowledgment records that limitation and does not establish image inspection.

To record an explicit synthetic decision, replace the fingerprint, alias and reason below with the values for that review:

.venv/bin/sectioncheck decide examples/synthetic/manifest.json --annotations examples/synthetic/annotations.json --review-fingerprint REVIEW_FINGERPRINT_FROM_REPORT --decision approve --reviewer-alias YOUR_LOCAL_ALIAS --reason "Your decision and reasoning" --acknowledge physical_calibration --acknowledge source_footprint --out decision.json

Those two acknowledgments match the bundled translated example. Another input may have a different set. Approval requires every warning and not-evaluated check to be named exactly once. Hard errors cannot be overridden. --decision reject records a negative decision and needs no acknowledgments; it cannot authorize export. Both decisions require a nonblank alias/reason and a valid timezone-bearing timestamp, generated locally by the command.

Decisions bind exact manifest/annotation bytes, verified image hashes, transform and policy, core/ROI/decision schemas, the tool version and packaged Python source, and NumPy/Pillow/jsonschema/Shapely/GEOS versions. Even annotation reformatting invalidates a previous decision. Editing inputs after a report requires a new review and decision. A copied or edited local record is not trusted identity; this protects against accidental stale exports within the declared workflow. The 0.2.1 source and version changes invalidate 0.2.0 decisions. Generate and inspect a fresh report before recording another decision.

Export and verify

.venv/bin/sectioncheck export examples/synthetic/manifest.json --annotations examples/synthetic/annotations.json --decision-file decision.json --out roi-export
.venv/bin/sectioncheck verify-export examples/synthetic/manifest.json --annotations examples/synthetic/annotations.json --decision-file decision.json --export-dir roi-export

Export re-reads and validates all bound inputs before writing a new directory containing target-annotations.json and receipt.json. Existing destinations are rejected. Verification re-imports the output, checks topology and exact expected coordinates, and checks the decision/output hashes and receipt. It rejects stale inputs, altered outputs and changed decision records. Originals remain untouched; target coordinates are separate derived geometry.

The synthetic tests also compare against independently authored asymmetric coordinates, areas, hole and part counts using Shapely. They do not rely solely on a transform's own forward/inverse round trip. verify-export is local profile re-import, not a claim that QuPath or another researcher tool accepted the output.

Evidence and continuation

examples/exercise_synthetic_workflow.py runs review, explicit automated approve, export, verification, explicit reject, rejected export, stale-policy rejection and edited-output rejection in a new directory. It preserves input hashes and checks two authored ROIs, three polygon parts, one hole, and areas 2,700/3,775 pixels squared against independently written expected geometry. Its alias and reason explicitly identify automation. --require-wheel additionally checks that the imported package comes from site-packages.

Next researcher-dependent work is to agree the actual review task and ROI contract, implement a pinned VALIS adapter, and demonstrate export/re-import in the chosen tool on an authorized pair. No real-data result, user benefit, external-viewer compatibility or release readiness is inferred from this demo.