colourspace-explorer 1.5__py3-none-any.whl

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/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)

colourspace/gamut.py

@@ -0,0 +1,367 @@
+# -*- coding: utf-8 -*-
+"""
+Limits of the full human gamut, or the sRGB gamut, in CIE LCH space: Cmax(L,H)
+"""
+
+from __future__ import print_function
+import sys
+import numpy as np
+import pylab as plt
+import matplotlib.ticker as ticker
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+from mpl_toolkits.mplot3d import Axes3D
+from scipy import interpolate
+from . import convert
+from . import limits
+
+import os
+this_dir, this_filename = os.path.split(__file__)
+this_dir += "/gamut"
+
+# the gamut is cached
+Cmax = {}
+
+# ranges for L and H
+# (several functions need to know this)
+L_min = 0 ; L_max = 100
+H_min = 0 ; H_max = 360
+
+#---------------------------
+# find the gamut boundary
+# method 1: sample the LH plane, for each point convert to native space and check if within limits
+#---------------------------
+
+def valid_LCH_full(L,C,H):
+    """ Checks if a LCH colour is in the human gamut """
+    X,Y,Z = convert.Lab2XYZ(convert.LCH2Lab((L,C,H)))
+    XYZ = np.stack((X,Y,Z),axis=-1)
+    return limits.within_limits(XYZ,'XYZ',kind='cmp') # assumes limits have been set
+
+def valid_LCH_sRGB(L,C,H):
+    """ Checks if a LCH colour is in the sRGB gamut """
+    R,G,B = convert.LCH2RGB(L,C,H)
+    valid = lambda x: np.logical_and(0 <= x, x <= 1)
+    return valid(R)*valid(G)*valid(B)
+    #return np.logical_and(np.logical_and(valid(R),valid(G)),valid(B))
+
+valid_LCH = {"full": valid_LCH_full, \
+             "sRGB": valid_LCH_sRGB}
+
+def find_Cmax_forward(res, gmt, save=False, plot=True, version='mapping'):
+    """ Finds the maximum Cmax for each (L,H) pair with a precision of res points per unit of L,C,H """
+    if res not in Cmax.keys(): Cmax[res] = {}
+    if gmt=='full' and not 'XYZ' in limits.triangulation['cmp'].keys():
+        limits.set_limits(l_step=10, l_min=360, l_max=780)
+        limits.triangulate('XYZ')
+    L = np.linspace(L_min,L_max,int((L_max-L_min)*res+1))
+    H = np.linspace(H_min,H_max,int((H_max-H_min)*res+1))
+    Cmax[res][gmt] = np.zeros((len(L),len(H)),dtype=np.float32)
+    # version with loops
+    if version == 'looping':
+        for i in range(len(L)):
+            for k in range(len(H)):
+                Cmax[res][gmt][i,k] = find_Cmax_for_LH(L=L[i], H=H[k], Cres=1./res, gmt=gmt)
+                sys.stdout.write("L = %.2f, H = %.2f, Cmax = %.2f"%(L[i],H[k],Cmax[res][gmt][i,k]))
+                sys.stdout.write("\r")
+                sys.stdout.flush()
+        sys.stdout.write("\n")
+        sys.stdout.flush()
+    # version with mapping
+    if version == 'mapping':
+        LL, HH = np.meshgrid(L,H,indexing='ij')
+        Cmax[res][gmt][:,:] = find_Cmax_for_LH(LL, HH, Cres=1./res, gmt=gmt)
+    if version == 'mapping3D':
+        C = np.linspace(0, 200, int(200.*res)+1)
+        LLL, CCC, HHH = np.meshgrid(L,C,H,indexing='ij')
+        valid = valid_LCH[gmt](LLL,CCC,HHH)
+        for i in range(len(L)):
+            for k in range(len(H)):
+                j_valid = np.where(valid[i,:,k])[0]
+                Cmax[res][gmt][i,k] = C[j_valid[-1]] if len(j_valid)>0 else 0
+    if save: save_Cmax_npy(res=res, gmt=gmt)
+    if plot: plot_Cmax(res=res, gmt=gmt)
+
+def find_Cmax_for_LH(L, H, Cres, gmt):
+    """Finds the maximum C for a given (L,H) at a given resolution in a given gamut"""
+    edge_detector = lambda L,H: find_edge_by_dichotomy(lambda c: valid_LCH[gmt](L,c,H), xmin=0, xmax=200, dx=Cres)
+    Cmax = np.vectorize(edge_detector)(L,H)
+    Cmax = np.where(L<=  0,     0,Cmax)
+    Cmax = np.where(L>=100,     0,Cmax)
+    Cmax = np.where(L<   0,np.nan,Cmax)
+    Cmax = np.where(L> 100,np.nan,Cmax)
+    #Cmax = np.where(np.logical_or(L<=0,L>=100),     0,Cmax)
+    #Cmax = np.where(np.logical_or(L< 0,L> 100),np.nan,Cmax)
+    return Cmax
+
+def find_edge_by_dichotomy(func, xmin, xmax, dx=1., iter_max=100):
+    """Returns the point `x` (within resolution `dx`) where boolean function `func` changes value
+       `func` is assumed to switch from True to False between `xmin` and `xmax`
+    """
+    xleft  = xmin
+    xright = xmax
+    xmid = 0.5*(xright-xleft)
+    i = 0
+    delta = dx
+    while delta >= dx and i<iter_max:
+        i += 1
+        #print("i = %4i: x = [%6.2f, %6.2f]: func(%6.2f) = %i"%(i,xleft,xright,xmid,func(xmid)),end='')
+        if func(xmid): xleft  = xmid
+        else:          xright = xmid
+        xmid_old = xmid
+        xmid = 0.5*(xleft+xright)
+        delta = abs(xmid_old-xmid)
+        #print("-> x = [%6.2f, %6.2f], delta=%f"%(xleft,xright,delta))
+    if i >= iter_max: print("edge not found at precision ",dx,"in ",iter_max," iterations")
+    return np.around(xmid,int(np.ceil(np.log10(1./dx))))
+
+#---------------------------
+# find the gamut boundary
+# method 2: discretize the gamut boundary in the native space, project it back to the LH plane
+#---------------------------
+
+def get_RGB_faces(num=10):
+    """ Samples the faces of the RGB cube with `num` points per axis """
+    array = {}
+    for coord in ['R','G','B']: array[coord] = np.array([])
+    block = {}
+    block['0'] = np.zeros(num**2)
+    block['1'] = np.ones( num**2)
+    x = np.linspace(0,1,int(num))
+    X,Y = np.meshgrid(x,x)
+    block['x'] = X.flatten()
+    block['y'] = Y.flatten()
+    for x,y,z in [('R','G','B'), ('G','B','R'), ('B','R','G')]:
+        for side in ['0','1']:
+            array[x] = np.concatenate((array[x], block['x']))
+            array[y] = np.concatenate((array[y], block['y']))
+            array[z] = np.concatenate((array[z], block[side]))
+    return array['R'],array['G'],array['B']
+
+def get_edges_LCH_sRGB(res):
+    R,G,B = get_RGB_faces(num=res)
+    L,C,H = convert.RGB2LCH(R,G,B)
+    return np.stack((L,C,H),axis=-1)
+
+def get_edges_LCH_full(res):
+    limits.set_limits(l_step=res, l_min=360, l_max=780)
+    return limits.limits['cmp']['LCH']
+
+get_edges_LCH = {"full": get_edges_LCH_full, \
+                 "sRGB": get_edges_LCH_sRGB}
+
+def find_Cmax_backward(res_native, res_LH, gmt, save=False, plot=True):
+    """ Finds the maximum Cmax(L,H) by discretizing the gamut boundary in its native space
+        for sRGB gamut: res_native = number of points along R, G, B
+        for full gamut: res_native = delta_Lambda in nm
+        the LH plane will be re-sampled regularly at resolution res_LH
+    """
+    if res_LH not in Cmax.keys(): Cmax[res_LH] = {}
+    # get edges in LCH space
+    LCH_max = get_edges_LCH[gmt](res_native)
+    # interpolate the implicit function C(L,H)
+    L = LCH_max[:,0]
+    C = LCH_max[:,1]
+    H = LCH_max[:,2]
+    L_grid, H_grid = np.mgrid[L_min:L_max:1j*(L_max-L_min+1)*res_LH, H_min:H_max:1j*(H_max-H_min+1)*res_LH]
+    C_grid = interpolate.griddata((L,H),C,(L_grid,H_grid),method='linear')
+    C_grid[np.where(np.isnan(C_grid))] = 0
+    # fix the edges
+    C_grid[:, 0] = 0.5*(C_grid[:,1]+C_grid[:,-2])
+    C_grid[:,-1] = 0.5*(C_grid[:,1]+C_grid[:,-2])
+
+    Cmax[res_LH][gmt] = np.zeros(C_grid.shape,dtype=np.float32)
+    Cmax[res_LH][gmt][:,:] = C_grid[:,:]
+    if save: save_Cmax_npy(res=res_LH, gmt=gmt)
+    if plot: plot_Cmax(res=res_LH, gmt=gmt)
+
+#-------------------
+# display the gamut
+#-------------------
+
+def get_extremum(res, gmt):
+    """ Prints the LCH value of the colour of highest C """
+    C = Cmax[res][gmt].max()
+    iL,iH = np.unravel_index(Cmax[res][gmt].argmax(),Cmax[res][gmt].shape)
+    nL = len(Cmax[res][gmt][:,0])
+    L = L_min + iL/(nL-1.) * (L_max-L_min)
+    nH = len(Cmax[res][gmt][0,:])
+    H = H_min + iH/(nH-1.) * (H_max-H_min)
+    return np.array((L,C,H))
+
+def plot_Cmax(res, gmt, vmax=200, fig=1, figsize=None, dpi=None, dir=this_dir, fname="Cmax", axes=['on','off']):
+    """ Plots Cmax(H,L) """
+    plot2D(Cmax[res][gmt], name=gmt, vmax=vmax, fname='%s_res%i_%s'%(fname,res,gmt), fig=fig, figsize=figsize, dpi=dpi, dir=dir, axes=axes)
+
+def plot2D(array, marker='', colour='', vmin=0, vmax=200, cbar=3, fig=1, figsize=None, dpi=None, aspect="equal", name="", fname="Cmax", dir=this_dir, axes=['on','off']):
+    """ Plots a surface represented explicitly by a 2D array XY or implicitly by a set of 3D points XYZ """
+    cmap = "Greys_r"
+    norm = plt.Normalize(vmin=vmin, vmax=vmax)
+    if dir != "":
+        fname='%s/%s'%(dir,fname)
+        ext = ".png"
+    if fig != 0:
+        plt.figure(fig,figsize=figsize)
+        plt.title("%s gamut"%name)
+        plt.xlabel("H")
+        plt.ylabel("L", rotation='horizontal')
+        plt.xlim([0,360])
+        plt.ylim([0,100])
+        if array.shape[1]==3:
+            # array is the 3D surface of a 2D function
+            L = array[:,0]
+            C = array[:,1]
+            H = array[:,2]
+            plt.tricontourf(H,L,C, cmap=cmap, norm=norm)
+            if marker != '':
+                ax = plt.gca()
+                if len(colour)>0:
+                    ax.plot(H,L,marker,c=colour)
+                else:
+                    #ax.plot(H,L,marker,color=convert.clip3(convert.LCH2RGB(L,C,H)).tolist())
+                    for h, l, c in zip(H, L, array): ax.plot(h,l,marker,color=convert.clip3(convert.LCH2RGB(c[0],c[1],c[2])))
+            plt.gca().set_aspect(aspect)
+        else:
+            # array is a 2D map
+            plt.imshow(array, origin='lower', extent=[H_min, H_max, L_min, L_max], aspect=aspect, interpolation='nearest', cmap=cmap, norm=norm)
+        locator = ticker.MultipleLocator(60)
+        plt.gca().xaxis.set_major_locator(locator)
+        if cbar>0:
+            cax = make_axes_locatable(plt.gca()).append_axes("right", size="%.f%%"%cbar, pad=0.10)
+            cb = plt.colorbar(plt.gci(), cax=cax)
+            cb.locator = ticker.MultipleLocator(50)
+            cb.update_ticks()
+            cb.set_label("Cmax")
+        if dir != "" and 'on' in axes:
+            print("writing %s"%(fname+"_axon"+ext))
+            plt.savefig(fname+"_axon"+ext, dpi=dpi, bbox_inches='tight')
+    if dir != "" and 'off' in axes and array.shape[1] > 3:
+        print("writing %s"%(fname+"_axoff"+ext))
+        plt.imsave(arr=array, origin='lower', cmap=cmap, vmin=vmin, vmax=vmax, fname=fname+"_axoff"+ext, dpi=dpi if dpi!=None else 200)
+        #plt.imsave(fname+"_axoff"+ext, plt.get_cmap(cmap)(norm(np.flipud(array))), dpi=dpi if dpi!=None else 200)
+
+def plot3D(RGB, angle=(0,0), fig=0, figsize=None, dpi=None, dir="", fname="RGB"):
+    """ Plots a set of (R,G,B) points in 3D
+        (beware: mplot3d does not composite colours correctly, and cannot handle large sets)
+    """
+    # figure
+    fg = plt.figure("RGB",figsize=figsize)
+    ax = fg.add_subplot(111, projection='3d')
+    ax.set_xlabel("R")
+    ax.set_ylabel("G")
+    ax.set_zlabel("B")
+    ax.xaxis.pane.fill = False
+    ax.yaxis.pane.fill = False
+    ax.zaxis.pane.fill = False
+    ax.view_init(angle[0],angle[1])
+    #ax.grid(False)
+    # plot
+    R,G,B = RGB
+    RGB_list = np.stack((R,G,B),axis=-1)
+    print(len(RGB_list)," points")
+    ax.scatter(R,G,B,color=RGB_list,marker='o',depthshade=False)
+    # save
+    if dir != "":
+        fname = "%s/%s_%s.png"%(dir,fname,space)
+        print("writing %s"%(fname))
+        plt.savefig(fname, dpi=dpi, bbox_inches='tight')
+    if fig<0: plt.close(fg)
+
+#-------------------------
+# save and load the gamut
+#-------------------------
+
+def save_Cmax_npy(res, gmt, dir=this_dir):
+    """ Saves a gamut as a numpy binary file """
+    global Cmax
+    fname = '%s/Cmax_res%.0f_%s.npy'%(dir,res,gmt)
+    print("saving gamut to %s"%fname)
+    np.save(fname, Cmax[res][gmt])
+
+def load_Cmax_npy(res, gmt, dir=this_dir):
+    """ Loads a gamut from a numpy binary file """
+    global Cmax
+    fname = '%s/Cmax_res%.0f_%s.npy'%(dir,res,gmt)
+    print("loading gamut from %s"%fname)
+    if res not in Cmax.keys(): Cmax[res] = {}
+    Cmax[res][gmt] = np.load(fname)
+
+def save_Cmax_txt(res, gmt, dir=this_dir):
+    """ Saves a gamut as a text file """
+    global Cmax
+    fname = '%s/Cmax_res%.0f_%s.txt'%(dir,res,gmt)
+    file = open(fname, 'w')
+    print("saving gamut to %s"%fname)
+    L = np.linspace(L_min,L_max,int((L_max-L_min)*res+1))
+    H = np.linspace(H_min,H_max,int((H_max-H_min)*res+1))
+    digits = np.ceil(np.log10(res))
+    format = "%%%i.%if"%(4+digits,digits)
+    formats = format+"\t"+format+"\t"+format+"\n"
+    for i in range(len(L)):
+        for k in range(len(H)):
+            file.write(formats%(L[i],H[k],Cmax[res][gmt][i,k]))
+    file.close()
+
+def load_Cmax_txt(res, gmt, dir=this_dir):
+    """ Loads a gamut from a text file (as written by save_Cmax_txt()) """
+    global Cmax
+    Cmax[res] = {}
+    fname = '%s/Cmax_res%.0f_%s.txt'%(dir,res,gmt)
+    file = open(fname, 'r')
+    print("loading gamut from %s"%fname)
+    L = np.linspace(L_min,L_max,int((L_max-L_min)*res+1))
+    H = np.linspace(H_min,H_max,int((H_max-H_min)*res+1))
+    Cmax[res][gmt] = np.zeros((len(L),len(H)),dtype=np.float32)
+    for i in range(len(L)):
+        for k in range(len(H)):
+            Cmax[res][gmt][i,k] = float(file.readline().strip("\n").split("\t")[-1])
+    file.close()
+
+#---------------
+# use the gamut
+#---------------
+
+def set_Cmax(res,gmt):
+    """ Loads or computes a gamut as needed (only needed once) """
+    global Cmax
+    if res in Cmax.keys() and gmt in Cmax[res].keys(): return
+    try:
+        load_Cmax_npy(res,gmt)
+    except:
+        print("couldn't load gamut '%s' at res=%f, computing it"%(gmt,res))
+        find_Cmax_forward(res, gmt)
+
+def Cmax_for_LH(L,H,res=1,gmt='full'):
+    """ Returns the maximum C for a given pair (L,H)
+        at a given resolution in a given gamut """
+    global Cmax
+    set_Cmax(res,gmt) # the gamut array is cached
+    H = H%360
+    L_valid = np.logical_and(L>=0, L<=100)
+    C = np.where(L_valid,interpolate_Cmax_for_LH(L,H,Cmax[res][gmt]),np.nan)
+    return C
+
+def interpolate_Cmax_for_LH(L,H,Cmax):
+    """ Bi-linearly interpolates tabulated Cmax(L,H) at given L,H
+        (expects L in [L_min,L_max] = [0,100] and H in [H_min,Hmax] = [0,360])
+    """
+    # L
+    nL = Cmax.shape[0]
+    i = (L-L_min)/float(L_max-L_min) * (nL-1)
+    i0 = (np.floor(i)).astype(int)
+    i0 = np.maximum(np.minimum(i0,nL-1),0)
+    i1 = np.where(i0 < nL-1, i0 + 1, i0)
+    x = i - i0
+    # H
+    nH = Cmax.shape[1]
+    j = (H-H_min)/float(H_max-H_min) * (nH-1)
+    j = np.where(np.isnan(j),0,j) # to avoid casting error
+    j0 = (np.floor(j)).astype(int)
+    j0 = np.maximum(np.minimum(j0,nH-1),0)
+    j1 = np.where(j0 < nH-1, j0 + 1, j0)
+    y = j - j0
+    # C (bilinear interpolation)
+    C = Cmax[i0,j0] * (1-x)*(1-y) \
+      + Cmax[i0,j1] * (1-x)*   y  \
+      + Cmax[i1,j0] *    x *(1-y) \
+      + Cmax[i1,j1] *    x *   y
+    return C