Vimba .NET API Vimba .NET API Programmer's Manual V1.2 2013-Jun-25 Allied Vision Technologies GmbH Taschenweg 2a D-07646 Stadtroda / Germany
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
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
Vimba .NET API - Programmer's Manual
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
Vimba .NET API - Programmer's Manual
4 / 22
1 Contacting Allied Vision Technologies
1 Contacting Allied VisionTechnologies
Note • Technical Informationhttp://www.alliedvisiontec.com
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]
Vimba .NET API - Programmer's Manual
5 / 22
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
Vimba .NET API - Programmer's Manual
6 / 22
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.
Vimba .NET API - Programmer's Manual
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.
Vimba .NET API - Programmer's Manual
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
Vimba .NET API - Programmer's Manual
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
Vimba .NET API - Programmer's Manual
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() );
Vimba .NET API - Programmer's Manual
11 / 22
9 Opening a camera
18 }19 }20 finally21 {22 sys.Shutdown();23 }
To close a camera use Camera.Close.
Vimba .NET API - Programmer's Manual
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.
Vimba .NET API - Programmer's Manual
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.
• 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 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.
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 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).
Vimba .NET API - Programmer's Manual
16 / 22
11 Image Acquisition and Capture
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 }
Vimba .NET API - Programmer's Manual
17 / 22
11 Image Acquisition and Capture
57
58 m_Camera.QueueFrame(frame);59 }
Vimba .NET API - Programmer's Manual
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
Vimba .NET API - Programmer's Manual
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.
• 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 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.
Vimba .NET API - Programmer's Manual
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
Vimba .NET API - Programmer's Manual
22 / 22