Baumer-GAPI2 SDK Programmer‘s Guide -...
42
Baumer-GAPI2 SDK Programmer‘s Guide
Transcript of Baumer-GAPI2 SDK Programmer‘s Guide -...
Baumer-GAPI2 SDKProgrammer‘s Guide
2
3
Table of Contents1. Introduction .............................................................................................................. 5
2. Baumer-GAPI2 .......................................................................................................... 52.1 Baumer-GAPI2 Stack Components ........................................................................ 5
2.1.1 Hardware ......................................................................................................... 52.1.2 Baumer GenICam-API...................................................................................... 5
2.2 Software Components ............................................................................................ 62.2.1 Baumer-GAPI2 Modules .................................................................................. 6
2.3 Gerneral System Requirements .............................................................................. 6
3. Central Idea Behind BGAPI2 ................................................................................... 83.1 Interface Classes ................................................................................................... 9
3.1.1 INode, NodeMap, Node .................................................................................... 93.1.2 EventControl ................................................................................................... 12
3.2 Main Classes ........................................................................................................ 143.2.1 System............................................................................................................ 143.2.2 Interface.......................................................................................................... 153.2.3 Device............................................................................................................. 153.2.4 DataStream .................................................................................................... 163.2.5 Buffer .............................................................................................................. 17
3.3 List Classes ........................................................................................................... 183.3.1 SystemList ...................................................................................................... 193.3.2 InterfaceList .................................................................................................... 193.3.3 DeviceList ....................................................................................................... 193.3.4 DataStreamList ............................................................................................... 193.3.5 BufferList ........................................................................................................ 20
3.4 Additional Classes ................................................................................................. 223.4.1 Image.............................................................................................................. 223.4.2 Image Processor ............................................................................................ 233.4.3 Trace............................................................................................................... 24
3.5 IException ............................................................................................................ 25
4. Programming Basics in Baumer-GAPI2 ............................................................... 264.1 Setting System variables ...................................................................................... 27
4.2 Implementation ..................................................................................................... 284.2.1 Implementation C++ ....................................................................................... 284.2.2 Implementation in C# ..................................................................................... 30
5. Application development with Baumer-GAPI ..................................................... 335.1 First steps ............................................................................................................. 33
5.1.1 Preparation ..................................................................................................... 345.1.2 SystemList ...................................................................................................... 355.1.3 Open a System ............................................................................................... 355.1.4 Get the InterfaceList and fill it ......................................................................... 365.1.5 Open an Interface ........................................................................................... 365.1.6 Get the DeviceList and fill it ............................................................................ 365.1.7 Open a Device ................................................................................................ 375.1.8 Get DataStreamList and fill it .......................................................................... 375.1.9 Open a DataStream ....................................................................................... 385.1.10 Create the BufferList and allocate Buffer memory ........................................ 385.1.11 Allocate Image Buffer to the DataStream ..................................................... 395.1.12 Start Camera and fill the Image Buffer ......................................................... 405.1.13 Releasing the resources ............................................................................... 41
4
HardwareDriver NIC
TCP/IPstack
Gigabit EthernetPlug in
Baumer Filter Driver(optional)
Network Inte face Card (NIC)
Hardware Driver
Hardware
Customer
C# Component
Operatingsystem
Baumer-GAPI2GenTL Consumer
GenTL Producer
Image LibraryCo or
management
Imageprocess ng
Algorithms
HardwareDriver X
BaumerDriver X
interface XPlug in
Hardware X
Bus Driver
USB 3 0Plug in
Baumer USB 3 0 Device Driver
USB 3 0 Host Con roller
Baumer GAPI2 Library
C++ API
Framework (OS module)
C# module
Application (image processing interface written by the customer)
Figure 1 ►BGAPI 2 stack
Framework:Baumer-GAPI 2 is tested with Windows®: .NET™ 4.0
5
Introduction1. This programmer’s guide is addressed to programmers who need to integrate Baumer cameras into their own software. It corresponds to the GenICam API of Baumer-GAPI2 and the use of Microsoft® Visual Studio® from version 2005 (C++) and version 2010 (C#).
Baumer-G2. API2Baumer-GAPI2 is the abbreviation for Baumer “Generic Application Programming Inter-face” in version 2. With this API Baumer provides an interface for optimal integration and control of Baumer cameras.
The fundamental basis for BGAPI2 is the GenICam (Generic Interface for Cameras) stan-dard and the employment of GenTL as standardized interface.
BGAPI2 provides interfaces to several programming languages as C++ and to the .NET™ Framework on Windows® operating systems, which in turn allow the use of other lan-guages such as C# or VB.NET.
2.1 Baumer-GAPI2 Stack Components
Hardware 2.1.1
2.1.1.1 Gigabit Ethernet
Working with Baumer Gigabit Ethernet cameras requires the installation of appropriate hardware – such as a NIC (Network Interface Card) on your PC.
NoticeFor Gigabit Ethernet Baumer recommends the employment of NICs with an Intel® chip-set.
The hardware is delivered with a hardware driver which is required in order to establish communications between hardware and software.
Baumer GenICam-API2.1.2
Producer2.1.2.1
Within the GenICam Producer a complete camera system is mapped to the software. The Producer provides the 5 main classes that are used in any BGAPI2 application.
Consumer2.1.2.2
The consumer is the counterpart of the producer mentioned above. Here all the available producers are managed (loading, opening, closing).
Furthermore the consumer provides all additional classes and enables the exception han-dling.
Framework2.1.2.3
A Framework represents a software platform, which provides a runtime environment, an API and several services to the programmer. It is required, for example, when program-ming in C# or VB.NET.
API stands for “Application Programming Interface”.An API is a software interface between two programs, usually between operating system and an application.
API:
Installation:For further information on installing the Baumer-GAPI SDK refer to the appropri-ate Installation Guide for your operating system and hardware interface.
CameraL nk® USB3VisionGigE Vis on®
(GEV)
Programmer
▲ Figure 2The GenICam vision
GenICam:GenICam stands for Generic Interface for Cameras and is a generic programming interface for industrial cameras. It’s goal is to decouple indus-trial camera interfaces from the user application programming interface (API).
6
Software Components2.2 The BGAPI2 is package of several libraries in form of dynamic link libraries (dll's). Thereat previously mentioned GenTL producer represents an exception. The producer is deliv-ered as a common transport interface (.cti-file).
2.2.1 Baumer-GAPI2 Modules
The Baumer-GAPI2 is partitioned into several modules. Depending on your chosen pro-gramming language, either more or fewer of these may be used.
2.2.1.1 Baumer-GAPI2 Library
As previously stated, Baumer-GAPI2 supports several programming languages to create an application. Therefore the Baumer-GAPI2 Library represents a uniform API for the cross-interface camera control. Here, global camera control functions are defined.
2.2.1.2 Image Library
This library includes several functions for image processing and image editing.
Programming Languages2.2.1.3
As shown in Figure 1, the implementation of C++ and C# is partially realized hierarchi-cally.
This means that the C++ API and C# API resorts directly to the BGAPI2 library.
Gerneral System Requirements2.3
Single-camera system Recommended
Multi-camera system Recommended
CPU DUAL-Core, Intel® Xeon® W3503 DUAL-Core, Intel® Xeon® W3503Clock 2.4 GHz 2.4 GHzRAM 4 GB 4 GBOperating system (OS)
Microsoft® Windows® 7 32 / 64 bit systems (required for USB 3.0) Microsoft® Windows® 8 32 / 64 bit systems (required for USB 3.0)
Compiler Microsoft Compiler only (included in Microsoft® Visual Studio)
Frame-work (optional)
Windows® OS: .NET™ Framework 4.0 or higher for C# implementation
7
Inte
rface
C
lass
es
Nam
espa
ce: E
vent
s
Nam
espa
ce: E
xcep
tions
Nam
espa
ce: B
GAP
I2
Cla
sses
of B
GA
PI2
Mai
n C
lass
es
List
C
lass
es
Addi
tiona
l C
lass
es
Exce
ptio
n C
lass
es
Syst
emIn
terf
ace
Dev
ice
Dat
aStr
eam
Bu�e
r
Inte
rfac
eLis
tSy
stem
List
Inva
lidPa
ram
eter
Exce
ptio
n
IOEx
cept
ion
Abo
rtEx
cept
ion
Inva
lidBu
�er
Exce
ptio
n
Not
Ava
ilabl
eExc
epti
on
Even
tCon
trol
SysV
arM
issi
ngEx
cept
ion
Reso
urce
InU
seEx
cept
ion
Acc
essD
enie
dExc
epti
on
Inva
lidH
andl
eExc
epti
on
Inva
lidId
Exce
ptio
n
Inte
rfac
eEv
entC
ontr
ol
PnPE
vent
Dev
iceE
vent
Dev
ice
Even
tCon
trol
Dat
aStr
eam
Even
tCon
trol
NoD
ataE
xcep
tion
Not
Impl
emen
tedE
xcep
tion
Not
Init
ializ
edEx
cept
ion
Erro
rExc
epti
on
IExc
epti
on
Dev
iceL
ist
Dat
aStr
eam
List
Bu�
erLi
st
INO
DE
NO
DE
Imag
e Pr
oces
sor
Trac
eIm
age
NO
DEM
AP
▲ Figure 3Classes of BGAPI2
8
Central Idea Behind BGAPI23. The fundamental idea behind the Baumer SDK was to free the programmer from need of defining and instantiating all the required and usable objects and to transfer these tasks to the BGAPI2.
The API bases on five main classes (System, Interface, Device, DataStream, Buffer) and the use of the GenTL interface.
On BGAPI2 there are two entry points for the user. On one hand, application program-ming can be started by using the system list. On the other hand BGAPI2 offers the pos-sibility to use the image processor separately.
En
try point
BGAPI2
Programmer
SystemListImage Processor
System
System 0System 1
...
NodeListNodeTree
Node 0Node 1
...Node n
InterfaceList
Interface 0Interface 1
...Interface n
Interface
Device
DataStream
Bu�er
Image
DeviceList
Device 0Device 1
...Device n
DataStreamList
Data Stream 0Data Stream 1
...Data Stream n
Bu�erList
Bu�er 0Bu�er 1
...Bu�er n
NodeListNodeTree
Node 0Node 1
...Node n
(Remote-) NodeList(Remote-) NodeTree
Node 0Node 1
...Node n
NodeListNodeTree
Node 0Node 1
...Node n
NodeListNodeTree
Node 0Node 1
...Node n
▲ Figure 3Fundamental Approach of GenAPI and GenTL
Figure 4 ►Interaction diagram
Baumer GenICam API
GenTL
GenAPI
Third Party Tools
Consumer Consumer
Producer 1e g GigE S andard
Producer
Producer 2e g bgapi gige
Producer 3e g bgapi2 usb c i
Customer Application
9
Interface Classes 3.1 The major part of the functionality of BGAPI2 is provided by the two interface classes NodeInterface and EventInterface. For instance the main classes inhertit functionalities from INode.
INode, NodeMap, Node3.1.1
INode
Parent class for: System Interface Device DataStream Buffer
The INode class allows the direct access to all compo-nents of the xml-file.
Functions of the class INode
BGAPI2::INode:: ...
GetNode(String name); Returns a pointer to a specified object of the Node class.
GetNodeTree(); Returns the tree view of all nodes of the XML file.
GetNodeList(); Returns a one-dimensional list of the nodes of the XML file.
NodeMap
Member of INode
NodeMap is the collection class for nodes.
Functions of the class NodeMap
BGAPI2::NodeMap:: ...
GetNode(String name); Returns a pointer to a specified object of the Node class.
GetNodeTree(); Returns the tree view of all nodes of the XML fileGetNodeList(); Returns a one-dimensional list of the nodes of the XML
file.
10
NODE
Member of INode
A Node presents one feature from the XML descrip-tion file.
Functions of the class Node
BGAPI2::Node:: ...
GetInterface(); Returns the inferface of the respective Node.GetExtension(); Returns custom specific data from the XML-file.GetToolTip(); Returns a Tool-Tip.GetDescription(); Returns the the description of the feature.GetName(); Returns the name of the feature.GetDisplayName(); Returns a meaningful for displaying in Graphical User
Inferfaces (GUI).GetVisibility(); Returns the visibility of the node (Invisible, Beginner,
Expert, Guru).GetImplemented(); Returns the status of implementation of the feature.GetAvailable(); Returns the availability of the feature.GetLocked(); Returns information whether the feature is locked
(read only) or not.GetImposedAccessMode(); Returns the the startup behavior of the featureGetCurrentAccessMode(); Returns the current access modeGetAlias(); Returns the name of another node which decribes the
same feature in a different mannerGetRepresentation(); Gives a hint how to display the feature within the ap-
plication (GUI).GetUnit(); Returns the unit of the feature [e.g. ms, Hz].HasUnit(); Query whether the feature has a unit.GetEventID(); Returns the ID of an event.Enumeration value
GetEnumNodeList(); Returns a list of Enum Entries of the feature.Set value in string format (General purpose function)GetValue(); Retrieving values as a converted string.SetValue( String Value );
Setting a value as string, regardless of the interface type (it will be converted from string).
Integer functions (only for Integer Interface)GetInt(); Retrieving of values.SetInt( bo_int64 value );
Setting values as an integer.
GetIntMin(); Returns the minimum value.GetIntMax(); Returns the maximum value.GetIntInc(); Returns the step size for setting a value.Float functions (only for Float Interface)GetDouble(); Retrieving of value.SetDouble( bo_double value );
Setting values as an float.
GetDoubleMin(); Returns the minimum value.GetDoubleMax(); Returns the maximum value.String functions (only for String interface)
11
GetMaxStringLength(); Retrieving the maximum length of the string.GetString(); Retrieving of values.SetString( String value );
Setting values as an string.
Command value (only for Command Interface)Execute(); One-time exexution of a command.IsDone(); Query, whether the command has been executed.Boolean value (only for Bool Interface)GetBool(); Retrieving of the values (true / false).SetBool( bo_bool value );
Setting boolean values.
Access type (only for Category interface)GetNodeTree(); Returns the tree view of all nodes.GetNodeList(); Returns a one-dimensional list of the nodes.SelectorsIsSelector(); Query, whether the feature is a selector.GetSelectedNodeList(); Returns a list of features that are influenced by the
Selector.Register access (only for Register Interface)getLength(); Read a length of an address.getAdress(); Read an address.get( void *pBuffer, bo_unint64 len);
Read a register.
set(void *pBuffer, bo_uint64 len);
Write a register.
12
EventControl3.1.2
This class provides access to custom events as well as the event node.
InterfaceEventControl3.1.2.1
Interface EventControl
Inherits from: EventControl
Parent class for: Interface
InterfaceEventControl provides the Plug´n Play event.
Functions of the class InterfaceEventControl
BGAPI2::InterfaceEventControl:: ...
RegisterPnPEvent(EventMode eventMode);
Enables the P´n´P Eventhandling.
UnregisterPnPEvent(); Disables the P´n´P Eventhandling.GetPnPEvent(PnPEvent * pP-nPEvent, bo_using64 iTim-eout);
Polling function for the P´n´P Events.
DeviceEventControl3.1.2.2
Device EventControl
Inherits from: Eventcontrol
Parent class for: Device
This class provides access to standard events.
Functions of the class Device EventControl
BGAPI2::DeviceEventControl:: ...
RegisterDeviceEvent(Event eventMode);
Enables standard compliant device events, speci-fied within the xml description file.
UnregisterDeviceEvent(); Disable standard compliant device events, speci-fied within the xml description file.
GetDeviceEvent(DeviceEvent * pDeviceEvent, bo_uint64 iTimeout);
Polling function for event devices.
13
DataStreamEventControl 3.1.2.3
DataStreamEventControl
Inherits from: EventControl
Parent class for: DataStream
DataStreamEventControl provices "new Buffere-vent", which is used a image notification.
Functions of the class DataStream EventControl
BGAPI2::DataStreamEventControl:: ...
RegisterNewBufferEvent(); Enables standard compliant buffer events speci-fied within the xml description file.
UnregisterNewBuffer-Event();
Disables tandard compliant buffer events speci-fied within the xml description file.
GetFilledBuffer(bo_uint64 iTimeout);
Polling with timeout.
CancelGetFilledBuffer(); Cancellation routine for GetfilledBuffer.
14
Main Classes3.2 The main classes represent the fundamental logical and physical components of the im-age processing system.
The main classes are: System, Interface, Device, DataStream and Buffer.
System3.2.1
System
Inherits from: EventControl INode
The System is the abstraction of the Producer and previ-ously mentioned producer.
Functions of the class System
BGAPI2::System:: ...
System(String file-path);
Setting the path to the producer file.
Open(); Open a System (producer file).Close(); Close the System (producer file).GetInterfaces(); Returns a list of all available interfaces (InterfaceList).GetID(); Returns the unique string identifier of the System, which is
used in the SystemList.GetVendor(); Returns the name of the producer vendor.GetModel(); Returns the model name of the producer.GetVersion(); Returns the version number of system file.GetTLType(); Returns type of System (GEV, USB3, ...) .GetName(); Returns the name of system file.GetPathName(); Retrieving the filepath.GetDisplayName(); Returns a meaningful name of the System for display only.
15
Interface3.2.2
Interface
Inherits from: Interface EventControl INode
The class Interface represents a physical interface, e.g. GEV or a logical interface, such as USB.
Functions of the class Interface
BGAPI2::Interface:: ...
Open(); Open an Interface.Close(); Close the Interface.GetDevices(); Returns the list of available devices for this interface (De-
viceList).GetID(); Returns the unique string ID which is used in InterfaceList.GetDisplayName(); Returns a meaningful name of the Interface for display only.GetTLType(); Returns interface type (GEV, USB, ...).
Device3.2.3
Device
Inherits from: Device EventControl INode
The main class Device is used to retrieve information (e.g. model, manufacturer, access modes) of the device (camera) and also to control the device.
Functions of the class Device
BGAPI2::Device:: ...
OpenReadOnly(); Open as read only, no parameters can be changed.Open(); Open a device with read and write access.OpenExclusive(); Open a device exclusively with read and write access, the
device is blocked for other software tools.Close(); Close the device.IsOpen(); Open a device with read only access, changing parameters
is denied.StartStacking(); Start command for parameter stacking (parameters will be
queued).WriteStack(); Single write command to transmit all stacked parameters
at once.GetDataStreams(); Returns a list of available DataStreams.GetID(); Returns the unique string ID of device (such as MAC ad-
dress on GEV).GetVendor(); Returns the vendor of the camera.
16
GetModel(); Returns the camera model (e.g. MXGC20c).GetTLType(); Returns the device type of system (such as GEV,
USB3, ...). GetDisplayName(); Returns a meaningful name, for display only.GetAccessStatus(); Returns how the device is / can be opened:
Open(); OpenReadOnly(); OpenExclusive();
GetPayloadSize(); Returns the Payloadsize.GetRemoteNode (String name);
Returns a pointer to a specified object of the connected device.
GetRemoteNode-Tree();
Returns the tree view of all nodes of the XML file of the connected device.
GetRemoteNodeL-ist();
Returns a one-dimensional list of the nodes of the XML file of the connected devices.
GetRemoteConfigura-tionFile();
Returns the XML description file of the connected device.
DataStream3.2.4
DataStream
Inherits from: DataStream EventControl Node
This class is responsable for the buffer handling.
Functions of the class DataStream
BGAPI2::DataStream:: ...
Open(); Open a DataStream.Close(); Close the DataStream.GetBufferList(); Returns a list of already created buffers (BufferList).GetID(); Returns the unique string identifier of the DataStream.GetPayloadSize(); Returns the size Payloadsize.GetDefinesPayload-Size();
Checks if Datastream can provide Payloadsize.
GetIsGrabbing(); Returns whether the DataStream is already started or not.GetTLType(); Returns the type of the DataStream.StartAcquisition (bo_uint64 iNumToAcquire);
Starts the acquisition of a specified number of images.
StopAcquisition(); Stops the image acquisition.AbortAcquisition(); Aborts the image acquisition immediately.
17
Buffer3.2.5
Buffer
Inherits from: EventControl
This class realizes the data access to the memory. It con-tains information about the received data (e.g. image size, pixel format) too.
The Buffer module encapsulates a single memory buffer. Its purpose is to act as the target for the image acquisition. Buffers can be allocated automatically by the producer or by the user.NoticeOn activated Chunk mode, there is no access to some features of the buffer object (e.g. GetHeight, GetWidth or GetPixelFormat). Please use the GetChunkNodeTree function instead.
Functions of the class Buffer
BGAPI2::Buffer:: ...
Buffer(); Creates a buffer object.Buffer( void * pU-serObj );
Creates a buffer object including user specific data.
Buffer( void *pUs-erBuffer, bo_uint64 uUserBufferSize, void *pUserObj);
Creates a buffer object with using user allocated memory.
GetID(); Returns the unique ID of buffer (e.g. Buffer_01f94fb), not the memory address of the buffer.
QueueBuffer(); Allocates the buffer to the input queue of a DataStream.GetMemPtr(); Returns the memory address of the buffer.GetMemSize(); Returns the memory size of the buffer.GetUserObj(); Returns the user specific data of the buffer.GetTimestamp(); Returns the buffer´s timestamp.GetNewData(); Returns "true" if the buffer is filled until GetFilledBuffer is
performed.GetIsQueued(); Returns "true" as long as the buffer is allocated to the input
queue of a DataStream.GetIsAcquiring(); Returns "true", if buffer being filled.GetIsIncomplete(); Returns "true" on defect image data.GetTLType(); Returns the type of buffer (GEV, USB3, ...).GetSizeFilled(); Returns the current fill level of the buffer [Bytes].GetWidth(); Returns the image width.GetHeight(); Returns the image height.GetXOffset(); Returns the offset in x-direction.GetYOffset(); Returns the offset in y-direction.GetFrameID(); Returns a hardware generated counter (1...65535).GetImagePresent(); Returns the availability of the image within the buffer.GetImageOffset(); Returns the position of the first byte of image data within
the buffer.GetPayloadType(); Returns whether the payload is chunck or image data .GetPixelFormat(); Returns the pixel format of the image.
18
GetDeliveredImage-Height();
Returns the number of lines of a transmitted image.
GetDelivered-ChunkPayloadSize();
Returns the delivered chunk payload size.
GetChunkLayoutID(); Returns the ID of the layout.GetChunkNodeTree(); Returns the tree view of all chunk nodes.
List Classes3.3 This classes aim to the discovery and listing of the main objects.
The list classes are: SystemList, InterfaceList, DeviceList, DataStreamList and Buffer-List.
In any list class there are three different ways to handle the objects within a list. The first of them is the iterator, which can be used for interating through the lists using begin and end functions.
The second approach is the access by using the subscript operator. And the third way of object handling is realized by the find function.
Each list entry consists of an ID, which is used as key value and a pointer to an object of the main classes.
This functions are availalble for all List Classes.
BGAPI2::[respective List Class]:: ...
iterator This is the iterator class.
begin(); Retrieving the iterator that points to the first list entry.
end(); Retrieving the iterator that points to the last list entry (+1).
Refresh(bo_uint64 iTimeout); Refresh with timout. (not available for the BufferList)
size(); Returns the number of found list entries.
operator[](const String& val) This is the subscript operator for the access to a free selectable point of a list.
find(const String& _keyval); Returns the iterator for the desired list entry, that is defined by the unique ...
erase(iterator& _where); Erases a list entry, using the iterator.
erase(const String& _keyval); Erases a list entry, using the unique string identifier.
clear(); Clears the list.
19
SystemList3.3.1
SystemList This class is used to list objects of the System class.
Special feature of the SystemList: This object is a Singleton. It is not possible to create other objects of this class. It always accesses to the same object. Therefore, a release function is ne-cessary.
Functions of the class SystemList
BGAPI2::SystemList:: ...
GetInstance(); Create the instance of the SystemList.
ReleaseInstance(); Release the instance of the SystemList.
CreateInstanceFromPath (String producerpath);
Forces the usage of only one producer for the listing.
Add(System * pSystem); Adds a producer to the list.
Refresh(); Refreshes the SystemList.
InterfaceList3.3.2
InterfaceList This class is used to list objects of the Interface class.
DeviceList3.3.3
DeviceList This class is used to list objects of the Device class.
DataStreamList3.3.4
DataStreamList This class is used to list objects of the DataStream class.
20
BufferList3.3.5
BufferList This class is used to list objects of the Buffer class.
Special feature of the BufferList: With this list class the pro-grammer can add buffers to the buffer list. Therefore there is no refresh function.
Functions of the class BufferList
BGAPI2::BufferList:: ...
Add(Buffer *pBuffer); Adds a new Butter to the BufferList.RevokeBuffer(Buffer *pBuffer);
Revokes the buffer from the BufferList.
FlushInputToOutput-Queue();
Flushing all buffers form the input queue to the out-put queue.
FlushAllToInputQueue(); Flushing all available buffers to the input queue.FlushUnqueuedToInput-Queue();
Flushing all announced buffer to the input queue.
DiscardOutputBuffers(); Discarding all buffers from the output queue to an-nounced status.
DiscardAllBuffers(); Discarding all buffers form any queue to announced status.
GetDeliveredCount(); Returns the number of buffers that are retrieved from the output queue by using GetFilledBuffer.
GetUnderrunCount(); Returns the number of buffer underruns.GetAnnouncedCount(); Returns the number of announced buffers.GetQueuedCount(); Returns the number of queued buffer (input queue).GetAwaitDeliveryCount(); Returns the number of queued buffer (output
queue).
21
FlushInputToOutputQueue
RevokeBuffer
QueueBuffer/FlushAllToInputQueue
Add
GetFilledBuffer/DiscardAllBuffers/DiscardOutputBuffers
DiscardAllBuffers
Start of new Frame
Fill
Queued------------
Inpuf BufferPool
Pending------------
Output BufferPool
Announce
Buffer
Memory
delete & free
create & allocate
FlushAllToInputQueue
Frame Acquisition complete
◄ Figure 6Buffer handling
22
Additional Classes3.4 Beside the previously mentioned classes, the BGAPI2 also contains three additional classes.
The first two of them (Image & ImageProcessor) are used for image handling and ma-nipulation and are encapsulated in the bgapi2_img.dll. The third class (Trace) aims to the tracing functionality.
Image3.4.1
Image This class provides the ability of image transformation.
Functions of the class Image
BGAPI2::Image:: ...
GetWidth(); Returns the width of the image.GetHeight(); Returns the height of the image.GetPixelFormat(); Returns the pixel format of the image.TransformImage( String sPixelFor-mat, Image** ppOutputImage );
Performs the image transformation.
GetBuffer(); Returns the buffer of the image.GetTransformBufferLength(String sPixelFormat);
Returns the required buffer length of the image, after tranformation to a specified pixel format.
TransformImageToBuffer( String sPi-xelFormat, void* pBuffer, bo_uint64 uBufferSize );
Performs the image transformation using user allocated buffer of the pre-viously determined length (GetTrans-formBufferLength).
GetHistogram(bo_tHistRecords His-togram);
Returns the histogramm array of the image
Release(); Releases the occupied resources (ex-cept the user allocated buffer).
23
Image Processor3.4.2
Image Processor The task of this class is the creation of image objects
Functions of the class Image Processor
BGAPI2::ImageProcessor:: ...
GetInstance(); Creates a singleton instance of the class.
ReleaseInstance(); Releases the image processor in-stance.
GetVersion(); Returns the version of the Image pro-cessor.
CreateImage(bo_uint width, bo_uint height, String pixelformat, void* pBuffer, bo_uint64 uBuffer-Size);
Creates a BGAPI Image object based on a filled buffer.
CreateTransformedImage(Image* pInputImage, const char* szDes-tinationPixelformat);
Creates an image object and performes a pixel format transformation.
SetDestinationFlip( bool verti-cal, bool horicontal );
Flips the image in the specified direc-tion.
GetDestinationFlip( bool *verti-cal, bool *horicontal );
Returns the direction of the image flip-ping.
24
Trace3.4.3
Trace BGAPI2 Trace offers the possibility to monitor the program flow and detect errors.
Functions of the class Trace
BGAPI2::Trace:: ...
Enable( bo_bool benable ); Enables or disables of the tracing.ActivateOutputToFile( bo_bool bac-tive, String tracefilename );
Provides the possibility to print trace outputs to the specified file.
ActivateOutputToDebugger( bo_bool vactive );
Provides the possibility to print trace outputs to the debugger.
ActivateMaskError( bool vactive ); Activates error tracingActivateMaskWarning( bo_bool bac-tive );
Activates warning tracing.
ActivateMaskInformation( bo_bool bactive );
Activates information tracing.
ActivateOutputOptionTimestamp( bo_bool bactive );
Includes the timestamp to the trace output.
ActivateOutputOptionTimestampDiff( bo_bool bactive);
Includes the time lag from the last to the current trace output.
ActivateOutputOptionPrefix( bo_bool bactive );
Includes the module, that created the trace output (such as producer, con-sumer ...)
25
IException 3.5
IException This class is responable for the exception handling and represents the parent class of all exception classes.
Functions of the IException
BGAPI2::IException:: ...
GetErrorDescription(); Returns a description of the error.
GetFunctionName(); Returns the function name, where the error oc-cured.
GetType(); Returns the type of the error.
Exception Class DescriptionNotInitializedException The requested object is not initialized.NotImplementedException The requested function/feature is not implemented.ResourceInUseException The requested object is already used.AccessDeniedException Requested operation is not allowed.InvalidHandleException Given handle does not support the operation.InvalidIdException ID could not be connected to a resource.NoDataException The function has no data to work on.InvalidParameterExcep-tion
One of the parameter given was not valid or out of range and none of the error codes above fits.
IOException Communication error has occurred.
AbortExceptionAn operation has been aborted before it could be completed.
InvalidBufferExceptionNo Buffer announced or one or more buffers with invalid buffer size.
NotAvailableExceptionResource or information is not available at a given time in a current state.
SysVarMissingExceptionSystem variable is not available or specified (see section 4.1).
ErrorException General purpose exception
26
Programming Basics in 4. Baumer-GAPI2During the installation process, all required files were copied to your system.
Default path Windows® 32 bit / 64 bit:
C:\Program Files\Baumer\Baumer GAPI SDK
In the following, these folders are refered to as <BGAPI2 SDK>
NoticeLocation of the Runtime Modules
All Baumer-GAPI2 DLL's must be provided within the same directory as the calling application. This accounts for the fact, that the BGAPI2_genicam.dll tries to find its modules within the directory in which it finds itself.
Further searches the BGAPI2_genicam.dll in the GENTL PATH for producers.
Please take care to refer to the correct directory (Win32 = 32bit / x64 = 64 bit).
This mainly should be considered for the employment of Microsoft® Visual Studio – here the working directory needs to be suitable adjusted.
27
Setting System variables4.1 Microsoft® Windows® 7
NoticeThe path to the system variable is set already during the installation process of the SDK. Follow the instructions to change the path to the system variables (bgapi2_xxx.cti).
1. Click Start, then choose Computer.
2. Click Properties.3. Select the tab Advanced.4. Click Environment Variables.5. Control whether in the System
variables the entry GENICAM_GEN-TL32_PATH exists.
If the entry does not exist continue with step 6.
If the entry exists continue with step 8.
6. Click New at System variables.7. Adjust the following.
Variable name:
GENICAM_GENTL32_PATH
Variables value:
32-bit systems
<BGAPI2 SDK>\Components\Bin\Win32
64-bit systems
<BGAPI2 SDK>\Components\Bin\x64
Continue with step 9.
8. Select the Variable GENICAM_GENTL32_PATH and click Edit.
Add the Baumer path to the Variable value. Separate it with a semicolon to existing entries.
Variables value:
32-bit systems
<BGAPI2 SDK>\Components\Bin\Win32
64-bit systems
<BGAPI2 SDK>\Components\Bin\x64
28
4.2 ImplementationDepending on the programming language you have chosen, you will need to include different header files and libraries. See the respective precaution of your employed pro-gramming language.
Implementation C++4.2.1
4.2.1.1 Header Files
<BGAPI2 SDK>\Components\Dev\C++\Inc
bgapi2_genicam.hpp Interface definition for Baumer-GAPI2, including classes, functions and function pointer for callbacks.
bgapi2_def.h Definitions for Baumer-GAPI2, including defines, enumera-tions and typedefs.
bgapi2_featurenames.h Summary of the features from the GenICam Standard Fea-tures Naming Convention.
To include the necessary header file for C++ write the following code:
#include "bgapi2_genicam.hpp"
4.2.1.2 Libraries
NoticeThe files required for 32 bit and 64 bit operating systems are totally different. Please include the correct folder. Including the wrong files may lead to problems!
Default path Windows® 32bit:
<BGAPI2 SDK>\Components\Dev\C++\Lib\Win32
Default path Windows® 64bit:
<BGAPI2 SDK>\Components\Dev\C++\Lib\x64
bgapi2_genicam.lib This is where all function names and their implementations are filed.
Header files:Files required for the compiler and containing forwarded declarations for subroutines, variables and other identifiers.
Library:Collection of recurrent routines.
29
Precaution4.2.1.3
Create a new project by generating a *.cpp file, then open the project properties from the context menu. Some required information such as the header files directory will need to be set here.
Please set the following values in “<Name of the project> Properties”:
“ ▪ C++” → “General”: “Additional Include Directories”:
<BGAPI SDK>\Dev\C++\Inc
“Linker” → “General”: “ ▪ Additional Library Directories”:
<BGAPI SDK>\Dev\C++\Lib\Win32
“Linker” → “Input”: “Additional Dependencies”: ▪
bgapi2_genicam.lib
“Build Events” → “Post-Build-Event”: “Command Line”: ▪
absolute path:
copy "<BGAPI SDK>\Components\Bin\Win32"\*.* .\
or the relative path (which is used in the examples):
copy ..\..\..\..\..\Bin\Win32\*.* .\
Notice32-Bit:
<BGAPI SDK>\Components\Bin\Win32
bgapi2_genicam.dll bgapi2_img.dll BO_GigEFilterDrv.dll MathParser.dll
64-Bit
<BGAPI SDK>\Components\Bin\x64
bgapi2_genicam.dll bgapi2_img.dll BO_GigEFilterDrv.dll MathParser.dll
Using 4.2.1.4 Namespace
In order to employ the BGAPI2 namespace for C++ as default, please enter the following code:
using namespace BGAPI2;
30
4.2.2 Implementation in C#
.NET Component4.2.2.1
Create a new project, open its properties via the context menu and select:
"Add Reference...".
Integrate the respective bgapi2_genicam_dotnet.dll.
Now you can see under References the inte-grated bgapi2_genicam_dotnet.dll.
Notice32-Bit:
<BGAPI SDK>\Components\Dev\C_Sharp\Win32
bgapi2_genicam_dotnet.dll
64-Bit
<BGAPI SDK>\Components\Dev\C_Sharp\x64
bgapi2_genicam_dotnet.dll
Then go to the added bgapi2_genicam_dot-net.dll Properties and set "Copy Local" to "True".
Build Events (C#
The reason for the command is that compiled .exe mu contain all require bgapi2.dll files in same directory.
31
Precaution4.2.2.2
The first method is applied with the provided examples.
Please set the following values under “<Name of the project> Properties”:
“Build Events” → “Post-Build-Event”: “Command Line”: ▪
absolute path:
copy "<BGAPI SDK>\Components\Bin\Win32"\*.* .\
or relative path:
relative path: copy "..\..\..\..\..\..\..\Bin\Win32"\*.* .\
Alternatively you can use this method:
Open the properties via the context menu and select:
"Add → Existing Item...".
Add the respective DLL files.
#):
e copy the
ust ed
the
32
Notice32-Bit:
<BGAPI SDK>\Components\Bin\Win32
bgapi2_genicam.dll bgapi2_img.dll BO_GigEFilterDrv.dll MathParser.dll
64-Bit
<BGAPI SDK>\Components\Bin\x64
bgapi2_genicam.dll bgapi2_img.dll BO_GigEFilterDrv.dll MathParser.dll
At each of the included files you must set "Copy to Output Directory" to "Copy always".
Using 4.2.2.3 Namespace
In order to employ the BGAPI2 namespace for C# as a default, please enter the following code:
using BGAPI2;
or put BGAPI2 to all calls at the head, e.g.:
BGAPI2.Interface BGAPI2.Device BGAPI2.Image BGAPI2.Exception
33
Application development with 5. Baumer-GAPI NoticeIn order to ensure a smooth flow of your application, it is not recommended to perform function calls during the image acquisition on high system load. If parallel processing is necessary, Baumer suggests the processing of these function calls in a separate thread.
5.1 First stepsIn this chapter, we will guide you on your way to the first image.
This tutorial relates to working with one interface and one camera in C++ and C#.
Inst
ance
s
entry point
Programmer
Baumer-GAPI2
Syst
emLi
stSy
stem
Inte
rfac
eD
evic
eD
ataS
trea
m
◄ Figure 7 Steps to the first image
34
Preparation5.1.1
Includes5.1.1.1
First, please create a new project and set the “Configuration Properties”.
C++ C#
and include the necessary header file#include "bgapi2_genicam.hpp"using namespace BGAPI2;
The standard library and the standard in-put/output header also need to be includ-ed:
#include <stdio.h> using System;#include <iostream> using System.Collections.Generic;#include <iomanip> using System.Linq;
using System.Text;using BGAPI2;
Declaration of Variables5.1.1.2
We also need to declare several variables and pointers for the main function:
C++ C#int main()
{
static void Main(string[] args)
{
Variable for SystemList and SystemBGAPI2::SystemList * systemList = NULL; BGAPI2.SystemList systemList = null;BGAPI2::System * pSystem = NULL; BGAPI2.System mSystem = null;BGAPI2::String sSystemID; string sSystemID = "";
Variables for InterfaceList and Interface:BGAPI2::InterfaceList * interfaceList = NULL;
BGAPI2.InterfaceList interfaceList = null;
BGAPI2::Interface * pInterface = NULL; BGAPI2.Interface mInterface = null;BGAPI2::String sInterfaceID; string sInterfaceID = "";
Variable for DeviceList and DeviceBGAPI2::DeviceList * deviceList = NULL; BGAPI2.DeviceList deviceList = null;BGAPI2::Device * pDevice = NULL; BGAPI2.Device mDevice = null;BGAPI2::String sDeviceID; string sDeviceID = "";
Variables for DataStreamList and DataStreamBGAPI2::DataStreamList * datastreamList = NULL;
DataStreamList datastreamList = null;
BGAPI2::DataStream * pDataStream = NULL; BGAPI2.DataStream mDataStream = null;BGAPI2::String sDataStreamID; string sDataStreamID = "";
Variables for BufferList and BufferBGAPI2::BufferList * bufferList = NULL; BufferList bufferList = null;BGAPI2::Buffer * pBuffer = NULL; BGAPI2.Buffer mBuffer = null;
Header files C++Header file of the default input/output library: This library includes macro definitions, constants, declarations of functions and types.
For more information look into the documentation for standard library.
35
SystemList5.1.2
C++ C#
instantiating and updating SystemListtry try{ {systemList = SystemList::GetInstance(); systemList = SystemList.Instance;systemList->Refresh(); systemList.Refresh();std::cout << "5.1.2 Detected systems: " << systemList->size() << std::endl;
System.Console.Write("5.1.2 Detected sys-tems: {0}\n", systemList.Count);
} }catch (BGAPI2::Exceptions::IException& ex) catch (BGAPI2.Exceptions.IException ex){ {std::cout << "ExceptionType: " << ex.GetType() << std::endl;
System.Console.Write("ErrorType: {0}.\n", ex.GetType());
std::cout << "ErrorDescription: " << ex.GetErrorDescription() << std::endl;
System.Console.Write("ErrorException {0}.\n", ex.GetErrorDescription());
std::cout << "in function: " << ex.GetFunctionName() << std::endl;
System.Console.Write("in function: {0}.\n", ex.GetFunctionName());
} }
NoticeTry and catch is used for error handling. In the following code they are omitted but should be used always.
Open a System5.1.3
First you need to search for the system in the list:
C++ C#for (SystemList::iterator sys = system-List->begin(); sys != systemList->end(); sys++)
foreach (KeyValuePair<string, BGAPI2.System> sys_pair in BGAPI2.SystemList.Instance)
{ { sys->second->Open(); sys_pair.Value.Open(); sSystemID = sys->first; sSystemID = sys_pair.Key; break; break;} }
Check whether the SystemID is available and assign the system pointer:if (sSystemID == "") if (sSystemID == "") return 0; // no system found return; // no system foundelse else pSystem = (*systemList)[sSystemID]; mSystem = systemList[sSystemID];
36
Get the InterfaceList and fill it5.1.4
Get the the InterfaceList of the selected System and update that list. For this example we used a timeout of 100 ms.
C++ C#interfaceList = pSystem->GetInterfaces(); interfaceList = mSystem.Interfaces;interfaceList->Refresh(100); interfaceList.Refresh(100);std::cout << "5.1.4 Detected interfaces: " << interfaceList->size() << std::endl;
System.Console.Write("5.1.4 Detected in-terfaces: {0}\n", interfaceList.Count);
Now the InterfaceList is filled with InterfaceID´s (key) (example: “{9EF543BB-B4FB-4817-9D61-DAE4988C8498}”) and interface pointers.
Open an Interface5.1.5
Now you search for the interface in the list (here open the first interface in the list):
C++ C#for(InterfaceList::iterator ifc = inter-faceList->begin(); ifc != interfaceList->end(); ifc++)
foreach (KeyValuePair<string, BGAPI2.In-terface> ifc_pair in interfaceList)
{ { ifc->second->Open(); ifc_pair.Value.Open(); sInterfaceID = ifc->first; sInterfaceID = ifc_pair.Key; break; break;} }
Check whether the InterfaceID is filled and assign the interface pointer:if (sInterfaceID == "") if (sInterfaceID == "") return 0; // no interface found return; // no interface foundelse else pInterface = (*interfaceList)[sInter faceID];
mInterface = interfaceList[sInterfaceID];
Get the DeviceList and fill it5.1.6
Get the the DeviceList of the selected Interface and update that list. Using a timeout of 100 ms.
C++ C#deviceList = pInterface->GetDevices(); deviceList = mInterface.Devices;deviceList->Refresh(100); deviceList.Refresh(100);std::cout << "5.1.6 Detected devices: " << deviceList->size() << std::endl;
System.Console.Write("5.1.6 Detected de-vices: {0}\n", deviceList.Count);
Now the DeviceList is filled with DeviceID´s (key) (example: “00_06_be_00_27_16”) and Device pointers.
37
Open a Device5.1.7
Now you search for the device in the list (here open the first device in the list):
C++ C#for (DeviceList::iterator dev = de-viceList->begin(); dev != deviceList->end(); dev++)
foreach (KeyValuePair<string, BGAPI2.De-vice> dev_pair in deviceList)
{ { dev->second->Open(); dev_pair:Value.Open(); sDeviceID = dev->first; sDeviceID = dev_pair.Key; break; break;} }
Check the DeviceID is filled and assign the device pointer:if (sDeviceID == "") if (sDeviceID == "") return 0; // no device found return; // no device foundelse else pDevice = (*deviceList)[sDeviceID]; mDevice = deviceList[sDeviceID];
Get DataStreamList and fill it5.1.8
Get the the DataStreamList of the selected Device and update that list. Using a timeout of 100 ms.
C++ C#datastreamList = pDevice->GetDataStreams();
datastreamList = mDevice.DataStreams;
datastreamList->Refresh(100); datastreamList.Refresh(100);std::cout << "5.1.8 Detected datastreams: " << datastreamList->size() << std::endl;
System.Console.Write("5.1.8 Detected datastreams: {0}\n", datastreamList.Count);
Now the DataStreamList is filled with DataStreamID´s (key) (example: “Stream0”) and data stream pointers.
38
Open a DataStream5.1.9
Now you search for the data stream in the list (here open the first datastream in the list):
C++ C#for(DataStreamList::iterator dst= datastreamList->begin();dst != datastream-List->end();dst++)
foreach (KeyValuePair<string, BGAPI2.DataStream> dst_pair in datastreamList)
{ { dst->second->Open(); dst_pair.Value.Open(); sDataStreamID = dst->first; sDataStreamID = dst_pair.Key; break; break;} }
Check the DataStreamID is filled and assign the data stream pointer:if (sDataStreamID == "") if (sDataStreamID == "") return 0; // no datastream found return; // no datastream foundelse else pDataStream = (*datastreamList) [sDataStreamID];
mDataStream = datastreamList[sDataStreamID];
Now the datastream is opened.
Create the BufferList and allocate Buffer memory5.1.10
The created BufferList is empty and needs to be filled with buffers.
C++ C#bufferList = pDataStream->GetBufferList(); bufferList = mDataStream.BufferList;for(int i=0; i<4; i++) // 4 buffers using internal buffers
for(int i=0; i<4; i++) // 4 buffers using internal buffers
{ { pBuffer = new BGAPI2::Buffer(); mBuffer = new BGAPI2.Buffer(); bufferList->Add(pBuffer); bufferList.Add(mBuffer);} }std::cout << "5.1.10 Count of buf-fers created: " << bufferList->size() << std::endl;
System.Console.Write("5.1.10 Count of buf-fers created: {0}\n", bufferList.Count);
39
Allocate Image Buffer to the DataStream5.1.11
C++ C#for (BufferList::iterator buf = bufferL-ist->begin(); buf != bufferList->end(); buf++)
foreach (KeyValuePair<string, BGAPI2.Buf-fer> buf_pair in bufferList)
{ { buf->second->QueueBuffer(); buf_pair.Value.QueueBuffer();} }std::cout << "5.1.11 Queued buffers: " << bufferList->GetQueuedCount() << std::endl;
System.Console.Write("5.1.11. Queued buf-fers: {0}\n", bufferList.Count);
40
Start Camera and fill the Image Buffer5.1.12
Start the data stream.
C++ C#pDataStream->StartAcquisitionContinuous(); mDataStream.StartAcquisition();
Start of the camera:
pDevice->GetRemoteNode("AcquisitionStart")->Execute();
mDevice.RemoteNodeList["AcquisitionStart"].Execute();
Fill the image buffer using a timeout of 1000 milliseconds. The memory pointer to the image data is displayed.
BGAPI2::Buffer * pBufferFilled = NULL; BGAPI2.Buffer mBufferFilled = null;try try{ { pBufferFilled = pDataStream- >GetFilledBuffer(1000);
mBufferFilled = mDataStream.Get FilledBuffer(1000);
if(pBufferFilled == NULL) if(mBufferFilled == null){ { std::cout << "Error: Buffer Timeout after 1000 msec" << std::endl;
System.Console.Write("Error: Buffer Timeout after 1000 msec\n");
} }else else{ { std::cout << " Image " << pBuffer Filled->GetFrameID();
System.Console.Write(" Image {0} ", mBufferFilled. FrameID);
std::cout << " received in memory address " << pBufferFilled->GetMemPtr();
System.Console. Write("received in memory address {0:X}\n",
std::cout << std::endl; (ulong)mBuffer Filled.MemPtr);
} }} catch (BGAPI2.Exceptions.IException ex)catch (BGAPI2::Exceptions::IException& ex) {{ System.Console.Write("ExceptionType:
{0}.\n", ex.GetType());std::cout << "ExceptionType: " << ex.GetType() << std::endl;
System.Console. Write("ErrorDescription: {0}.\n", ex.GetErrorDescription());
std::cout << "ErrorDescription: " << ex.GetErrorDescription() << std::endl;
System.Console.Write("in function: {0}\n", ex.GetFunctionName());
std::cout << "in function: " << ex.GetFunctionName() << std::endl; }
}
After the image processing put the Buffer object into the queue:
pBufferFilled->QueueBuffer(); mBufferFilled.QueueBuffer();Stop the camera:
pDevice->GetRemoteNode("AcquisitionStop")->Execute();
mDevice.RemoteNodeList["AcquisitionStop"].Execute();
Stop the data stream and delete the buffers: Device->GetRemoteNode("AcquisitionStop")->Execute(); mDataStream.StopAcquisition();
41
bufferList->DiscardAllBuffers(); bufferList.DiscardAllBuffers();while( bufferList->size() > 0) while (bufferList.Count > 0){ { pBuffer = bufferList->begin()->second; mBuffer = bufferList.Values.First();
bufferList->RevokeBuffer(pBuffer); bufferList.RevokeBuffer(mBuffer); delete pBuffer; }
Releasing the resources5.1.13
C++ C#pDataStream->Close(); mDataStream.Close();pDevice->Close(); mDevice.Close();pInterface->Close(); mInterface.Close();pSystem->Close(); mSystem.Close();BGAPI2::SystemList::ReleaseInstance();
To prevent the application from closing use the following code:
int endKey = 0; System.Console.Write("Input any number to close the program:\n");
std::cout << "Input any number to close the program:"; Console.Read();
std::cin >> endKey; return;return 0; } //end of Main} // end of main
Baumer Optronic GmbHBadstrasse 30DE-01454 Radeberg, GermanyPhone +49 (0)3528 4386 0 · Fax +49 (0)3528 4386 [email protected] · www.baumer.com
Tech
nica
l dat
a ha
s be
en fu
lly c
heck
ed, b
ut a
ccur
acy
of p
rinte
d m
atte
r not
gua
rant
eed.
Subject to change without notice. Printed in Germany
01/1
3.
v1
.0
110
9900
8
