Colour Documentation Release 0.3.10
Total Page:16
File Type:pdf, Size:1020Kb
Colour Documentation Release 0.3.10 Colour DeVELOPERS FEB 12, 2018 Contents 1 Features 3 2 Installation 5 3 Usage 7 3.1 Colour Manual............................................7 3.1.1 Tutorial...........................................7 3.1.1.1 Overview......................................8 3.1.1.2 From Spectral Power Distribution......................... 14 3.1.1.3 Convert to Tristimulus Values........................... 24 3.1.1.4 From CIE XYZ Colourspace............................ 25 3.1.1.5 Convert to Screen Colours............................. 25 3.1.1.6 Generate Colour Rendition Charts........................ 26 3.1.1.7 Convert to Chromaticity Coordinates....................... 29 3.1.1.8 And More. ..................................... 31 3.1.2 Reference.......................................... 31 3.1.2.1 Colour....................................... 31 3.1.2.2 Indices and tables................................. 452 3.1.3 Bibliography......................................... 452 3.1.3.1 Indirect References................................ 452 3.2 Examples............................................... 453 4 Contributing 461 5 Changes 463 6 Bibliography 465 7 See Also 467 8 About 469 Bibliography 471 I II Colour Documentation, Release 0.3.10 Colour is a Python colour science package implementing a comprehensive number of colour theory transfor- mations and algorithms. It is open source and freely available under the New BSD License terms. Contents 1 Colour Documentation, Release 0.3.10 2 Contents CHAPTER 1 FEATURES Colour features a rich dataset and collection of objects, please see the features page for more information. 3 Colour Documentation, Release 0.3.10 4 Chapter 1. FEATURES CHAPTER 2 Installation Anaconda from Continuum Analytics is the Python distribution we use to develop Colour: it ships all the scientific dependencies we require and is easily deployed cross-platform: $ conda create -y -n python-colour $ source activate python-colour $ conda install -y -c conda-forge colour-science Colour can be easily installed from the Python Package Index by issuing this command in a shell: $ pip install colour-science The detailed installation procedure is described in the Installation Guide. 5 Colour Documentation, Release 0.3.10 6 Chapter 2. Installation CHAPTER 3 Usage The two main references for Colour usage are the Colour Manual and the Jupyter Notebooks with detailed historical and theoretical context and images. 3.1 Colour Manual 3.1.1 TUTORIAL Colour spreads over various domains of Colour Science from colour models to optical phenomena, this tutorial will not give you a complete overview of the API but will still be a good introduction. Note: A directory full of examples is available at this path in your Colour installation: colour/examples. You can also explore it directly on Github: https://github.com/colour-science/colour/tree/master/colour/ examples from colour.plotting import * colour_plotting_defaults() visible_spectrum_plot() 7 Colour Documentation, Release 0.3.10 3.1.1.1 OvERVIEW Colour is organised around various sub-packages: • adaptation: Chromatic adaptation models and transformations. • algebra: Algebra utilities. • appearance: Colour appearance models. • biochemistry: Biochemistry computations. • continuous: Base objects for continuous data representation. • characterisation: Colour fitting and camera characterisation. • colorimetry: Core objects for colour computations. • constants: CIE and CODATA constants. • corresponding: Corresponding colour chromaticities computations. • difference: Colour difference computations. • examples: Examples for the sub-packages. • io: Input / output objects for reading and writing data. • models: Colour models. • notation: Colour notation systems. • phenomena: Computation of various optical phenomena. 8 Chapter 3. Usage Colour Documentation, Release 0.3.10 • plotting: Diagrams, figures, etc. • quality: Colour quality computation. • recovery: Reflectance recovery. • temperature: Colour temperature and correlated colour temperature computation. • utilities: Various utilities and data structures. • volume: Colourspace volumes computation and optimal colour stimuli. Most of the public API is available from the root colour namespace: import colour print(colour.__all__[:5]+[ '...']) ['handle_numpy_errors', 'ignore_numpy_errors', 'raise_numpy_errors', 'print_numpy_errors', 'warn_numpy_ ,!errors', '...'] The various sub-packages also expose their public API: from pprint import pprint import colour.plotting for sub_package in ('adaptation', 'algebra', 'appearance', 'biochemistry', 'characterisation', 'colorimetry', 'constants', 'continuous', 'corresponding', 'difference', 'io', 'models', 'notation', 'phenomena', 'plotting', 'quality', 'recovery', 'temperature', 'utilities', 'volume'): print(sub_package.title()) pprint(getattr(colour, sub_package).__all__[:5]+[ '...']) print('\n') Adaptation ['CHROMATIC_ADAPTATION_TRANSFORMS', 'XYZ_SCALING_CAT', 'VON_KRIES_CAT', 'BRADFORD_CAT', 'SHARP_CAT', '...'] Algebra ['cartesian_to_spherical', 'spherical_to_cartesian', 'cartesian_to_polar', 'polar_to_cartesian', 'cartesian_to_cylindrical', '...'] Appearance ['Hunt_InductionFactors', 'HUNT_VIEWING_CONDITIONS', 'Hunt_Specification', 'XYZ_to_Hunt', 'ATD95_Specification', 3.1. Colour Manual 9 Colour Documentation, Release 0.3.10 '...'] Biochemistry ['reaction_rate_MichealisMenten', 'substrate_concentration_MichealisMenten', '...'] Characterisation ['RGB_SpectralSensitivities', 'RGB_DisplayPrimaries', 'CAMERAS_RGB_SPECTRAL_SENSITIVITIES', 'COLOURCHECKERS', 'COLOURCHECKER_INDEXES_TO_NAMES_MAPPING', '...'] Colorimetry ['SpectralShape', 'SpectralPowerDistribution', 'MultiSpectralPowerDistribution', 'DEFAULT_SPECTRAL_SHAPE', 'constant_spd', '...'] Continuous ['AbstractContinuousFunction', 'Signal', 'MultiSignal', '...'] Constants ['CIE_E', 'CIE_K', 'K_M', 'KP_M', 'AVOGADRO_CONSTANT', '...'] Corresponding ['BRENEMAN_EXPERIMENTS', 'BRENEMAN_EXPERIMENTS_PRIMARIES_CHROMATICITIES', 'corresponding_chromaticities_prediction_CIE1994', 'corresponding_chromaticities_prediction_CMCCAT2000', 'corresponding_chromaticities_prediction_Fairchild1990', '...'] Difference ['DELTA_E_METHODS', 'delta_E', 'delta_E_CIE1976', 'delta_E_CIE1994', 'delta_E_CIE2000', '...'] Io ['IES_TM2714_Spd', 'read_image', 'write_image', 'read_spectral_data_from_csv_file', 10 Chapter 3. Usage Colour Documentation, Release 0.3.10 'read_spds_from_csv_file', '...'] Models ['XYZ_to_xyY', 'xyY_to_XYZ', 'xy_to_xyY', 'xyY_to_xy', 'xy_to_XYZ', '...'] Notation ['MUNSELL_COLOURS_ALL', 'MUNSELL_COLOURS_1929', 'MUNSELL_COLOURS_REAL', 'MUNSELL_COLOURS', 'munsell_value', '...'] Phenomena ['scattering_cross_section', 'rayleigh_optical_depth', 'rayleigh_scattering', 'rayleigh_scattering_spd', '...'] Plotting ['ASTM_G_173_ETR', 'PLOTTING_RESOURCES_DIRECTORY', 'DEFAULT_FIGURE_ASPECT_RATIO', 'DEFAULT_FIGURE_WIDTH', 'DEFAULT_FIGURE_HEIGHT', '...'] Quality ['TCS_SPDS', 'VS_SPDS', 'CRI_Specification', 'colour_rendering_index', 'CQS_Specification', '...'] Recovery ['SMITS_1999_SPDS', 'XYZ_to_spectral_Meng2015', 'RGB_to_spectral_Smits1999', 'REFLECTANCE_RECOVERY_METHODS', 'XYZ_to_spectral', '...'] Temperature ['CCT_TO_UV_METHODS', 'UV_TO_CCT_METHODS', 'CCT_to_uv', 'CCT_to_uv_Ohno2013', 'CCT_to_uv_Robertson1968', 3.1. Colour Manual 11 Colour Documentation, Release 0.3.10 '...'] Utilities ['handle_numpy_errors', 'ignore_numpy_errors', 'raise_numpy_errors', 'print_numpy_errors', 'warn_numpy_errors', '...'] Volume ['ILLUMINANTS_OPTIMAL_COLOUR_STIMULI', 'is_within_macadam_limits', 'is_within_mesh_volume', 'is_within_pointer_gamut', 'is_within_visible_spectrum', '...'] The code is documented and almost every docstrings have usage examples: print(colour.temperature.CCT_to_uv_Ohno2013.__doc__) Returns the *CIE UCS* colourspace *uv* chromaticity coordinates from given correlated colour temperature :math:`T_{cp}`, :math:`\Delta_{uv}` and colour matching functions using *Ohno (2013)* method. Parameters ---------- CCT : numeric Correlated colour temperature :math:`T_{cp}`. D_uv : numeric, optional :math:`\Delta_{uv}`. cmfs : XYZ_ColourMatchingFunctions, optional Standard observer colour matching functions. Returns ------- ndarray *CIE UCS* colourspace *uv* chromaticity coordinates. References ---------- .. [4] Ohno, Y. (2014). Practical Use and Calculation of CCT and Duv. LEUKOS, 10(1), 4755. doi:10.1080/15502724.2014.839020 Examples -------- >>> from colour import STANDARD_OBSERVERS_CMFS >>> cmfs = STANDARD_OBSERVERS_CMFS['CIE 1931 2 Degree Standard Observer'] >>> CCT = 6507.4342201047066 >>> D_uv = 0.003223690901513 >>> CCT_to_uv_Ohno2013(CCT, D_uv, cmfs) # doctest: +ELLIPSIS array([ 0.1977999..., 0.3122004...]) At the core of Colour is the colour.colorimetry sub-package, it defines the objects needed for spectral related computations and many others: 12 Chapter 3. Usage Colour Documentation, Release 0.3.10 import colour.colorimetry as colorimetry pprint(colorimetry.__all__) ['SpectralShape', 'SpectralPowerDistribution', 'MultiSpectralPowerDistribution', 'DEFAULT_SPECTRAL_SHAPE', 'constant_spd', 'zeros_spd', 'ones_spd', 'blackbody_spd', 'blackbody_spectral_radiance', 'planck_law', 'LMS_ConeFundamentals', 'RGB_ColourMatchingFunctions', 'XYZ_ColourMatchingFunctions', 'CMFS', 'LMS_CMFS', 'RGB_CMFS', 'STANDARD_OBSERVERS_CMFS', 'ILLUMINANTS', 'D_ILLUMINANTS_S_SPDS', 'HUNTERLAB_ILLUMINANTS', 'ILLUMINANTS_RELATIVE_SPDS', 'LIGHT_SOURCES', 'LIGHT_SOURCES_RELATIVE_SPDS', 'LEFS', 'PHOTOPIC_LEFS', 'SCOTOPIC_LEFS', 'BANDPASS_CORRECTION_METHODS', 'bandpass_correction', 'bandpass_correction_Stearns1988',