--- title: OpenQualia Measurement File Standard slug: oq/openqualia-measurement-file-standard docTags: createdAt: 2024-10-22T14:35:06.595Z --- Interoperability between OpenQualia implementations requires a standard file format for measurement files. The CGATS standard is widely used for spectral and colorimetric measurement. However, this standard is very loose and proper quality control requires more specificity. Therefore OpenQualia Measurement files should be fully [ANSI CGATS.17-2009](https://webstore.ansi.org/standards/npes/ansicgats172009?gad_source=1\&gclid=EAIaIQobChMIyrCOtO-KhwMVzEX_AR2FIQcFEAAYASAAEgL2AvD_BwE) compatible (“CGATS compatible”) with the below *additional* requirements. ### Examples Some compliant and non-compliant examples can be found [here](https://drive.google.com/drive/u/0/folders/1JSrKhvoL4l1QsJrSqMtx3wR7M8ekAU8g). Questions or concerns about these examples should be emailed to [Doug Peterson](mailto\:dep@digitaltransitions.com). ### Format - EITHER - The file identifier (First line of characters) shall be `OQM` and the file extension shall be `.oqm.txt` standing for OpenQuality Measurement. This is preferred as it clarifies the file is CGATS compatible but also meets the additional more specific  requirements for OpenQualia Measurements. The use of “.txt” in this extension ensures the file will default to be opened in a text editor. OR - The file identifier (First line of characters) shall be `CGATS.17` and the file extension shall be `.cgats.txt`. The use of “.txt” in this extension ensures the file will default to be opened in a text editor. - A `#` character introduces a comment line. ### General Header - There shall be a single `DESCRIPTOR` keyword containing the full name of the target, using the [canonical Target Name List](https://docs.google.com/spreadsheets/d/1-XqxR5RHKNiJvBEh7qFKvVhjc_3tgCO4fmb9v7ChbP0/edit?gid=0#gid=0). - There may be an `ORIGINATOR` keyword representing the individual or entity that performed the measurement. For example `Avian Rochester`. - There shall be a `CREATED` field. This refers to the date of the measurement of the target. It shall have an unambiguous date format, specifically ISO 8601:`YYYY-MM-DD`.  - There may be a CALIBRATION\_DATE field. This refers to the date of the most recent calibration of the measurement device (not the date of the measurement of the target). It shall have an unambiguous date format, specifically ISO 8601:`YYYY-MM-DD`. For example, if the i1 was sent to X-Rite for calibration on June 3, 2022 it would read `2022-06-03`. If no recalibration or recertification has been performed the date of purchase should be used; it is understood this is not ideal since the device may have been manufactured and calibrated well before purchase, but it is preferable compared to not providing a date. - There shall be a `SERIAL` keyword that references the specific target measured. - There may be a keyword `TARGET_INSTRUMENT` which will identify the instrument used to make the measurements.  - There may be a keyword `MEASUREMENT_SOURCE` with a string of key=value pairs, separated by a space. The value shall contain `Illumination=` followed by D50 or D65 or other illuminant. The value shall contain `ObserverAngle=` followed by either `2` or `10`. The value may contain other keys and values, here's an example: `MEASUREMENT_SOURCE "Illumination=D50 ObserverAngle=2 WhiteBase=Abs Density=Status E Filter=Undefined"` - If the file contains Lab or XYZ values, there shall be two keywords, `ILLUMINANT` and `OBSERVER`, containing the values that were assumed when converting the values from spectral distribution to the respective color space. Values should be strings for `ILLUMINANT` (i.e. `“D50”`) and numbers for `OBSERVER` (i.e. `2`). - If spectral values are included in the file, the following keywords and values  may be used:  - `SPECTRAL_BANDS` shall contain the number of spectral bands in the readings, e.g. `36`. - `SPECTRAL_START_NM` shall contain the wavelength in nanometers of the first band, e.g. `380.0`. - `SPECTRAL_END_NM` shall contain the wavelength in nanometers of the last band, e.g. `730.0`. - The `NUMBER_OF_FIELDS` keyword shall have a value that indicates the number of fields in each data set, e.g. `43`. This includes the number in `SPECTRAL_BANDS` plus additional fields such as `SAMPLE_ID`, `SAMPLE_NAME` or extra formats such as RGB, LAB or XYZ. - The start of the declaration of the fields shall be marked by the `BEGIN_DATA_FORMAT` keyword (as per CGATS). Then shall follow the names of the fields. Standard CGATS field names such as: `SAMPLE_ID`, `SAMPLE_NAME`, `RGB_R`, `RGB_G`, `RGB_B`, `XYZ_X`, `XYZ_Y`, `XYZ_Z`, `LAB_L`, `LAB_A`, `LAB_B` shall be used where appropriate. ### Target Layout (Measurement Order) - The physical patches on the target will be identified using the Field `SAMPLE_NAME` or `SAMPLE_ID`.  They may be identified using either a letter-number pair or a sequential numbering scheme as determined by the physical labels on the target. If both a letter-number pair and a number exist within the measurement file, the letter-number pair will take priority and any other sequential numbering will be ignored.  Below are the general rules for the use of letter-number pairs versus sequential numbering. - If the physical target has patch location identifiers using letters for columns and numbers for rows, or alternatively if each patch is labeled with a letter-number pair, then the field `SAMPLE_NAME` or `SAMPLE_ID` shall contain the location index of the measured value as marked on the physical target, in letter-number format, with or without a hyphen. Both `A1` and `A-1` are valid, the former is preferred.  Examples of this type of target are the Color Checker SG and the DT Next Generation Target v2. - If the physical target has patch labels with numbers only, the field `SAMPLE_ID` or `SAMPLE_NAME` shall contain the patch number as labeled on the target.  For Example, the Golden Thread Device and Object Level targets have patch number labels. - If the physical target has a rectangular matrix of patches without any labels, then a letter-number pair shall be assigned using the following rules.  (The orientation of the text on the target shall determine the orientation of the rows and columns.  If no text is present then the orientation shall be assumed to be landscape, with the long dimension in a horizontal direction.) - Columns are identified with the alphabetical label `A`, `B`, `C`, `D`…. etc - Rows are identified with numbers `1`, `2`, `3`…. This letter-number pair will be identified in the Field `SAMPLE_NAME` or `SAMPLE_ID`.  An example of this type of target is the Color Checker Classic - If the physical target has a linear array of patches without sequentially numbered labels, then a sequential numbering scheme can be used, where the order is either left to right or top to bottom, depending on the orientation of the target.  (The orientation of the text on the target shall determine the orientation of the rows and columns.  If no text is present then the orientation shall be assumed to be landscape, with the long dimension in a horizontal direction.)  The field `SAMPLE_ID` or `SAMPLE_NAME` shall contain the number as defined in the scheme above. Examples of this type of target are the Munsell Linear Gray Scale or the Kodak/Tiffen Grayscale Q-13 - If the patches on the target are not labeled and do not fit any of the above criteria, then the specific numbering scheme is defined in the section titled, Unique Target Measurement Order - Spectral band values shall be named `SPEC_XXX` or `nmXXX`, or `SPECTRAL_NMXXX`, where XXX is the nearest integer values of the number of nanometers of the band. - The definition of the fields shall be terminated by the `END_DATA_FORMAT` keyword. - The `NUMBER_OF_SETS` keyword shall have a value that indicates the number of sets of data, e.g. `100`. This should match the number of reference patches on the physical target. ### Patch Measurement Data - The start of the values of the data sets shall be marked by the `BEGIN_DATA` keyword. - Each set of data shall be on one line, and shall be separated by white space or tab. All device values shall be percentages (e.g. values from 0.0 to 100.0). XYZ values shall be normalized to a Y value of 100.0. L\*a\*b\* values will have their normal range (L\* 0.0 to 100.0, a\* and b\* typically -128.0 to 128.0). - The end of the values of the data sets shall be marked by the `END_DATA` keyword. ### Unique Target Measurement Order - For targets without any identification labels or do not have a matrix of patches, this section is reserved to show an illustration of the target with a numbering sequence that must be followed.