Vimba Image Transform Manual

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 36

Vimba
Vimba Image Transform
Manual
1.5
Vimba Image Transform Manual 1.5 2016-02-27
Legal Noce
Legal Notice
Trademarks
Unless stated otherwise, all trademarks appearing in this document of Allied Vision Technologies are
brands protected by law.
Warranty
The informaon provided by Allied Vision is supplied without any guarantees or warranty whatsoever, be
it specific or implicit. Also excluded are all implicit warranes concerning the negoability, the suitability
for specific applicaons or the non-breaking of laws and patents. Even if we assume that the informaon
supplied to us is accurate, errors and inaccuracy may sll occur.
Copyright
All texts, pictures and graphics are protected by copyright and other laws protecng intellectual property.
It is not permied to copy or modify them for trade use or transfer, nor may they be used on websites.
Allied Vision Technologies GmbH 02/2016
All rights reserved.
Managing Director: Mr. Frank Grube
Tax ID: DE 184383113
Headquarters:
Taschenweg 2a
D-07646 Stadtroda, Germany
Tel.: +49 (0)36428 6770
Fax: +49 (0)36428 677-28
e-mail: info@alliedvision.com
Vimba Image Transform Manual 1.5 2
Contents
Contents
1 Contacng Allied Vision 6
2 Document history and convenons 7
2.1 Documenthistory...................................... 8
2.2 Convenons used in this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.1 Styles........................................ 8
2.2.2 Symbols....................................... 9
3 General aspects of the library 10
3.1 Variants ........................................... 11
3.1.1 Opmizing OpenMP performance . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 Supported image data formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.3 Supportedtransformaons................................. 15
4 API usage 17
4.1 General ........................................... 18
4.2 FillingImageInformaon .................................. 18
4.3 Specifying Transformaon Opons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.3.1 Adding color transformaons . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.3.2 Changing the debayering algorithm . . . . . . . . . . . . . . . . . . . . . . . . 19
4.4 Transformingimages .................................... 20
5 Transformaon examples 21
5.1 Debayering into an Rgb8 image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.2 Debayering into a Mono8 image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.3 Applying a color correcon to an Rgb8 image . . . . . . . . . . . . . . . . . . . . . . . 23
5.4 Debayering a 12-bit image into a Mono16 image with addional color correcon . . . . 24
6 Funcon reference 26
6.1 Informaon ......................................... 27
6.1.1 VmbGetVersion().................................. 27
6.1.2 VmbGetErrorInfo() ................................. 27
6.1.3 VmbGetApiInfoString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.2 Transformaon ....................................... 28
6.2.1 VmbImageTransform() ............................... 28
6.3 Helperfuncons ...................................... 29
6.3.1 VmbSetImageInfoFromInputImage() . . . . . . . . . . . . . . . . . . . . . . . . 29
6.3.2 VmbSetImageInfoFromInputParameters() . . . . . . . . . . . . . . . . . . . . . 30
6.3.3 VmbSetImageInfoFromPixelFormat() . . . . . . . . . . . . . . . . . . . . . . . . 30
6.3.4 VmbSetImageInfoFromString() . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Vimba Image Transform Manual 1.5 3
Contents
6.3.5 VmbSetDebayerMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.3.6 VmbSetColorCorreconMatrix3x3() . . . . . . . . . . . . . . . . . . . . . . . . 32
7 Structs 33
7.1 VmbImage.......................................... 34
7.2 VmbImageInfo........................................ 34
7.3 VmbPixelInfo ........................................ 35
7.4 VmbTransformInfo ..................................... 35
A Supported PFNC transformaons 36
Vimba Image Transform Manual 1.5 4
List of Tables
List of Tables
1 Vimba pixel formats and their counterparts in interface standards (1/2) . . . . . . . . . 13
2 Vimba pixel formats and their counterparts in interface standards (2/2) . . . . . . . . . 14
3 Minimum sizes for certain pixel formats . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4 Supported transformaon formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5 Supported PFNC transformaons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Vimba Image Transform Manual 1.5 5
1 Contacng Allied Vision
1 Contacting Allied Vision
Connect with Allied Vision by funcon
hps://www.alliedvision.com/en/meta-header/contact
Find an Allied Vision office or distributor
hps://www.alliedvision.com/en/about-us/where-we-are
Email
info@alliedvision.com
support@alliedvision.com
Telephone
EMEA: +49 36428-677-0
The Americas: +1 978-225-2030
Asia-Pacific: +65 6634-9027
China: +86 (21) 64861133
Headquarters
Allied Vision Technologies GmbH
Taschenweg 2a
07646 Stadtroda
Germany
Tel: +49 (0)36428 677-0
Fax: +49 (0)36428 677-28
President/CEO: Frank Grube
Registraon Office: AG Jena HRB 208962
Vimba Image Transform Manual 1.5 6
2 Document history and conventions
This chapter includes:
2.1 Document history . . . . . . . . . . . . . . . . . . . . . 8
2.2 Convenons used in this manual . . . . . . . . . . . . 8
2.2.1 Styles ....................... 8
2.2.2 Symbols...................... 9
Vimba Image Transform Manual 1.5 7
2 Document history and convenons
2.1 Document history
Version Date Changes
1.0 2013-03-22 Inial version
1.2 2013-06-18 Small correcons, layout changes
1.3 2014-08-12 Rework of the whole document
1.4 2015-11-09 Renamed several Vimba components and documents (”AVT” no longer in
use), added table for pixel formats and chapter for OpenMP, added return
value descripons for funcons
1.5 2016-02-27 Rework of examples and supported transformaon table
2.2 Convenons used in this manual
To give this manual an easily understood layout and to emphasize important informaon, the following
typographical styles and symbols are used:
2.2.1 Styles
Style Funcon Example
Emphasis Programs, or highlighng important things Emphasis
Publicaon tle Publicaon tles Title
Web reference Links to web pages Link
Document reference Links to other documents Document
Output Outputs from soware GUI Output
Input Input commands, modes Input
Feature Feature names Feature
Vimba Image Transform Manual 1.5 8
2 Document history and convenons
2.2.2 Symbols
Praccal Tip
Safety-related instrucons to avoid malfuncons
Instrucons to avoid malfuncons
i
Further informaon available online
Vimba Image Transform Manual 1.5 9
3 General aspects of the library
This chapter includes:
3.1 Variants .......................... 11
3.1.1 Opmizing OpenMP performance . . . . . . . . 11
3.2 Supported image data formats . . . . . . . . . . . . . . 12
3.3 Supported transformaons . . . . . . . . . . . . . . . . 15
Vimba Image Transform Manual 1.5 10
3 General aspects of the library
The purpose of the Vimba Image Transform library is to transform images received via Vimba APIs into
common image formats. It is part of Vimba and doesn’t require a separate installaon.
Applicaons using Vimba C or C++ API may need to integrate Vimba Image Transform library as an ad-
dional library, whereas a subset of it is seamlessly integrated into the Vimba .NET API via method
Frame.Fill() (See the Vimba.NET Manual if installed). As of Vimba 2.0, two addional funcons enable
seng a compable desnaon format without knowing the PFNC naming scheme.
3.1 Variants
The Vimba Image Transform Library is available in two variants:
• The standard variant executes a funcon call in a single thread.
• The OpenMP variant distributes the funcon calls over mulple processor cores (parallel comput-
ing).
The OpenMP variant is recommended for achieving a high performance with mul-core PCs: Although
addional me is required to schedule the sub tasks, its performance roughly scales by the number of
free cores.
Both library variants have the same interface and the same name, but are delivered in different folders in
the Vimba installaon, allowing you to use the variant you want.
The OpenMP variant of the library can be found in the subdirectory OpenMP beneath the single-threaded
library variant.
Windows supports OpenMP V2.0, whereas Unix-based systems support OpenMP V4.0.
3.1.1 Opmizing OpenMP performance
The movaon behind OpenMP is to speed up computaons by distribung them to the available com-
pung cores (hyper-threading or real ones).
To minimize the addional cost of thread management (starng/stopping threads), the OpenMP runme
environment tries to reuse threads as much as possible.
Since the default values are not adjusted to your parcular use case, we recommend opmizing them to
achieve high performance with low CPU load.
Acve waing tasks and CPU load
Ideally, threads are created when OpenMP is first used in an applicaon, and they are always reused
without being interrupted by the system. In cases where the applicaon has no work items ready when
tasks finish, the waing tasks consume CPU power for a certain me and then become passive.
During acve waing, OpenMP uses high CPU load while no real work is done. This may lead to situa-
ons where OpenMP consumes too many resources although the use case isn’t demanding (low image
resoluon, slow frame rate).
Vimba Image Transform Manual 1.5 11
3 General aspects of the library
Example
If frames arrive at 10 frames per second, there is one work item every 100 ms. Even if image transfor-
maon only takes 10 ms, the threads are acve for about 100 ms. OpenMP is underulized in this case
because 90% of what it’s doing is waing for new work.
If frames arrive at 100 frames per second (frames arrive at 10 ms intervals), OpenMP is working to capac-
ity, and all threads can take on new work directly aer they have finished the previous one.
It is recommended to use the same OpenMP runme environment that the Vimba
Image Transform library uses (Windows: Visual Studio 2010 or higher; Linux:
gomp). In this case, Vimba Image Transform and the applicaon share OpenMP
threads, workload is opmally distributed between worker tasks, and waing
threads get new work fast.
Seng up environment variables
To opmize OpenMP, set up environment variables that determine the number of threads used and
OpenMP’s waing me behavior.
• Linux and Windows
–OMP_NUM_THREADS=[number of threads for OpenMP usage]
Limits the number of threads that are ulized by OpenMP. Lower this value to reduce the CPU
load that OpenMP is taking away from other applicaon threads.
–OMP_WAIT_POLICY=[ACTIVE|PASSIVE]
Changes the policy OpenMP uses when threads wait for new work to arrive. ACTIVE is the
default seng. Under Windows, you can change it only aer installing Microso KB2686593
Hoix. If a too long acve waing me causes high CPU load, change the environment variable
to PASSIVE. Then threads don’t consume CPU power while waing for new work.
• Linux
–GOMP_SPINCOUNT=[number of spins for acve waing]
If OpenMP is set to OMP_WAIT_POLICY=ACTIVE, this variable determines how long a thread
waits acvely with consuming CPU power before waing passively without consuming CPU
power. If work items arrive at a high rate, it is best to let the thread’s spin wait acvely for the
next work load. If work items arrive sporadically, a high spin count leads to unnecessary high
CPU load.
Seng GOMP_SPINCOUNT to 0 is the same as seng OMP_WAIT_POLICY to PASSIVE.
Further reading
•GCC Environment Variables
•Visual Studio OpenMP Environment Variables
3.2 Supported image data formats
In contrast to image file formats, image data formats contain no embedded meta-data, but only pure
images as rectangular arrays of pixels. These pixels have certain characteriscs, e.g. a certain color or bit
Vimba Image Transform Manual 1.5 12
3 General aspects of the library
depth and the endianness for a bit depth of more than eight, and they may appear in a certain order. All
this is described in a pixel format name.
All implemented image transformaons only accept mul-byte pixel formats in
lile-endian byte order.
For this library, pixel formats from the IIDC and GigE Vision interface specificaon, from the Pixel For-
mat Naming Convenon as well as common display formats on Windows and Linux plaorms have been
selected.
The names of the pixel formats mainly match the list of values of the ”PixelFormat” feature in the Standard
Features Naming Convenon of GenICam, but the concrete name depends on the interface standard
according to the following table:
Vimba Pixel format
(VmbPixelFormat...)
GigE Vision<2.0¹
FireWire
PFNC (USB3 Vision,
GigE Vision>=2.0)
Mono8 Mono8 Mono8
Mono10 Mono10 Mono10
Mono10p - Mono10p
Mono12 Mono12 Mono12
Mono12p - Mono12p
Mono12Packed Mono12Packed -
Mono14 Mono14 Mono14
Mono16 Mono16 Mono16
BayerXY²8BayerXY²8 BayerXY²8
BayerXY²10 BayerXY²10 BayerXY²10
BayerXY²10p - BayerXY²10p
BayerXY²12 BayerXY²12 BayerXY²12
BayerXY²12p - BayerXY²12p
BayerXY²12Packed BayerXY²12Packed -
BayerXY²16 BayerXY²16 BayerXY²16
Table 1: Vimba pixel formats and their counterparts in interface standards (1/2)
Vimba Image Transform Manual 1.5 13
3 General aspects of the library
Vimba Pixel format
(VmbPixelFormat...)
GigE Vision<2.0¹
FireWire
PFNC (USB3 Vision,
GigE Vision>=2.0)
Rgb8 RGB8Packed RGB8
Bgr8 BGR8Packed BGR8
Rgba8 RGBA8Packed RGBa8
Bgra8 BGRA8Packed BGRa8
Rgb10 RGB10Packed RGB10
Bgr10 BGR10Packed BGR10
Rgba10 - RGBa10
Bgra10 - BGRa10
Rgb12 RGB12Packed RGB12
Bgr12 BGR12Packed BGR12
Rgba12 - RGBa12
Bgra12 - BGRa12
Rgb16 RGB16Packed RGB16
Bgr16 - BGR16
Rgba16 - RGBa16
Bgra16 - BGRa16
Yuv411 YUV411Packed YUV411_8_UYYVYY
Yuv422 YUV422Packed YUV422_8_UYVY
Yuv444 YUV444Packed YUV8_UYV
YCbCr411_8_CbYYCrYY - YCbCr411_8_CbYYCrYY (layout/values same as Yuv411)
YCbCr422_8_CbYCrY - YCbCr422_8_CbYCrY (layout/values same as Yuv422)
YCbCr8_CbYCr - YCbCr8_CbYCr (layout/values same as Yuv444)
Table 2: Vimba pixel formats and their counterparts in interface standards (2/2)
¹Allied Vision GigE cameras comply with GigE Vision 1.2
²BayerXY is any of BayerGR, BayerRG, BayerGB or BayerBG
Vimba Image Transform Manual 1.5 14
3 General aspects of the library
Since the following pixel formats span a few bytes, or in some cases several lines, their width and height
or size (in pixels) must be divisible by the following values:
Pixel format Width Height Size
Mono12Packed,Mono12p 112
BayerXY¹... 221
Yuv411/YCbCr411_8_CbYYCrYY 411
Yuv422/YCbCr422_8_CbYCrY 211
Table 3: Minimum sizes for certain pixel formats
3.3 Supported transformaons
The ”Target” values from table 4 can be used within the helper funcons 6.3.1 and 6.3.2. Please see an
example in secon 5.1 for the applicaon of a transformaon operaon.
Converng an image from a lower to a higher bit depth aligns the image data to
the least significant bit.
¹BayerXY is any of BayerGR, BayerRG, BayerGB or BayerBG
Vimba Image Transform Manual 1.5 15
3 General aspects of the library
Source Target Mono
8Bit
Mono
16Bit
Color²
8Bit
Color²
16Bit
Mono8 D-D-
Mono10 D-D-
Mono10p D-D-
Mono12 D-D-
Mono12p D-D-
Mono12Packed D-D-
Mono14 D-D-
Mono16 DDD-
BayerXY¹8D-D-
BayerXY¹10 D D D D
BayerXY¹10p D D D D
BayerXY¹12 D D D D
BayerXY¹12p D D D D
BayerXY¹12Packed D D D D
BayerXY¹16 D D D D
Rgb8 D-D-
Bgr8 D-D-
Rgba8 D-D-
Bgra8 D-D-
Yuv411/YCbCr411_8_CbYYCrYY D-D-
Yuv422/YCbCr422_8_CbYCrY D-D-
Yuv444/YCbCr8_CbYCr D-D-
Table 4: Supported transformaon formats
¹BayerXY is any of BayerGR, BayerRG, BayerGB or BayerBG
²Color is any of RGB, RGBA, BGR or BGRA format
Vimba Image Transform Manual 1.5 16
4 API usage
This chapter includes:
4.1 General .......................... 18
4.2 Filling Image Informaon . . . . . . . . . . . . . . . . . 18
4.3 Specifying Transformaon Opons . . . . . . . . . . . . 18
4.3.1 Adding color transformaons . . . . . . . . . . 19
4.3.2 Changing the debayering algorithm . . . . . . . 19
4.4 Transforming images . . . . . . . . . . . . . . . . . . . 20
Vimba Image Transform Manual 1.5 17
4 API usage
4.1 General
Every concrete image transformaon must specify its three parameters:
• The fully-qualified input image (including complete format specificaon)
• The complete output format (plus a pointer to enough memory to hold the transformed image)
• The transformaon itself (including transformaon opons if there is more than one possible way
from the input format to the output format)
VmbImageTransform() is the main funcon, which covers all three transformaon parameters. It uses
two VmbImage pointers to specify the source and desnaon image and a list of VmbTransformInfo
structs to specify the transformaon.
To ease filling the structs that are needed for a successful call of VmbImageTransform(), several helper
funcons for inializing them are available:
• Methods for filling the necessary format informaon of either the input or the output image (de-
scribed in chapter Filling Image Informaon).
• Methods for filling oponal transformaon parameters to invoke special and addional funconality,
as can be seen in chapter Specifying Transformaon Opons.
4.2 Filling Image Informaon
The transformaon library in Vimba 2.0 offers an easy way of seng the appropriate compable des-
naon format. The first two funcons, also described in secon 6.3.1 and 6.3.2, set a compable output
format and relieves the programmer from learning the PFNC naming scheme.
Inialize the VmbImage with:
1. VmbSetImageInfoFromIputImage() by providing an vimba input image, the output layout and
bit depth
2. VmbSetImageInfoFromInputParameters() by providing the input format, the input image size,
the output layout and bit depth
3. VmbSetImageInfoFromPixelFormat() by providing a VmbPixelFormat_t value and the size
4. VmbSetImageInfoFromString() by providing a string that describes the pixel format and the size
(expert)
5. Filling the fields explicitly one by one (not recommended)
4.3 Specifying Transformaon Opons
Depending on your applicaon and the desired image characteriscs, you can choose between several
transformaon opons.
Vimba Image Transform Manual 1.5 18
4 API usage
4.3.1 Adding color transformaons
A common way to transform color images is using a 3x3 matrix with method
VmbSetColorCorrectionMatrix3x3(). The matrix you have to specify is a 3x3 row order float
matrix.
rr rg rb
gr gg gb
br bg bb
4.3.2 Changing the debayering algorithm
Every transformaon of a Bayer image requires defining how to interpolate or combine the color pixels.
Because of beer system performance, a simple 2x2 demosaicing algorithm is the default. Changing this
algorithm is possible with the help of an addional transformaon parameter to VmbImageTransform(),
which can be filled with the help of funcon VmbSetDebayerMode() (using a VmbDebayerMode as in-
put).
VmbDebayerMode can be one of the following values:
Value Descripon
VmbDebayerMode2x2 2x2 with green averaging (this is the default if no debayering algorithm is
added as transformaon opon)
VmbDebayerMode3x3 3x3 with equal green weighng per line
VmbDebayerModeLCAA Debayering with horizontal local color an-aliasing¹
VmbDebayerModeLCAAV Debayering with horizontal and vercal local color an-aliasing¹
VmbDebayerModeYUV422 Debayering with YUV422-alike sub-sampling¹
If one of VmbDebayerModeLCAA,VmbDebayerModeLCAAV, or
VmbDebayerModeYUV422 is used, the input buffers are used as intermedi-
ate buffers for the transformaon for performance reasons. If you intend to
use the input buffer for another purpose, debayer aerwards or copy the input
buffer beforehand.
¹For 8-bit images only
Vimba Image Transform Manual 1.5 19
4 API usage
4.4 Transforming images
When you’ve prepared all the parameters of a transformaon, use the pre-filled structs and call
VmbImageTransform().
Inapplicable transformaon opons are ignored (e.g. debayering opons to a
monochrome input image).
Vimba Image Transform Manual 1.5 20
5 Transformation examples
This chapter includes:
5.1 Debayering into an Rgb8 image . . . . . . . . . . . . . 22
5.2 Debayering into a Mono8 image . . . . . . . . . . . . . 22
5.3 Applying a color correcon to an Rgb8 image . . . . . 23
5.4 Debayering a 12-bit image into a Mono16 image
with addional color correcon . . . . . . . . . . . . . 24
Vimba Image Transform Manual 1.5 21
5 Transformaon examples
5.1 Debayering into an Rgb8 image
Example for a transformaon of a BayerGR8 image with 640x480 pixels into an Rgb8 image of the same
size:
VmbImage sourceImage;
VmbImage destinationImage ;
VmbTransformInfo info;
// set size member for verification inside API
sourceImage .Size = sizeof ( sourceImage );
destinationImage. Size = sizeof ( destinationImage );
// attach the data buffers
sourceImage .Data = pInBuffer;
destinationImage. Data = pOutBuffer;
// fill image info from pixel format
VmbSetImageInfoFromPixelFormat ( VmbPixelFormatBayerGR8 ,
640,
480,
&sourceImage);
// fill destination image info from input image
VmbSetImageInfoFromInputImage ( &sourceImage ,
VmbPixelLayoutRGB,
8,
& destin ationIma ge );
// set the debayering algorithm to simple 2 by 2
VmbSetDebayerMode ( VmbDebayerMode2x2 , &info );
// perform the transformation
VmbImageTransform ( & sourceImage , &destinationImage , &info , 1 );
5.2 Debayering into a Mono8 image
Example for preparing a transformaon of a BayerRG8 image with 640x480 pixels into a Mono8 image of
the same size:
VmbImage sourceImage;
VmbImage destinationImage ;
VmbTransformInfo info;
// set size member for verification inside API
sourceImage .Size = sizeof ( sourceImage );
destinationImage. Size = sizeof ( destinationImage );
// attach the data buffers
sourceImage .Data = pInBuffer;
Vimba Image Transform Manual 1.5 22
5 Transformaon examples
destinationImage. Data = pOutBuffer;
// fill image info from pixel format string
std ::string name ( " PixelFormatBayerRG8 " );
VmbSetImageInfoFromString ( name.c_str(),
static_cast< VmbUint32_t >( name. size() ),
640,
480,
&sourceImage );
// fill image info from pixel known input parameters
VmbSetImageInfoFromInputParameters ( VmbPixelFormatBayerRG8 ,
640,
480,
VmbPixelLayoutMono ,
8
&destinationImage );
// set the debayering algorithm to 3 by 3
VmbSetDebayerMode ( VmbDebayerMode3x3 , &info );
// perform the transformation
VmbImageTransform ( & sourceImage , &destinationImage , &info , 1 );
5.3 Applying a color correcon to an Rgb8
image
Example for applying a color correcon to an Rgb8 image with 640x480 pixels:
VmbImage sourceImage;
VmbImage destinationImage ;
VmbTransformInfo info;
const VmbFloat_t mat [] = { 1.0f, 0.0f, 0.0f,
0.0f, 1.0f, 0.0f,
0.0f, 0.0f, 1.0f };
// set size member for verification inside API
sourceImage .Size = sizeof ( sourceImage );
destinationImage. Size = sizeof ( destinationImage );
// attach the data buffers
sourceImage .Data = pInBuffer;
destinationImage. Data = pOutBuffer;
// fill image info from pixel format
VmbSetImageInfoFromPixelFormat ( VmbPixelFormatRgb8 ,
640,
480,
&sourceImage );
Vimba Image Transform Manual 1.5 23
5 Transformaon examples
// fill destination image info from input image
VmbSetImageInfoFromInputImage ( &sourceImage ,
VmbPixelLayoutRGB,
8,
& destin ationIma ge );
// set the transformation matrix
VmbSetColorCorrectionMatrix3x3 ( mat , &info );
// perform the transformation
VmbImageTransform ( & sourceImage , &destinationImage , &info , 1 );
5.4 Debayering a 12-bit image into a
Mono16 image with addional color
correcon
Example for preparing a transformaon of a BayerGR12 image with 640x480 pixels into a Mono16 image
of the same size:
VmbImage sourceImage;
VmbImage destinationImage ;
Vm bTran sfo rmI nfo info [2];
const VmbFloat_t mat [] = { 1.0f, 0.0f, 0.0f,
0.0f, 1.0f, 0.0f,
0.0f, 0.0f, 1.0f };
// set size member for verification inside API
sourceImage .Size = sizeof ( sourceImage );
destinationImage. Size = sizeof ( destinationImage );
// attach the data buffers
sourceImage .Data = pInBuffer;
destinationImage. Data = pOutBuffer;
// fill image info from pixel format
VmbSetImageInfoFromPixelFormat ( VmbPixelFormatBayerGR12Packed ,
640,
480,
&sourceImage );
// fill destination image info from input image
VmbSetImageInfoFromInputImage ( &sourceImage ,
VmbPixelLayoutMono ,
16,
& destin ationIma ge );
// set the debayering algorithm to 2 by 2
Vimba Image Transform Manual 1.5 24
5 Transformaon examples
Vm bSe tDe bayerM ode ( Vm bDebayerMode2x2 , & info [0] );
// set the transformation matrix
Vm bSet Col orCo rre ctio nMatri x3x3 ( mat , & info [1] );
// perform the transformation
VmbImageTransform ( & sourceImage , &destinationImage , &info , 2 );
Vimba Image Transform Manual 1.5 25
6 Functionreference
This chapter includes:
6.1 Informaon ........................ 27
6.1.1 VmbGetVersion() . . . . . . . . . . . . . . . . . 27
6.1.2 VmbGetErrorInfo() . . . . . . . . . . . . . . . . 27
6.1.3 VmbGetApiInfoString() . . . . . . . . . . . . . . 27
6.2 Transformaon . . . . . . . . . . . . . . . . . . . . . . 28
6.2.1 VmbImageTransform() . . . . . . . . . . . . . . 28
6.3 Helper funcons . . . . . . . . . . . . . . . . . . . . . 29
6.3.1 VmbSetImageInfoFromInputImage() . . . . . . . 29
6.3.2 VmbSetImageInfoFromInputParameters() . . . . . 30
6.3.3 VmbSetImageInfoFromPixelFormat() . . . . . . . 30
6.3.4 VmbSetImageInfoFromString() . . . . . . . . . . 31
6.3.5 VmbSetDebayerMode() . . . . . . . . . . . . . . 31
6.3.6 VmbSetColorCorreconMatrix3x3() . . . . . . . . 32
Vimba Image Transform Manual 1.5 26
6 Funcon reference
6.1 Informaon
6.1.1 VmbGetVersion()
Inquire the library version. This funcon can be called at anyme, even before the library is inialized.
Type Name Descripon
out VmbUint32_t* pValue Contains the library version (Major,Minor,Sub,Build)
•VmbErrorBadParameter: if the given pointer is NULL
6.1.2 VmbGetErrorInfo()
Translate Vimba error codes into a human-readable string.
Type Name Descripon
in VmbError_t errorCode The error code to get a readable string for
out VmbANSIChar_t* pInfo Pointer to a zero terminated string that will contain the
error informaon on return
in VmbUint32_t maxInfoLength The length of the pInfo buffer
•VmbErrorBadParameter: if the given pointer is NULL, or if maxInfoLength is 0
•VmbErrorMoreData: if maxInfoLength is too small to hold the complete error informaon
6.1.3 VmbGetApiInfoString()
Get informaon about the currently loaded Vimba ImageTransform API.
Type Name Descripon
in VmbAPIInfo_t infoType Type of informaon to return
out VmbANSIChar_t* pInfo Pointer to a zero terminated string that will contain the
informaon on return
in VmbUint32_t maxInfoLength The length of the info buffer
•VmbErrorBadParameter: if the given pointer is NULL
Vimba Image Transform Manual 1.5 27
6 Funcon reference
•VmbErrorMoreData: if maxInfoLength is too small to hold the complete informaon
Parameter infoType may be one of the following values:
Value Descripon
VmbAPIInfoAll Return all informaon about the API
VmbAPIInfoPlatform Return informaon about the plaorm the API was built for (x86 or x64)
VmbAPIInfoBuild Return info about the API build (debug or release)
VmbApiInfoTechnology Return info about the supported technologies the API was built for (e.g.
OpenMP)
6.2 Transformaon
6.2.1 VmbImageTransform()
Transform images from one pixel format to another with possible transformaon opons. The transfor-
maon is defined by the provided images and the desired transformaon.
Type Name Descripon
in const VmbImage* pSource Image to transform
in/out VmbImage* pDesnaon Desnaon image
in const VmbTransformInfo* pParameter Oponal transform parameters
in VmbUint32_t parameterCount Number of transform parameters
•VmbErrorBadParameter:
–if any image pointer or their ”Data” members is NULL
–if Width or Height don’t match between source and desnaon
–if one of the parameters for the conversion does not fit
•VmbErrorStructSize: if the image structs size don’t match their ”Size” member
•VmbErrorNotImplemented: if there is no transformaon between source and desnaon format
Fill source and desnaon image info structure with
VmbSetImageInfoFromPixelFormat() or VmbSetImageInfoFromString()
and keep those structures as template. For calls to transform, aach the image
to the ”Data” member. When set, the oponal parameters are constraints on
the transform.
Vimba Image Transform Manual 1.5 28
6 Funcon reference
6.3 Helper funcons
6.3.1 VmbSetImageInfoFromInputImage()
Set image info member values in VmbImage from input VmbImage. Use simple target layout and bit per
pixel values to set the desired target format.
Type Name Descripon
in const VmbImage* pInputmage Source image for transformaon operaon
in VmbPixelLayout_t OutputPixelLayout Pixel layout of the target image
in VmbUint32_t BitPerPixel Bits per pixel of the target image
in/out VmbImage* pOutputImage Pointer to Vimba image to set the info to
•VmbErrorBadParameter:
–if the given pointer is NULL
–if one of the parameters for the conversion does not fit
•VmbErrorNotImplemented: transformaon is not supported
Vimba Image Transform Manual 1.5 29
6 Funcon reference
6.3.2 VmbSetImageInfoFromInputParameters()
Set image info member values in VmbImage from pixel format. Use simple target layout and bit per pixel
values to set the desired target format.
Type Name Descripon
in VmbPixelFormat_t InputPixelFormat PixelFormat describes the pixel format used by
the image data member
in VmbUint32_t Width Width of the image in pixels
in VmbUint32_t Height Height of the image in pixels
in VmbPixelLayout_t OutputPixelLayout Pixel layout of the target image
in VmbUint32_t BitsPerPixel Bits per pixel of the target image
in/out VmbImage* pOutputImage Pointer to Vimba image to set the info to
•VmbErrorBadParameter: if the given pointer is NULL or one of the image struct members is invalid
•VmbErrorNotImplemented: transformaon is not supported
6.3.3 VmbSetImageInfoFromPixelFormat()
This is an expert funcon. Set image info member values in VmbImage from pixel format. Please use table
5 from appendix as reference.
Type Name Descripon
in VmbPixelFormat_t PixelFormat PixelFormat describes the pixel format used by the im-
age data member.
in VmbUint32_t Width Width of the image in pixels
in VmbUint32_t Height Height of the image in pixels
in/out VmbImage* pImage Pointer to Vimba image to set the info to
•VmbErrorBadParameter: if the given pointer is NULL or one of the image struct members is invalid
•VmbErrorStructSize: if the image struct size doesn’t match its ”Size” member
VmbPixelFormat_t can be obtained from Vimba C/C++ APIs frame or from
the PixelFormat feature. For displaying images, it is suggested to use
VmbSetImageInfoFromString() or to look up a matching VmbPixelFormat.
Vimba Image Transform Manual 1.5 30
6 Funcon reference
6.3.4 VmbSetImageInfoFromString()
This is an expert funcon. Set image info member values in VmbImage from string.
Type Name Descripon
in const VmbANSIChar_t* imageFormat Image format as a (const) case insensive string
that is either a PixelFormat (Vmb is oponal) or
a pixel struct name
in VmbUint32_t StringLength The length of the pixel format string
in VmbUint32_t Width Width of the image in pixels
in VmbUint32_t Height Height of the image in pixels
in/out VmbImage* pImage Pointer to Vimba image to set the info to
•VmbErrorBadParameter:
–if one of the given pointers or the ”Data” member in the image is NULL
–if Width or Height don’t match between source and desnaon
–if one of the parameters for the conversion does not fit
•VmbErrorStructSize: if the image struct size does not match its ”Size” member
•VmbErrorResources: if the there was a memory fault during processing
6.3.5 VmbSetDebayerMode()
Set transformaon opons to a predefined debayering mode.
Type Name Descripon
in VmbDebayerMode_t DebayerMode The mode used for debayering the source raw
image, default mode is 2x2 debayering. Debay-
ering modes only work for image widths and
heights divisible by two.
in/out VmbTransformInfo_t* pTransformInfo Parameter that contains informaon about
special transform funconality.
•VmbErrorBadParameter: if the given pointer is NULL
Debayering is only applicable to image formats with both an even width and an
even height.
Vimba Image Transform Manual 1.5 31
6 Funcon reference
6.3.6 VmbSetColorCorreconMatrix3x3()
Set transformaon opons to a 3x3 color matrix transformaon.
Type Name Descripon
in const VmbFloat_t* pMatrix Color correcon matrix
in/out VmbTransformInfo_t* pTransformInfo Parameter that is filled with informaon about
special transform funconality.
•VmbErrorBadParameter: if one of the given pointers is NULL
Vimba Image Transform Manual 1.5 32
7 Structs
This chapter includes:
7.1 VmbImage......................... 34
7.2 VmbImageInfo . . . . . . . . . . . . . . . . . . . . . . . 34
7.3 VmbPixelInfo . . . . . . . . . . . . . . . . . . . . . . . . 35
7.4 VmbTransformInfo . . . . . . . . . . . . . . . . . . . . . 35
Vimba Image Transform Manual 1.5 33
7 Structs
7.1 VmbImage
VmbImage encapsulates image data for the transformaon funcon.
Struct entry Purpose
VmbUint32_t Size Size of the structure
void* Data Pointer to the payload received from Vimba C/C++ API or to the display
image data
VmbImageInfo ImageInfo Internal informaon data used for mapping the images to the correct
transformaon, imageInfo data can be set with VmbSetImageInfo()
helper funcons from VmbPixelFormat_t or format string
7.2 VmbImageInfo
VmbImageInfo contains image informaon needed for the transformaon funcon.
Struct entry Purpose
VmbUint32_t Width The width of the image in pixels. For macro pixel formats like YUV, it is
the width in sub pixels
VmbUint32_t Height The height of the image in pixels
VmbInt32_t Stride The offset from the current line to the next line, a value not equal to
Width is currently not supported
VmbPixelInfo PixelInfo Informaon about the pixel format
Vimba Image Transform Manual 1.5 34
7 Structs
7.3 VmbPixelInfo
VmbPixelInfo describes the pixel format of an image.
Struct entry Purpose
VmbUint32_t BitsPerPixel Number of bits for one image pixel, or sub pixel in macro pixel
formats
VmbUint32_t BitsUsed Number of bits used per pixel, e.g. RGB12 has 48 bits per
pixel and 36 bits used
VmbAlignment_t Alignment For image formats where BitsPerPixel is not equal to bitsUsed,
the alignment specifies the bit layout of the pixel
VmbEndianness_t Endianness Specifies the endianness of pixels that are larger than one
byte
VmbPixelLayout_t PixelLayout Describes the layout of the pixel component, e.g., RGB or BGR
layout
VmbBayerPattern_t BayerPaern For raw image data, this field specifies the color filter array
layout of the sensor
7.4 VmbTransformInfo
Transformaon parameters given as a pointer to a VmbTransformInfo struct are used to invoke special
and addional funconality, which is applied while interpreng the source image (debayering) or trans-
forming the images (color correcon).
Struct entry Purpose
VmbTransformType_t TransformType Transform info type, may be VmbTransformTypeDe-
bayerMode or VmbTransformTypeColorCorrecon-
Matrix
VmbTransformParameter Parameter Transform info variant, may be VmbTransformParam-
eterDebayer or VmbTransformParameterMatrix3x3
Vimba Image Transform Manual 1.5 35
A Supported PFNC transformaons
A Supported PFNC transformations
Source
Target
Mono8
Mono10
Mono12
Mono16
Rgb/Bgr8
Rgba/Bgra8
Rgb/Bgr10
Rgba/Bgra10
Rgb/Bgr12
Rgba/Bgra12
Rgb/Bgr16
Rgba/Bgra16
Yuv422
Mono8 D---D D ------D
Mono10 D---D D -------
Mono10p D---D D -------
Mono12 D---D D -------
Mono12p D---D D -------
Mono12Packed D---D D -------
Mono14 D---D D -------
Mono16 D- - DDD-------
BayerXY¹8D---D D ------D
BayerXY¹10 DD- - D D D D -----
BayerXY¹10p DD- - D D D D -----
BayerXY¹12 D-D-D D - - D D ---
BayerXY¹12p D-D-D D - - D D ---
BayerXY¹12Packed D-D-D D - - D D ---
BayerXY¹16 D- - DDD- - - - DD-
Rgb8 D---D D -------
Bgr8 D---D D -------
Rgba8 / Argb8 D---D D -------
Bgra8 D---D D -------
Yuv411/YCbCr411_8_CbYYCrYY D---D D -------
Yuv422/YCbCr422_8_CbYCrY D---D D ------D
Yuv444/YCbCr8_CbYCr D---D D -------
Table 5: Supported PFNC transformaons
¹BayerXY is any of BayerGR, BayerRG, BayerGB or BayerBG
Vimba Image Transform Manual 1.5 36

Navigation menu