CoolerSpace is a Python library that provides type checking for programs that manipulate colors.
CoolerSpace is available on PyPI! You can install CoolerSpace with pip.
pip install coolerspace
Alternatively, if you wish to build CoolerSpace yourself, please use the following commands:
git clone https://github.com/horizon-research/CoolerSpace.git
cd CoolerSpace
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install build
python3 -m build
After running these commands, install the generated wheel file. It should be located in the dist/ folder.
Please refer here for examples of CoolerSpace programs.
Please note that the code below assumes that you have imported coolerspace as cs.
import coolerspace as cs
In order to specify a user input value, use the following syntax:
x = cs.create_input(input_variable_name,shape, type)
Here, input_variable_name is the name of the variable used when running the ONNX file.
shape is the shape of the input data. For example, a full HD picture would have the shape [1080, 1920].
type is the type of the input variable. An example of a valid type is cs.XYZ.
Valid types are enumerated in the spaces.py file of coolerspace.
Please refer to our paper for an exhaustive list.
Besides using cs.create_input, coolerspace objects can be created via the following constructor
cs.sRGB([0, 0, 0])
The above line of code creates an sRGB object. cs.sRGB can be substituted for other CoolerSpace types.
CoolerSpace objects can be cast between different types.
cs.sRGB(xyz)
The above line of code converts a value of the cs.XYZ type to a value of the cs.sRGB type.
Arithmetic operations can be performed on CoolerSpace objects. The list of valid arithmetic operations is detailed in our paper.
xyz1: cs.XYZ = ...
xyz2: cs.XYZ = ...
xyz3 = xyz1 * 0.5 + xyz2 * 0.5
Outputs can be created with the following syntax:
cs.create_output(cs_object)
cs_object is a CoolerSpace object you would like to output when running the ONNX program.
Use the cs.compile command to specify what path you would like to compile the ONNX file to:
cs.compile(path)
If you would like to cite CoolerSpace, please use the following:
@article{coolerspace,
title={CoolerSpace: A Language for Physically Correct and Computationally Efficient Color Programming},
author={Chen, Ethan and Chang, Jiwon and Zhu, Yuhao},
journal={Proceedings of the ACM on Programming Languages},
year={2024}
doi={10.1145/3689741}
}
CoolerSpace's output ONNX files can be optimized using equality saturation. Our optimization tool is stored in a separate GitHub repository, found here. We also have a benchmarking suite for CoolerSpace, found here. The benchmarking suite was used to gather the data found in the paper.