CVB++ 14.1
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< CubeAddition (const Cube &cube1, const Cube &cube2, PixelOverflow overflowHandling=PixelOverflow::Unhandled)
 Element-wise addition of two cubes. More...
 
std::unique_ptr< CubeSubtraction (const Cube &minuend, const Cube &subtrahend, PixelOverflow overflowHandling=PixelOverflow::Unhandled)
 Element-wise subtraction of two cubes. More...
 
std::unique_ptr< CubeMultiplication (const Cube &cube1, const Cube &cube2, PixelOverflow overflowHandling=PixelOverflow::Unhandled)
 Element-wise multiplication of two cubes. More...
 
std::unique_ptr< CubeDivision (const Cube &dividend, const Cube &divisor)
 Element-wise division of two Cubes. More...
 
std::unique_ptr< CubeNormalization (const Cube &cubeIn, const Cube &whiteReference, const Cube &blackReference, NormalizationMethod normalizationMethod)
 Normalizes a cube. More...
 
std::unique_ptr< ImageCubeToXYZ (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< ImageCubeToLab (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< ImageXYZToLab (const Image &xyzImage, const Interpolator &interpolator)
 Converts an image from XYZ to Lab. More...
 
std::unique_ptr< ImageLabToRGB8 (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::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);
static std::unique_ptr< Cube > FromImages(const std::vector< ImagePtr > &images, CubeEncoding bufferLayout)
Initializes a stacked cube using an array of images.
Definition: cube.hpp:111
@ Wavelength
Array of wavelengths with the unit given in FieldID::WavelengthUnit.
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::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
}
}
}
static DataType Int16BppUnsigned() noexcept
Represents 16-bit unsigned integer pixels.
Definition: data_type.hpp:87
static std::unique_ptr< Cube > Create(int numSamples, int numLines, int numBands, DataType dataType, CubeEncoding bufferLayout=CubeEncoding::BandInterleavedByLine)
Creates a Continuous Cube object.
Definition: cube.hpp:71
Linear access properties.
Definition: linear_access_data.hpp:21
std::intptr_t LineInc() const noexcept
Line-increment for linear access.
Definition: linear_access_data.hpp:70
std::uintptr_t BasePtr() const noexcept
Linear access base pointer.
Definition: linear_access_data.hpp:48
std::intptr_t BandInc() const noexcept
Band-increment for linear access.
Definition: linear_access_data.hpp:81
std::intptr_t SampleInc() const noexcept
Sample-increment for linear access.
Definition: linear_access_data.hpp:59
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,
// .. To Lab
auto interpolator = Cvb::Interpolator::Create(*normalizedCube,
Cvb::Spectral::InterpolationMethod::linear);
auto labImg = Cvb::Spectral::CubeToLab(*normalizedCube, *interpolator);
auto rgbImg = Cvb::Spectral::LabToRGB8(*labImg, *interpolator);
static std::unique_ptr< Cube > Load(Cvb::String EnviHeader, Cvb::String EnviBinary)
Static function Loads a cube from ENVI.
Definition: cube.hpp:315
static std::unique_ptr< Interpolator > Create(const Cube &cube, StdObserver stdObserver, StdIlluminant stdIlluminant, InterpolationMethod interpolationMethod)
Creates an Interpolator object.
Definition: interpolator.hpp:57
std::unique_ptr< Image > LabToRGB8(const Image &LabImage, const Interpolator &interpolator)
Converts a Lab image to a sRGB 8bit image.
Definition: convert_color_space.hpp:119
@ CIE2006_2deg
2006 Observer with 2 deg
std::unique_ptr< Cube > Normalization(const Cube &cubeIn, const Cube &whiteReference, const Cube &blackReference, NormalizationMethod normalizationMethod)
Normalizes a cube.
Definition: arithmetic.hpp:107
std::unique_ptr< Image > CubeToLab(const Cube &cube, const Interpolator &interpolator)
Converts a normalized cube to a Lab image.
Definition: convert_color_space.hpp:66

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.

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.

Equal power Spectrum.

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]cube1Any kind of cube is supported as long as the dimensions match with cube2
[in]cube2Any kind of cube is supported as long as the dimensions match with cube1
[in]overflowHandlingIn 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]cubeNormalized linear Cube. Number of bands need to match with the ones in Interpolator handle.
[in]interpolatorContains 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]cubeNormalized linear Cube of datatype float or double. Number of bands need to match with the ones in interpolator.
[in]interpolatorContains the interpolated values of the relative spectral power distribution from color matching functions and standard illuminant.
[in,out]LabImageOutImage 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]cubeNormalized linear Cube with matching number of bands with the ones in interpolator handle.
[in]interpolatorContains 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]cubeNormalized linear Cube of datatype float or double. Number of bands need to match with the ones in Interpolator handle.
[in]interpolatorContains the interpolated values of the relative spectral power distribution from color matching functions and standard illuminant.
[in,out]xyzImageOutImage 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]dividendAny kind of cube is supported as long as the dimensions match with divisor
[in]divisorAny 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]LabImage3-planed image of data type float / double containing the Lab-values
[in]interpolatorContains 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]cube1Any kind of cube is supported as long as the dimensions match with cube2
[in]cube2Any kind of cube is supported as long as the dimensions match with cube1
[in]overflowHandlingIn 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]cubeInSpectral Cube to work on
[in]whiteReferenceThe white reference contains a linear Cube with matching dimensions for samples and bands to cubeIn
[in]blackReferenceThe black reference contains a linear Cube with matching dimensions for samples and bands to cubeIn
[in]normalizationMethodDefines 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]minuendAny kind of cube is supported as long as the dimensions match with subtrahend
[in]subtrahendAny kind of cube is supported as long as the dimensions match with minuend
[in]overflowHandlingIn 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]xyzImage3-planed image of data type float / double containing the XYZ-values
[in]interpolatorContains 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