ICamera Interface#

Provides convenient access to a camera device.

Syntax#

C#

public interface ICamera : IDisposable

VB

Public Interface ICamera
    Inherits IDisposable

The ICamera type exposes the following members.

Properties#

	Name	Description
	CameraInfo	Provides access to camera information. The camera information can be updated if camera properties have changed. Camera properties may change e.g. if a GigE camera has been assigned a new IP address after reconnection.
	IsConnected	Indicates if the camera device is properly connected to the camera object while the camera object is open.
	IsOpen	Indicates if camera object has been opened.
	Parameters	Returns the parameter collection of the camera for accessing all parameters. Example: camera.Parameters[PLCamera.Width].GetValue();
	StreamGrabber	Returns the stream grabber of the camera object.

Methods#

	Name	Description
	Close	Closes the connection to the camera.
	CreateFileStream	Create a file stream for upload or download.
	ExecuteSoftwareTrigger	Executes the software trigger command.
	GetSfncVersion	Gets the version number of the SFNC specification that the camera complies to.
	Open()	Opens a connection to the camera device.
	Open(Int32, TimeoutHandling)	Tries to open a connection to the camera until a timeout occurs. If the camera device is not available, the method tries to access the camera until a timeout occurs.
	WaitForFrameTriggerReady	Polls the parameters of the camera until the camera is ready to receive a software trigger.

Events#

	Name	Description
	CameraClosed	Occurs after the connection to the camera has been closed.
	CameraClosing	Occurs before the connection to the camera is closed.
	CameraOpened	Occurs after the connection to the camera has been opened successfully via Open() or Open(Int32, TimeoutHandling).
	CameraOpening	Occurs before the connection to the camera is opened via Open() or Open(Int32, TimeoutHandling).
	ConnectionLost	Occurs when the physical connection to the camera has been lost unexpectedly.

ICamera.CameraClosed Event#

Occurs after the connection to the camera has been closed.

Syntax#

C#

event EventHandler<EventArgs> CameraClosed

VB

Event CameraClosed As EventHandler(Of EventArgs)

Value#

Type: System.EventHandler(EventArgs)

Remarks#

During the execution of this event, the camera is already closed.

If an event handler throws an exception, it will be ignored and the remaining handlers will be called.

This event is fired inside the lock of the camera instance.

ICamera.CameraClosing Event#

Occurs before the connection to the camera is closed.

Syntax#

C#

event EventHandler<EventArgs> CameraClosing

VB

Event CameraClosing As EventHandler(Of EventArgs)

Value#

Type: System.EventHandler(EventArgs)

Remarks#

If the camera is closed properly, the connection to the camera is still open during the execution of this event.

If an event handler throws an exception, it will be ignored and the remaining handlers will be called.

This event is fired inside the lock of the camera instance.

ICamera.CameraOpened Event#

Occurs after the connection to the camera has been opened successfully via Open() or Open(Int32, TimeoutHandling).

Syntax#

C#

event EventHandler<EventArgs> CameraOpened

VB

Event CameraOpened As EventHandler(Of EventArgs)

Value#

Type: System.EventHandler(EventArgs)

Remarks#

During the execution of this event, the connection to the camera is already open.

If an event handler called by this event throws an exception, the connection to the camera will be closed and the exception will be propagated to the caller of Open(). No other handlers will be called.

This event is fired inside the lock of the camera instance.

ICamera.CameraOpening Event#

Occurs before the connection to the camera is opened via Open() or Open(Int32, TimeoutHandling).

Syntax#

C#

event EventHandler<EventArgs> CameraOpening

VB

Event CameraOpening As EventHandler(Of EventArgs)

Value#

Type: System.EventHandler(EventArgs)

Remarks#

During the execution of this event, the connection to the camera is not yet open.

If an event handler called by this event throws an exception, it will be propagated to the caller of Open(). No other handlers will be called.

This event is fired inside the lock of the camera instance.

ICamera.ConnectionLost Event#

Occurs when the physical connection to the camera has been lost unexpectedly.

Syntax#

C#

event EventHandler<EventArgs> ConnectionLost

VB

Event ConnectionLost As EventHandler(Of EventArgs)

Value#

Type: System.EventHandler(EventArgs)

Remarks#

Called event handlers should expect exceptions if they call methods of the camera. It is safe to call Close().

If an event handler throws an exception, it will be ignored and the remaining handlers will be called.

This event is fired inside the lock of the camera instance. Event handlers should make no assumptions on the thread from which the event handler is called.

ICamera.Close Method#

Closes the connection to the camera.

Syntax#

C#

void Close()

VB

Sub Close

Remarks#

If the connection to the camera has been already closed, the function returns successfully.
If the camera is currently grabbing, grabbing is stopped.
The OnClose event is raised. If any event handler throws an exception it will be ignored and the next event handler will be called.
The connection to the camera device is closed.
The OnClosed event is raised. If any event handler throws an exception, it will be ignored and the next event handler will be called.

Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety: Does not throw exceptions.

ICamera.CreateFileStream Method#

Create a file stream for upload or download.

Syntax#

C#

Stream CreateFileStream(
    string Filename,
    FileAccess Direction
)

VB

Function CreateFileStream ( 
    Filename As String,
    Direction As FileAccess
) As Stream

Parameters#

Filename: Type: System.String
Name of the file in the camera. PLCamera.FileSelector contains a list of available file names.
Direction: Type: System.IO.FileAccess
Write to the camera or read from the camera.

Return Value#

Type: Stream
Returns a stream object for writing or reading.

Remarks#

Preconditions for updating the camera info:

The camera is open.

Example:

// Copy a file into a byte array:
using (Stream fs = m_camera.CreateFileStream( fileName, System.IO.FileAccess.Read ))
using (MemoryStream ms = new MemoryStream())
{
    fs.CopyTo( ms ); 
    byte [] Buffer = ms.ToArray();
}

It is not possible to access multiple files in parallel. Dispose the stream before opening the next.

Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety: Does throw exceptions.

ICamera.ExecuteSoftwareTrigger Method#

Executes the software trigger command.

Syntax#

C#

void ExecuteSoftwareTrigger()

VB

Sub ExecuteSoftwareTrigger

Remarks#

To use this method, the camera has to be configured for software triggering.

Before executing a software trigger, you should check whether the camera is ready to accept a software trigger using WaitForFrameTriggerReady(Int32, TimeoutHandling)Preconditions:

The camera device is physically connected and a connection to the camera has been opened.
The camera device supports software triggering.
The grabbing is started using a stream grabber.

Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety:Can throw exceptions.

ICamera.GetSfncVersion Method#

Gets the version number of the SFNC specification that the camera complies to.

Syntax#

C#

Version GetSfncVersion()

VB

Function GetSfncVersion As Version

Return Value#

Type: Version
Returns the version number of the SFNC specification that the camera complies to. If no SFNC version information is available, a version of 0.0.0.0 is returned.

Remarks#

You can use the SFNC version number to determine which parameters the camera can provide.

Preconditions:

The connection to the camera device must be open.

Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety: Can throw exceptions.

ICamera.Open Method#

Opens a connection to the camera device.

Syntax#

C#

ICamera Open()

VB

Function Open As ICamera

Return Value#

Type: ICamera
Returns a reference to the opened camera.

Remarks#

If the connection to the camera is already open, the function returns successfully.
The CameraOpening event is fired. The notification of event handlers stops in case any eventhandler throws an exception.
The connection to the camera device is established.
The CameraOpened event is fired if the camera object has been opened successfully. The notification of event handlers stops in case any eventhandler throws an exception.

Opening the camera connection may fail if the camera connection has been already opened by another instance or if a physical connection could not be established. You can check the current state of a camera by calling CameraFinder::GetDeviceAccessibilityInfo

Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety: Can throw exceptions if the camera cannot be opened successfully or if any of the event handlers throws an exception.

ICamera.Open Method (Int32, TimeoutHandling)#

Tries to open a connection to the camera until a timeout occurs. If the camera device is not available, the method tries to access the camera until a timeout occurs.

Syntax#

C#

bool Open(
    int timeoutMs,
    TimeoutHandling timeoutHandling
)

VB

Function Open ( 
    timeoutMs As Integer,
    timeoutHandling As TimeoutHandling
) As Boolean

Parameters#

timeoutMs: Type: System.Int32
The timeout period in milliseconds.
timeoutHandling: Type: Basler.Pylon.TimeoutHandling
The action to perform when the function exits with a timeout.

Return Value#

Type: Boolean
Returns false if the camera cannot be found or opened.

Remarks#

If the camera is already open, the function returns successfully.
If the camera device is not available, the method tries to rediscover the camera by enumerating all camera devices of the same type or by checking the availability until a timeout occurs or the camera class is disposed.
If the camera is not found, the method returns or throws an exception. The action depends on the timeoutHandling parameter.
Calls Open()) if the camera device has been found by enumeration and it is accessible (see GetDeviceAccessibilityInfo(ICameraInfo)).

Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety: Can throw exceptions if the camera cannot be opened successfully or if any of the event handlers throws an exception.

ICamera.WaitForFrameTriggerReady Method#

Polls the parameters of the camera until the camera is ready to receive a software trigger.

Syntax#

C#

bool WaitForFrameTriggerReady(
    int timeoutMs,
    TimeoutHandling timeoutHandling
)

VB

Function WaitForFrameTriggerReady ( 
    timeoutMs As Integer,
    timeoutHandling As TimeoutHandling
) As Boolean

Parameters#

timeoutMs: Type: System.Int32
The timeout period in milliseconds. If the SoftwareTrigger.IsDone() method does not return true within the given period, a timeout will occur. The exact timeout behaviour can be set using the timeoutHandling parameter.
timeoutHandling: Type: Basler.Pylon.TimeoutHandling
The action to perform when the functions exits with a timeout.

Return Value#

Type: Boolean
Returns true if the camera was ready to receive a software trigger within the given time period. Otherwise, the action specified in timoutHandling is performed.

Remarks#

After issuing a software trigger, there is a short time period within which the camera is unable to accept another trigger. During this period, all triggers are ignored. You can use this function to poll until the camera is ready to accept a trigger.

Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety: Can throw exceptions.

ICamera.Open Method#

Overload List#

	Name	Description
	Open()	Opens a connection to the camera device.
	Open(Int32, TimeoutHandling)	Tries to open a connection to the camera until a timeout occurs. If the camera device is not available, the method tries to access the camera until a timeout occurs.

ICamera.CameraInfo Property#

Provides access to camera information. The camera information can be updated if camera properties have changed. Camera properties may change e.g. if a GigE camera has been assigned a new IP address after reconnection.

Syntax#

C#

ICameraInfo CameraInfo { get; set; }

VB

Property CameraInfo As ICameraInfo
    Get
    Set

Return Value#

Type: ICameraInfo
Returns information about the camera.

Remarks#

Returns the camera information collection containing detailed camera information, e.g. name or serial number.

Preconditions for updating the camera info:

The camera is closed.
The properties SerialNumber and the DeviceType of the updated camera information and the current camera information are identical.
The updated camera information is provided by the CameraFinder.

Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety: Does not throw exceptions when read. Can throw exceptions when set and the preconditions are not met.

ICamera.IsConnected Property#

Indicates if the camera device is properly connected to the camera object while the camera object is open.

Syntax#

C#

bool IsConnected { get; }

VB

ReadOnly Property IsConnected As Boolean
    Get

Return Value#

Type: Boolean
Returns true if the camera device is properly connected to the camera object while the camera object is open. Returns false if the camera object is closed.

Remarks#

Caution
Due to technical reasons, the property may not be updated immediately after the first error caused by a device removal occurs.

The connection to the camera device can be lost if it is physically disconnected from the PC.

Thread Safety:This method is synchronized with the lock of the camera object.

Error Safety: Does not throw exceptions.

ICamera.IsOpen Property#

Indicates if camera object has been opened.

Syntax#

C#

bool IsOpen { get; }

VB

ReadOnly Property IsOpen As Boolean
    Get

Return Value#

Type: Boolean
Returns true if camera object has been opened.

Remarks#

The camera object will not automatically close itself if the connection to the camera device is lost, e.g., if the camera device is physically disconnected from the PC.

Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety: Does not throw exceptions.

ICamera.Parameters Property#

Returns the parameter collection of the camera for accessing all parameters. Example: camera.Parameters[PLCamera.Width].GetValue();

Syntax#

C#

IParameterCollection Parameters { get; }

VB

ReadOnly Property Parameters As IParameterCollection
    Get

Return Value#

Type: IParameterCollection
Returns the parameter collection of the camera.

Remarks#

You can use the parameter collection to configure the camera device and the camera instance through parameters. You can access parameters by their name or predefined parameter lists.

There are several predefined parameter lists available:

PLCamera
PLCameraInstance
PLStreamGrabber
PLEventGrabber
PLTransportLayer

For more information about the parameters, see the documentation for the parameter list.

You can access parameters by passing a key from a parameter list to the index operator, e.g. C#

camera.Parameters[PLCamera.Width].GetValue();

Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety: Does not throw exceptions

ICamera.StreamGrabber Property#

Returns the stream grabber of the camera object.

Syntax#

C#

IStreamGrabber StreamGrabber { get; }

VB

ReadOnly Property StreamGrabber As IStreamGrabber
    Get

Return Value#

Type: IStreamGrabber
Returns the stream grabber of the camera object.

Remarks#

The stream grabber can be used retrieve images from the camera.

Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety: Does not throw exceptions.