High-level functions that are photometry related

Functions
cpl_error_code	cpl_photom_fill_blackbody (cpl_vector *spectrum, cpl_unit out_unit, const cpl_vector *evalpoints, cpl_unit in_unit, double temp)
	The Planck radiance from a black-body.

Detailed Description

Synopsis:

#include "cpl_photom.h"

Function Documentation

cpl_photom_fill_blackbody()

cpl_error_code cpl_photom_fill_blackbody	(	cpl_vector *	spectrum,
		cpl_unit	out_unit,
		const cpl_vector *	evalpoints,
		cpl_unit	in_unit,
		double	temp
	)

The Planck radiance from a black-body.

Parameters

spectrum	Preallocated, the computed radiance
out_unit	CPL_UNIT_PHOTONRADIANCE, CPL_UNIT_ENERGYRADIANCE or CPL_UNIT_LESS
evalpoints	The evaluation points (wavelengths or frequencies)
in_unit	CPL_UNIT_LENGTH or CPL_UNIT_FREQUENCY
temp	The black body temperature [K]

Returns

CPL_ERROR_NONE or the relevant _cpl_error_code_

The Planck black-body radiance can be computed in 5 different ways: As a radiance of either energy [J*radian/s/m^3] or photons [radian/s/m^3], and in terms of either wavelength [m] or frequency [1/s]. The fifth way is as a unit-less radiance in terms of wavelength, in which case the area under the planck curve is 1.

The dimension of the spectrum (energy or photons or unit-less, CPL_UNIT_LESS) is controlled by out_unit, and the dimension of the input (length or frequency) is controlled by in_unit.

evalpoints and spectrum must be of equal, positive length.

The input wavelengths/frequencies and the temperature must be positive.

The four different radiance formulas are: Rph1(l,T) = 2pi c/l^4/(exp(hc/klT)-1) Rph2(f,T) = 2pi f^2/c^2/(exp(hf/kT)-1) Re1(l,T) = 2pi hc^2/l^5/(exp(hc/klT)-1) = Rph1(l,T) * hc/l Re2(f,T) = 2pi hf^3/c^2/(exp(hf/kT)-1) = Rph2(f,T) * hf R1(l,T) = 15h^5c^5/(pi^4k^5l^5T^5/(exp(hc/klT)-1) = Rph1(l,T) * h^4c^3/(2pi^5k^5T^5)

where l is the wavelength, f is the frequency, T is the temperature, h is the Planck constant, k is the Boltzmann constant and c is the speed of light in vacuum.

When the radiance is computed in terms of wavelength, the radiance peaks at l_max = CPL_PHYS_Wien/temp. When the radiance is unit-less this maximum, R1(l_max,T), is approximately 3.2648. R1(l,T) integrated over l from 0 to infinity is 1.

A unit-less black-body radiance in terms of frequency may be added later, until then it is an error to combine CPL_UNIT_LESS and CPL_UNIT_FREQUENCY.

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if an input pointer is NULL
• CPL_ERROR_INCOMPATIBLE_INPUT if the size of evalpoints is different from the size of spectrum
• CPL_ERROR_UNSUPPORTED_MODE if in_unit and out_unit are not as requested
• CPL_ERROR_ILLEGAL_INPUT if temp or a wavelength is non-positive

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_ERROR_UNSUPPORTED_MODE, CPL_MATH_2PI, CPL_MATH_PI, cpl_vector_get_data(), cpl_vector_get_data_const(), and cpl_vector_get_size().