Vimba Image Transform Manual
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 36
| Download | |
| Open PDF In Browser | View PDF |
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
2 Document history and conven ons
2.1 Document history . . . . . . . .
2.2 Conven ons used in this manual
2.2.1 Styles . . . . . . . . . .
2.2.2 Symbols . . . . . . . . .
6
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3 General aspects of the library
3.1 Variants . . . . . . . . . . . . . . . . . .
3.1.1 Op mizing OpenMP performance
3.2 Supported image data formats . . . . . .
3.3 Supported transforma ons . . . . . . . .
.
.
.
.
.
.
.
.
4 API usage
4.1 General . . . . . . . . . . . . . . . . . . .
4.2 Filling Image Informa on . . . . . . . . . .
4.3 Specifying Transforma on Op ons . . . . .
4.3.1 Adding color transforma ons . . .
4.3.2 Changing the debayering algorithm
4.4 Transforming images . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
7
8
8
8
9
.
.
.
.
10
11
11
12
15
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
17
18
18
18
19
19
20
5 Transforma on examples
5.1 Debayering into an Rgb8 image . . . . . . . . . . . . . . .
5.2 Debayering into a Mono8 image . . . . . . . . . . . . . .
5.3 Applying a color correc on to an Rgb8 image . . . . . . .
5.4 Debayering a 12-bit image into a Mono16 image with addi
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
onal color correc on
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
21
22
22
23
24
6 Func on reference
6.1 Informa on . . . . . . . . . . . . . . . . . . . .
6.1.1 VmbGetVersion() . . . . . . . . . . . . .
6.1.2 VmbGetErrorInfo() . . . . . . . . . . . .
6.1.3 VmbGetApiInfoString() . . . . . . . . . .
6.2 Transforma on . . . . . . . . . . . . . . . . . .
6.2.1 VmbImageTransform() . . . . . . . . . .
6.3 Helper func ons . . . . . . . . . . . . . . . . .
6.3.1 VmbSetImageInfoFromInputImage() . . .
6.3.2 VmbSetImageInfoFromInputParameters()
6.3.3 VmbSetImageInfoFromPixelFormat() . . .
6.3.4 VmbSetImageInfoFromString() . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
26
27
27
27
27
28
28
29
29
30
30
31
Vimba Image Transform Manual 1.5
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3
Contents
6.3.5
6.3.6
VmbSetDebayerMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VmbSetColorCorrec onMatrix3x3() . . . . . . . . . . . . . . . . . . . . . . . .
7 Structs
7.1 VmbImage . . . . .
7.2 VmbImageInfo . . .
7.3 VmbPixelInfo . . .
7.4 VmbTransformInfo
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
A Supported PFNC transforma ons
Vimba Image Transform Manual 1.5
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
31
32
33
34
34
35
35
36
4
List of Tables
List of Tables
1
2
3
4
5
Vimba pixel formats and their counterparts in interface standards (1/2)
Vimba pixel formats and their counterparts in interface standards (2/2)
Minimum sizes for certain pixel formats . . . . . . . . . . . . . . . . .
Supported transforma on formats . . . . . . . . . . . . . . . . . . . .
Supported PFNC transforma ons . . . . . . . . . . . . . . . . . . . . .
Vimba Image Transform Manual 1.5
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
13
14
15
16
36
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
2.2
Vimba Image Transform Manual 1.5
Document history
Conven ons used
2.2.1 Styles . .
2.2.2 Symbols .
. . . .
in this
. . . .
. . . .
. . . . .
manual
. . . . .
. . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
8
8
8
9
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
3.2
3.3
Vimba Image Transform Manual 1.5
Variants . . . . . . . . . . . . . . . . . .
3.1.1 Op mizing OpenMP performance
Supported image data formats . . . . . .
Supported transforma ons . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11
11
12
15
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 addi 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 computing).
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 compu 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 situaons 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 transforma 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 capacity, 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 Format 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²8
BayerXY²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
1
1
2
BayerXY¹...
2
2
1
Yuv411/YCbCr411_8_CbYYCrYY
4
1
1
Yuv422/YCbCr422_8_CbYCrY
2
1
1
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
Mono8
Mono10
Mono10p
Mono12
Mono12p
Mono12Packed
Mono14
Mono16
BayerXY¹8
BayerXY¹10
BayerXY¹10p
BayerXY¹12
BayerXY¹12p
BayerXY¹12Packed
BayerXY¹16
Rgb8
Bgr8
Rgba8
Bgra8
Yuv411/YCbCr411_8_CbYYCrYY
Yuv422/YCbCr422_8_CbYCrY
Yuv444/YCbCr8_CbYCr
Mono
8Bit
Mono
16Bit
Color²
8Bit
Color²
16Bit
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
-
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
-
-
D
-
D
D
D
D
D
D
-
-
D
D
D
D
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
4.2
4.3
4.4
Vimba Image Transform Manual 1.5
General . . . . . . . . . . . . . . . . . . .
Filling Image Informa on . . . . . . . . . .
Specifying Transforma on Op ons . . . . .
4.3.1 Adding color transforma ons . . .
4.3.2 Changing the debayering algorithm
Transforming images . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
18
18
18
19
19
20
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 (described 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 input).
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 intermediate 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
5.2
5.3
5.4
Vimba Image Transform Manual 1.5
Debayering into an Rgb8 image . . . . . . . . . .
Debayering into a Mono8 image . . . . . . . . . .
Applying a color correc on to an Rgb8 image . .
Debayering a 12-bit image into a Mono16 image
with addi onal color correc on . . . . . . . . . .
. . .
. . .
. . .
22
22
23
. . .
24
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
VmbImage
VmbTransformInfo
sourceImage ;
destinationImage ;
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,
& destinationImage );
// 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
VmbImage
VmbTransformInfo
sourceImage ;
destinationImage ;
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
VmbImage
VmbTransformInfo
const VmbFloat_t
sourceImage ;
destinationImage ;
info;
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,
& destinationImage );
// 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
VmbImage
VmbTransformInfo
const VmbFloat_t
sourceImage ;
destinationImage ;
info [2];
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,
& destinationImage );
// set the debayering algorithm to 2 by 2
Vimba Image Transform Manual 1.5
24
5 Transforma on examples
VmbSetDebayerMode ( VmbDebayerMode2x2 , &info [0] );
// set the transformation matrix
VmbSetColorCorrectionMatrix3x3 ( mat , &info [1] );
// perform the transformation
VmbImageTransform ( & sourceImage , & destinationImage , &info , 2 );
Vimba Image Transform Manual 1.5
25
6
Function reference
This chapter includes:
6.1
6.2
6.3
Vimba Image Transform Manual 1.5
Informa on . . . . . . . . . . . . . . . . . . . .
6.1.1 VmbGetVersion() . . . . . . . . . . . . .
6.1.2 VmbGetErrorInfo() . . . . . . . . . . . .
6.1.3 VmbGetApiInfoString() . . . . . . . . . .
Transforma on . . . . . . . . . . . . . . . . . .
6.2.1 VmbImageTransform() . . . . . . . . . .
Helper func ons . . . . . . . . . . . . . . . . .
6.3.1 VmbSetImageInfoFromInputImage() . . .
6.3.2 VmbSetImageInfoFromInputParameters() .
6.3.3 VmbSetImageInfoFromPixelFormat() . . .
6.3.4 VmbSetImageInfoFromString() . . . . . .
6.3.5 VmbSetDebayerMode() . . . . . . . . . .
6.3.6 VmbSetColorCorrec onMatrix3x3() . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
27
27
27
27
28
28
29
29
30
30
31
31
32
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.
out
Type
Name
Descrip on
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.
in
out
in
Type
Name
Descrip on
VmbError_t
errorCode
The error code to get a readable string for
VmbANSIChar_t*
pInfo
Pointer to a zero terminated string that will contain the
error informa on on return
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.
in
out
in
Type
Name
Descrip on
VmbAPIInfo_t
infoType
Type of informa on to return
VmbANSIChar_t*
pInfo
Pointer to a zero terminated string that will contain the
informa on on return
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 transforma on is defined by the provided images and the desired transforma on.
Type
Name
Descrip on
const VmbImage*
pSource
Image to transform
VmbImage*
pDes na on
Des na on image
in
const VmbTransformInfo*
pParameter
Op onal transform parameters
in
VmbUint32_t
parameterCount
Number of transform parameters
in
in/out
• 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
VmbImage*
pOutputImage
Pointer to Vimba image to set the info to
in/out
• 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
VmbImage*
pOutputImage
Pointer to Vimba image to set the info to
in/out
• 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 image data member.
in
VmbUint32_t
Width
Width of the image in pixels
in
VmbUint32_t
Height
Height of the image in pixels
VmbImage*
pImage
Pointer to Vimba image to set the info to
in/out
• 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
VmbImage*
pImage
Pointer to Vimba image to set the info to
in/out
• 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.
in
in/out
Type
Name
Descrip on
VmbDebayerMode_t
DebayerMode
The mode used for debayering the source raw
image, default mode is 2x2 debayering. Debayering modes only work for image widths and
heights divisible by two.
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.
in
in/out
Type
Name
Descrip on
const VmbFloat_t*
pMatrix
Color correc on matrix
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
7.2
7.3
7.4
Vimba Image Transform Manual 1.5
VmbImage . . . .
VmbImageInfo . .
VmbPixelInfo . . .
VmbTransformInfo
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
34
34
35
35
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 transforming the images (color correc on).
Struct entry
Purpose
VmbTransformType_t
TransformType
Transform info type, may be VmbTransformTypeDebayerMode or VmbTransformTypeColorCorrec onMatrix
VmbTransformParameter
Parameter
Transform info variant, may be VmbTransformParameterDebayer or VmbTransformParameterMatrix3x3
Vimba Image Transform Manual 1.5
35
A Supported PFNC transforma ons
Mono8
Mono10
Mono10p
Mono12
Mono12p
Mono12Packed
Mono14
Mono16
BayerXY¹8
BayerXY¹10
BayerXY¹10p
BayerXY¹12
BayerXY¹12p
BayerXY¹12Packed
BayerXY¹16
Rgb8
Bgr8
Rgba8 / Argb8
Bgra8
Yuv411/YCbCr411_8_CbYYCrYY
Yuv422/YCbCr422_8_CbYCrY
Yuv444/YCbCr8_CbYCr
Yuv422
Rgba/Bgra16
Rgb/Bgr16
Rgba/Bgra12
Rgb/Bgr12
Rgba/Bgra10
Rgb/Bgr10
Rgba/Bgra8
Rgb/Bgr8
Mono16
Mono12
Mono10
Source
Mono8
Supported PFNC transformations
Target
A
D - - - D D - - - - - - D
D - - - D D - - - - - - D - - - D D - - - - - - D - - - D D - - - - - - D - - - D D - - - - - - D - - - D D - - - - - - D - - - D D - - - - - - D - - D D D - - - - - - D - - - D D - - - - - - D
D D - - D D D D - - - - D D - - D D D D - - - - D - D - D D - - D D - - D - D - D D - - D D - - D - D - D D - - D D - - D - - D D D - - - - D D D - - - D D - - - - - - D - - - D D - - - - - - D - - - D D - - - - - - D - - - D D - - - - - - D - - - D D - - - - - - D - - - D D - - - - - - D
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
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : No Page Mode : UseOutlines Page Count : 36 Creator : LaTeX with Navt.cls Title : Vimba Image Transform Manual Subject : Vimba Image Transform Manual- 1.5 Author : - Allied Vision Technologies Producer : XeTeX 0.99992 Create Date : 2016:02:29 16:12:57+01:00EXIF Metadata provided by EXIF.tools