Repository files navigation

CoolerSpace is a Python library that provides type checking for programs that manipulate colors.

WARNING: This library is currently not ready for production use. For research purposes, please double check the requirements at pyproject.toml and requirements.txt.

CoolerSpace isavailable 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.gitcd CoolerSpacepython3 -m venv venvsource venv/bin/activatepip install -r requirements.txtpip install buildpython3 -m build

After running these commands, install the generated wheel file. It should be located in thedist/ folder.

Please referhere for examples of CoolerSpace programs.

Please note that the code below assumes that you have importedcoolerspace 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 iscs.XYZ.Valid types are enumerated in thespaces.py file of coolerspace.Please refer to our paper for an exhaustive list.

Besides usingcs.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 thecs.XYZ type to a value of thecs.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 thecs.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, foundhere.We also have a benchmarking suite for CoolerSpace, foundhere.The benchmarking suite was used to gather the data found in the paper.