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

Calibration

The Aesthetix is calibrated via the generic calibration endpoints — 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`.

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:

Black — establishes the optical zero for the specular and aspecular paths.
White — references the reflectance and visual-contrast scales against the white standard.
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.

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.

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.

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:

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 for the full response format.