Declare every axis
Origin, x/y/z polarity, handedness, units, and laterality are required. An adapter that cannot determine them must stop instead of guessing.
Eye Surface Record v0.1
A scanner-neutral record contract for specialty lens workflow.
ESR defines how a surface export declares geometry, coordinate frame, quality, provenance, and privacy boundaries before Foveo or a partner adapter ever reviews a lens artifact.
Why It Exists
Most bad integrations fail quietly. ESR makes the assumptions explicit.
Carry the weak spots
Coverage, dropout, missing samples, noise, and transform history travel with the record so the reviewer sees what the file can and cannot support.
Make replay possible
Source metadata, canonical hashes, and transform logs let a clinic or lab compare the same record later without relying on memory.
Code Contract
The adapter returns a real record or refuses the file.
The current repo includes a Python adapter interface, ESR hashing and validation helpers, and a synthetic fixture adapter covered by ten conformance tests. No network call, patient field, or inferred coordinate frame is allowed during parse.
{
"esr_version": "0.1",
"geometry": { "units": "mm", "data": { "z_mm": [[...]] } },
"coordinate_frame": {
"origin": "corneal_apex",
"x_positive": "temporal",
"y_positive": "superior",
"z_positive": "anterior",
"handedness": "right"
},
"quality": { "coverage_fraction": 0.84 },
"provenance": { "transform_log": [{ "op": "RESAMPLE" }] },
"record_hash": "sha256..."
}
Conformance
Ten tests before an adapter is trusted.
Sniff and frame
Detect supported files and reject undetermined coordinate frames.
Units and hashes
Normalize to millimeters and produce stable canonical hashes across repeated parses.
Round trip and gaps
Validate replay hashes and report missing geometry without silent filling.
No PHI
Block patient identifiers, contact details, prescriptions, and real clinical metadata.
Transforms and refusal
Record each transform and fail closed on unsupported or corrupt exports.
No network parse
Adapters parse local files only; live API integrations need separate approval and controls.
Public Boundary
This is an interoperability surface, not a clinical claim.
ESR is intended for synthetic fixtures, written-permission test exports, public documentation, and formal partner conversations. It does not approve diagnosis, fitting, manufacturing, dispensing, regulatory use, or wearable lens fabrication.