OpenQualia Measurement File Standard
6min
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 compatible (“CGATS compatible”) with the below additional requirements.
Some compliant and non-compliant examples can be found here. Questions or concerns about these examples should be emailed to Doug Peterson.
- 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.
- There shall be a single DESCRIPTOR keyword containing the full name of the target, using the canonical Target Name List.
- 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.
- 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.
- 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.
- 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.
Updated 22 Oct 2024
Did this page help you?