colourspace-explorer 1.5__tar.gz

colourspace_explorer-1.5/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Gilles Ferrand
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

colourspace_explorer-1.5/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.1
+Name: colourspace-explorer
+Version: 1.5
+Summary: A package providing tools for working with colours in python
+Author-email: Gilles Ferrand <astro.ferrand@gmail.com>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2025, Gilles Ferrand
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Homepage, https://github.com/gillesferrand/colourspace
+Keywords: colour,colour space,colour maps
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: scipy
+Requires-Dist: colorspacious
+Requires-Dist: colour-science
+
+This package provides some tools to work with colour in Python in a way that matches human perception. The adopted colour space is CIELCH, the cylindrical representation of CIELAB, with coordinates L = lightness in [0,100], C = chroma >= 0, H = hue angle in [0, 360].
+The package relies on [NumPy](https://numpy.org) for array manipulations, [Matplotlib](https://matplotlib.org) for plotting, and optionally other colour packages listed below.
+
+**convert** provides functions to convert a colour triplet between HCL and sRGB spaces, using either built-in [formulas](http://www.easyrgb.com/en/math.php) or wrappers to [colorspacious](https://pypi.python.org/pypi/colorspacious/) or [colour](http://colour-science.org) packages.
+
+**gamut** provides functions to compute and visualize the boundary Cmax(L,H) of the sRGB gamut and of the full human gamut. These boundaries can be obtained by two methods: (1) for each point in the LCH plane, convert the colour to the target space (RGB or XYZ) and check whether it falls within the gamut; (2) get the contour points of the gamut in the space where it is naturally defined (RGB or XYZ), and convert them back to LCH space. For the latter method, to resample the function Cmax(L,H) on a regular grid the script relies on [scipy.interpolate](https://docs.scipy.org/doc/scipy/reference/interpolate.html). Both methods assume knowledge of the gamut in some space, this is trivial for the sRGB gamut, not for the human gamut hence the limits script below.  
+The pre-computed gamuts at resolutions of 1 and 10 bins per unit L,H are included as Numpy binary files (30 MB).
+
+**limits** provides functions to compute and visualize the limits of the human gamut (optimal colour stimuli, a.k.a. MacAdam limits). As explained on [Bruce Lindbloom's website](http://www.brucelindbloom.com/index.html?LabGamutDisplayHelp.html) they are obtained by considering all possible step-functions as spectral distributions. The conversion from light spectrum to XYZ colour is made with [colour](http://colour-science.org) (the computed limits can be compared with the crude triangulation provided by this package). To triangulate the limit surface in 3D the script relies on [scipy.spatial](https://docs.scipy.org/doc/scipy/reference/spatial.html) (this is required by method 1 above).  
+The pre-computed limits at resolutions of 1, 5, 10, 20 nm are included as Numpy binary files (4.5 MB).
+
+**slices** provides functions to draw slices in the colour space: L-H planes as a function of C (or for the maximum possible C), C-H planes as a function of L, and L-C planes as a function of H.
+
+**maps** provides functions to generate colour maps for Matplotlib, and/or written as png images. Three kinds of cmaps are implemented, which separate the different perceptual dimensions: equi-luminant (varying only in H, at the max C), diverging (varying only in C between two hues H1 and H2), and mono-hue (varying only in L, at the maximum C). It includes utility functions for testing a cmap on mock data, and for displaying the path taken by a cmap in the colour space.
+
+The package comes with five notebooks, which demonstrate the use of the five scripts.  
+The notebook files can be copied in the current directory using function colourspace.copy_tutorials() found in script tutorials/copy_tutorials.py.
+Static renderings of the notebooks can also be seen [on nbviewer](https://nbviewer.org/github/gillesferrand/colourspace/tree/master/src/colourspace/tutorials/):  
+[1. Conversions between colour spaces](https://nbviewer.org/github/gillesferrand/colourspace/blob/master/src/colourspace/tutorials/1.%20convert.ipynb)  
+[2. Mapping the sRGB gamut](https://nbviewer.org/github/gillesferrand/colourspace/blob/master/src/colourspace/tutorials/2.%20sRGB%20gamut.ipynb)  
+[3. Mapping the human gamut](https://nbviewer.org/github/gillesferrand/colourspace/blob/master/src/colourspace/tutorials/3.%20full%20gamut.ipynb)  
+[4. Slicing the LCH space](https://nbviewer.org/github/gillesferrand/colourspace/blob/master/src/colourspace/tutorials/4.%20slices.ipynb)  
+[5. Making custom colour maps](https://nbviewer.org/github/gillesferrand/colourspace/blob/master/src/colourspace/tutorials/5.%20cmaps.ipynb)  
+Additional case study:
+[5.1 Helix colour scheme](https://nbviewer.org/github/gillesferrand/colourspace/blob/master/src/colourspace/tutorials/5.1%20cmaps%20helix.ipynb)
+
+---
+This package is provided "as is", with no warranty of any kind.  
+The code can be freely used by whoever wants to explore modern colour theory.

colourspace_explorer-1.5/README.md

@@ -0,0 +1,29 @@
+This package provides some tools to work with colour in Python in a way that matches human perception. The adopted colour space is CIELCH, the cylindrical representation of CIELAB, with coordinates L = lightness in [0,100], C = chroma >= 0, H = hue angle in [0, 360].
+The package relies on [NumPy](https://numpy.org) for array manipulations, [Matplotlib](https://matplotlib.org) for plotting, and optionally other colour packages listed below.
+
+**convert** provides functions to convert a colour triplet between HCL and sRGB spaces, using either built-in [formulas](http://www.easyrgb.com/en/math.php) or wrappers to [colorspacious](https://pypi.python.org/pypi/colorspacious/) or [colour](http://colour-science.org) packages.
+
+**gamut** provides functions to compute and visualize the boundary Cmax(L,H) of the sRGB gamut and of the full human gamut. These boundaries can be obtained by two methods: (1) for each point in the LCH plane, convert the colour to the target space (RGB or XYZ) and check whether it falls within the gamut; (2) get the contour points of the gamut in the space where it is naturally defined (RGB or XYZ), and convert them back to LCH space. For the latter method, to resample the function Cmax(L,H) on a regular grid the script relies on [scipy.interpolate](https://docs.scipy.org/doc/scipy/reference/interpolate.html). Both methods assume knowledge of the gamut in some space, this is trivial for the sRGB gamut, not for the human gamut hence the limits script below.  
+The pre-computed gamuts at resolutions of 1 and 10 bins per unit L,H are included as Numpy binary files (30 MB).
+
+**limits** provides functions to compute and visualize the limits of the human gamut (optimal colour stimuli, a.k.a. MacAdam limits). As explained on [Bruce Lindbloom's website](http://www.brucelindbloom.com/index.html?LabGamutDisplayHelp.html) they are obtained by considering all possible step-functions as spectral distributions. The conversion from light spectrum to XYZ colour is made with [colour](http://colour-science.org) (the computed limits can be compared with the crude triangulation provided by this package). To triangulate the limit surface in 3D the script relies on [scipy.spatial](https://docs.scipy.org/doc/scipy/reference/spatial.html) (this is required by method 1 above).  
+The pre-computed limits at resolutions of 1, 5, 10, 20 nm are included as Numpy binary files (4.5 MB).
+
+**slices** provides functions to draw slices in the colour space: L-H planes as a function of C (or for the maximum possible C), C-H planes as a function of L, and L-C planes as a function of H.
+
+**maps** provides functions to generate colour maps for Matplotlib, and/or written as png images. Three kinds of cmaps are implemented, which separate the different perceptual dimensions: equi-luminant (varying only in H, at the max C), diverging (varying only in C between two hues H1 and H2), and mono-hue (varying only in L, at the maximum C). It includes utility functions for testing a cmap on mock data, and for displaying the path taken by a cmap in the colour space.
+
+The package comes with five notebooks, which demonstrate the use of the five scripts.  
+The notebook files can be copied in the current directory using function colourspace.copy_tutorials() found in script tutorials/copy_tutorials.py.
+Static renderings of the notebooks can also be seen [on nbviewer](https://nbviewer.org/github/gillesferrand/colourspace/tree/master/src/colourspace/tutorials/):  
+[1. Conversions between colour spaces](https://nbviewer.org/github/gillesferrand/colourspace/blob/master/src/colourspace/tutorials/1.%20convert.ipynb)  
+[2. Mapping the sRGB gamut](https://nbviewer.org/github/gillesferrand/colourspace/blob/master/src/colourspace/tutorials/2.%20sRGB%20gamut.ipynb)  
+[3. Mapping the human gamut](https://nbviewer.org/github/gillesferrand/colourspace/blob/master/src/colourspace/tutorials/3.%20full%20gamut.ipynb)  
+[4. Slicing the LCH space](https://nbviewer.org/github/gillesferrand/colourspace/blob/master/src/colourspace/tutorials/4.%20slices.ipynb)  
+[5. Making custom colour maps](https://nbviewer.org/github/gillesferrand/colourspace/blob/master/src/colourspace/tutorials/5.%20cmaps.ipynb)  
+Additional case study:
+[5.1 Helix colour scheme](https://nbviewer.org/github/gillesferrand/colourspace/blob/master/src/colourspace/tutorials/5.1%20cmaps%20helix.ipynb)
+
+---
+This package is provided "as is", with no warranty of any kind.  
+The code can be freely used by whoever wants to explore modern colour theory.

colourspace_explorer-1.5/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+[tool.setuptools]
+package-dir = {"" = "src"}
+[tool.setuptools.package-data]
+colourspace = ["gamut/*.npy","limits/*.npy","tutorials/*.ipynb"]
+
+[project]
+name = "colourspace-explorer"
+version = "1.5"
+description = "A package providing tools for working with colours in python"
+readme = "README.md"
+authors = [{ name = "Gilles Ferrand", email = "astro.ferrand@gmail.com" }]
+license = { file = "LICENSE" }
+requires-python = ">=3.7"
+dependencies = ["numpy", "matplotlib", "scipy", "colorspacious", "colour-science"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Operating System :: OS Independent",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+]
+keywords = ["colour","colour space","colour maps",]
+
+[project.urls]
+"Homepage" = "https://github.com/gillesferrand/colourspace"

colourspace_explorer-1.5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

colourspace_explorer-1.5/src/colourspace/__init__.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+
+__author__ = "Gilles Ferrand (U. of Manitoba / RIKEN)"
+__version__ = "1.5"
+
+from . import convert
+from . import gamut
+from . import limits
+from . import slices
+from . import maps
+
+from .tutorials.copy_tutorials import copy_tutorials

colourspace_explorer-1.5/src/colourspace/convert.py

@@ -0,0 +1,165 @@
+# -*- coding: utf-8 -*-
+"""
+Conversion between colour spaces: CIE LCH <-> CIE Lab <-> CIE XYZ <->sRGB
+Can use either:
+- custom formulas taken from http://www.easyrgb.com/en/math.php
+- wrapper to "colorspacious" package from https://pypi.python.org/pypi/colorspacious/
+- wrapper to "colour" package from http://colour-science.org
+"""
+
+from __future__ import print_function
+import numpy as np
+
+convertor = None
+illuminant = None
+LCH2RGB = lambda L,C,H: [np.nan, np.nan, np.nan]
+RGB2LCH = lambda R,G,B: [np.nan, np.nan, np.nan]
+
+def set_convertor(name, ill='D65'):
+    """ Binds the conversion functions LCH2RGB() and RGB2LCH() to the choosen colour package
+    """
+    global LCH2RGB, RGB2LCH, convertor, illuminant
+    if name not in ['custom', 'colorspacious', 'colourscience']:
+        print("Unknown conversion module")
+        return
+    convertor = name
+    illuminant = ill
+    if name=='custom':
+        LCH2RGB = lambda L,C,H: XYZ2RGB(Lab2XYZ(LCH2Lab((L,C,H))))
+        RGB2LCH = lambda R,G,B: Lab2LCH(XYZ2Lab(RGB2XYZ((R,G,B))))
+    if name=='colorspacious':
+        from colorspacious import cspace_convert
+        func_LCH2RGB = lambda L,C,H: cspace_convert([L,C,H], {"name": "CIELCh", "XYZ100_w": ill}, "sRGB1")
+        func_RGB2LCH = lambda R,G,B: cspace_convert([R,G,B], "sRGB1", {"name": "CIELCh", "XYZ100_w": ill})
+    if name=='colourscience':
+        import colour
+        if hasattr(colour,'ILLUMINANTS'    ): cs_ill = colour.ILLUMINANTS    ['CIE 1931 2 Degree Standard Observer'][ill]
+        if hasattr(colour,'CCS_ILLUMINANTS'): cs_ill = colour.CCS_ILLUMINANTS['CIE 1931 2 Degree Standard Observer'][ill]
+        func_LCH2RGB = lambda L,C,H: colour.XYZ_to_sRGB(colour.Lab_to_XYZ(colour.LCHab_to_Lab([L,C,H]), illuminant=cs_ill))
+        func_RGB2LCH = lambda R,G,B: colour.Lab_to_LCHab(colour.XYZ_to_Lab(colour.sRGB_to_XYZ([R,G,B]), illuminant=cs_ill))
+    if name=='colorspacious' or name=='colourscience':
+        def LCH2RGB(L,C,H):
+            if hasattr(L, '__iter__'):
+                RGB = np.array(list(map(func_LCH2RGB,L,C,H)))
+                R = RGB[:,0]
+                G = RGB[:,1]
+                B = RGB[:,2]
+            else:
+                R,G,B = func_LCH2RGB(L,C,H)
+            return R, G, B
+        def RGB2LCH(R,G,B):
+            if hasattr(R, '__iter__'):
+                LCH = np.array(list(map(func_RGB2LCH,R,G,B)))
+                L = LCH[:,0]
+                C = LCH[:,1]
+                H = LCH[:,2]
+            else:
+                L,C,H = func_RGB2LCH(R,G,B)
+            return L, C, H
+    print("convertor = '%s' (illuminant = '%s')"%(name,illuminant))
+
+set_convertor('custom')
+
+# cartesian CIE Lab <-> cylindrical CIE LCH
+
+def LCH2Lab(LCH):
+    L,C,H = LCH
+    #L = np.float(L)
+    a = C * np.cos(H*2*np.pi/360.)
+    b = C * np.sin(H*2*np.pi/360.)
+    return (L, a, b)
+
+def Lab2LCH(Lab):
+    L,a,b = Lab
+    #L = np.float(L)
+    C = np.sqrt(a**2+b**2)
+    H = np.arctan2(b,a) * 360/(2*np.pi)
+    H = np.where(H<0, H+360, H)
+    return (L, C, H+0.)
+
+# perceptual CIE XYZ <-> uniform CIE Lab
+
+# standard illuminants for 2° observer
+Xn = {}
+Yn = {}
+Zn = {}
+# D65
+Xn['D65'] =  95.047
+Yn['D65'] = 100.000
+Zn['D65'] = 108.883
+# D50
+Xn['D50'] =  96.422
+Yn['D50'] = 100.000
+Zn['D50'] =  82.521
+
+def XYZ2Lab(XYZ):
+    X,Y,Z = XYZ
+    L = 116 *  f_forward(Y/Yn[illuminant]) - 16
+    a = 500 * (f_forward(X/Xn[illuminant]) - f_forward(Y/Yn[illuminant]))
+    b = 200 * (f_forward(Y/Yn[illuminant]) - f_forward(Z/Zn[illuminant]))
+    return (L,a,b)
+
+def Lab2XYZ(Lab):
+    L,a,b = Lab
+    X = Xn[illuminant] * f_reverse((L+16)/116.+a/500.)
+    Y = Yn[illuminant] * f_reverse((L+16)/116.)
+    Z = Zn[illuminant] * f_reverse((L+16)/116.-b/200.)
+    return (X,Y,Z)
+
+def f_forward(x):
+    return np.where(x > (6/29.)**3, x**(1/3.), 1/3.*(29/6.)**2*x+4/29.)
+
+def f_reverse(x):
+    return np.where(x > 6/29., x**3, 3*(6/29.)**2*(x-4/29.))
+
+# human CIE XYZ <-> machine sRGB
+
+RGB_max = 1.
+
+def XYZ2RGB(XYZ):
+    X,Y,Z = XYZ
+    R = RGB_max * gamma_forward( +3.2406 * X/100. -1.5372 * Y/100. -0.4986 * Z/100. )
+    G = RGB_max * gamma_forward( -0.9689 * X/100. +1.8758 * Y/100. +0.0415 * Z/100. )
+    B = RGB_max * gamma_forward( +0.0557 * X/100. -0.2040 * Y/100. +1.0570 * Z/100. )
+    return (R,G,B)
+
+def RGB2XYZ(RGB):
+    R,G,B = RGB
+    X = 100 * ( +0.4124 * gamma_reverse(R/RGB_max) +0.3576 * gamma_reverse(G/RGB_max) +0.1805 * gamma_reverse(B/RGB_max) )
+    Y = 100 * ( +0.2126 * gamma_reverse(R/RGB_max) +0.7152 * gamma_reverse(G/RGB_max) +0.0722 * gamma_reverse(B/RGB_max) )
+    Z = 100 * ( +0.0193 * gamma_reverse(R/RGB_max) +0.1192 * gamma_reverse(G/RGB_max) +0.9505 * gamma_reverse(B/RGB_max) )
+    return (X,Y,Z)
+
+def gamma_forward(Cln):
+    mask = Cln <= 0.0031308
+    g = np.empty_like(Cln)
+    g[ mask] = 12.92*Cln[mask]
+    g[~mask] = 1.055*(Cln[~mask]**(1/2.4))-0.055
+    return g
+
+def gamma_reverse(Cnl):
+    mask = Cnl <= 0.04045
+    g = np.empty_like(Cnl)
+    g[ mask] = Cnl[mask]/12.92
+    g[~mask] = ((Cnl[~mask]+0.055)/1.055)**2.4
+    return g
+
+# RGB gamut check
+
+def crop1(R,min=0,max=1):
+    R_crop = np.where(R      < min, np.nan, R     )
+    R_crop = np.where(R_crop > max, np.nan, R_crop)
+    return R_crop
+
+def crop3(RGB,min=0,max=1):
+    R,G,B = RGB
+    return np.stack((crop1(R,min,max),crop1(G,min,max),crop1(B,min,max)),axis=-1)
+
+def clip1(R,min=0,max=1):
+    R_clip = np.where(R      < min, min, R     )
+    R_clip = np.where(R_clip > max, max, R_clip)
+    return R_clip
+
+def clip3(RGB,min=0,max=1):
+    R,G,B = RGB
+    return np.stack((clip1(R,min,max),clip1(G,min,max),clip1(B,min,max)),axis=-1)