orisys-app/apps/autocal/docs/sequence-format.md

# Calibration sequence format (`.oryseq`)

A calibration sequence is a small JSON document: the **profile** that generated
the points, plus the **points** themselves. It is written by
`导出序列…` in the Sequence tab and read by `导入序列…`.

The Finger simulation page separately exports an operator CSV list with centred
UV pixels, sensor/platform millimetres and mapping identity. It uses the
[manual calibration coordinate convention](calibration-data-format.zh.md);
that list is not an `.oryseq` and is not imported into the acquisition page.

Why JSON and not a binary container: a sequence is at most a few hundred points
of text. It is read by a human, diffed in review, and emailed to whoever runs the
bench. Binary would buy nothing and cost all three. (The *acquired data* of a run
is a different problem — per-point time series are large and will need a sidecar;
that decision belongs to workflow P8, not here.)

## Conventions

The format follows this repository's existing documents rather than inventing a
convention. Where it matches `session.json` and `force_calibration.json`, that is
deliberate:

| Convention | Value |
|---|---|
| Version field | `"format_version": "1.0"` — a dotted **string**, compared as a tuple |
| Identity | `"kind": "autocal.sequence"` — checked on import |
| Extension | `.oryseq` by convention; import accepts any `.json` |
| Encoding | UTF-8, `indent=2`, `ensure_ascii=False`, trailing newline |
| Write | temp file then `Path.replace` — a half-written sequence that still parses looks like a design |

## The document

```json
{
  "format_version": "1.0",
  "kind": "autocal.sequence",
  "created_at": "2026-09-20T10:31:00+00:00",
  "name": "5 点灵敏度扫描",
  "note": "",
  "versions": { "app": "0.1.0", "shared": "0.1.0", "shared_api": "0.1" },
  "device": {
    "sensor_type": "box",
    "config_ref": "…\\config\\sensors\\box\\sensor.json",
    "geometry_id": "finger-1.0.0",
    "probe_tip_set": true
  },
  "frame": { "targets": "platform", "length_unit": "mm", "units_per_mm": 10.0 },
  "profile": {
    "mode": "flat", "pitch_mm": 2.0, "margin_mm": 1.0, "radius_mm": 0.0,
    "clear_height_mm": 5.0, "approach_speed_mm_s": 2.0, "press_speed_mm_s": 0.5,
    "press_depth_mm": 0.2, "dwell_s": 0.5, "settle_window_s": 0.5,
    "repeats": 3, "order": "serpentine"
  },
  "points": [
    {
      "id": 1,
      "target_mm": { "x": 0.0, "y": 0.0, "z": 12.4 },
      "sensor_mm": { "x": 0.0, "y": 0.0, "z": 0.0 },
      "clearance_mm": 5.0,
      "enabled": true,
      "note": ""
    }
  ],
  "summary": {
    "count": 12, "enabled": 12,
    "min_mm": { "x": 0.0, "y": 0.0, "z": 12.4 },
    "max_mm": { "x": 10.0, "y": 4.0, "z": 12.4 },
    "span_mm": { "x": 10.0, "y": 4.0, "z": 0.0 },
    "pitch_mm": 2.0,
    "estimated_duration_s": 380.0
  }
}
```

## Fields

### `frame` — required

| Field | Meaning |
|---|---|
| `targets` | the frame `target_mm` is expressed in; today always `"platform"` |
| `length_unit` | `"mm"`; anything else is refused |
| `units_per_mm` | the pulse equivalent the points were built with |

A sequence whose numbers do not say whether they are millimetres or user units is
a sequence that will eventually be read wrong. `units_per_mm` is recorded so a
file from a differently-configured axis is detectable rather than silently
believed.

### `profile` — required

The twelve fields the Sequence tab edits, and nothing else. A field absent from
the file is **kept at its current value and reported**, never silently defaulted
to another bench's number.

### `points` — required, may be empty

| Field | Meaning |
|---|---|
| `id` | 1-based, stable within the file; used for run progress and resume |
| `target_mm` | where the axes go — required, with all three of `x`, `y`, `z` |
| `sensor_mm` | where that point lands on the sensor; optional but written |
| `uv_px` | `{u, v}`: the point's place on the flat map, in pixels from the map origin; optional (added without a version change, older files simply lack it). The capture page takes its points by U/V, so a point with `uv_px` can be sent there directly |
| `clearance_mm` | the standoff for this point |
| `enabled` | false = designed but deliberately skipped |
| `note` | free text |

Both positions are stored on purpose. The platform target is what the run uses;
the sensor position is what makes the point checkable against the surface.
Deriving one from the other on every load would silently change what the points
mean the moment a sensor is re-fixtured — and a re-fixture is exactly when a
stored transform should be *noticed*, not recomputed from.

### `summary` — derived, not authoritative

Present so a human reading the file sees the point count and travel span without
counting rows, and so a diff is legible. It is **recomputed on load**; a mismatch
is reported as a warning and the recomputed values win. That is how a hand-edited
document announces itself instead of quietly disagreeing with its own contents.

`estimated_duration_s` assumes a constant traverse rate
(`sequence_io.ASSUMED_TRAVERSE_MM_S`) and ignores acceleration. It is a planning
figure and is labelled an estimate wherever it is shown.

### `device` — a reference, not a requirement

Records which sensor the sequence was designed for. Importing a sequence for
another sensor is **allowed and warned about**, because re-fixturing
deliberately is a normal thing to do.

## Import rules

Every rejection names the specific problem — `invalid file` tells an operator
nothing.

| Condition | Behaviour |
|---|---|
| not JSON | refused, with line and column |
| top level not an object | refused |
| `kind` missing or different | refused, naming what was found |
| `format_version` missing or not a string | refused |
| `format_version` newer than this build | refused, naming both versions |
| `frame` missing, or `length_unit` not `mm` | refused |
| `profile` not an object | refused |
| a profile key absent | imported; the current value is kept and the key is reported |
| `points` absent | imported as profile-only, and reported |
| a point without `target_mm.x/y/z` | refused, naming the point and the axis |
| `summary` disagreeing with `points` | imported; recomputed, and reported |
| current design is unsaved | the operator is asked before it is replaced |

Version strings are compared as tuples, never as strings: `"1.10"` is newer than
`"1.9"`, and a string comparison would make a newer file look older and load it
as if it were supported.

## Compatibility rules

- **Adding an optional key** does not change `format_version`.
- **Adding a required key, or changing a field's meaning or unit**, does.
- A reader must refuse a document whose version it does not support rather than
  interpreting the parts it recognises — a sequence half-applied is worse than
  one rejected.
- `1.x` readers are expected to accept `1.y` for `y <= x` on the same major
  version and report anything they did not use.

## Where the pieces live

| Concern | Module |
|---|---|
| The document, validation, the derived summary | `apps/autocal/src/orisys_autocal/sequence_io.py` |
| The design screen and its controls | `apps/autocal/src/orisys_autocal/ui/sequence_panel.py` |
| The file dialogs and the unsaved-work guard | `apps/autocal/src/orisys_autocal/ui/window.py` |
| Why a sequence is an artifact (P8) | `apps/autocal/docs/workflow.md` |