colour.io Package

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:
  • 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']