URL Format
OQ Labels must be a valid URL following the URL Standard. The URL must start with https:// rather than http:// and must contain the following query parameters:
- TargetID – the serial number of the target. If the target has an existing physical serial number (e.g. the DT NGT2 has a serial number written on the front bottom right of the target) then this serial number should be used for the TargetID. In the case the target does not natively have a serial number the user can make one up, but should use only letters, numbers, and dashes avoiding spaces or special characters.
- Manufacturer – The make of the target. That is the entity whose brand is marked most prominently on the target. For example, for a DT NGT2 the manufacturer is Digital Transitions or DT.
The label URL is meant to be user friendly in the case that it is scanned by a user using their smartphone. For programmatic use within a software workflow the label should be passed by the user with one additional parameter added:
- AccessMode – This parameter is NOT present in the label itself. It allows client software (e.g. image quality analysis software such as ImageZebra or DT Nexus) to directly receive a CGATS file rather than a user-friendly web page. The following values are possible
- =Interactive (default) – This is the default value, so if AccessMode is missing (as it is in the label itself) then the result will be a user-friendly website that provides at minimum: a brief explanation of OQ Labels, a link to download the most recent measurement file, and the “Measurement Freshness” of that measurement (see “Measurement Freshness” later in this document). This provides a better experience for someone who scans the code with their smartphone than being taken directly to a measurement file in a machine-readable format. Additional features of the interactive view are left to the host, but could include such things as an image of the target with values available via hover, a sample file that includes such a target, an overlay (PNG) with the measured values to use in software such as Capture One for visual QC. It is also acceptable for such pages to include commercial links to related software and hardware; for example, a link to purchase the same or similar targets, a link to purchase measurement service for the target, or software to analyze images containing such targets.
- =ActiveMeasurement – This is the value expected to be added by image quality software. It should result in a measurement file that comports with the “OpenQualia Compatible Measurement File Format” requirements (basically CGATS with certain typically-optional fields required).
- =AllMeasurementsZip (optional) – This allows software to automatically retrieve a zip file of all measurements, including older and current measurements. It is NOT required that a OpenQualia Measurement File Host implement this parameter value.
In URL encoding the first parameter name is preceded by ?, and additional parameters are separated using &. Below is an example of those parameters: ?Manufacturer=DT&TargetType=DTNGT2&TargetID=DT-AR-2020041
Additional parameters may be added (e.g. a proprietary field to allow a proprietary feature in a particular program, such as User or MeasurementGeometry). OpenQualia-compatible software should use all provided parameters in the URL used to download the measurement file, but is otherwise free to disregard the additional parameters.
For Manufacturer and TargetName a standardized short-form and long-form canonical names can be found here. OpenQualia targets must use these canonical names when encoding OQ Labels to avoid confusion where the label uses a slightly different name for the target than the software expects; for example ColorChecker SG rather than ColorChecker Digital SG.
Query Parameter Matching
Evaluation of the Manufacturer and TargetName values should be done in a case agnostic and whitespace agnostic manner. Either short-form or long-form are equally acceptable. For example, colorcheckerclassic, CCC, and ccc are all acceptable, as is ColorChecker Classic (which would be URL encoded as ColorChecker%20Classic). OpenQualia recommends encoding without whitespace and in TitleCase to maximize the readability of the resulting URL.
TargetType and Manufacturer Display
We recommend presenting the decoded values of these parameters using their Long Form canonical name. That is, OpenQualia suggests encoding ColorCheckerClassic but displaying ColorChecker Classic.
