colour.io Package¶

Sub-Modules¶

Module Contents¶

class colour.io.IES_TM2714_Spd(path=None, header=None, spectral_quantity=None, reflection_geometry=None, transmission_geometry=None, bandwidth_FWHM=None, bandwidth_corrected=None)¶

Bases: colour.colorimetry.spectrum.SpectralPowerDistribution

Defines a IES TM-27-14 spectral power distribution.

This class can read and write IES TM-27-14 spectral data XML files.

Parameters:

Parameters:	path (unicode, optional) – Spectral data XML file path. header (IES_TM2714_Header, optional) – IES TM-27-14 spectral power distribution header. spectral_quantity (unicode, optional) – {‘flux’, ‘absorptance’, ‘transmittance’, ‘reflectance’, ‘intensity’, ‘irradiance’, ‘radiance’, ‘exitance’, ‘R-Factor’, ‘T-Factor’, ‘relative’, ‘other’} Quantity of measurement for each element of the spectral data. reflection_geometry (unicode, optional) – {‘di:8’, ‘de:8’, ‘8:di’, ‘8:de’, ‘d:d’, ‘d:0’, ‘45a:0’, ‘45c:0’, ‘0:45a’, ‘45x:0’, ‘0:45x’, ‘other’} Spectral reflectance factors geometric conditions. transmission_geometry (unicode, optional) – {‘0:0’, ‘di:0’, ‘de:0’, ‘0:di’, ‘0:de’, ‘d:d’, ‘other’} Spectral transmittance factors geometric conditions. bandwidth_FWHM (numeric, optional) – Spectroradiometer full-width half-maximum bandwidth in nanometers. bandwidth_corrected (bool, optional) – Specifies if bandwidth correction has been applied to the measured data.

path (unicode, optional) – Spectral data XML file path.
header (IES_TM2714_Header, optional) – IES TM-27-14 spectral power distribution header.
spectral_quantity (unicode, optional) – {‘flux’, ‘absorptance’, ‘transmittance’, ‘reflectance’, ‘intensity’, ‘irradiance’, ‘radiance’, ‘exitance’, ‘R-Factor’, ‘T-Factor’, ‘relative’, ‘other’} Quantity of measurement for each element of the spectral data.
reflection_geometry (unicode, optional) – {‘di:8’, ‘de:8’, ‘8:di’, ‘8:de’, ‘d:d’, ‘d:0’, ‘45a:0’, ‘45c:0’, ‘0:45a’, ‘45x:0’, ‘0:45x’, ‘other’} Spectral reflectance factors geometric conditions.
transmission_geometry (unicode, optional) – {‘0:0’, ‘di:0’, ‘de:0’, ‘0:di’, ‘0:de’, ‘d:d’, ‘other’} Spectral transmittance factors geometric conditions.
bandwidth_FWHM (numeric, optional) – Spectroradiometer full-width half-maximum bandwidth in nanometers.
bandwidth_corrected (bool, optional) – Specifies if bandwidth correction has been applied to the measured data.

mapping¶

path¶

header¶

spectral_quantity¶

reflection_geometry¶

transmission_geometry¶

bandwidth_FWHM¶

bandwidth_corrected¶

read()¶

write()¶

Notes

Reflection Geometry

di:8: Diffuse / eight-degree, specular component included.
de:8: Diffuse / eight-degree, specular component excluded.
8:di: Eight-degree / diffuse, specular component included.
8:de: Eight-degree / diffuse, specular component excluded.
d:d: Diffuse / diffuse.
d:0: Alternative diffuse.
45a:0: Forty-five degree annular / normal.
45c:0: Forty-five degree circumferential / normal.
0:45a: Normal / forty-five degree annular.
45x:0: Forty-five degree directional / normal.
0:45x: Normal / forty-five degree directional.
other: User-specified in comments.

Transmission Geometry

0:0: Normal / normal.
di:0: Diffuse / normal, regular component included.
de:0: Diffuse / normal, regular component excluded.
0:di: Normal / diffuse, regular component included.
0:de: Normal / diffuse, regular component excluded.
d:d: Diffuse / diffuse.
other: User-specified in comments.

Examples

>>> from os.path import dirname, join
>>> directory = join(dirname(__file__), 'tests', 'resources')
>>> spd = IES_TM2714_Spd(join(directory, 'Fluorescent.spdx'))
>>> spd.read()
True
>>> spd.header.manufacturer
'Unknown'
>>> # Doctests ellipsis for Python 2.x compatibility.
>>> spd[501.7]  
array(0.095...)

bandwidth_FWHM

Property for self.__bandwidth_FWHM private attribute.

Returns:	self.__bandwidth_FWHM.
Return type:	numeric

bandwidth_corrected

Property for self.__bandwidth_corrected private attribute.

Returns:	self.__bandwidth_corrected.
Return type:	bool

header

Property for self.__header private attribute.

Returns:	self.__header.
Return type:	IES_TM2714_Header

mapping

Property for self.mapping attribute.

Return type:	Structure

Warning

IES_TM2714_Spd.mapping is read only.

path

Property for self.__path private attribute.

Returns:	self.__path.
Return type:	unicode

read()

Reads and parses the spectral data XML file path.

Returns:	Definition success.
Return type:	bool

Examples

>>> from os.path import dirname, join
>>> directory = join(dirname(__file__), 'tests', 'resources')
>>> spd = IES_TM2714_Spd(join(directory, 'Fluorescent.spdx'))
>>> spd.read()
True
>>> spd.header.description
'Rare earth fluorescent lamp'
>>> # Doctests ellipsis for Python 2.x compatibility.
>>> spd[400]  
array(0.034...)

reflection_geometry

Property for self.__reflection_geometry private attribute.

Returns:	self.__reflection_geometry.
Return type:	unicode

spectral_quantity

Property for self.__spectral_quantity private attribute.

Returns:	self.__spectral_quantity.
Return type:	unicode

transmission_geometry

Property for self.__transmission_geometry private attribute.

Returns:	self.__transmission_geometry.
Return type:	unicode

write()

Write the spd spectral data to XML file path.

Returns:	Definition success.
Return type:	bool

Examples

>>> from os.path import dirname, join
>>> from shutil import rmtree
>>> from tempfile import mkdtemp
>>> directory = join(dirname(__file__), 'tests', 'resources')
>>> spd = IES_TM2714_Spd(join(directory, 'Fluorescent.spdx'))
>>> spd.read()
True
>>> temporary_directory = mkdtemp()
>>> spd.path = join(temporary_directory, 'Fluorescent.spdx')
>>> spd.write()
True
>>> rmtree(temporary_directory)

colour.io.read_image(path, bit_depth=u'float32')¶

Reads given image using OpenImageIO.

Parameters:	path (unicode) – Image path. bit_depth (unicode, optional) – {‘float32’, ‘uint8’, ‘uint16’, ‘float16’} Image bit_depth.
Returns:	Image as a ndarray.
Return type:	ndarray

Examples

>>> import os
>>> path = os.path.join('tests', 'resources', 'CMSTestPattern.exr')
>>> image = read_image_as_array(path)  

colour.io.write_image(image, path, bit_depth=u'float32')¶

Writes given image using OpenImageIO.

Parameters:	image (array_like) – Image data. path (unicode) – Image path. bit_depth (unicode, optional) – {‘float32’, ‘uint8’, ‘uint16’, ‘float16’} Image bit_depth.
Returns:	Definition success.
Return type:	bool

Examples

>>> import os
>>> path = os.path.join('tests', 'resources', 'CMSTestPattern.exr')
>>> image = read_image_as_array(path)  
>>> path = os.path.join('tests', 'resources', 'CMSTestPattern.png')
>>> write_image(image, path, 'uint8')  
True

colour.io.read_spectral_data_from_csv_file(path, delimiter=u', ', fields=None, default=0)¶

Reads the spectral data from given CSV file in the following form:

390, 4.15003E-04, 3.68349E-04, 9.54729E-03 395, 1.05192E-03, 9.58658E-04, 2.38250E-02 400, 2.40836E-03, 2.26991E-03, 5.66498E-02 ... 830, 9.74306E-07, 9.53411E-08, 0.00000

and returns it as an OrderedDict of dict as follows:

OrderedDict([ (‘field’, {‘wavelength’: ‘value’, ..., ‘wavelength’: ‘value’}), ..., (‘field’, {‘wavelength’: ‘value’, ..., ‘wavelength’: ‘value’})])

Parameters:	path (unicode) – Absolute CSV file path. delimiter (unicode, optional) – CSV file content delimiter. fields (array_like, optional) – CSV file spectral data fields names. If no value is provided the first line of the file will be used as spectral data fields names. default (numeric, optional) – Default value for fields row with missing value.
Returns:	CSV file content.
Return type:	OrderedDict
Raises:	`RuntimeError` – If the CSV spectral data file doesn’t define the appropriate fields.

Notes

A CSV spectral data file should define at least define two fields: one for the wavelengths and one for the associated values of one spectral power distribution.
If no value is provided for the fields names, the first line of the file will be used as spectral data fields names.

Examples

>>> import os
>>> from pprint import pprint
>>> csv_file = os.path.join(
...     os.path.dirname(__file__),
...     'tests',
...     'resources',
...     'colorchecker_n_ohta.csv')
>>> spds_data = read_spectral_data_from_csv_file(csv_file)
>>> pprint(list(spds_data.keys()))
['1',
 '2',
 '3',
 '4',
 '5',
 '6',
 '7',
 '8',
 '9',
 '10',
 '11',
 '12',
 '13',
 '14',
 '15',
 '16',
 '17',
 '18',
 '19',
 '20',
 '21',
 '22',
 '23',
 '24']

colour.io.read_spds_from_csv_file(path, delimiter=u', ', fields=None, default=0)¶

Reads the spectral data from given CSV file and return its content as an OrderedDict of colour.colorimetry.spectrum.SpectralPowerDistribution classes.

Parameters:	path (unicode) – Absolute CSV file path. delimiter (unicode, optional) – CSV file content delimiter. fields (array_like, optional) – CSV file spectral data fields names. If no value is provided the first line of the file will be used for as spectral data fields names. default (numeric) – Default value for fields row with missing value.
Returns:	`colour.colorimetry.spectrum.SpectralPowerDistribution` classes of given CSV file.
Return type:	OrderedDict

Examples

>>> import os
>>> from pprint import pprint
>>> csv_file = os.path.join(
...     os.path.dirname(__file__),
...     'tests',
...     'resources',
...     'colorchecker_n_ohta.csv')
>>> spds = read_spds_from_csv_file(csv_file)
>>> pprint(tuple(spds.items()))  
(('1',
  <...SpectralPowerDistribution object at 0x...>),
 ('2',
  <...SpectralPowerDistribution object at 0x...>),
 ('3',
  <...SpectralPowerDistribution object at 0x...>),
 ('4',
  <...SpectralPowerDistribution object at 0x...>),
 ('5',
  <...SpectralPowerDistribution object at 0x...>),
 ('6',
  <...SpectralPowerDistribution object at 0x...>),
 ('7',
  <...SpectralPowerDistribution object at 0x...>),
 ('8',
  <...SpectralPowerDistribution object at 0x...>),
 ('9',
  <...SpectralPowerDistribution object at 0x...>),
 ('10',
  <...SpectralPowerDistribution object at 0x...>),
 ('11',
  <...SpectralPowerDistribution object at 0x...>),
 ('12',
  <...SpectralPowerDistribution object at 0x...>),
 ('13',
  <...SpectralPowerDistribution object at 0x...>),
 ('14',
  <...SpectralPowerDistribution object at 0x...>),
 ('15',
  <...SpectralPowerDistribution object at 0x...>),
 ('16',
  <...SpectralPowerDistribution object at 0x...>),
 ('17',
  <...SpectralPowerDistribution object at 0x...>),
 ('18',
  <...SpectralPowerDistribution object at 0x...>),
 ('19',
  <...SpectralPowerDistribution object at 0x...>),
 ('20',
  <...SpectralPowerDistribution object at 0x...>),
 ('21',
  <...SpectralPowerDistribution object at 0x...>),
 ('22',
  <...SpectralPowerDistribution object at 0x...>),
 ('23',
  <...SpectralPowerDistribution object at 0x...>),
 ('24',
  <...SpectralPowerDistribution object at 0x...>))

colour.io.write_spds_to_csv_file(spds, path, delimiter=u', ', fields=None)¶

Writes the given spectral power distributions to given CSV file.

Parameters:	spds (dict) – Spectral power distributions to write. path (unicode) – Absolute CSV file path. delimiter (unicode, optional) – CSV file content delimiter. fields (array_like, optional) – CSV file spectral data fields names. If no value is provided the order of fields will be the one defined by the sorted spectral power distributions dict.
Returns:	Definition success.
Return type:	bool
Raises:	`RuntimeError` – If the given spectral power distributions have different shapes.

colour.io.read_spds_from_xrite_file(path)¶

Reads the spectral data from given X-Rite file and returns it as an OrderedDict of colour.colorimetry.spectrum.SpectralPowerDistribution classes.

Parameters:	path (unicode) – Absolute X-Rite file path.
Returns:	`colour.colorimetry.spectrum.SpectralPowerDistribution` classes of given X-Rite file.
Return type:	OrderedDict

Notes

This parser is minimalistic and absolutely not bullet proof.

Examples

>>> import os
>>> from pprint import pprint
>>> xrite_file = os.path.join(
...     os.path.dirname(__file__),
...     'tests',
...     'resources',
...     'xrite_digital_colour_checker.txt')
>>> spds_data = read_spds_from_xrite_file(xrite_file)
>>> pprint(list(spds_data.keys()))  
['X1', 'X2', 'X3', 'X4', 'X5', 'X6', 'X7', 'X8', 'X9', 'X10']