Spectral (CVSpectral.dll) 15.0
Spectral Cube Handling

Spectral Cube exports. More...

Data Structures

struct  CVSCuboid
 Spectral Cuboid. More...
 
struct  CVSRange
 Index range. More...
 

Enumerations

enum  CVSCubeEncoding { CVSVP_BandInterleavedByLine = 0 , CVSVP_BandSequential = 1 , CVSVP_BandInterleavedByPixel = 2 }
 Cube Encoding. More...
 
enum  CVSCubeType { CVSCT_ContinuousCube = 0 , CVSCT_LinearNonOwningCube = 1 , CVSCT_MappedCube = 2 , CVSCT_StackedCube = 3 }
 Cube Type. More...
 
enum  CVSNormalizationMethod { CVSNM_AverageReferences1 = 0 }
 Normalization Method. More...
 

Functions

cvbres_t CVSCreateContinuousCube (cvbdim_t NumberOfSamples, cvbdim_t NumberOfLines, cvbdim_t NumberOfBands, cvbdatatype_t DataType, CVSCubeEncoding BufferLayout, CVCOMPOSITE &ImageCube)
 Initializes a continuous image cube. More...
 
cvbres_t CVSCreateConvertedCube (CVCOMPOSITE ImageCubeIn, CVSCubeEncoding TargetCubeEncoding, CVCOMPOSITE &ImageCubeOut)
 Converts cube to given TargetCubeEncoding. More...
 
cvbres_t CVSCreateCroppedCube (CVCOMPOSITE ImageCube, const CVSCuboid &ClipBox, cvbbool_t TargetMapped, CVCOMPOSITE &ImageCubeOut)
 Retrieves a cropped image cube. More...
 
cvbres_t CVSCreateCubeFromPointer (void *pCubeMemory, cvbdim_t NumbersOfDimensions[], cvbdatatype_t DataType, intptr_t IncrementsOfDimensions[], PFFINALRELEASE ReleaseCallback, void *pPrivate, CVCOMPOSITE &ImageCubeOut)
 Creates a Linear Non-Owning Cube from pointer. More...
 
cvbres_t CVSCreateDuplicatedContinuousCube (CVCOMPOSITE ImageCubeIn, CVCOMPOSITE &ImageCubeOut)
 Duplicates the image cube as continuous cube. More...
 
cvbres_t CVSCreateStackedCube (IMG ImageArray[], size_t NumberOfImages, CVSCubeEncoding SourceInterleaveType, CVCOMPOSITE &ImageCube)
 Initializes a Stacked ImageCube using an array of images. More...
 
cvbres_t CVSCreateTransposedCube (CVCOMPOSITE ImageCubeIn, CVSCubeEncoding TargetCubeEncoding, cvbbool_t TargetMapped, CVCOMPOSITE &ImageCubeOut)
 Transposes an ImageCube. More...
 
cvbres_t CVSCubeGetBufferView (CVCOMPOSITE ImageCube, IMG &BufferView)
 Retrieves the buffer view of the image cube. More...
 
cvbres_t CVSCubeGetDatatype (CVCOMPOSITE ImageCube, cvbdatatype_t &DataType)
 Retrieves data type of cube. More...
 
cvbres_t CVSCubeGetLinearAccess (CVCOMPOSITE ImageCube, void *&pBaseAddress, intptr_t &SampleInc, intptr_t &LineInc, intptr_t &BandInc)
 Retrieves the spectral linear access data from the cube. More...
 
cvbres_t CVSCubeGetMetaData (CVCOMPOSITE ImageCube, CVSMETADATA &MetaData)
 Get the MetaData of an Image Cube object. More...
 
cvbres_t CVSCubeGetSlice (CVCOMPOSITE ImageCube, cvbdim_t PlaneIndex, cvbbool_t TargetMapped, IMG &ImageOut)
 Retrieves a slice of an image cube. More...
 
cvbres_t CVSCubeGetSpectrumAsDouble (CVCOMPOSITE ImageCube, cvbdim_t SampleIndex, cvbdim_t LineIndex, double SpectralPixelValues[], size_t &NumberOfBands)
 Retrieves a vector containing the pixel value of each band as double. More...
 
cvbres_t CVSCubeGetSpectrumAsInteger (CVCOMPOSITE ImageCube, cvbdim_t SampleIndex, cvbdim_t LineIndex, cvbval_t SpectralPixelValues[], size_t &NumberOfBands)
 Retrieves a vector containing the pixel value of each band as integer. More...
 
cvbres_t CVSCubeGetType (CVCOMPOSITE ImageCube, CVSCubeType &CubeType)
 Retrieves Cube type. More...
 
cvbres_t CVSCubeSetMetaData (CVCOMPOSITE ImageCube, CVSMETADATA MetaData)
 Set the MetaData of an Image Cube object. More...
 
cvbres_t CVSCubeSwapSamplesAndLines (CVCOMPOSITE ImageCubeIn, CVCOMPOSITE &ImageCubeOut)
 Swaps the dimensions for samples and lines and returns a copy. More...
 
cvbres_t CVSLoadEnviFile (const char *HeaderFileName, const char *BinaryFileName, CVCOMPOSITE &ImageCubeOut)
 Load an ENVI-formated spectral cube. More...
 
cvbres_t CVSLoadEnviFileW (const wchar_t *HeaderFileName, const wchar_t *BinaryFileName, CVCOMPOSITE &ImageCubeOut)
 Load an ENVI-formated spectral cube. More...
 
cvbres_t CVSWriteEnviFile (CVCOMPOSITE ImageCubeIn, const char *HeaderFileName, const char *BinaryFileName)
 Write an ImageCube as ENVI. More...
 
cvbres_t CVSWriteEnviFileW (CVCOMPOSITE ImageCubeIn, const wchar_t *HeaderFileName, const wchar_t *BinaryFileName)
 Write an ImageCube as ENVI. More...
 

Detailed Description

Spectral Cube exports.

Version
0.2.0.0

An Image Cube (or Cube) is a representation of a hyper spectral image. To put it in perspective with conventional images: A gray scale image has one value for each pixel. A RGB image has three values for each pixel. An Image Cube however contain of n values for each pixel. These values are located in the spectral domain which is also referred to as band. The number of bands is equal to the number of wavelengths defined in the Image Cube.
In CVB an Image Cube object consists of a Meta Data and a buffer view.

The dimensions of the Image Cube are referred to as sample in the range [0, Samples[, line in the range [0, Lines[ and band in the range [0, Bands[ . The dimensions of an Image in CVB are referred to as x in the range [0, width[ , y in the range [0, height[ and z in the range [0, dimensions[ The Interleaved value in the Meta Data defines the mapping between these two spaces.

There are four distinct types of Image Cubes: Continuous Image Cubes, Mapped Image Cubes, Stacked Image Cubes and Linear Non-Owning Cubes


For details see function documentation.

Enumeration Type Documentation

◆ CVSCubeEncoding

Cube Encoding.

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 CVSVP_BandInterleavedByLine manner: [samples bands lines]
  • Sensors using tunable spectral filters (spectral scanning) deliver images in the CVSVP_BandSequential manner: [samples lines bands]
  • Sensors using snapshot approach may deliver images in the CVSVP_BandInterleavedByPixel manner: [bands samples lines]

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

  • samples: xDisplay
  • lines: yDisplay
Enumerator
CVSVP_BandInterleavedByLine 

Sensors using the pushbroom approach (spatial scanning) deliver images in the CVSVP_BandInterleavedByLine manner: [samples bands lines].

CVSVP_BandSequential 

Sensors using tunable spectral filters (spectral scanning) deliver images in the CVSVP_BandSequential manner: [samples lines bands].

CVSVP_BandInterleavedByPixel 

Sensors using snapshot approach may deliver images in the CVSVP_BandInterleavedByPixel manner: [bands samples lines].

◆ CVSCubeType

Cube Type.

Defines a the type of the cube

Enumerator
CVSCT_ContinuousCube 

Linear Cube with owning buffer.

CVSCT_LinearNonOwningCube 

Linear Cube without owning buffer.

CVSCT_MappedCube 

Mapped Cube holds a reference of a Continuous Cube.

CVSCT_StackedCube 

Stacked Cube with potentially non-linear buffer.

◆ CVSNormalizationMethod

Normalization Method.

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

Default case: CVSNM_AverageReferences1 This means that first white and the black reference are averaged over samples and lines [Samples x Lines x Bands] --> [1 x 1 x Bands]). The forumla used for calculating the normalization is then: (ImgCube - BRef) / (WRef - BRef)

Enumerator
CVSNM_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)

Function Documentation

◆ CVSCreateContinuousCube()

cvbres_t CVSCreateContinuousCube ( cvbdim_t  NumberOfSamples,
cvbdim_t  NumberOfLines,
cvbdim_t  NumberOfBands,
cvbdatatype_t  DataType,
CVSCubeEncoding  BufferLayout,
CVCOMPOSITE &  ImageCube 
)

Initializes a continuous image cube.

The buffer is not initialized with any values

Parameters
[in]NumberOfSamplesNumber of samples
[in]NumberOfLinesNumber of lines
[in]NumberOfBandsNumber of bands
[in]DataTypeData type of each element
[in]BufferLayoutBuffer interleaved type
[out]ImageCubehandle
Returns
See also
CVSCreateStackedCube CVSCreateDuplicatedContinuousCube

◆ CVSCreateConvertedCube()

cvbres_t CVSCreateConvertedCube ( CVCOMPOSITE  ImageCubeIn,
CVSCubeEncoding  TargetCubeEncoding,
CVCOMPOSITE &  ImageCubeOut 
)

Converts cube to given TargetCubeEncoding.

Creates a continous image cube and copies data. The number of Samples, Lines and Bands are equal, but the order in the buffer is different.

Parameters
[in]ImageCubeInInput image cube handle
[in]TargetCubeEncodingTarget Cube encoding
[out]ImageCubeOutConverted image cube handle
Returns
See also
CVSCreateDuplicatedContinuousCube, CVSCubeGetBufferView

◆ CVSCreateCroppedCube()

cvbres_t CVSCreateCroppedCube ( CVCOMPOSITE  ImageCube,
const CVSCuboid ClipBox,
cvbbool_t  TargetMapped,
CVCOMPOSITE &  ImageCubeOut 
)

Retrieves a cropped image cube.

There are two options on cropping an image cube: Mapped and by Buffer When cropping an image cube with TargetMapped = true, the buffer is not copied. Instead the target image cube contains a mapped bufferView which references the source bufferView. There reference count of the source image cube is incremented internally. When cropping in image cube with TargetMapped = false, the cropped subset of the buffer is duplicated to the new image cube.

Parameters
[in]ImageCubeHandle to the input image cube
[in]ClipBoxThe borders of the Clipbox (Min and Max) are included in the target
[in]TargetMappedFlag to define if the output image cube shall be cropped by mapping or by creating a new buffer
[out]ImageCubeOutHandle to the output image cube
Returns
See also
CVSCubeGetSlice CVSCubeGetBufferView

◆ CVSCreateCubeFromPointer()

cvbres_t CVSCreateCubeFromPointer ( void *  pCubeMemory,
cvbdim_t  NumbersOfDimensions[],
cvbdatatype_t  DataType,
intptr_t  IncrementsOfDimensions[],
PFFINALRELEASE  ReleaseCallback,
void *  pPrivate,
CVCOMPOSITE &  ImageCubeOut 
)

Creates a Linear Non-Owning Cube from pointer.

The resulting image cubes is a Linear Non-Owning Cube.

Parameters
[in]pCubeMemoryBase pointer to memory
[in]NumbersOfDimensionsAn array of size 3 containing {numberOfSamples, numberOfLines, numberOfBands}
[in]DataTypecvbdatatype_t of the whole image cube
[in]IncrementsOfDimensionsAn array of size 3 containing {samplesIncrement, linesIncrement, bandsIncrement}. The interleaved type is deduced by the value of the increments. This results in xInc < yInc < zInc.
[in]ReleaseCallbackRelease callback function. This callback function is called when the reference count of ImageCubeOut reaches zero.
[in,out]pPrivatePointer which is passed to the ReleaseCallback to store user state like an object pointer.
[out]ImageCubeOutVariable that receives the handle to the newly created image cube.
Returns
See also
CVSCreateContinuousCube

◆ CVSCreateDuplicatedContinuousCube()

cvbres_t CVSCreateDuplicatedContinuousCube ( CVCOMPOSITE  ImageCubeIn,
CVCOMPOSITE &  ImageCubeOut 
)

Duplicates the image cube as continuous cube.

The resulting image Cube is a deep copy of the input but contains a continuous buffer.

Parameters
[in]ImageCubeInAny kind of image cube handle
[out]ImageCubeOutContinuous image cube
Returns
See also
CVSCreateContinuousCube CVSCubeGetBufferView

◆ CVSCreateStackedCube()

cvbres_t CVSCreateStackedCube ( IMG  ImageArray[],
size_t  NumberOfImages,
CVSCubeEncoding  SourceInterleaveType,
CVCOMPOSITE &  ImageCube 
)

Initializes a Stacked ImageCube using an array of images.

Creates a stacked ImageCube using the given image arrays without copying any buffer.

Attention
Increments the RefCount for each image
Parameters
[in]ImageArraySingle planed image array
[in]NumberOfImagesNumber of images
[in]SourceInterleaveTypeBuffer interleaved type of all images
[out]ImageCubehandle
Returns
See also
CVSCreateContinuousCube CVSCreateDuplicatedContinuousCube

◆ CVSCreateTransposedCube()

cvbres_t CVSCreateTransposedCube ( CVCOMPOSITE  ImageCubeIn,
CVSCubeEncoding  TargetCubeEncoding,
cvbbool_t  TargetMapped,
CVCOMPOSITE &  ImageCubeOut 
)

Transposes an ImageCube.

Creates a transposed ImageCube. The number of Samples, Lines and Bands are equal but the order in the buffer is different The TargetMapped flag determines the way the ImageCube is transposed:

  • true: The BufferView is mapped. In this mode only Continuous and previously transposed ImageCubes are accepted. To call this function with Stacked ImageCubes - which were previously created with an array of images - need to call the function CVSCreateDuplicatedContinuousCube first. The buffer is not copied in this operation. This operation is way faster than transposing the buffer itself.
  • false: In this mode the whole buffer is transposed. In this case all kinds of ImageCubes are accepted as input. The returned ImageCube contains a continuous buffer which is ideal for fast plane wise access (CVSCubeGetSlice). This operation itself is slow.
Parameters
[in]ImageCubeInInput image cube handle
[in]TargetCubeEncodingTarget Cube encoding
[in]TargetMappedSet this flag to false to transpose the buffer (slow). Otherwise to true in order to transpose the view (fast)
[out]ImageCubeOutTransposed image cube handle
Returns
See also
CVSCreateDuplicatedContinuousCube CVSCubeGetBufferView

◆ CVSCubeGetBufferView()

cvbres_t CVSCubeGetBufferView ( CVCOMPOSITE  ImageCube,
IMG BufferView 
)

Retrieves the buffer view of the image cube.

The buffer view is an image handle which contains the buffer of the image cube. This image is of size Width x Height x Dimensions. These dimensions can mapped to samples, lines and bands depending on the interleaved type.

Attention
This function increments the RefCount of BufferView
Parameters
[in]ImageCubehandle
[out]BufferViewView on the Buffer as Image handle
Returns
See also
CVSCubeGetMetaData

◆ CVSCubeGetDatatype()

cvbres_t CVSCubeGetDatatype ( CVCOMPOSITE  ImageCube,
cvbdatatype_t DataType 
)

Retrieves data type of cube.

Parameters
[in]ImageCubeAny kind of image cube handle
[out]DataTypeDatatype of the cube
Returns
See also
CVSCubeGetType

◆ CVSCubeGetLinearAccess()

cvbres_t CVSCubeGetLinearAccess ( CVCOMPOSITE  ImageCube,
void *&  pBaseAddress,
intptr_t &  SampleInc,
intptr_t &  LineInc,
intptr_t &  BandInc 
)

Retrieves the spectral linear access data from the cube.

Parameters
[in]ImageCubeOnly for linear cubes
[out]pBaseAddressWill receive the pointer to the first pixel of the first line if linear access is possible
[out]SampleIncWill receive the increment in the samples direction
[out]LineIncWill receive the increment in the lines direction
[out]BandIncWill receive the increment in the bands direction
Returns
See also
CVSCubeGetType

◆ CVSCubeGetMetaData()

cvbres_t CVSCubeGetMetaData ( CVCOMPOSITE  ImageCube,
CVSMETADATA &  MetaData 
)

Get the MetaData of an Image Cube object.

This function returns the MetaData object of its Image Cube.

Attention
The RefCount of MetaData is incremented. Release the Object when done
Parameters
[in]ImageCubehandle
[out]MetaDatahandle
Returns
See also
MetaData Handling CVSCreateMetaData CVSCubeSetMetaData

◆ CVSCubeGetSlice()

cvbres_t CVSCubeGetSlice ( CVCOMPOSITE  ImageCube,
cvbdim_t  PlaneIndex,
cvbbool_t  TargetMapped,
IMG ImageOut 
)

Retrieves a slice of an image cube.

Get an image handle on a certain plane of the image cube. The image slice returned is a deep copy of the the actual image plane in the cube The slice axis depends on the cube encoding:

  • CVSVP_BandInterleavedByLine : Sample-Band slice
  • CVSVP_BandSequential : Sample-Line slice
  • CVSVP_BandInterleavedByPixel : Band-Sample slice
Parameters
[in]ImageCubehandle
[in]PlaneIndexPlane Index in the range [0, numberOfPlanes[
[in]TargetMappedWhen set to true the output image is a mapped view of the original buffer.
[out]ImageOutSlice as Image handle
Returns
See also
CVSCreateTransposedCube CVSCubeGetBufferView

◆ CVSCubeGetSpectrumAsDouble()

cvbres_t CVSCubeGetSpectrumAsDouble ( CVCOMPOSITE  ImageCube,
cvbdim_t  SampleIndex,
cvbdim_t  LineIndex,
double  SpectralPixelValues[],
size_t &  NumberOfBands 
)

Retrieves a vector containing the pixel value of each band as double.

Retrieves the pixel value of each band at the given position. This function casts each pixel value from the original datatype to double. To get the matching wavelengths call CVSCubeGetMetaData and CVSMetaDataGetAsFloatArray with CVSFI_Wavelength.

Attention
This function is somewhat slow as it casts each pixel value from the original data type to double
Parameters
[in]ImageCubeHandle to the input image cube
[in]SampleIndexIndex of the Sample to get the Spectral Intensity from
[in]LineIndexIndex of the Line to get the Spectral Intensity from
[in,out]SpectralPixelValuesPixel values as double array. To get the array size of field name set SpectralPixelValues to nullptr
[in,out]NumberOfBandsSize of the allocated SpectralPixelValues array. To get the array size of SpectralPixelValues set SpectralPixelValues to nullptr
Returns
See also
CVSCubeGetSpectrumAsInteger CVSCubeGetMetaData CVSMetaDataGetAsFloatArray

◆ CVSCubeGetSpectrumAsInteger()

cvbres_t CVSCubeGetSpectrumAsInteger ( CVCOMPOSITE  ImageCube,
cvbdim_t  SampleIndex,
cvbdim_t  LineIndex,
cvbval_t  SpectralPixelValues[],
size_t &  NumberOfBands 
)

Retrieves a vector containing the pixel value of each band as integer.

Retrieves the pixel value of each band at the given position. This function casts each pixel value from the original datatype to cvbval_t To get the matching wavelengths call CVSCubeGetMetaData and CVSMetaDataGetAsFloatArray with CVSFI_Wavelength.

Attention
This function is somewhat slow as it casts each pixel value from the original data type to cvbval_t
Parameters
[in]ImageCubeHandle to the input image cube
[in]SampleIndexIndex of the Sample to get the Spectral Intensity from
[in]LineIndexIndex of the Line to get the Spectral Intensity from
[in,out]SpectralPixelValuesPixel values as cvbval_t array. To get the array size of field name set SpectralPixelValues to nullptr
[in,out]NumberOfBandsSize of the allocated SpectralPixelValues array. To get the array size of SpectralPixelValues set SpectralPixelValues to nullptr
Returns
See also
CVSCubeGetSpectrumAsDouble CVSCubeGetMetaData CVSMetaDataGetAsFloatArray

◆ CVSCubeGetType()

cvbres_t CVSCubeGetType ( CVCOMPOSITE  ImageCube,
CVSCubeType CubeType 
)

Retrieves Cube type.

Parameters
[in]ImageCubeAny kind of image cube handle
[out]CubeTypeCube type
Returns
See also
CVSCubeGetDatatype

◆ CVSCubeSetMetaData()

cvbres_t CVSCubeSetMetaData ( CVCOMPOSITE  ImageCube,
CVSMETADATA  MetaData 
)

Set the MetaData of an Image Cube object.

This function changes the MetaData object of the Image Cube. The previous MetaData object is discarded. This function does not check if the given MetaData is suitable to the image cube (eg. same dimensions like buffer).

Attention
This function increments the RefCount of the MetaData and takes the ownership
Parameters
[in]ImageCubehandle
[in]MetaDatahandle needs to match with view and buffer of image cube
Returns
See also
MetaData Handling CVSCreateMetaData CVSCubeGetMetaData

◆ CVSCubeSwapSamplesAndLines()

cvbres_t CVSCubeSwapSamplesAndLines ( CVCOMPOSITE  ImageCubeIn,
CVCOMPOSITE &  ImageCubeOut 
)

Swaps the dimensions for samples and lines and returns a copy.

The output Spectral Cube contains a swapped bufferView of the same type. In the meta data the definition for interleave stays the same. The change can be seen in the number of samples and number of lines which are swapped in the output. The function is for interoperability between vendors with different definitions for Samples and Lines in the ENVI-Format

Attention
This function is somewhat slow as it creates a deep copy of the buffer
Parameters
[in]ImageCubeInHandle to the input image cube
[out]ImageCubeOutContains a deep copy of the original image cube. Samples and Lines are swapped
Returns
See also
CVSCreateConvertedCube

◆ CVSLoadEnviFile()

cvbres_t CVSLoadEnviFile ( const char *  HeaderFileName,
const char *  BinaryFileName,
CVCOMPOSITE &  ImageCubeOut 
)

Load an ENVI-formated spectral cube.

No validation of mandatory fields is done

Parameters
[in]HeaderFileNamePath to header file (*.hdr)
[in]BinaryFileNamePath to binary file (*.bin)
[out]ImageCubeOutCube handle
Returns
See also
CVSLoadEnviFileW CVSWriteEnviFile

◆ CVSLoadEnviFileW()

cvbres_t CVSLoadEnviFileW ( const wchar_t *  HeaderFileName,
const wchar_t *  BinaryFileName,
CVCOMPOSITE &  ImageCubeOut 
)

Load an ENVI-formated spectral cube.

No validation of mandatory fields is done

Parameters
[in]HeaderFileNamePath to header file (*.hdr)
[in]BinaryFileNamePath to binary file (*.bin)
[out]ImageCubeOutCube handle
Returns
See also
CVSLoadEnviFile CVSWriteEnviFileW

◆ CVSWriteEnviFile()

cvbres_t CVSWriteEnviFile ( CVCOMPOSITE  ImageCubeIn,
const char *  HeaderFileName,
const char *  BinaryFileName 
)

Write an ImageCube as ENVI.

No validation of mandatory fields is done

Parameters
[in]ImageCubeInCube handle
[in]HeaderFileNamePath to header file (*.hdr)
[in]BinaryFileNamePath to binary file (*.bin)
Returns
See also
CVSWriteEnviFileW CVSLoadEnviFile

◆ CVSWriteEnviFileW()

cvbres_t CVSWriteEnviFileW ( CVCOMPOSITE  ImageCubeIn,
const wchar_t *  HeaderFileName,
const wchar_t *  BinaryFileName 
)

Write an ImageCube as ENVI.

No validation of mandatory fields is done

Parameters
[in]ImageCubeInImageCube Cube handle
[in]HeaderFileNamePath to header file (*.hdr)
[in]BinaryFileNamePath to binary file (*.bin)
Returns
See also
CVSWriteEnviFile CVSLoadEnviFileW