VmbNUC API Function Reference

Overview

VmbNUCCreateMetaData() VmbNUCFreeMetaData() VmbNUCMetaDataAddFloatGain() VmbNUCMetaDataAddEnumGain() VmbNUCMetaDataAddSensorTemp() VmbNUCMetaDataAddExposureTime()

VmbNUCFrameInit() VmbNUCFrameFree()

VmbNUCReadImageFromFile() VmbNUCWriteImageToFile()

VmbNUCAddImage() VmbNUCAddFrame()

VmbNUCGetIdealValue()

VmbNUCProcess()

VmbNUCExport()

VmbNUCPrintVersion()

API Version

void VmbNUCPrintVersion(void): Print library version and the copyright.

Metadata Initialization

VmbNUCError_t VmbNUCCreateMetaData(VmbNUCHandle_t *metaDataHandle)

Create structure for holding VmbNUC metadata, required for export. Initializes default values for GainType (‘Unknown’), Gain (0.0), TemperatureSetpoint (-999.0), ExposureTime (0.0).

Parameters:

metaDataHandle – [inout] Pointer to the meta data handle.

Returns:

An error code indicating success or the type of error that occurred.

VmbNUCError_t VmbNUCFreeMetaData(VmbNUCHandle_t metaDataHandle)

Free memory that was allocated for the metadata structure.

Parameters:

metaDataHandle – [in] Metadata handle.

Returns:

An error code indicating success or the type of error that occurred.

VmbNUCError_t VmbNUCMetaDataAddFloatGain(VmbNUCHandle_t metaDataHandle, float gain)

Add float value for Gain to the metadata structure. Sets GainType = ‘Float’.

Parameters:

metaDataHandle – [in] Pointer to the meta data handle.
gain – [in] Gain value.

Returns:

An error code indicating success or the type of error that occurred.

VmbNUCError_t VmbNUCMetaDataAddEnumGain(VmbNUCHandle_t metaDataHandle, const char *gain)

Add enum value for Gain to the metadata structure. Sets GainType = ‘Enum’.

Parameters:

metaDataHandle – [in] Pointer to the meta data handle.
gain – [in] Gain value (supported: ‘Gain0’, ‘Gain1’, ‘Gain2’).

Returns:

An error code indicating success or the type of error that occurred.

VmbNUCError_t VmbNUCMetaDataAddSensorTemp(VmbNUCHandle_t metaDataHandle, float temperatureSetpoint)

Add float value for TemperatureSetpoint to the metadata structure.

Parameters:

metaDataHandle – [in] Pointer to the meta data handle.
temperatureSetpoint – [in] TemperatureSetpoint value.

Returns:

An error code indicating success or the type of error that occurred.

VmbNUCError_t VmbNUCMetaDataAddExposureTime(VmbNUCHandle_t metaDataHandle, float exportureTime)

Add float value for ExposureTime to the metadata structure.

Parameters:

metaDataHandle – [in] Pointer to the meta data handle.
exportureTime – [in] ExposureTime value.

Returns:

An error code indicating success or the type of error that occurred.

typedef void *VmbNUCHandle_t: Handle, e.g. for a metadata structure.

Frame Initialization

VmbNUCError_t VmbNUCFrameInit(const VmbUint32_t width, const VmbUint32_t height, const VmbPixelFormat_t pixelFormat, VmbNUCFrame_t *frame)

Initialize the provided frame instance by populating members and allocating memory for the imageData buffer. All frames that were initialized with this function must be freed via VmbNUCFrameFree.

Parameters:

width – [in] Image width.
height – [in] Image height.
pixelFormat – [in] Pixel format; for values see VmbPixelFormatType.
frame – [inout] Pointer to VmbNUC_Frame_t instance that should be initialized. All fields of this instance will be zeroed during initialization.

Returns:

An error code indicating success or the type of error that occurred.

void VmbNUCFrameFree(VmbNUCFrame_t *frame)

Free memory that was allocated for the imageData buffer via VmbNUCFrameInit.

Parameters:

frame – [in] frame instance for which memory should be freed

struct VmbNUCFrame

Frame structure for holding averaged image data for NUC calculation.

Public Members

VmbPixelFormat_t pixelFormat: Pixel format of the image.

VmbUint8_t *imageData: The start of the image data buffer, if present: size equal bufferSize, or NULL.

VmbUint32_t bufferSize: The size of the imageData buffer (width * height * bytesPerPixel)

VmbImageDimension_t width: Width of an image.

VmbImageDimension_t height: Height of an image.

VmbUint8_t avgImagesCnt: Number of averaged images.

Read/Write Image File

VmbNUCError_t VmbNUCReadImageFromFile(const char *filePath, const VmbPixelFormat_t pixelFormat, VmbNUCFrame_t *frame)

Read image data from the given filePath. This function supports PGM files with up to 16 bit of grayscale data.

Parameters:

filePath – [in] Absolute path to a local image file.
pixelFormat – [in] PixelFormat of the image data store in the local image file.
frame – [out] Frame holding the image data loaded from filePath. It is initialized internally via VmbNUCFrameInit. That means the user is responsible to call VmbNUCFrameFree for the frame before disposing of it.

Returns:

An error code indicating success or the type of error that occurred.

VmbNUCError_t VmbNUCWriteImageToFile(const char *filePath, const VmbNUCFrame_t *frame)

Write pixel values stored in frame to a PGM file at the given filePath.

Parameters:

filePath – [in] Absolute path at which the image file should be stored.
frame – [in] Frame that holds the image data that should be stored in the image file.

Returns:

An error code indicating success or the type of error that occurred.

Averaged Image

VmbNUCError_t VmbNUCAddImage(const VmbUint32_t width, const VmbUint32_t height, const VmbPixelFormat_t pixelFormat, void *srcImageData, VmbNUCFrame_t *dstImage)

Add one frame to one of the two averaged images (low/high exposure).

Parameters:

width – [in] Image width.
height – [in] Image height.
pixelFormat – [in] Pixel format of the image data.
srcImageData – [in] Raw image buffer.
dstImage – [out] Output image (including its metadata: size, format etc.)

Returns:

An error code indicating success or the type of error that occurred.

VmbNUCError_t VmbNUCAddFrame(const VmbNUCFrame_t *srcImage, VmbNUCFrame_t *dstImage)

Add one VmbFrame to one of the two averaged images (low/high exposure).

Parameters:

srcImage – [in] Input image (including its metadata: size, format etc.)
dstImage – [out] Output image (including its metadata: size, format etc.)

Returns:

An error code indicating success or the type of error that occurred.

VmbNUCError_t VmbNUCGetIdealValue(const VmbNUCFrame_t *srcImage, VmbUint32_t *idealValue)

Get ideal value of the specified picture (low/high exposure). The ideal value is the value, that every pixel ideally should report for the uniform exposure scenario.

Parameters:

srcImage – [in] Averaged image, for which the ideal value should be calculated
idealValue – [out] Calculated ideal value.

Returns:

An error code indicating success or the type of error that occurred.

NUC Process

VmbNUCError_t VmbNUCProcess(const VmbNUCFrame_t *avgImage0, const VmbUint32_t idealValue0, const VmbNUCFrame_t *avgImage1, const VmbUint32_t idealValue1, const VmbNUCFrame_t *srcImage, VmbNUCFrame_t *dstImage)

Start the NUC calculation process.

Parameters:

avgImage0 – [in] Averaged image 0 (low exposure)
idealValue0 – [in] Ideal value of the low exposure image.
avgImage1 – [in] Averaged image 1 (high exposure)
idealValue1 – [in] Ideal value of the high exposure image.
srcImage – [in] Source image
dstImage – [out] Corrected image

Returns:

An error code indicating success or the type of error that occurred.

NUC Export

VmbNUCError_t VmbNUCExport(const VmbNUCHandle_t metaData, const VmbNUCExportParameter_t expParam, const VmbNUCFrame_t *avgImage0, const VmbUint32_t idealValue0, const VmbNUCFrame_t *avgImage1, const VmbUint32_t idealValue1)

Start the export of NUC data into the binary file, which can be uploaded to the camera.

Parameters:

metaData – [in] Handle to the structure containing meta-data for the binary creation.
expParam – [in] Structure containing export parameters (like the export format, path).
avgImage0 – [in] Averaged image 0 (low exposure)
idealValue0 – [in] Ideal value of the low exposure image.
avgImage1 – [in] Averaged image 1 (high exposure)
idealValue1 – [in] Ideal value of the high exposure image.

Returns:

An error code indicating success or the type of error that occurred.

struct VmbNUCExportParameter

Structure for holding parameter for export of NUC data into a binary file.

Public Members

VmbNUCExportType_t exportType: Type of the export file.

const char *path: Absolute path, where the export file should be created.

VmbUint32_t serialNumber: Optional parameter for Goldeye Pro: serial number of the camera.

typedef struct VmbNUCExportParameter VmbNUCExportParameter_t: Structure for holding parameter for export of NUC data into a binary file.

Common Types

typedef unsigned char VmbUint8_t: 8-bit unsigned integer.

typedef unsigned int VmbUint32_t: 32-bit unsigned integer.

typedef int VmbInt32_t: 32-bit signed integer.

typedef VmbUint32_t VmbPixelFormat_t: Type for the pixel format; for values see VmbPixelFormatType.

enum VmbNUCErrorType

Error codes, returned by most functions.

Values:

enumerator VmbNUCErrorSuccess: No error.

enumerator VmbNUCErrorBadParameter: One of the parameters is invalid (usually an illegal pointer)

enumerator VmbNUCErrorInvalidValue: The value is not valid; either out of bounds or not an increment of the minimum.

enumerator VmbNUCErrorNotImplemented: API feature is not implemented.

enumerator VmbNUCErrorNotSupported: API feature is not supported.

enumerator VmbNUCErrorIO: IO error for example in reading/writing files.

enumerator VmbNUCErrorNoData: The function has no data to work on.

enumerator VmbNUCErrorUnknown: Error condition unknown.

enumerator VmbNUCErrorWrongSize: Wrong buffer size.

enumerator VmbNUCErrorInternalFault: Unexpected fault in the underlying std-function.

enumerator VmbNUCErrorOutOfMemory: Unable to allocate required memory.

enumerator VmbNUCErrorCustom: The minimum error code to use for user defined error codes to avoid conflict with existing error codes.

enum VmbPixelFormatType

Pixel format types. As far as possible, the Pixel Format Naming Convention (PFNC) has been followed, allowing a few deviations. If data spans more than one byte, it is always LSB aligned, except if stated differently.

Values:

enumerator VmbPixelFormatMono8: Monochrome, 8 bits (PFNC: Mono8)

enumerator VmbPixelFormatMono10: Monochrome, 10 bits in 16 bits (PFNC: Mono10)

enumerator VmbPixelFormatMono10p: Monochrome, 10 bits continuously packed (4x10 bits in 40 bits) (PFNC: Mono10p)

enumerator VmbPixelFormatMono12: Monochrome, 12 bits in 16 bits (PFNC: Mono12)

enumerator VmbPixelFormatMono12Packed: Monochrome, 2x12 bits in 24 bits (GEV:Mono12Packed)

enumerator VmbPixelFormatMono12p: Monochrome, 2x12 bits in 24 bits (PFNC: MonoPacked)

enumerator VmbPixelFormatMono14: Monochrome, 14 bits in 16 bits (PFNC: Mono14)

enumerator VmbPixelFormatMono16: Monochrome, 16 bits (PFNC: Mono16)

enumerator VmbPixelFormatBayerGR8: Bayer-color, 8 bits, starting with GR line (PFNC: BayerGR8)

enumerator VmbPixelFormatBayerRG8: Bayer-color, 8 bits, starting with RG line (PFNC: BayerRG8)

enumerator VmbPixelFormatBayerGB8: Bayer-color, 8 bits, starting with GB line (PFNC: BayerGB8)

enumerator VmbPixelFormatBayerBG8: Bayer-color, 8 bits, starting with BG line (PFNC: BayerBG8)

enumerator VmbPixelFormatBayerGR10: Bayer-color, 10 bits in 16 bits, starting with GR line (PFNC: BayerGR10)

enumerator VmbPixelFormatBayerRG10: Bayer-color, 10 bits in 16 bits, starting with RG line (PFNC: BayerRG10)

enumerator VmbPixelFormatBayerGB10: Bayer-color, 10 bits in 16 bits, starting with GB line (PFNC: BayerGB10)

enumerator VmbPixelFormatBayerBG10: Bayer-color, 10 bits in 16 bits, starting with BG line (PFNC: BayerBG10)

enumerator VmbPixelFormatBayerGR12: Bayer-color, 12 bits in 16 bits, starting with GR line (PFNC: BayerGR12)

enumerator VmbPixelFormatBayerRG12: Bayer-color, 12 bits in 16 bits, starting with RG line (PFNC: BayerRG12)

enumerator VmbPixelFormatBayerGB12: Bayer-color, 12 bits in 16 bits, starting with GB line (PFNC: BayerGB12)

enumerator VmbPixelFormatBayerBG12: Bayer-color, 12 bits in 16 bits, starting with BG line (PFNC: BayerBG12)

enumerator VmbPixelFormatBayerGR12Packed: Bayer-color, 2x12 bits in 24 bits, starting with GR line (GEV:BayerGR12Packed)

enumerator VmbPixelFormatBayerRG12Packed: Bayer-color, 2x12 bits in 24 bits, starting with RG line (GEV:BayerRG12Packed)

enumerator VmbPixelFormatBayerGB12Packed: Bayer-color, 2x12 bits in 24 bits, starting with GB line (GEV:BayerGB12Packed)

enumerator VmbPixelFormatBayerBG12Packed: Bayer-color, 2x12 bits in 24 bits, starting with BG line (GEV:BayerBG12Packed)

enumerator VmbPixelFormatBayerGR10p: Bayer-color, 10 bits continuously packed, starting with GR line (PFNC: BayerGR10p)

enumerator VmbPixelFormatBayerRG10p: Bayer-color, 10 bits continuously packed, starting with RG line (PFNC: BayerRG10p)

enumerator VmbPixelFormatBayerGB10p: Bayer-color, 10 bits continuously packed, starting with GB line (PFNC: BayerGB10p)

enumerator VmbPixelFormatBayerBG10p: Bayer-color, 10 bits continuously packed, starting with BG line (PFNC: BayerBG10p)

enumerator VmbPixelFormatBayerGR12p: Bayer-color, 12 bits continuously packed, starting with GR line (PFNC: BayerGR12p)

enumerator VmbPixelFormatBayerRG12p: Bayer-color, 12 bits continuously packed, starting with RG line (PFNC: BayerRG12p)

enumerator VmbPixelFormatBayerGB12p: Bayer-color, 12 bits continuously packed, starting with GB line (PFNC: BayerGB12p)

enumerator VmbPixelFormatBayerBG12p: Bayer-color, 12 bits continuously packed, starting with BG line (PFNC: BayerBG12p)

enumerator VmbPixelFormatBayerGR16: Bayer-color, 16 bits, starting with GR line (PFNC: BayerGR16)

enumerator VmbPixelFormatBayerRG16: Bayer-color, 16 bits, starting with RG line (PFNC: BayerRG16)

enumerator VmbPixelFormatBayerGB16: Bayer-color, 16 bits, starting with GB line (PFNC: BayerGB16)

enumerator VmbPixelFormatBayerBG16: Bayer-color, 16 bits, starting with BG line (PFNC: BayerBG16)

enumerator VmbPixelFormatRgb8: RGB, 8 bits x 3 (PFNC: RGB8)

enumerator VmbPixelFormatBgr8: BGR, 8 bits x 3 (PFNC: BGR8)

enumerator VmbPixelFormatRgb10: RGB, 12 bits in 16 bits x 3 (PFNC: RGB12)

enumerator VmbPixelFormatBgr10: RGB, 12 bits in 16 bits x 3 (PFNC: RGB12)

enumerator VmbPixelFormatRgb12: RGB, 12 bits in 16 bits x 3 (PFNC: RGB12)

enumerator VmbPixelFormatBgr12: RGB, 12 bits in 16 bits x 3 (PFNC: RGB12)

enumerator VmbPixelFormatRgb14: RGB, 14 bits in 16 bits x 3 (PFNC: RGB12)

enumerator VmbPixelFormatBgr14: RGB, 14 bits in 16 bits x 3 (PFNC: RGB12)

enumerator VmbPixelFormatRgb16: RGB, 16 bits x 3 (PFNC: RGB16)

enumerator VmbPixelFormatBgr16: RGB, 16 bits x 3 (PFNC: RGB16)

enumerator VmbPixelFormatArgb8: ARGB, 8 bits x 4 (PFNC: RGBa8)

enumerator VmbPixelFormatRgba8: RGBA, 8 bits x 4, legacy name.

enumerator VmbPixelFormatBgra8: BGRA, 8 bits x 4 (PFNC: BGRa8)

enumerator VmbPixelFormatRgba10: RGBA, 8 bits x 4, legacy name.

enumerator VmbPixelFormatBgra10: RGBA, 8 bits x 4, legacy name.

enumerator VmbPixelFormatRgba12: RGBA, 8 bits x 4, legacy name.

enumerator VmbPixelFormatBgra12: RGBA, 8 bits x 4, legacy name.

enumerator VmbPixelFormatRgba14: RGBA, 8 bits x 4, legacy name.

enumerator VmbPixelFormatBgra14: RGBA, 8 bits x 4, legacy name.

enumerator VmbPixelFormatRgba16: RGBA, 8 bits x 4, legacy name.

enumerator VmbPixelFormatBgra16: RGBA, 8 bits x 4, legacy name.

enumerator VmbPixelFormatYuv411: YUV 4:1:1 with 8 bits (PFNC: YUV411_8_UYYVYY, GEV:YUV411Packed)

enumerator VmbPixelFormatYuv422: YUV 4:2:2 with 8 bits (PFNC: YUV422_8_UYVY, GEV:YUV422Packed)

enumerator VmbPixelFormatYuv444: YUV 4:4:4 with 8 bits (PFNC: YUV8_UYV, GEV:YUV444Packed)

enumerator VmbPixelFormatYuv422_8: YUV 4:2:2 with 8 bits Channel order YUYV (PFNC: YUV422_8)

enumerator VmbPixelFormatYCbCr8_CbYCr: YCbCr 4:4:4 with 8 bits (PFNC: YCbCr8_CbYCr) - identical to VmbPixelFormatYuv444.

enumerator VmbPixelFormatYCbCr422_8: YCbCr 4:2:2 8-bit YCbYCr (PFNC: YCbCr422_8)

enumerator VmbPixelFormatYCbCr411_8_CbYYCrYY: YCbCr 4:1:1 with 8 bits (PFNC: YCbCr411_8_CbYYCrYY) - identical to VmbPixelFormatYuv411.

enumerator VmbPixelFormatYCbCr601_8_CbYCr: YCbCr601 4:4:4 8-bit CbYCrt (PFNC: YCbCr601_8_CbYCr)

enumerator VmbPixelFormatYCbCr601_422_8: YCbCr601 4:2:2 8-bit YCbYCr (PFNC: YCbCr601_422_8)

enumerator VmbPixelFormatYCbCr601_411_8_CbYYCrYY: YCbCr601 4:1:1 8-bit CbYYCrYY (PFNC: YCbCr601_411_8_CbYYCrYY)

enumerator VmbPixelFormatYCbCr709_8_CbYCr: YCbCr709 4:4:4 8-bit CbYCr (PFNC: YCbCr709_8_CbYCr)

enumerator VmbPixelFormatYCbCr709_422_8: YCbCr709 4:2:2 8-bit YCbYCr (PFNC: YCbCr709_422_8)

enumerator VmbPixelFormatYCbCr709_411_8_CbYYCrYY: YCbCr709 4:1:1 8-bit CbYYCrYY (PFNC: YCbCr709_411_8_CbYYCrYY)

enumerator VmbPixelFormatYCbCr422_8_CbYCrY: YCbCr 4:2:2 with 8 bits (PFNC: YCbCr422_8_CbYCrY) - identical to VmbPixelFormatYuv422.

enumerator VmbPixelFormatYCbCr601_422_8_CbYCrY: YCbCr601 4:2:2 8-bit CbYCrY (PFNC: YCbCr601_422_8_CbYCrY)

enumerator VmbPixelFormatYCbCr709_422_8_CbYCrY: YCbCr709 4:2:2 8-bit CbYCrY (PFNC: YCbCr709_422_8_CbYCrY)

enumerator VmbPixelFormatYCbCr411_8: YCbCr 4:1:1 8-bit YYCbYYCr (PFNC: YCbCr411_8)

enumerator VmbPixelFormatYCbCr8: YCbCr 4:4:4 8-bit YCbCr (PFNC: YCbCr8)

enumerator VmbPixelFormatLast