Cvb::Spectral Namespace Reference

Namespace for the Spectral package. More...

Classes
class	Cube
	Spectral Cube object. More...
class	CubeRange
	3D rectangle in the samples, lines and bands domain. More...
class	Interpolator
	Spectral Interpolator object. More...
class	LinearAccessData
	Linear access properties. More...
class	MetaData
	Spectral MetaData object. More...
class	WrappedCube
	Spectral Wrapped cube objects are linear non-owning cubes. More...

Typedefs
using	MetaDataPtr = std::shared_ptr< MetaData >
	Convenience shared pointer for MetaData.
using	CubePtr = std::shared_ptr< Cube >
	Convenience shared pointer for Cube.
using	WrappedCubePtr = std::shared_ptr< WrappedCube >
	Convenience shared pointer for WrappedCube.
using	InterpolatorPtr = std::shared_ptr< Interpolator >
	Convenience shared pointer for Interpolator.

Enumerations
enum class	FieldID {   Interleave = CExports::CVSFI_Interleave , Samples = CExports::CVSFI_Samples , Lines = CExports::CVSFI_Lines , Bands = CExports::CVSFI_Bands ,   DataType = CExports::CVSFI_DataType , ByteOrder = CExports::CVSFI_ByteOrder , FileType = CExports::CVSFI_FileType , HeaderOffset = CExports::CVSFI_HeaderOffset ,   Wavelength = CExports::CVSFI_Wavelength , WavelengthUnit = CExports::CVSFI_WavelengthUnit , Fwhm = CExports::CVSFI_Fwhm }
	FieldID enum class to access fields in the MetaData object. More...
enum class	FieldType {   Invalid = CExports::CVSFT_Invalid , String = CExports::CVSFT_String , Float = CExports::CVSFT_Float , Integer = CExports::CVSFT_Integer ,   StringArray = CExports::CVSFT_StringArray , FloatArray = CExports::CVSFT_FloatArray , IntegerArray = CExports::CVSFT_IntegerArray }
	Data type of a field. More...
enum class	CubeEncoding { BandInterleavedByLine = CExports::CVSVP_BandInterleavedByLine , BandSequential = CExports::CVSVP_BandSequential , BandInterleavedByPixel = CExports::CVSVP_BandInterleavedByPixel }
	View Perspective: Defines how the mapping between a typical x-y image and samples-lines-bands is done. When acquiring images the interleaved type depends on the technology the imaging sensor uses to acquire spectral data. A sequence of images is returned by the camera in the following manner: [xSensor ySensor time] Now depending on the spectral imaging sensor the these dimensions are mapped to samples, lines and bands. More...
enum class	CubeType { ContinuousCube = CExports::CVSCT_ContinuousCube , LinearNonOwningCube = CExports::CVSCT_LinearNonOwningCube , MappedCube = CExports::CVSCT_MappedCube , StackedCube = CExports::CVSCT_StackedCube }
	Defines the type of the cube. More...
enum class	NormalizationMethod { AverageReferences1 = CExports::CVSNM_AverageReferences1 }
	Defines the method used for normalizing the spectral cube with a white and a black reference. More...
enum class	StdIlluminant {   UNDEFINED = CExports::CVSSI_UNDEFINED , E = CExports::CVSSI_E , A = CExports::CVSSI_A , D50 = CExports::CVSSI_D50 ,   D65 = CExports::CVSSI_D65 }
	Defines Standard Illumination. More...
enum class	StdObserver {   UNDEFINED = CExports::CVSSO_UNDEFINED , CIE2006_2deg = CExports::CVSSO_CIE2006_2deg , CIE2006_10deg = CExports::CVSSO_CIE2006_10deg , CIE1964_10deg = CExports::CVSSO_CIE1964_10deg ,   CIE1931_2deg = CExports::CVSSO_CIE1931_2deg }
	Defines Standard Observer. More...
enum class	InterpolationMethod { Linear }
	Defines the interpolation method. More...
enum class	PixelOverflow { Unhandled , Truncate }
	Defines how arithmetic overflows and underflows are handled. More...

Functions
std::unique_ptr< Cube >	Addition (const Cube &cube1, const Cube &cube2, PixelOverflow overflowHandling=PixelOverflow::Unhandled)
	Element-wise addition of two cubes. More...
std::unique_ptr< Cube >	Subtraction (const Cube &minuend, const Cube &subtrahend, PixelOverflow overflowHandling=PixelOverflow::Unhandled)
	Element-wise subtraction of two cubes. More...
std::unique_ptr< Cube >	Multiplication (const Cube &cube1, const Cube &cube2, PixelOverflow overflowHandling=PixelOverflow::Unhandled)
	Element-wise multiplication of two cubes. More...
std::unique_ptr< Cube >	Division (const Cube &dividend, const Cube &divisor)
	Element-wise division of two Cubes. More...
std::unique_ptr< Cube >	Normalization (const Cube &cubeIn, const Cube &whiteReference, const Cube &blackReference, NormalizationMethod normalizationMethod)
	Normalizes a cube. More...
std::unique_ptr< Image >	CubeToXYZ (const Cube &cube, const Interpolator &interpolator)
	Converts a normalized cube to an XYZ image. More...
void	CubeToXYZ (const Cube &cube, const Interpolator &interpolator, Image &xyzImageOut)
	Converts a normalized cube to a XYZ and fills the input image with values. More...
std::unique_ptr< Image >	CubeToLab (const Cube &cube, const Interpolator &interpolator)
	Converts a normalized cube to a Lab image. More...
void	CubeToLab (const Cube &cube, const Interpolator &interpolator, Image &LabImageOut)
	Converts the cube to a Lab image. More...
std::unique_ptr< Image >	XYZToLab (const Image &xyzImage, const Interpolator &interpolator)
	Converts an image from XYZ to Lab. More...
std::unique_ptr< Image >	LabToRGB8 (const Image &LabImage, const Interpolator &interpolator)
	Converts a Lab image to a sRGB 8bit image. More...

Detailed Description

Namespace for the Spectral package.

Online Manual

Common Vision Blox-Tool Spectral

Examples

Spectral/ColorConvert Spectral/CubeAcquisition

Remarks

CMake users: Link to imported target CVB::CvbSpectral \ Here is a little getting started tutorial with the most basic calls

You have a vector of images and want to create a cube

#include <cvb/spectral/spectral.hpp>
#include <cvb/spectral/cube.hpp>
 
std::vector<Cvb::ImagePtr> imgVec = // Get images from camera
Cvb::Spectral::CubePtr stackedCube = Cvb::Cube::FromImages(imgVec, Cvb::Spectral::CubeEncoding::BandInterleavedByLine);
 
Cvb::Spectral::MetaDataPtr metaData = stackedCube->MetaData();
std::vector<double> wavelengths(imgVec.size());
for (int i = 0; i < imgVec.size(); ++i)
  wavelengths.at(i) = 400 + i;
metaData->WriteField<std::vector<double>>(Cvb::Spectral::FieldID::Wavelength, wavelengths);

You want to access the pixel values of the cube

#include <cvb/spectral/spectral.hpp>
#include <cvb/spectral/cube.hpp>
 
int numSamples = 300, numLines = 400, numBands = 255;
Cvb::Spectral::CubePtr continuousCube = Cvb::Cube::Create(numSamples, numLines, numBands, Cvb::DataType::Int16BppUnsigned(), Cvb::Spectral::CubeEncoding::BandInterleavedByLine);
 
Cvb::Spectral::LinearAccessData linAccess = continuousCube->LinearAccess();
for (int sampleIt = 0; sampleIt < numSamples; ++sampleIt)
{
  intptr_t pBaseSample = linAccess.BasePtr() + sampleIt * linAccess.SampleInc();
  for (int lineIt = 0; lineIt < numLines; ++lineIt)
  {
    intptr_t pBaseLine = pBaseSample + lineIt * linAccess.LineInc();
    for (int bandIt = 0; bandIt < numBands; ++bandIt)
    {
      uint16_t& rVal = *reinterpret_cast<uint16_t*>(pBaseLine + bandIt * linAccess.BandInc());
      rVal = sampleIt + lineIt + bandIt; // Creating a diagonal ramp
    }
  }
}

You want the Lab-values from a cube

#include <cvb/spectral/spectral.hpp>
#include <cvb/spectral/cube.hpp>
#include <cvb/spectral/arithmetic.hpp>
#include <cvb/spectral/interpolator.hpp>
#include <cvb/spectral/convert_color_space.hpp>
 
Cvb::Spectral::CubePtr whiteRef = Cvb::Cube::Load(CVB_LIT("/Path/to/WhiteRef.hdr"), CVB_LIT("/Path/to/WhiteRef.bin"));
Cvb::Spectral::CubePtr blackRef = Cvb::Cube::Load(CVB_LIT("/Path/to/BlackRef.hdr"), CVB_LIT("/Path/to/BlackRef.bin"));
Cvb::Spectral::CubePtr imgCube = Cvb::Cube::Load(CVB_LIT("/Path/to/SampleImage.hdr"), CVB_LIT("/Path/to/SampleImage.bin"));
 
// .. normalize
auto normalizedCube = Cvb::Spectral::Normalization(*imgCube,
 *whiteRef, *blackRef,
 Cvb::Spectral::NormalizationMethod::AverageReferences1);
 
// .. To Lab
auto interpolator = Cvb::Interpolator::Create(*normalizedCube,
  Cvb::Spectral::StdObserver::CIE2006_2deg,
  Cvb::Spectral::StdIlluminant::D65,
  Cvb::Spectral::InterpolationMethod::linear);
auto labImg = Cvb::Spectral::CubeToLab(*normalizedCube, *interpolator);
auto rgbImg = Cvb::Spectral::LabToRGB8(*labImg, *interpolator);

Enumeration Type Documentation

CubeEncoding

enum class CubeEncoding

strong

View Perspective: Defines how the mapping between a typical x-y image and samples-lines-bands is done. When acquiring images the interleaved type depends on the technology the imaging sensor uses to acquire spectral data. A sequence of images is returned by the camera in the following manner: [xSensor ySensor time] Now depending on the spectral imaging sensor the these dimensions are mapped to samples, lines and bands.

• Sensors using the pushbroom approach (spatial scanning) deliver images in the CubeEncoding::BandInterleavedByLine manner: [samples bands lines]
• Sensors using tunable spectral filters (spectral scanning) deliver images in the CubeEncoding::BandSequential manner: [samples lines bands]
• Sensors using snapshot approach may deliver images in the CubeEncoding::BandInterleavedByPixel manner: [bands samples lines]

When viewing a spectral cube the spatial dimensions are mapped in the following manner:

• samples: xDisplay
• lines: yDisplay

Enumerator
BandInterleavedByLine	Sensors using the pushbroom approach (spatial scanning) deliver images in the CVSVP_BandInterleavedByLine manner: [samples bands lines]
BandSequential	Sensors using tunable spectral filters (spectral scanning) deliver images in the CVSVP_BandSequential manner: [samples lines bands]
BandInterleavedByPixel	Sensors using snapshot approach may deliver images in the CVSVP_BandInterleavedByPixel manner: [bands samples lines]

CubeType

enum class CubeType

strong

Defines the type of the cube.

Enumerator
ContinuousCube	Linear Cube with owning buffer.
LinearNonOwningCube	Linear Cube without owning buffer.
MappedCube	Mapped Cube holds a reference of a continuous Cube.
StackedCube	Stacked Cube with potentially non-linear buffer.

FieldID

enum class FieldID

strong

FieldID enum class to access fields in the MetaData object.

Enumerator
Interleave	Defines the way the spectral data of the buffer is ordered (CubeEncoding)
Samples	The number of samples.
Lines	The number of lines.
Bands	The number of bands.
DataType	Datatype as defined in the ENVI-format 1 = uint8 2 = int16 3 = int32 4 = flt32 5 = flt64 6 = complex flt32 9 = complex flt64 12 = uint16 13 = uint32 14 = int64 15 = uint64
ByteOrder	Byte order 0 = Least significant byte first (LSF) 1 = Most significant byte first (MSF)
FileType	File type: Default value: "ENVI Standard"
HeaderOffset	Header offset in bytes Number of bytes to skip when reading the ENVI-binary file
Wavelength	Array of wavelengths with the unit given in FieldID::WavelengthUnit.
WavelengthUnit	Wavelength unit Micrometers um Nanometers nm Millimeters mm Centimeters cm Meters m Wavenumber Angstroms GHz MHz Index Unknown
Fwhm	Array of Full-width-half-maximum values The same unit as in FieldID::WavelengthUnit

FieldType

enum class FieldType

strong

Data type of a field.

Enumerator
Invalid	Invalid field when the field has not been defined yet.
String	Field contains string value.
Float	Field contains floating point value.
Integer	Field contains integer value.
StringArray	Field contains string array value.
FloatArray	Field contains floating point array value.
IntegerArray	Field contains integer array value.

InterpolationMethod

enum class InterpolationMethod

strong

Defines the interpolation method.

Enumerator
Linear	linear interpolation, at the border the last value is used

NormalizationMethod

enum class NormalizationMethod

strong

Defines the method used for normalizing the spectral cube with a white and a black reference.

Enumerator
AverageReferences1	White and black reference are averaged over samples and lines ([Samples x Lines x Bands] --> [1 x 1 x Bands]). The normalization formula used is: (ImgCube - BRef) / (WRef - BRef)

PixelOverflow

enum class PixelOverflow

strong

Defines how arithmetic overflows and underflows are handled.

Enumerator
Unhandled	No operation is done on the resulting pixel values.
Truncate	Resulting pixel values are truncated at the data type's min and max values.

StdIlluminant

enum class StdIlluminant

strong

Defines Standard Illumination.

Enumerator
UNDEFINED	Undefined Standard Illuminant.
E	Equal power Spectrum.
A	Illuminant A.
D50	Illuminant D50.
D65	Illuminant D65.

StdObserver

enum class StdObserver

strong

Defines Standard Observer.

Enumerator
UNDEFINED	Undefined Standard Observer.
CIE2006_2deg	2006 Observer with 2 deg
CIE2006_10deg	2006 Observer with 10 deg
CIE1964_10deg	1964 Observer with 10 deg
CIE1931_2deg	1931 Observer with 2 deg

Function Documentation

Addition()

std::unique_ptr< Cube > Addition	(	const Cube &	cube1,
		const Cube &	cube2,
		PixelOverflow	overflowHandling = PixelOverflow::Unhandled
	)

Element-wise addition of two cubes.

Creates a new cube after adding all values of cube1 and cube2 for each element (cube1 + cube2)

Parameters

[in]	cube1	Any kind of cube is supported as long as the dimensions match with cube2
[in]	cube2	Any kind of cube is supported as long as the dimensions match with cube1
[in]	overflowHandling	In case of Truncate: Clips the resulting pixel values to the maximum/minimum possible value of the resulting data type. In case of Unhandled the result might lead to overflow

Returns

Linear cube of the same dimensions and data type. The metadata is a copy from cube1

See also

Subtraction Multiplication Division

CubeToLab() [1/2]

std::unique_ptr< Image > CubeToLab	(	const Cube &	cube,
		const Interpolator &	interpolator
	)

Converts a normalized cube to a Lab image.

Parameters

[in]	cube	Normalized linear Cube. Number of bands need to match with the ones in Interpolator handle.
[in]	interpolator	Contains the interpolated values of the relative spectral power distribution from color matching functions and standard illuminant.

Returns

3-planed float32 image containing the values of Lab (L-value in plane=0, a-value in plane=1, b-value in plane=2).

See also

CubeToXYZ LabToRGB8

Takes an image cube and converts it to a Lab image.

Examples

Spectral/ColorConvert.

CubeToLab() [2/2]

void CubeToLab	(	const Cube &	cube,
		const Interpolator &	interpolator,
		Image &	LabImageOut
	)

Converts the cube to a Lab image.

Takes a normalized image cube and converts it to a Lab image

Parameters

[in]	cube	Normalized linear Cube of datatype float or double. Number of bands need to match with the ones in interpolator.
[in]	interpolator	Contains the interpolated values of the relative spectral power distribution from color matching functions and standard illuminant.
[in,out]	LabImageOut	Image needs to support linear access and be of datatype float / double with the dimensions: samples x lines x 3 [width x height x planes]. This image can be a mapped image

See also

CubeToLab

CubeToXYZ() [1/2]

std::unique_ptr< Image > CubeToXYZ	(	const Cube &	cube,
		const Interpolator &	interpolator
	)

Converts a normalized cube to an XYZ image.

Parameters

[in]	cube	Normalized linear Cube with matching number of bands with the ones in interpolator handle.
[in]	interpolator	Contains the interpolated values of the relative spectral power distribution from color matching functions and standard illuminant.

Returns

3-planed float32 image containing the values of XYZ (X-value in plane=0, Y-value in plane=1, Z-value in plane=2).

See also

CubeToXYZ

Takes an image cube and converts it to a XYZ image.

CubeToXYZ() [2/2]

void CubeToXYZ	(	const Cube &	cube,
		const Interpolator &	interpolator,
		Image &	xyzImageOut
	)

Converts a normalized cube to a XYZ and fills the input image with values.

Parameters

[in]	cube	Normalized linear Cube of datatype float or double. Number of bands need to match with the ones in Interpolator handle.
[in]	interpolator	Contains the interpolated values of the relative spectral power distribution from color matching functions and standard illuminant.
[in,out]	xyzImageOut	Image needs to support linear access and be of datatype float / double with the dimensions: samples x lines x 3 [width x height x planes]. This image can be a mapped image

See also

CubeToXYZ

Takes an image cube and converts it to a XYZ image. In addition this function takes an existing image and fills it with xyz-values.

Division()

std::unique_ptr< Cube > Division	(	const Cube &	dividend,
		const Cube &	divisor
	)

Element-wise division of two Cubes.

Creates a new Cube after dividing all values of dividend and divisor for each element (dividend / divisor)

Parameters

[in]	dividend	Any kind of cube is supported as long as the dimensions match with divisor
[in]	divisor	Any kind of cube is supported as long as the dimensions match with dividend

Returns

Linear cube of the same dimensions and data type. The metadata is a copy from dividend

See also

Addition Subtraction Multiplication

LabToRGB8()

std::unique_ptr< Image > LabToRGB8	(	const Image &	LabImage,
		const Interpolator &	interpolator
	)

Converts a Lab image to a sRGB 8bit image.

Parameters

[in]	LabImage	3-planed image of data type float / double containing the Lab-values
[in]	interpolator	Contains the interpolated values of the relative spectral power distribution from color matching functions and standard illuminant.

Returns

3-planed uint8 image containing the values of sRGB (R-value in plane=0, G-value in plane=1, B-value in plane=2).

See also

CubeToXYZ XYZToLab

Examples

Spectral/ColorConvert.

Multiplication()

std::unique_ptr< Cube > Multiplication	(	const Cube &	cube1,
		const Cube &	cube2,
		PixelOverflow	overflowHandling = PixelOverflow::Unhandled
	)

Element-wise multiplication of two cubes.

Creates a new cube after multiplying all values of cube1 and cube2 for each element (cube1 * cube2)

Parameters

[in]	cube1	Any kind of cube is supported as long as the dimensions match with cube2
[in]	cube2	Any kind of cube is supported as long as the dimensions match with cube1
[in]	overflowHandling	In case of Truncate: Clips the resulting pixel values to the maximum/minimum possible value of the resulting data type. In case of Unhandled the result might lead to overflow

Returns

Linear cube of the same dimensions and data type. The metadata is a copy from cube1

See also

Addition Subtraction Division

Normalization()

std::unique_ptr< Cube > Normalization	(	const Cube &	cubeIn,
		const Cube &	whiteReference,
		const Cube &	blackReference,
		NormalizationMethod	normalizationMethod
	)

Normalizes a cube.

This function creates a normalized cube using the white- and black reference and the object cube. More details in NormalizationMethod

Note

This function will throw an error for stacked cubes (CubeType::StackedCube). If you want to use this function anyhow, duplicate your cube with Cube::Clone to get a continous cube.

Parameters

[in]	cubeIn	Spectral Cube to work on
[in]	whiteReference	The white reference contains a linear Cube with matching dimensions for samples and bands to cubeIn
[in]	blackReference	The black reference contains a linear Cube with matching dimensions for samples and bands to cubeIn
[in]	normalizationMethod	Defines the normalization method. More detailed information in NormalizationMethod

Returns

Linear cube of the same dimensions and data type. The metadata is a copy from cubeIn

See also

Addition Subtraction Multiplication Division

Examples

Spectral/ColorConvert.

Subtraction()

std::unique_ptr< Cube > Subtraction	(	const Cube &	minuend,
		const Cube &	subtrahend,
		PixelOverflow	overflowHandling = PixelOverflow::Unhandled
	)

Element-wise subtraction of two cubes.

Creates a new cube after subtracting all values of minuend and subtrahend for each element (minuend - subtrahend)

Parameters

[in]	minuend	Any kind of cube is supported as long as the dimensions match with subtrahend
[in]	subtrahend	Any kind of cube is supported as long as the dimensions match with minuend
[in]	overflowHandling	In case of Truncate: Clips the resulting pixel values to the maximum/minimum possible value of the resulting data type. In case of Unhandled the result might lead to overflow

Returns

Linear cube of the same dimensions and data type. The metadata is a copy from minuend

See also

Addition Multiplication Division

XYZToLab()

std::unique_ptr< Image > XYZToLab	(	const Image &	xyzImage,
		const Interpolator &	interpolator
	)

Converts an image from XYZ to Lab.

Parameters

[in]	xyzImage	3-planed image of data type float / double containing the XYZ-values
[in]	interpolator	Contains the interpolated values of the relative spectral power distribution from color matching functions and standard illuminant.

Returns

3-planed float32 image containing the values of Lab (L-value in plane=0, a-value in plane=1, b-value in plane=2).

See also

CubeToXYZ LabToRGB8