OpenQualia Measurement File Standard

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 questions or concerns about these examples should be emailed to doug peterson 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