Vimba .

NET API

Vimba .NET API Programmer's Manual

V1.2

2013-Jun-25

Allied Vision Technologies GmbH Taschenweg 2a D-07646 Stadtroda / Germany

Legal Notice
Trademarks
Unless stated otherwise, all trademarks appearing in this document of Allied Vision Technologies are brands protected by law.

Warranty
The information provided by Allied Vision Technologies is supplied without any guarantees or warranty whatsoever, be it specic or implicit. Also excluded are all implicit warranties concerning the negotiability, the suitability for specic applications or the non-breaking of laws and patents. Even if we assume that the information supplied to us is accurate, errors and inaccuracy may still occur.

Copyright
All texts, pictures and graphics are protected by copyright and other laws protecting intellectual property. It is not permitted to copy or modify them for trade use or transfer, nor may they be used on websites.

Allied Vision Technologies GmbH 06/2013

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@alliedvisiontec.com

Vimba .NET API - Programmer's Manual

2 / 22

Contents

Contents
1 Contacting Allied Vision Technologies 2 Introduction 2.1 Document history . . . . . . . 2.2 Conventions used in this manual 2.2.1 Styles . . . . . . . . . 2.2.2 Symbols . . . . . . . . 3 General aspects of the API 4 Module Setup 5 Module Version 6 Module Initialization 7 Object Lifetime 8 List available cameras 9 Opening a camera 10 Feature Access 5 6 6 6 6 6 7 7 7 7 8 9 11 13 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11 Image Acquisition and Capture 15 11.1 Image Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 11.2 Image Acquisition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 12 Additional conguration: List available interfaces 13 Error Codes 19 21

Vimba .NET API - Programmer's Manual

3 / 22

Listings

Listings
1 2 3 4 5 6 7 Get Cameras . . . . Open Camera . . . Open Camera by IP . Acquisition Start . Payload Size . . . . Streaming . . . . . Get Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 11 11 13 13 17 19

Vimba .NET API - Programmer's Manual

4 / 22

Contacting Allied Vision Technologies

Contacting Allied Vision Technologies

Note

Technical Information http://www.alliedvisiontec.com Support support@alliedvisiontec.com Allied Vision Technologies GmbH (Headquarters) Taschenweg 2a 07646 Stadtroda, Germany Tel.: +49 36428-677-0 Fax.: +49 36428-677-28 Email: info@alliedvisiontec.com Allied Vision Technologies Canada Inc. 101-3750 North Fraser Way Burnaby, BC, V5J 5E9, Canada Tel: +1 604-875-8855 Fax: +1 604-875-8856 Email: info@alliedvisiontec.com Allied Vision Technologies Inc. 38 Washington Street Newburyport, MA 01950, USA Toll Free number +1 877-USA-1394 Tel.: +1 978-225-2030 Fax: +1 978-225-2029 Email: info@alliedvisiontec.com Allied Vision Technologies Asia Pte. Ltd. 82 Playfair Road #07-02 D'Lithium Singapore 368001 Tel. +65 6634-9027 Fax:+65 6634-9029 Email: info@alliedvisiontec.com Allied Vision Technologies (Shanghai) Co., Ltd. 2-2109 Hongwell International Plaza 1602# ZhongShanXi Road Shanghai 200235, China Tel: +86 (21) 64861133 Fax: +86 (21) 54233670 Email: info@alliedvisiontec.com
Vimba .NET API - Programmer's Manual

5 / 22

Introduction

2
2.1

Introduction
Document history
Date 2012-Sep-27 2013-Mar-05 2013-Jun-18 Changes Initial version Added which methods can be called within a callback, xed wording and formatting issues Small corrections, layout changes

Version 1.0 1.1 1.2

2.2

Conventions used in this manual

To give this manual an easily understood layout and to emphasize important information, the following typographical styles and symbols are used:

2.2.1
Style Bold Courier

Styles
Function Programs, inputs or highlighting important things Code listings etc. Constants Modes, elds Links Example bold Input CONSTANT Mode ( Link )

Upper case Italics Parentheses and/or blue

2.2.2

Symbols
Note

L
Caution

This symbol highlights important information.

a
www

This symbol highlights important instructions. You have to follow these instructions to avoid malfunctions.

This symbol highlights URLs for further information. The URL itself is shown in blue. Example: http://www.alliedvisiontec.com

Vimba .NET API - Programmer's Manual

6 / 22

Module Initialization

General aspects of the API

AVT Vimba NET API is an object orientated .NET API. It utilizes dierent transport layers to connect to the various camera interfaces (FireWire, Gigabit Ethernet) and is therefore to be considered as generic in terms of camera interfaces.

Module Setup

Vimba NET API is a .NET 2.0 assembly. Hence, a C# application using the Vimba NET API should ideally be built with the .Net 2.0 framework. If a newer .NET framework version is used, the following text must be added to the app.cong le (example given for .NET framework 4.0):
1 2 3 4 5

<configuration > <startup useLegacyV2RuntimeActivationPolicy ="true"> <supportedRuntime version ="v4 .0" sku=". NETFramework , Version =v4.0" /> </startup > </ configuration >

Module Version

As new features are introduced to Vimba API, your software remains backwards compatible. Please use the property Vimba.Version to check the version number of Vimba NET API.

Module Initialization

The entry point to the Vimba NET API is the Vimba object. Use new Vimba to obtain a .NET reference to it. The Vimba object allows to control the API's behavior and to query for interfaces and cameras. Before calling any Vimba NET API function (other than Vimba.Version), it is necessary to initialize the API by calling Vimba.Startup. When the Vimba NET API is nished, call Vimba.Shutdown to free resources. These two API functions must always be paired. It is possible, although not recommended, to call the pair several times within the same program.

Vimba .NET API - Programmer's Manual

7 / 22

Object Lifetime

Object Lifetime

All .NET Vimba objects are connected to a corresponding internal object by an internal kind of shared pointer. That means a Vimba NET object will not be destroyed by a simple dereferencing in the user application. It will be destroyed when the last reference within the complete application (consisting of the user application and Vimba) is dropped. If an internal situation causes longer lifetime of this object, it could be destroyed at a later time. The best example for this is a Camera object which is created during Vimba startup (if the camera is already plugged in) or during runtime (when plugged in later). The Camera object will not be destroyed by Vimba until it is physically unplugged or Vimba is shut down. Consequently, for a camera that is stays connected, the returned Camera object reference will always stay the same. Another example is the Frame object created by the user application. This object will live as long as the framework works with it and will be destroyed when the framework and user application have no reference anymore.

Vimba .NET API - Programmer's Manual

8 / 22

List available cameras

List available cameras

Listing 1: Get Cameras

For a quick start see ListCameras example of the Vimba SDK. Vimba.Cameras will enumerate all cameras recognized by the underlying transport layers.
string strName ; Vimba sys = new Vimba (); CameraCollection cameras =null; try { sys. Startup (); cameras = sys. Cameras ; Console . WriteLine ( " Cameras found: " + cameras . Count ); Console . WriteLine (); foreach ( Camera camera in cameras ) { try { strName = camera .Name; } catch ( VimbaException ve ) { strName = ve. Message ; } Console . WriteLine ( "/// Camera Name: " + strName ); } } finally { sys. Shutdown (); }

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29

The Camera class provides the properties listed in Table 1 to obtain information about a camera. Type string string string string VmbAccessModeType string Name Id Name Model SerialNumber PermittedAccess InterfaceID Purpose The unique ID The name The model name The serial number The mode to open the camera The ID of the interface the camera is connected to

Table 1: Basic properties of the Camera class To get notied when a camera is detected or disconnected, use Vimba.OnCameraListChangeHandler. In the implementation of this function, it is possible to react on cameras being plugged in or out as it will
Vimba .NET API - Programmer's Manual

9 / 22

List available cameras

get called by Vimba NET API on the according event. Please note that Vimba.Shutdown only returns after all callbacks have nished execution. Below, you nd a list of functions that cannot be called within the callback routine. Vimba.Startup Vimba.Shutdown Vimba.Cameras.get Feature.xxxValue.set Feature.RunCommand

Vimba .NET API - Programmer's Manual

10 / 22

Opening a camera

Opening a camera

A camera must be opened for control and to capture images. To open a camera simply call Camera.Open. In case the ID of a camera is already known (e.g. GigE cameras can also be identied by their IP or MAC address) call Vimba.OpenCameraByID. An example for opening a camera retrieved from the camera list is shown in Listing 2. Listing 2: Open Camera
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

Vimba sys = new Vimba (); CameraCollection cameras =null; try { sys. Startup (); cameras = sys. Cameras ; foreach ( Camera camera in cameras ) { try { camera .Open( VmbAccessModeType . VmbAccessModeFull ); Console . WriteLine ( "/// Camera opened " ); } catch ( VimbaException ve ) { Console . WriteLine ( "/// Camera open error : " + ve. MapReturnCodeToString () ); } } } finally { sys. Shutdown (); }

Listing 3 shows how to open a camera by its IP address. Listing 3: Open Camera by IP
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

Vimba sys = new Vimba (); Camera camera =null; try { sys. Startup (); try { camera = sys. OpenCameraByID ( " 192.168.0.42 ", VmbAccessModeType . VmbAccessModeFull ); Console . WriteLine ( "/// Camera opened " ); } catch ( VimbaException ve ) { Console . WriteLine ( "/// Camera open error : " + ve. MapReturnCodeToString () );

Vimba .NET API - Programmer's Manual

11 / 22

Opening a camera

18 19 20 21 22 23

} } finally { sys. Shutdown (); }

To close a camera use Camera.Close.

Vimba .NET API - Programmer's Manual

12 / 22

10

Feature Access

10

Feature Access

For a quick start see ListFeatures example of the Vimba SDK. GenICam-compliant features are used to control and monitor various aspects of the drivers, cameras, and interfaces. There are several feature types which have type-specic properties and allow type-specic functionality: Integer, Float, Enum, String, Boolean, Raw data. Additionally, since not all the features are available all the time, there is a general necessity for querying the accessibility of features. Vimba API provides its own set of access functions for every feature data type. To start continuous acquisition, set the feature AcquisitionMode to Continuous and run the command feature AcquisitionStart as shown in Listing 4. Listing 4: Acquisition Start
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

FeatureCollection features =null; Feature feature =null; try { features = camera . Features ; feature = features [ " AcquisitionMode " ]; feature . EnumValue = " Continuous "; feature = features [ " AcquisitionStart " ]; feature . RunCommand (); Console . WriteLine ( "/// Acquisition started " ); } finally { Console . WriteLine ( "/// Feature error" ); }

To read the image size in bytes please take a look at Listing 5. Listing 5: Payload Size
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

FeatureCollection features =null; Feature feature =null; long payloadSize ; try { features = camera . Features ; feature = features [ " PayloadSize " ]; payloadSize = feature . IntValue ; Console . WriteLine ( "/// PayloadSize = " + payloadSize . ToString () ); } finally { Console . WriteLine ( "/// Feature error" ); }

Table 2 introduces the basic features found on all cameras. A feature has a name, a type, and access ags such as read-permitted and write-permitted. The property Camera.Features lists all features available for a camera. This list remains static while the camera is open. The Feature class provides not only the feature's value but further information. With properties like Feature.IntValue or Feature.BoolValue, a feature's value can be queried and set. Table 3 lists the Vimba NET API properties of the Feature class used to access feature values.
Vimba .NET API - Programmer's Manual

13 / 22

10

Feature Access

Feature AcquisitionMode AcquisitionStart AcquisitionStop PixelFormat Width Height PayloadSize

Type Enumeration Command Command Enumeration Uint32 Uint32 Uint32

Access Flags R/W

Description The acquisition mode of the camera. Value set: Continuous, SingleFrame, MultiFrame. Start acquiring images. Stop acquiring images.

R/W R/W R/W R

The image format. Possible values are e.g.: Mono8, RGB8Packed, YUV411Packed, BayerRG8, Image width, in pixels. Image height, in pixels. Number of bytes in the camera payload, including the image.

Table 2: Basic features found on all cameras Feature Type Enumeration long double string bool Command Raw Set/Get EnumValue IntValue FloatValue StringValue BoolValue RunCommand RawValue Range EnumRange IntRangeMin, IntRangeMax FloatRangeMin, FloatRangeMax Other IsEnumValueAvailable IntIncrement

Table 3: Properties for reading and writing a Feature To get notied when a feature's value changes, use Feature.OnFeatureChangeHandler. In the implementation of this function it is possible to react on updated feature values as it will get called by Vimba NET API on the according event. Please note that Vimba.Shutdown blocks until all callbacks have nished execution. Below, you nd a list of functions that cannot be called within the callback routine. Vimba.Startup Vimba.Shutdown Vimba.Cameras.get Feature.xxxValue.set Feature.RunCommand

Vimba .NET API - Programmer's Manual

14 / 22

11

Image Acquisition and Capture

11

Image Acquisition and Capture

For a quick start see SynchronousGrab, AsynchronousGrab or SampleViewer examples of the Vimba SDK. To obtain an image from your camera, rst set up Vimba API to capture images, then start the acquisition on the camera. These two concepts capture and acquisition while related, are independent operations as it is shown below (the bracketed tokens refer to the example at the end of this chapter). To capture images sent by the camera, follow these steps: 1. 2. 3. 4. Camera.AnnounceFrame Make a frame known to the API so that it can allocate internal resources (1). Camera.StartCapture Start the capture engine of the API. Prepare the capture stream (2). Camera.QueueFrame Queue (an already announced) frame. As images arrive from the camera, they are placed in the next frame's buer in the queue, and returned to the user (3). When done, Camera.EndCapture Stop the capture engine and close the image capture stream.

None of the steps above cause the camera to acquire an image. To eect image acquisition on the camera, follow these steps: 1. 2. 3. Set feature AcquisitionMode (e.g. to Continuous) (4). Run command-feature AcquisitionStart (5). When done, run command-feature AcquisitionStop.

Normally, image capture is initialized and frame buers are queued before the command AcquisitionStart is run, but the order can vary depending on the application. To guarantee a particular image is captured, you must ensure that your frames are queued before the camera is instructed to start acquisition.

11.1

Image Capture

Images are captured (copied from the camera to a buer on the host) using the asynchronous function Camera.QueueFrame (3). As long as the frame queue holds a frame whose buer is large enough to contain the image data it is lled with the incoming image. Allocating a frame's buer is left to the API. Although it is possible to allocate a piece of memory yourself that you then pass into the API. In both cases rst query the needed amount of memory through the feature PayloadSize (A) or calculate it yourself. Then create a Frame object and pass either the size of desired memory or a pointer to already allocated memory to the constructor (B). After that, announce the frame (1), start the capture engine (2) and queue the frame you have just created with Camera.QueueFrame (3) so it can be lled when acquisition has started. Before a queued frame can be used or modied, the application needs to know when the image capture is complete. Two mechanisms are available: either block your thread until capture is complete using Camera.AcquireSingleImage for just a single image or Camera.AcquireMultipleImages for many images, or register an observer with Camera.OnFrameReceivedHandler (C). In this event it is possible to implement a frame handling code as well as queue the frame again after it has been processed. This working routine is called when image capture is complete. Below, you nd a list of functions that cannot be called within the callback routine.
Vimba .NET API - Programmer's Manual

15 / 22

11

Image Acquisition and Capture

Vimba.Startup Vimba.Shutdown Camera.Open Camera.Close Camera.AcquireSingleImage Camera.AcquireMultipleImages Camera.StartContinuousImageAcquisition Camera.StopContinuousImageAcquisition Camera.StartCapture Camera.EndCapture Camera.AnnounceFrame Camera.RevokeFrame Camera.RevokeAllFrames

NOTE: Always check that Frame.ReceiveStatus returns VmbFrameStatusComplete when a frame is returned to ensure the data is valid. Many frames can be placed on the frame queue, and their image buers will be lled in the same order they were queued. To capture more images, keep submitting new frames (frames that you have processed can be re-queued) as the old frames complete. Most applications need not queue more than two or three frames at a time. If you want to cancel all the frames on the queue, call Camera.Flush. In case the API has done memory allocation this memory is not released until the Camera class' FlushQueue, RevokeAllFrames / RevokeFrame, EndCapture or Close function has been called.

11.2

Image Acquisition

Image acquisition is set up via the features AcquisitionMode (4), AcquisitionStart (5), and AcquisitionStop. Listing 6 shows a minimal streaming example (without error handling for the sake of simplicity).

Vimba .NET API - Programmer's Manual

16 / 22

11

Image Acquisition and Capture

Listing 6: Streaming
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56

Camera m_Camera =null; private void StartCamera () { Vimba sys = new Vimba (); CameraCollection cameras =null; FeatureCollection features =null; Feature feature =null; long payloadSize ; Frame [] frameArray = new Frame [3]; sys. Startup (); cameras = sys. Cameras ; m_Camera = cameras [0]; m_Camera .Open( VmbAccessModeType . VmbAccessModeFull ); m_Camera . OnFrameReceived += new Camera . OnFrameReceivedHandler ( OnFrameReceived ); features = m_Camera . Features ; feature = features [ " PayloadSize " ]; payloadSize = feature . IntValue ; for ( int index =0; index < frameArray . Length ; ++ index ) { frameArray [ index ] = new Frame( payloadSize ); m_Camera . AnnounceFrame ( frameArray [index] ); } m_Camera . StartCapture (); for ( int index =0; index < frameArray . Length ; ++ index ) { m_Camera . QueueFrame ( frameArray [index] ); } feature = features [ " AcquisitionMode " ]; feature . EnumValue = " Continuous "; feature = features [ " AcquisitionStart " ]; feature . RunCommand (); } private void OnFrameReceived ( Frame frame ) (C) { if ( InvokeRequired ) // if not from this thread invoke it in our context { Invoke (new Camera . OnFrameReceivedHandler ( OnFrameReceived ), frame ); } if ( VmbFrameStatusType . VmbFrameStatusComplete == frame. ReceiveStatus ) { Console . WriteLine ( "/// Frame status complete " ); }

(C)

(A)

(B) (1)

(2)

(3)

(4)

(5)

Vimba .NET API - Programmer's Manual

17 / 22

11

Image Acquisition and Capture

57 58 59

m_Camera . QueueFrame ( frame ); }

Vimba .NET API - Programmer's Manual

18 / 22

12

Additional conguration: List available interfaces

12

Additional conguration: List available interfaces

Listing 7: Get Interfaces

Vimba.Interfaces will enumerate all interfaces recognized by the underlying transport layers. See Listing 7 for an example.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29

string strName ; Vimba sys = new Vimba (); InterfaceCollection interfaces =null; try { sys. Startup (); interfaces = sys. Interfaces ; Console . WriteLine ( " Interfaces found: " + interfaces .Count ); Console . WriteLine (); foreach ( Interface interFace in interfaces ) { try { strName = interFace .Name; } catch ( VimbaException ve ) { strName = ve. Message ; } Console . WriteLine ( "/// Interface Name: " + strName ); } } finally { sys. Shutdown (); }

The Interface class provides the following properties to obtain information about an interface listed in Table 4. Type string string VmbInterfaceType string VmbAccessModeType Name ID Name Type SerialNumber PermittedAccess Purpose The unique ID The name The camera interface type The serial number The mode to open the interface

Table 4: Basic properties of Interface class To get notied when an interface is detected or disconnected, use Vimba.OnInterfaceListChangeHandler. In the implementation of this function it is possible to
Vimba .NET API - Programmer's Manual

19 / 22

12

Additional conguration: List available interfaces

react on interfaces being plugged in or out as it will get called by Vimba NET API on the according event. Please note that Vimba.Shutdown blocks until all callbacks have nished execution. Below, you nd a list of functions that cannot be called within the callback routine. Vimba.Startup Vimba.Shutdown Vimba.Cameras.get Feature.xxxValue.set Feature.RunCommand

Vimba .NET API - Programmer's Manual

20 / 22

13

Error Codes

13

Error Codes

All Vimba API functions return an error code of type VmbErrorType. Typical errors are listed with each function in the context help. However, any of the error codes listed in Table 5 might be returned.

Vimba .NET API - Programmer's Manual

21 / 22

13

Error Codes

Error Code VmbErrorSuccess VmbErrorInternalFault VmbErrorApiNotStarted VmbErrorNotFound VmbErrorBadHandle VmbErrorDeviceNotOpen VmbErrorInvalidAccess VmbErrorBadParameter VmbErrorStructSize VmbErrorMoreData VmbErrorWrongType VmbErrorInvalidValue VmbErrorTimeout VmbErrorOther VmbErrorResources VmbErrorInvalidCall VmbErrorNoTL VmbErrorNotImplemented VmbErrorNotSupported VmbErrorIncomplete VmbErrorNETBadParameter VmbErrorNETIncomplete VmbErrorNETInvalidCall VmbErrorNETNotSupported VmbErrorNETInternalFault

Value 0 -1 -2 -3 -4 -5 -6 -7 -8 -9 -10 -11 -12 -13 -14 -15 -16 -17 -18 -19 -100 -101 -102 -103 -104

Description No error Unexpected fault in Vimba or driver Startup was not called before the current comand The designated instance (camera, feature etc.) cannot be found The given handle is not valid Device was not opened for usage Operation is invalid with the current access mode One of the parameters was invalid (usually an illegal pointer) The given struct size is not valid for this version of the API More data was returned in a string/list than space was provided The feature type for this access function was wrong The value was not valid; either out of bounds or not an increment of the minimum Timeout during wait Other error Resources not available (e.g. memory) Call is invalid in the current context (e.g. callback) No transport layers were found API feature is not implemented API feature is not supported A multiple registers read or write was partially completed One of the .NET parameters was invalid (usually an illegal reference or empty) A multiple .NET frame acquisition was incomplete A .NET call is invalid in the current context (e.g. acquisition is already running) A .NET parameter value is not supported (e.g. unsupported pixelformat) Unexpected fault in VmbAPINET

Table 5: Error codes returned by Vimba

Vimba .NET API - Programmer's Manual

22 / 22