Contributing

Defects

You encountered a problem while using Colour, please consider reporting it on the Issue Tracker.

The first thing to do, is to check if there are any existing issues describing your problem, if there is one, you are welcome commenting into it and provide more details. However, please avoid creating duplicates, they add noise to the issue tracker and we will have to label them as Duplicate and close them.

When reporting a defect please provide the output of the following command if possible, and if it makes sense to do so:

python -c "import colour;colour.utilities.describe_environment()"

The typical output is something along those lines:

===============================================================================
*                                                                             *
*   Interpreter :                                                             *
*       python : 3.11.6 (main, Oct  2 2023, 20:46:14) [Clang 14.0.3           *
*   (clang-1403.0.22.14.1)]                                                   *
*                                                                             *
*   colour-science.org :                                                      *
*       colour : v0.4.3-61-gbfc42ac2e                                         *
*                                                                             *
*   Runtime :                                                                 *
*       imageio : 2.31.5                                                      *
*       matplotlib : 3.8.0                                                    *
*       networkx : 2.8.8                                                      *
*       numpy : 1.26.1                                                        *
*       pandas : 1.5.3                                                        *
*       pygraphviz : 1.11                                                     *
*       PyOpenColorIO : 2.3.0                                                 *
*       scipy : 1.11.3                                                        *
*       tqdm : 4.66.1                                                         *
*       trimesh : 3.23.5                                                      *
*       xxhash : 3.4.1                                                        *
*                                                                             *
===============================================================================

If you are reporting an exception, please provide the complete traceback, it will help us understand what happened.

Features & Enhancements

If you would like a new feature to be supported or an enhancement of an existing feature, don't hesitate to link any resources or references you feel like would help its implementation: publications, wikipedia article, etc...

If there is an implementation existing in another language, we will be most likely be able to port it although the licence must be compatible with the BSD-3-Clause terms.

We are also running Matlab, so don't hesitate to provide snippets for it if you have functions you would like to be ported.

Development for Colour

Here is a succinct overview of the steps you will most likely go through:

git clone git@github.com:$USER/colour.git

cd colour

uv sync --all-extras

uv run pre-commit install

git remote add upstream git@github.com:colour-science/colour

git remote -v
origin  https://github.com/$USER/colour (fetch)
origin  https://github.com/$USER/colour (push)
upstream  https://github.com/colour-science/colour (fetch)
upstream  https://github.com/colour-science/colour (push)

git checkout develop
git pull upstream develop

git checkout -b feature/mie_scattering

uv run invoke tests

source .venv/bin/activate
invoke tests

uv run invoke quality

git add mie_scattering.py
git commit -m 'Implement "Mie Scattering" support.'

git push origin feature/mie_scattering

Overview

We follow the Google Python Style Guide and especially the Python Language Rules although with the main exception being the docstrings / documentation formatted with Numpy Docstrings Style.

We use type hints to statically indicate and verify the type of objects in the codebase with mypy.

The code has to be PEP 8 compliant although but before anything else, it needs to be consistent with the Colour Science literature:

For example, the base CIE colourspace is CIE XYZ with upper case notation. It can be converted to chromaticity coordinates xy with lower case notation. If we were to fully abide by the PEP 8 recommendations, we would have written a conversion definition as follows:

def xyz_to_xy(xyz: ArrayLike) -> Tuple:
    x, y, z = np.ravel(xyz)
    x, y = x / (x + y + z), y / (x + y + z)

    return x, y

Abstracting the fact that the above definition is totally undocumented, it can be confusing to understand when we are referencing big X tristimulus value or little x chromaticity coordinate.

For those cases, and there are legions of them in Colour Science, we have decided to go for clarity and consistency with the literature for the object names:

def XYZ_to_xy(XYZ: ArrayLike) -> Tuple:
    X, Y, Z = np.ravel(XYZ)
    x, y = X / (X + Y + Z), Y / (X + Y + Z)

    return x, y

When the reference is using upper case named variables, we try to follow the same convention, it is unfortunately not PEP 8 compliant but has the benefit of a much easier comparison between the implementation and the reference.

We suggest that contributors follow the same rule.

Python Language Rules

• All the code must be annotated with type hints.

• All the code must be covered by unit tests and doctests.

• All the code must be documented to the same standard than NumPy, SciPy and scikit-image.

• All the code must be checked with the pre-commit hooks.

• Pull requests should not be merged without being reviewed and ensuring that the Github Actions continuous integration suite succeeded.

• Examples should be provided for new features.

Python Style Rules

• Ensure consistency with Colour Science literature first.

• Ensure PEP 8 compliance.

• Try using a close to LaTeX syntax for variables names so that they are easier to compare to the reference.

  For instance, a variable defined $$D_{uv}$$ in a paper would be defined as D_uv in the code, $$L^*$$ as Lstar and $$X_{ab}^{\prime}$$ as Xp_ab.

• Try using uppercase for author names in definitions:

def CCT_to_xy_Kang2002(CCT): ...

• Please use British English words instead of American English ones as the CIE does, the most important of all being colour instead of color. You can consult the CIE Termlist if any doubts.

• Import NumPy as follows:

import numpy as np

• Doctests may need ellipsis, don't rely on global nose settings and specify it using the dedicated pragma as follows:

Lab = np.array([100.00000000, -7.41787844, -15.85742105])
Lab_to_LCHab(Lab)  # doctest: +ELLIPSIS

array([ 100.        ,   17.5066479...,  244.9304684...])

• Numbers in the API are usually rounded as follows:

  • Dataset numbers are kept as is if they are from a known reference or rounded to 15 digits if computed with the API (spectral distributions, chromaticity coordinates, etc...).

  • Unit tests and doctests input numbers are kept as is if they are from a reference or rounded to 8 digits if computed with the API.

  • Unit tests output numbers are rounded to 8 digits.

  • Doctests output numbers trimmed with ellipsis to 7 digits.

• We recommend a set of values for use with examples and unit tests. A Gist is available with the generating code.

  Priority should be given for CIE Standard Illuminant D Series D65 computed values:

Recommended Values for Use in Colour Examples and Unit Tests

Illuminants "xy"

D65 : array([0.31270000, 0.32900000])
D50 : array([0.34570000, 0.35850000])
A : array([0.44757000, 0.40745000])
E : array([0.33333333, 0.33333333])
F2 : array([0.37208000, 0.37529000])
CC I : array([0.34570000, 0.35850000])


Illuminants "XYZ"

D65 : array([0.95045593, 1.00000000, 1.08905775])
D50 : array([0.96429568, 1.00000000, 0.82510460])
A : array([1.09846607, 1.00000000, 0.35582280])
F2 : array([0.99144661, 1.00000000, 0.67315942])
E : array([1.00000000, 1.00000000, 1.00000000])
CC I : array([0.96429568, 1.00000000, 0.82510460])


ColorChecker 2005 "XYZ" Adapted to "D65"

red : array([0.20654008, 0.12197225, 0.05136952])
green : array([0.14222010, 0.23042768, 0.10495772])
blue : array([0.07818780, 0.06157201, 0.28099326])
cyan : array([0.14525849, 0.19799077, 0.40724370])
yellow : array([0.55676530, 0.58671628, 0.09785344])
magenta : array([0.30795495, 0.20024152, 0.31071274])
neutral 5 (.70 D) : array([0.18182171, 0.19153665, 0.21009620])


ColorChecker 2005 "XYZ" Adapted to "D50"

red : array([0.21638819, 0.12570000, 0.03847493])
green : array([0.14985004, 0.23180000, 0.07900179])
blue : array([0.06857861, 0.05750000, 0.21375591])
cyan : array([0.13605127, 0.19300000, 0.30938736])
yellow : array([0.59342537, 0.59810000, 0.07188823])
magenta : array([0.31084193, 0.20090000, 0.23565391])
neutral 5 (.70 D) : array([0.18438363, 0.19150000, 0.15918203])


ColorChecker 2005 "XYZ" Adapted to "A"

red : array([0.25330530, 0.13765139, 0.01543307])
green : array([0.18673833, 0.23111171, 0.03285972])
blue : array([0.05610693, 0.04992541, 0.09429057])
cyan : array([0.13623492, 0.18062024, 0.13553082])
yellow : array([0.73088905, 0.62177441, 0.02548927])
magenta : array([0.34280970, 0.20770559, 0.10214220])
neutral 5 (.70 D) : array([0.20988974, 0.19141324, 0.06866269])


ColorChecker 2005 "XYZ" Adapted to "E"

red : array([0.21781186, 0.12541048, 0.04697113])
green : array([0.15434689, 0.22960951, 0.09620221])
blue : array([0.07683480, 0.06006092, 0.25833845])
cyan : array([0.14893167, 0.19487065, 0.37427698])
yellow : array([0.59874058, 0.59196415, 0.08899633])
magenta : array([0.31991986, 0.20277158, 0.28536138])
neutral 5 (.70 D) : array([0.19126715, 0.19151544, 0.19291812])


ColorChecker 2005 "XYZ" Adapted to "F2"

red : array([0.22545552, 0.12877805, 0.03103172])
green : array([0.15832594, 0.23204226, 0.06406107])
blue : array([0.06385467, 0.05509729, 0.17506386])
cyan : array([0.13364947, 0.18951306, 0.25307753])
yellow : array([0.62718558, 0.60525456, 0.05690008])
magenta : array([0.31720246, 0.20226568, 0.19243480])
neutral 5 (.70 D) : array([0.18952683, 0.19147512, 0.12987334])


Luminance "XYZ" Adapted to "D65"

red : 12.19722535
green : 23.04276781
blue : 6.15720079
cyan : 19.79907683
yellow : 58.67162787
magenta : 20.02415243
neutral 5 (.70 D) : 19.15366501


Luminance "XYZ" Adapted to "D50"

red : 12.57000000
green : 23.18000000
blue : 5.75000000
cyan : 19.30000000
yellow : 59.81000000
magenta : 20.09000000
neutral 5 (.70 D) : 19.15000000


Luminance "XYZ" Adapted to "A"

red : 13.76513858
green : 23.11117127
blue : 4.99254109
cyan : 18.06202404
yellow : 62.17744084
magenta : 20.77055938
neutral 5 (.70 D) : 19.14132354


Luminance "XYZ" Adapted to "E"

red : 12.54104823
green : 22.96095053
blue : 6.00609174
cyan : 19.48706483
yellow : 59.19641488
magenta : 20.27715822
neutral 5 (.70 D) : 19.15154358


Luminance "XYZ" Adapted to "F2"

red : 12.87780528
green : 23.20422641
blue : 5.50972884
cyan : 18.95130571
yellow : 60.52545632
magenta : 20.22656850
neutral 5 (.70 D) : 19.14751195


ColorChecker 2005 "sRGB - Linear" under "D65"

red : array([0.45620519, 0.03081071, 0.04091952])
green : array([0.05433312, 0.29879493, 0.07185472])
blue : array([0.01862364, 0.05140184, 0.28880425])
cyan : array([-0.03667845, 0.24755074, 0.39815738])
yellow : array([0.85356364, 0.56517342, 0.01475279])
magenta : array([0.53522616, 0.09013008, 0.30472718])
neutral 5 (.70 D) : array([0.19002735, 0.19183638, 0.19312568])


ColorChecker 2005 "sRGB - OETF" under "D65"

red : array([0.70573936, 0.19248268, 0.22354168])
green : array([0.25847007, 0.58276101, 0.29718877])
blue : array([0.14565317, 0.25130933, 0.57378757])
cyan : array([-0.47388561, 0.53467479, 0.66380090])
yellow : array([0.93264474, 0.77675390, 0.12708884])
magenta : array([0.75809823, 0.33206288, 0.58800664])
neutral 5 (.70 D) : array([0.47315229, 0.47524148, 0.47672343])


ColorChecker 2005 "Munsell Value"

red : 4.08244375
green : 5.39132685
blue : 2.97619312
cyan : 5.06675596
yellow : 8.04387670
magenta : 5.10225899
neutral 5 (.70 D) : 4.98656896


ColorChecker 2005 "ASTM D1535-08e1 Luminance"

red : 12.23634268
green : 22.89399987
blue : 6.29022535
cyan : 19.86282567
yellow : 58.37987916
magenta : 20.18160934
neutral 5 (.70 D) : 19.15426585

• Some commonly used dataset elements have aliases like 'cie_2_1931' for 'CIE 1931 2 Degree Standard Observer'. Those are provided for convenience and are reserved for external usage, please use the long form for consistency across the API.

• In the same way as above, some computation methods are using a title case like 'Ohno 2013', while the mapping object holding them is case insensitive, please use the title case form for consistency across the API.

• Some very big lines sometimes cannot be wrapped (doctests, html links), you can use the # noqa pragma in those cases, although do it in last resort, we have already too much of them.

• Avoid / to wrap lines, prefer using the parenthesis ().

• The code formatting is performed using ruff via a pre-commit hook.

• Inline comments must have two spaces.

• Ensure that you have blank line at the end of the files.

• Ensure that trailing whitespaces are stripped.

• Prefix unused variable with an underscore:

_L, a, b = tsplit(Lab)

Citations

It's likely that the code you contribute will be based upon references, we are using a slightly modified APA 7th Edition citation style available for download and generating citations as follows:

Davis, W., & Ohno, Y. (2010). Color quality scale. Optical Engineering, 49(3), 033602. doi:10.1117/1.3360335

Wyszecki, G., & Stiles, W. S. (2000). Table I(6.5.3) Whiteness Formulae (Whiteness Measure Denoted by W). In Color Science: Concepts and Methods, Quantitative Data and Formulae (pp. 837–839). Wiley. ISBN:978-0-471-39918-6

Lindbloom, B. (2014). RGB Working Space Information. Retrieved April 11, 2014, from http://www.brucelindbloom.com/WorkingSpaceInfo.html

We are storing all our citations in a database maintained by Zotero and it is recommended that you are given a citation key by us.

Commits

A good committing strategy implies that separated commits should be done for any particular changes: One should not commit multiple bugs fixes or large change sets at once.

This unnecessarily increase complexity for any code merge or rollbacks needs and prevent a grainier control over the version control. One exception to this rule is for the initial design steps when creating a new sub-package or feature (please consider squashing the commits), but once the said sub-package is in production, a regular committing strategy should be applied.

Commit messages need to use imperative syntax, the first commit line must be a quick description of the modification content finished by a punctuation mark and can be followed by a detailed description separated by one line break. If the commit fixes a particular issue in the issue tracker, it's advised to state it in the commit message using the following syntax: Closes #32.

Yes:

Implement "Yoshi Ohno" correlated colour temperature calculation.

This implementation allows for a more precise correlated colour temperature
calculation by using a two solutions hybrid approach.

Closes #32.

No:

Coded new cool cct method

Feature Branches & History

History should never be re-written, although while working on your local feature branch, you may want to provide a cleaner commits history before submitting a pull request. It is perfectly fine to modify your local branch as you wish.

However, if you need to change history on a public and used feature branch, please inform the Colour Developers in order to avoid commit losses or a merging disaster.