In this set of notes we describe how to create custom calibrations for the Open Colorimeter using the command line program oc-cal. This program is part of the open-colorimeter-utils package which is available on PyPi (The Python Package Index). To use oc-cal you will need a working version of Python and we suggest using a version of Python >= 3.10.5.
You can install the open-colorimeter-utils package using the Package Installer for Python "pip". The basic installation command is as follows
pip install open-colorimeter-utils
Note, as with any python package, we recommend installing using into Python virtual environment when possible. For a brief introduction to Python virtual environments see the following.
Once you have the open-colorimeter-utils package installed you will be able to run the oc-cal program. To get help run
This should display the following information describing how to use the program
Usage: oc-cal [OPTIONS] [INPUT_FILES]... Generates an Open Colorimeter calibration .json file from the .toml input files .toml file format ----------------- name = "TestName" # Name of the test led = 630 # Led wavelength units = "ppm" # Measurement units fit_type = "polynomial" # Fit type, polynomial or linear fit_order = 2 # Order of the fit values = [ # Array of measurements [c0, c1, .... , cn], # Measurements in units [a1, a1, .... , an] # Corresponding absorbances ] Options: -o, --output-file FILENAME output file --help Show this message and exit.
To use oc-cal you simply pass it a list of .toml files containing your calibration data. The oc-cal program will then generate a calibration.json file which you can download to your colorimeter.
For example, suppose you have created two files called "caldata1.toml" and "caldata2.toml" containing calibration from two sets of measurements. Then to generate a calibrations.json file for you Open Colorimeter you would run
oc-cal caldata1.toml caldata2.toml
The calibrations.json file will be created in your current directory. To specify another location or a different name you can use the -o option
oc-cal -o some_other_name.json caldata1.toml caldata2.toml
In addition, when run, the oc-cal program will generate a plot showing the fit for set of measurements.
Calibration .toml files
The calibration data used by oc-cal is specified in files using the toml format - which stands for Tom's Obvious minimal langauge. The toml format is very simple and is a commonly used configuration file format. Further documentation of toml can be found here.
An example of the format of the .toml calibrations used by oc-cal is shown below.
name = "Ammonia API" led = 630 units = "ppm" fit_type = "polynomial" fit_order = 2 values = [ [0.00, 1.60, 3.20, 4.80, 6.40, 8.00], # concentration [0.00, 0.55, 1.10, 1.53, 1.87, 2.00] # absorbance ]
There are six key/value pairs in the calibration file
- name: a string specifying the name of the test
- led: an integer specifying the led wavelength used in nm
- units: a string specifying the units of the measurement, e.g. ppm.
- fit_type: the fit type for the calibration, either "linear" or "polynomial"
- fit_order: the order of the polynomial fit, must =1 for linear
- values: array of data values for measurement and corresponding absorbance
The source code for oc-cal can be found in the open-colorimeter-utils repository on github here.