Vimba NET Manual

Vimba .NET API

Vimba .NET API

Programmer's Manual

V1.22013-Jun-25

Allied Vision Technologies GmbHTaschenweg 2aD-07646 Stadtroda / Germany

Legal NoticeTrademarks

Unless stated otherwise, all trademarks appearing in this document of Allied Vision Technologies arebrands protected by law.

Warranty

The information provided by Allied Vision Technologies is supplied without any guarantees or warrantywhatsoever, be it specific or implicit. Also excluded are all implicit warranties concerning thenegotiability, the suitability for specific applications or the non-breaking of laws and patents. Even if weassume 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 GrubeTax ID: DE 184383113

Headquarters:

Taschenweg 2aD-07646 Stadtroda, GermanyTel.: +49 (0)36428 6770Fax: +49 (0)36428 677-28e-mail: [email protected]

Vimba .NET API - Programmer's Manual

2 / 22

mailto:[email protected]?subject=AVT1394TL

Contents

Contents1 Contacting Allied Vision Technologies 5

2 Introduction 62.1 Document history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.2 Conventions used in this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.2.1 Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.2.2 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3 General aspects of the API 7

4 Module Setup 7

5 Module Version 7

6 Module Initialization 7

7 Object Lifetime 8

8 List available cameras 9

9 Opening a camera 11

10 Feature Access 13

11 Image Acquisition and Capture 1511.1 Image Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1511.2 Image Acquisition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

12 Additional configuration: List available interfaces 19

13 Error Codes 21


3 / 22

Listings

Listings1 Get Cameras . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Open Camera . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Open Camera by IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Acquisition Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Payload Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Streaming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Get Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19


4 / 22

1 Contacting Allied Vision Technologies

1 Contacting Allied VisionTechnologies

Note • Technical Informationhttp://www.alliedvisiontec.com

• [email protected]

Allied Vision Technologies GmbH (Headquarters)Taschenweg 2a07646 Stadtroda, GermanyTel.: +49 36428-677-0Fax.: +49 36428-677-28Email: [email protected]

Allied Vision Technologies Canada Inc.101-3750 North Fraser WayBurnaby, BC, V5J 5E9, CanadaTel: +1 604-875-8855Fax: +1 604-875-8856Email: [email protected]

Allied Vision Technologies Inc.38 Washington StreetNewburyport, MA 01950, USAToll Free number +1 877-USA-1394Tel.: +1 978-225-2030Fax: +1 978-225-2029Email: [email protected]

Allied Vision Technologies Asia Pte. Ltd.82 Playfair Road#07-02 D'LithiumSingapore 368001Tel. +65 6634-9027Fax:+65 6634-9029Email: [email protected]

Allied Vision Technologies (Shanghai) Co., Ltd.2-2109 Hongwell International Plaza1602# ZhongShanXi RoadShanghai 200235, ChinaTel: +86 (21) 64861133Fax: +86 (21) 54233670Email: [email protected]


5 / 22

http://www.alliedvisiontec.com

mailto:[email protected]






2 Introduction

2 Introduction2.1 Document history

Version Date Changes1.0 2012-Sep-27 Initial version1.1 2013-Mar-05 Added which methods can be called within a callback, fixed wording and for-

matting issues1.2 2013-Jun-18 Small corrections, layout changes

2.2 Conventions used in this manual

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

2.2.1 Styles

Style Function ExampleBold Programs, inputs or highlight-

ing important thingsbold

Courier Code listings etc. InputUpper case Constants CONSTANT

Italics Modes, fields Mode

Parentheses and/or blue Links ( Link )

2.2.2 Symbols

Note

This symbol highlights important information.

CautionThis symbol highlights important instructions. You have to follow these instruc-tions to avoid malfunctions.

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


6 / 22

http://www.alliedvisiontec.com

6 Module Initialization

3 General aspects of the APIAVT Vimba NET API is an object orientated .NET API. It utilizes different transport layers to connect to thevarious camera interfaces (FireWire, Gigabit Ethernet) and is therefore to be considered as generic interms of camera interfaces.

4 Module SetupVimba NET API is a .NET 2.0 assembly. Hence, a C# application using the Vimba NET API should ideally bebuilt with the .Net 2.0 framework. If a newer .NET framework version is used, the following text must beadded to the app.config file (example given for .NET framework 4.0):

1 <configuration >2 <startup useLegacyV2RuntimeActivationPolicy="true">3 <supportedRuntime version="v4.0" sku=".NETFramework ,Version=v4.0" />4 </startup >5 </configuration >

5 Module VersionAs new features are introduced to Vimba API, your software remains backwards compatible. Please use theproperty Vimba.Version to check the version number of Vimba NET API.

6 Module InitializationThe entry point to the Vimba NET API is the Vimba object. Use new Vimba to obtain a .NET reference toit. 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 theAPI by calling Vimba.Startup.When the Vimba NET API is finished, call Vimba.Shutdown to free resources. These two API functionsmust always be paired. It is possible, although not recommended, to call the pair several times within thesame program.


7 / 22

7 Object Lifetime

7 Object LifetimeAll .NET Vimba objects are connected to a corresponding internal object by an internal kind of sharedpointer. That means a Vimba NET object will not be destroyed by a simple dereferencing in the userapplication. It will be destroyed when the last reference within the complete application (consisting ofthe 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 isalready plugged in) or during runtime (when plugged in later). The Camera object will not be destroyedby Vimba until it is physically unplugged or Vimba is shut down. Consequently, for a camera that is staysconnected, 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 theframework works with it and will be destroyed when the framework and user application have noreference anymore.


8 / 22

8 List available cameras

8 List available camerasFor a quick start see ListCameras example of the Vimba SDK.

Vimba.Cameras will enumerate all cameras recognized by the underlying transport layers.

Listing 1: Get Cameras1 string strName;2 Vimba sys = new Vimba();3 CameraCollection cameras=null;4

5 try6 {7 sys.Startup();8 cameras = sys.Cameras;9

10 Console.WriteLine( "Cameras found: " + cameras.Count );11 Console.WriteLine();12

13 foreach (Camera camera in cameras)14 {15 try16 {17 strName = camera.Name;18 }19 catch ( VimbaException ve )20 {21 strName = ve.Message;22 }23 Console.WriteLine( "/// Camera Name: " + strName );24 }25 }26 finally27 {28 sys.Shutdown();29 }

The Camera class provides the properties listed in Table 1 to obtain information about a camera.

Type Name Purpose

string Id The unique ID

string Name The name

string Model The model name

string SerialNumber The serial number

VmbAccessModeType PermittedAccess The mode to open the camera

string InterfaceID The ID of the interface the camera is connected to

Table 1: Basic properties of the Camera class

To get notified 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


9 / 22

8 List available cameras

get called by Vimba NET API on the according event. Please note that Vimba.Shutdown only returnsafter all callbacks have finished execution. Below, you find a list of functions that cannot be called withinthe callback routine.

• Vimba.Startup• Vimba.Shutdown• Vimba.Cameras.get• Feature.xxxValue.set• Feature.RunCommand


10 / 22

9 Opening a camera

9 Opening a cameraA 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 identified by their IP or MACaddress) call Vimba.OpenCameraByID.An example for opening a camera retrieved from the camera list is shown in Listing 2.

Listing 2: Open Camera1 Vimba sys = new Vimba();2 CameraCollection cameras=null;3

4 try5 {6 sys.Startup();7 cameras = sys.Cameras;8

9 foreach (Camera camera in cameras)10 {11 try12 {13 camera.Open( VmbAccessModeType.VmbAccessModeFull );14 Console.WriteLine( "/// Camera opened" );15 }16 catch ( VimbaException ve )17 {18 Console.WriteLine( "/// Camera open error : " +19 ve.MapReturnCodeToString() );20 }21 }22 }23 finally24 {25 sys.Shutdown();26 }

Listing 3 shows how to open a camera by its IP address.

Listing 3: Open Camera by IP1 Vimba sys = new Vimba();2 Camera camera=null;3

4 try5 {6 sys.Startup();7

8 try9 {

10 camera = sys.OpenCameraByID( "192.168.0.42",11 VmbAccessModeType.VmbAccessModeFull );12 Console.WriteLine( "/// Camera opened" );13 }14 catch ( VimbaException ve )15 {16 Console.WriteLine( "/// Camera open error : " +17 ve.MapReturnCodeToString() );


11 / 22

9 Opening a camera

18 }19 }20 finally21 {22 sys.Shutdown();23 }

To close a camera use Camera.Close.


12 / 22

10 Feature Access

10 Feature AccessFor 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, andinterfaces. There are several feature types which have type-specific properties and allow type-specificfunctionality: Integer, Float, Enum, String, Boolean, Raw data. Additionally, since not all the features areavailable all the time, there is a general necessity for querying the accessibility of features. Vimba APIprovides its own set of access functions for every feature data type.To start continuous acquisition, set the feature AcquisitionMode to Continuous and run the commandfeature AcquisitionStart as shown in Listing 4.

Listing 4: Acquisition Start1 FeatureCollection features=null;2 Feature feature=null;3

4 try5 {6 features = camera.Features;7 feature = features[ "AcquisitionMode" ];8 feature.EnumValue = "Continuous";9 feature = features[ "AcquisitionStart" ];

10 feature.RunCommand();11 Console.WriteLine( "/// Acquisition started" );12 }13 finally14 {15 Console.WriteLine( "/// Feature error" );16 }

To read the image size in bytes please take a look at Listing 5.

Listing 5: Payload Size1 FeatureCollection features=null;2 Feature feature=null;3 long payloadSize;4

5 try6 {7 features = camera.Features;8 feature = features[ "PayloadSize" ];9 payloadSize = feature.IntValue;

10 Console.WriteLine( "/// PayloadSize = " + payloadSize.ToString() );11 }12 finally13 {14 Console.WriteLine( "/// Feature error" );15 }

Table 2 introduces the basic features found on all cameras. A feature has a name, a type, and access flagssuch as read-permitted and write-permitted.The property Camera.Features lists all features available for a camera. This list remains static whilethe 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 andset. Table 3 lists the Vimba NET API properties of the Feature class used to access feature values.


13 / 22

10 Feature Access

Feature Type Access Flags Description

AcquisitionMode Enumeration R/W The acquisitionmode of the camera. Value set: Con-tinuous, SingleFrame, MultiFrame.

AcquisitionStart Command Start acquiring images.

AcquisitionStop Command Stop acquiring images.

PixelFormat Enumeration R/W The image format. Possible values are e.g.: Mono8,RGB8Packed, YUV411Packed, BayerRG8, …

Width Uint32 R/W Image width, in pixels.

Height Uint32 R/W Image height, in pixels.

PayloadSize Uint32 R Number of bytes in the camera payload, includingthe image.

Table 2: Basic features found on all cameras

Feature Type Set/Get Range OtherEnumeration EnumValue EnumRange IsEnumValueAvailablelong IntValue IntRangeMin, IntRangeMax IntIncrementdouble FloatValue FloatRangeMin, FloatRangeMaxstring StringValuebool BoolValueCommand RunCommandRaw RawValue

Table 3: Properties for reading and writing a Feature

To get notified when a feature's value changes, use Feature.OnFeatureChangeHandler. In theimplementation of this function it is possible to react on updated feature values as it will get called byVimba NET API on the according event. Please note that Vimba.Shutdown blocks until all callbacks havefinished execution. Below, you find a list of functions that cannot be called within the callback routine.



14 / 22

11 Image Acquisition and Capture

11 Image Acquisition and CaptureFor a quick start see SynchronousGrab, AsynchronousGrab or SampleViewer examples of the Vimba SDK.

To obtain an image from your camera, first set up Vimba API to capture images, then start the acquisitionon the camera. These two concepts – capture and acquisition – while related, are independent operationsas 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. Camera.AnnounceFrame – Make a frame known to the API so that it can allocate internalresources (1).

2. Camera.StartCapture – Start the capture engine of the API. Prepare the capture stream (2).

3. Camera.QueueFrame – Queue (an already announced) frame. As images arrive from the camera,they are placed in the next frame's buffer in the queue, and returned to the user (3).

4. 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 effect image acquisition on the camera,follow these steps:

1. Set feature AcquisitionMode (e.g. to Continuous) (4).

2. Run command-feature AcquisitionStart (5).

3. When done, run command-feature AcquisitionStop.

Normally, image capture is initialized and frame buffers are queued before the command AcquisitionStartis 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 buffer on the host) using the asynchronous functionCamera.QueueFrame (3). As long as the frame queue holds a frame whose buffer is large enough tocontain the image data it is filled with the incoming image. Allocating a frame's buffer is left to the API.Although it is possible to allocate a piece of memory yourself that you then pass into the API. In bothcases first query the needed amount of memory through the feature PayloadSize (A) or calculate ityourself. Then create a Frame object and pass either the size of desired memory or a pointer to alreadyallocated 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 filled whenacquisition has started.Before a queued frame can be used or modified, the application needs to know when the image capture iscomplete. Two mechanisms are available: either block your thread until capture is complete usingCamera.AcquireSingleImage for just a single image or Camera.AcquireMultipleImages for manyimages, or register an observer with Camera.OnFrameReceivedHandler (C). In this event it is possibleto implement a frame handling code as well as queue the frame again after it has been processed. Thisworking routine is called when image capture is complete. Below, you find a list of functions that cannotbe called within the callback routine.


15 / 22


• 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 isreturned to ensure the data is valid.Many frames can be placed on the frame queue, and their image buffers will be filled in the same orderthey were queued. To capture more images, keep submitting new frames (frames that you have processedcan be re-queued) as the old frames complete. Most applications need not queue more than two or threeframes at a time.If you want to cancel all the frames on the queue, call Camera.Flush. In case the API has done memoryallocation 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), andAcquisitionStop.Listing 6 shows a minimal streaming example (without error handling for the sake of simplicity).


16 / 22


Listing 6: Streaming1 Camera m_Camera=null;2

3 private void StartCamera()4 {5 Vimba sys = new Vimba();6 CameraCollection cameras=null;7 FeatureCollection features=null;8 Feature feature=null;9 long payloadSize;

10 Frame[] frameArray = new Frame[3];11

12 sys.Startup();13

14 cameras = sys.Cameras;15

16 m_Camera = cameras[0];17 m_Camera.Open(VmbAccessModeType.VmbAccessModeFull );18

19 m_Camera.OnFrameReceived +=20 new Camera.OnFrameReceivedHandler(OnFrameReceived); (C)21

22 features = m_Camera.Features;23 feature = features[ "PayloadSize" ]; (A)24 payloadSize = feature.IntValue;25

26 for ( int index=0; index <frameArray.Length; ++index )27 {28 frameArray[index] = new Frame( payloadSize ); (B)29 m_Camera.AnnounceFrame( frameArray[index] ); (1)30 }31

32 m_Camera.StartCapture(); (2)33

34 for ( int index=0; index <frameArray.Length; ++index )35 {36 m_Camera.QueueFrame( frameArray[index] ); (3)37 }38

39 feature = features[ "AcquisitionMode" ]; (4)40 feature.EnumValue = "Continuous";41

42 feature = features[ "AcquisitionStart" ]; (5)43 feature.RunCommand();44 }45

46 private void OnFrameReceived(Frame frame) (C)47 {48 if (InvokeRequired) // if not from this thread invoke it in our context49 {50 Invoke(new Camera.OnFrameReceivedHandler(OnFrameReceived), frame);51 }52

53 if (VmbFrameStatusType.VmbFrameStatusComplete == frame.ReceiveStatus)54 {55 Console.WriteLine( "/// Frame status complete" );56 }


17 / 22


57

58 m_Camera.QueueFrame(frame);59 }


18 / 22

12 Additional configuration: List available interfaces

12 Additional configuration: Listavailable interfaces

Vimba.Interfaces will enumerate all interfaces recognized by the underlying transport layers.See Listing 7 for an example.

Listing 7: Get Interfaces1 string strName;2 Vimba sys = new Vimba();3 InterfaceCollection interfaces=null;4

5 try6 {7 sys.Startup();8 interfaces = sys.Interfaces;9

10 Console.WriteLine( "Interfaces found: " + interfaces.Count );11 Console.WriteLine();12

13 foreach (Interface interFace in interfaces)14 {15 try16 {17 strName = interFace.Name;18 }19 catch ( VimbaException ve )20 {21 strName = ve.Message;22 }23 Console.WriteLine( "/// Interface Name: " + strName );24 }25 }26 finally27 {28 sys.Shutdown();29 }

The Interface class provides the following properties to obtain information about an interface listed inTable 4.

Type Name Purpose

string ID The unique ID

string Name The name

VmbInterfaceType Type The camera interface type

string SerialNumber The serial number

VmbAccessModeType PermittedAccess The mode to open the interface

Table 4: Basic properties of Interface class

To get notified when an interface is detected or disconnected, useVimba.OnInterfaceListChangeHandler. In the implementation of this function it is possible to


19 / 22

12 Additional configuration: 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 finished execution. Below, you find alist of functions that cannot be called within the callback routine.



20 / 22

13 Error Codes

13 Error CodesAll 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 inTable 5 might be returned.


21 / 22

13 Error Codes

Error Code Value Description

VmbErrorSuccess 0 No error

VmbErrorInternalFault -1 Unexpected fault in Vimba or driver

VmbErrorApiNotStarted -2 Startup was not called before the current comand

VmbErrorNotFound -3 The designated instance (camera, feature etc.) cannot befound

VmbErrorBadHandle -4 The given handle is not valid

VmbErrorDeviceNotOpen -5 Device was not opened for usage

VmbErrorInvalidAccess -6 Operation is invalid with the current access mode

VmbErrorBadParameter -7 One of the parameters was invalid (usually an illegalpointer)

VmbErrorStructSize -8 The given struct size is not valid for this version of the API

VmbErrorMoreData -9 More data was returned in a string/list than space was pro-vided

VmbErrorWrongType -10 The feature type for this access function was wrong

VmbErrorInvalidValue -11 The value was not valid; either out of bounds or not an in-crement of the minimum

VmbErrorTimeout -12 Timeout during wait

VmbErrorOther -13 Other error

VmbErrorResources -14 Resources not available (e.g. memory)

VmbErrorInvalidCall -15 Call is invalid in the current context (e.g. callback)

VmbErrorNoTL -16 No transport layers were found

VmbErrorNotImplemented -17 API feature is not implemented

VmbErrorNotSupported -18 API feature is not supported

VmbErrorIncomplete -19 A multiple registers read or write was partially completed

VmbErrorNETBadParameter -100 One of the .NET parameters was invalid (usually an illegalreference or empty)

VmbErrorNETIncomplete -101 A multiple .NET frame acquisition was incomplete

VmbErrorNETInvalidCall -102 A .NET call is invalid in the current context (e.g. acquisitionis already running)

VmbErrorNETNotSupported -103 A .NET parameter value is not supported (e.g. unsupportedpixelformat)

VmbErrorNETInternalFault -104 Unexpected fault in VmbAPINET

Table 5: Error codes returned by Vimba


22 / 22

Date post:	02-Jan-2016
Category:	Documents
Upload:	sinuhe-pahe
View:	1,613 times
Download:	53 times

Vimba NET Manual

Documents