# Calibration

> [!note] このページはまだ翻訳されておらず、英語で表示されています。


The Aesthetix is calibrated via the generic [calibration endpoints](rhopoint-elements-hub-endpoints-functionality-calibrations.md) — `GET/POST /v1/devices/{deviceId}/calibrations` and `GET /calibrations/status`. This page covers the Aesthetix-specific calibration types, what physical target each one needs, and the recommended order.

### Available Calibration Types

| `calibrationKey` | Title | Physical target | Parameters |
| --- | --- | --- | --- |
| `white` | White Calibration | White calibration standard | `reflectance` (0–1), `visualContrast` (0–1) |
| `black` | Black Calibration | Black calibration standard | `gloss` (GU) |
| `height` | Height Calibration | Texture standard | `height` (µm) |

Every calibration is valid for **two days** (recommended interval) and goes overdue after **seven days**. The hub tracks the timestamps per device serial number — see [`GET /calibrations/status`](rhopoint-elements-hub-endpoints-functionality-calibrations.md#getting-the-calibration-status).

> [!note]
> The Aesthetix Inline variant only exposes `black`. The `white` and `height` calibrations are not available there.

### Recommended Order

Run the calibrations in this sequence the first time a device is calibrated, after a long idle period, or whenever the status endpoint reports `NotCalibrated` / `CalibrationOverdue`:

1. **Black** — establishes the optical zero for the specular and aspecular paths.
2. **White** — references the reflectance and visual-contrast scales against the white standard.
3. **Height** — references the height scale against the texture standard.

White and height depend on a valid black calibration; running them first against an outdated black reference yields wrong scaling. The hub does not enforce this order, so the integrator's UI or workflow must.

### White Calibration

Used to reference reflectance and visual-contrast measurements against the white calibration standard supplied with the instrument.

```http
POST /v1/devices/{deviceId}/calibrations
Content-Type: application/json

{
  "calibrationKey": "white",
  "parameters": [
    { "key": "reflectance",    "value": 0.95 },
    { "key": "visualContrast", "value": 0.92 }
  ]
}
```

| Parameter | Unit | Notes |
| --- | --- | --- |
| `reflectance` | Fraction (`0.95` ≙ 95 %) | The reflectance value printed on the white standard. |
| `visualContrast` | Fraction (`0.92` ≙ 92 %) | The visual-contrast value printed on the white standard. |

**Before sending the request:** place the white standard over the measurement window with the white surface facing the optics. Hold the instrument steady — the device captures multiple frames during calibration.

### Black Calibration

Establishes the optical zero. The Aesthetix performs both **specular** and **aspecular** black calibration in a single request; the Aesthetix Inline only performs specular.

```http
POST /v1/devices/{deviceId}/calibrations
Content-Type: application/json

{
  "calibrationKey": "black",
  "parameters": [
    { "key": "gloss", "value": 0.5 }
  ]
}
```

| Parameter | Unit | Notes |
| --- | --- | --- |
| `gloss` | GU (Gloss Units) | The gloss value printed on the black standard. |

**Before sending the request:** place the black standard over the measurement window with the black surface facing the optics.

### Height Calibration

References the height (texture) scale against the texture standard.

```http
POST /v1/devices/{deviceId}/calibrations
Content-Type: application/json

{
  "calibrationKey": "height",
  "parameters": [
    { "key": "height", "value": 50.0 }
  ]
}
```

| Parameter | Unit | Notes |
| --- | --- | --- |
| `height` | µm | The reference height of the texture standard, in micrometres. |

**Before sending the request:** place the texture standard over the measurement window. Ensure it sits flat and centered.

### Verifying the Result

After the call returns successfully, query the status to confirm the new timestamp:

```http
GET /v1/devices/{deviceId}/calibrations/status
```

A freshly executed calibration moves to `CalibrationValid` and its `lastCalibrationTime` matches the request time (within network skew). If the status remains `NotCalibrated` after a successful response, the calibration parameter values were likely ignored — re-check the `key` names against `GET /v1/devices/{deviceId}/calibrations`.

### Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `E29 Calibration timeout` | The instrument disconnected during the calibration sequence. | Reconnect the device (re-scan + connect) and retry. |
| Calibration succeeds but downstream measurements are clearly wrong | Wrong physical target was on the window, or the target values printed on the standard were entered with the wrong scale (e.g. `95` instead of `0.95`). | Re-calibrate with the correct target and verify `reflectance`/`visualContrast` are passed as fractions, not percentages. |
| Status stays `NotCalibrated` after a 200 OK response | Parameter `key` was misspelled and ignored. | Read the accepted keys from `GET /v1/devices/{deviceId}/calibrations` and retry. |
| Calibration takes longer than the HTTP client timeout | Default client timeouts (often 5–10 s) are too short for calibration. | Raise the per-request timeout to at least 30 s. |

### Error Cases

| Condition | HTTP | Error Code |
| --- | --- | --- |
| Connected device not found | 404 | `E5` |
| Unknown `calibrationKey` | 404 | `E28` |
| Calibration timed out (likely hardware disconnect) | 502 | `E29` |

See [Error Handling](rhopoint-elements-hub-error-handling.md) for the full response format.