Camera

Provides access to the camera lists, the cameras, and camera related event handlers.

Classes:

`DeviceEventHandler`	A camera event handler that is returned by `attach_device_event_handler()` that handles callbacks for camera events.
`ImageEventHandler`	A camera image handler that is returned by `attach_image_event_handler()` that handles callbacks for camera images arrival events.
`CameraList`	Provides access to cameras enumerated by the system or interfaces as a list of cameras on the system or specific to that interface.
`Camera`	A Spinnaker based camera, such as GigE, USB2/3 etc.

class DeviceEventHandler

Bases: EventHandlerBase

A camera event handler that is returned by attach_device_event_handler() that handles callbacks for camera events.

This represents a callback function that is called on each event with 3 positional arguments: this instance, the Camera instance that created this, and the event name string.

Methods:

`get_event_data`	Returns the data associated with the callback event.
`get_event_metadata`	Returns the metadata associated with the callback event.

get_event_data(self, unicode event_name)

Returns the data associated with the callback event.

It returns a dictionary of data values or None if no data is associated with the event.

Warning

This is only valid if called from within the callback, not once the callback is completed.

get_event_metadata(self)

Returns the metadata associated with the callback event.

It returns a 3-tuple of (event_type, dev_name, dev_event_id). Where event_type is the string event type from event_names. dev_name is the name of the device event. And dev_event_id is the ID of the device event.

Warning

This is only valid if called from within the callback, not once the callback is completed.

class ImageEventHandler

Bases: EventHandlerBase

A camera image handler that is returned by attach_image_event_handler() that handles callbacks for camera images arrival events.

This represents a callback function that is called every time a new image becomes available with 3 positional arguments: this instance, the Camera instance that created this, and the Image instance representing the new image.

Remember to release() the image quickly so that the buffers can be re-used by the camera.

class CameraList

Bases: object

Provides access to cameras enumerated by the system or interfaces as a list of cameras on the system or specific to that interface.

Warning

Do not create a CameraList manually, rather get it from create_from_system() or create_from_interface().

Once a CameraList is created from the system or interface, updating the system or interface so it detects new cameras will not be reflected in existing CameraList. Instead, create a new one to access those new cameras.

Methods:

`create_camera_by_dev_id`	Retrieves a camera from this camera list using its device identifier.
`create_camera_by_index`	Retrieves a camera from this camera list using a zero-based index that is less than `get_size()`.
`create_camera_by_serial`	Retrieves a camera from this camera list using its serial number string.
`create_from_interface`	Creates and returns a new `CameraList` for accessing the cameras on a specific interface.
`create_from_system`	Creates and returns a new `CameraList` for accessing cameras across all interfaces on the system.
`extend_camera_list`	Appends all the cameras from the other camera list to this list.
`get_size`	Retrieves the number of cameras in the camera list.
`remove_camera_by_dev_id`	Removes a camera from this camera list using its device identifier.
`remove_camera_by_index`	Removes a camera from this camera list using its index.
`remove_camera_by_serial`	Removes a camera from this camera list using its serial number string.

create_camera_by_dev_id(self, unicode dev_id)

Retrieves a camera from this camera list using its device identifier.

Parameters: dev_id – The device identifier of the camera to retrieve. This can be gotten from get_unique_id().
Returns: A Camera.

create_camera_by_index(self, unsigned int index)

Retrieves a camera from this camera list using a zero-based index that is less than get_size().

Parameters: index – The index of the camera.
Returns: A Camera.

create_camera_by_serial(self, unicode serial)

Retrieves a camera from this camera list using its serial number string.

Parameters: serial – The serial number of the camera to retrieve.
Returns: A Camera.

You can get a camera’s serial number using the "DeviceSerialNumber" node once the camera is init_cam(). It’s pre-listed at DeviceSerialNumber.

static create_from_interface(InterfaceDevice interface, bool update_cams=True)

Creates and returns a new CameraList for accessing the cameras on a specific interface.

It returns either usb3 vision or gige vision cameras depending on the underlying transport layer of this interface.

Parameters

interface – A InterfaceDevice instance.
update_cams – Whether to update the interface’s internal camera list to detect new/removed cameras before getting the camera list.

Returns

A CameraList.

static create_from_system(SpinSystem system, bool update_interfaces=True, bool update_cams=True)

Creates and returns a new CameraList for accessing cameras across all interfaces on the system.

This returns both GigE Vision and Usb3 Vision cameras from all interfaces.

Parameters

system – A SpinSystem instance.
update_interfaces – Whether to update the system’s internal interface list before getting the camera list from all the interfaces.
update_cams – Whether to update the system’s internal camera list to detect new/removed cameras before getting the camera list.

Returns

A CameraList.

extend_camera_list(self, CameraList other_list)

Appends all the cameras from the other camera list to this list.

Parameters: other_list – The camera list to add to us.

get_size(self): Retrieves the number of cameras in the camera list.

remove_camera_by_dev_id(self, unicode dev_id)

Removes a camera from this camera list using its device identifier.

Parameters: dev_id – The device identifier of the camera to remove. This can be gotten from get_unique_id().

remove_camera_by_index(self, unsigned int index)

Removes a camera from this camera list using its index.

Parameters: index – The index of the camera to remove.

remove_camera_by_serial(self, unicode serial)

Removes a camera from this camera list using its serial number string.

Parameters: serial – The serial number of the camera to remove.

You can get a camera’s serial number using the "DeviceSerialNumber" node once the camera is init_cam(). It’s pre-listed at DeviceSerialNumber.

class Camera

Bases: object

A Spinnaker based camera, such as GigE, USB2/3 etc.

Warning

Do not create a Camera manually, rather get it from CameraList.create_camera_by_index(), CameraList.create_camera_by_serial(), or CameraList.create_camera_by_dev_id().

Before the camera can be used and most nodes are accessible, you need to initialize the camera using init_cam(). When you’re done, call deinit_cam().

Methods:

`attach_device_event_handler`	Registers the callback to get events from camera.
`attach_image_event_handler`	Registers the callback to get called on new camera images.
`begin_acquisition`	Starts the image acquisition engine from the camera.
`deinit_cam`	De-initializes a camera that was initialized with `init_cam()`.
`detach_device_event_handler`	Detaches an event handler previously returned by `attach_device_event_handler()`.
`detach_image_event_handler`	Detaches an event handler previously returned by `attach_image_event_handler()`.
`end_acquisition`	Stops the image acquisition engine.
`force_ip`	Forces the camera to be on the same subnet as its corresponding interface (e.g.
`get_access_mode`	Returns the access mode that the software has on the Camera as a string from `AccessMode_names`.
`get_buffer_count`	Gets the number of user memory buffers.
`get_buffer_ownership`	Gets data buffer ownership as a string from `buffer_owner_names`.
`get_buffer_size`	Gets the size of one user memory buffer (in bytes).
`get_buffer_total_size`	Gets the total size of all the user memory buffers (in bytes).
`get_gui_xml`	Retrieves the GUI XML from the camera, that can be passed into the Spinnaker GUI framework.
`get_max_packet_size`	Returns the largest packet size that can be safely used on the interface that the device is connected to.
`get_next_image`	Gets the next image that was received by the transport layer.
`get_node_map`	Gets the `NodeMap` that is generated from a GenICam XML file.
`get_num_data_streams`	Returns the number of streams that a device supports.
`get_num_images_in_use`	Returns the number of images that are currently in use.
`get_tl_dev_node_map`	Gets the `NodeMap` that is generated from a GenICam XML file for the GenTL Device module.
`get_tl_stream_node_map`	Gets the `NodeMap` that is generated from a GenICam XML file for the GenTL Stream module.
`get_unique_id`	This returns a unique id string that identifies the camera.
`init_cam`	Initializes a camera, allowing for much more interaction, including more properties.
`is_init`	Checks whether a camera is currently initialized.
`is_streaming`	Checks whether a camera is currently streaming.
`is_valid`	Checks whether a camera is still valid for use.
`read_port`	Reads a remote port on a physical Camera.
`release`	Releases the camera's resources, including the nodes.
`set_buffer_ownership`	Sets data buffer ownership from a string from `buffer_owner_names`.
`set_user_buffer`	Specify contiguous user allocated memory to use as data buffers.
`set_user_buffers`	Specify non-contiguous user allocated memory to use as data buffers.
`write_port`	Writes a remote port on a physical Camera.

Attributes:

`camera_nodes`	camera_nodes: rotpy.camera_nodes.CameraNodes The pre-listed camera nodes from `CameraNodes`.
`tl_dev_nodes`	tl_dev_nodes: rotpy.camera_nodes.TLDevNodes The pre-listed transport layer device nodes from `TLDevNodes`.
`tl_stream_nodes`	tl_stream_nodes: rotpy.camera_nodes.TLStreamNodes The pre-listed transport layer streaming nodes from `TLStreamNodes`.

attach_device_event_handler(self, callback, unicode name=u'')

Registers the callback to get events from camera.

Parameters

callback – A function that will be called upon camera events. See DeviceEventHandler for the function signature.
name – An optional event name. If empty (the default), all events will be handled.

Returns

A DeviceEventHandler instance representing the callback.

The callback will receive the camera events while it is registered, possibly even before this function returns(?) and could potentially be called by external threads. It’s best not to do any work in it.

Warning

The camera has to be initialized first with init_cam() before registering callbacks for events.

attach_image_event_handler(self, callback)

Registers the callback to get called on new camera images.

Parameters: callback – A function that will be called upon new images. See ImageEventHandler for the function signature.
Returns: A ImageEventHandler instance representing the callback.

The callback will receive the camera images while it is registered, possibly even before this function returns(?) and could potentially be called by external threads. It’s best not to do any work in it.

Warning

The camera has to be initialized first with init_cam() before registering handlers for images.

begin_acquisition(self)

Starts the image acquisition engine from the camera.

The camera must be initialized first with init_cam().

camera_nodes: camera_nodes: rotpy.camera_nodes.CameraNodes The pre-listed camera nodes from CameraNodes.

Use this property to get a pre-instantiated CameraNodes because CameraNodes is not user instantiable.

Note

Remember to check whether each of the pre-listed nodes are is_available(), is_readable(), is_writable() etc.

deinit_cam(self)

De-initializes a camera that was initialized with init_cam().

This should happen after you’re done with the camera.

detach_device_event_handler(self, DeviceEventHandler handler)

Detaches an event handler previously returned by attach_device_event_handler().

Parameters: handler – The DeviceEventHandler that handled the events.

Warning

Event handlers should be unregistered first before calling deinit_cam(). Otherwise an exception will be thrown in the deinit_cam() call and require the user to unregister event handlers before the camera can be re-initialized again.

detach_image_event_handler(self, ImageEventHandler handler)

Detaches an event handler previously returned by attach_image_event_handler().

Parameters: handler – The ImageEventHandler that handled the events.

Warning

Event handlers should be unregistered first before calling deinit_cam(). Otherwise an exception will be thrown in the deinit_cam() call and require the user to unregister event handlers before the camera can be re-initialized again.

end_acquisition(self)

Stops the image acquisition engine.

If end_acquisition() is called without a prior call to begin_acquisition() an error will be thrown.

All Images that were acquired using get_next_image() need to be release() first before calling this. All buffers in the input pool and output queue will be discarded when this is called.

force_ip(self): Forces the camera to be on the same subnet as its corresponding interface (e.g. for gigE cameras).

get_access_mode(self)

Returns the access mode that the software has on the Camera as a string from AccessMode_names.

The camera does not need to be initialized before calling this function.

get_buffer_count(self)

Gets the number of user memory buffers.

This will throw an exception if user memory buffer has not been set. If the user memory is contiguous, this will throw an exception unless begin_acquisition() has been called.

get_buffer_ownership(self)

Gets data buffer ownership as a string from buffer_owner_names.

The data buffers can be owned by System or User. If the system owns the buffers, the memory required for the buffers are allocated and freed by the library. If user owns the buffers, the user is responsible for allocating and ultimately freeing the memory. By default, data buffers are owned by the library.

get_buffer_size(self)

Gets the size of one user memory buffer (in bytes).

This will throw an exception if user memory buffer has not been set. If the user memory is contiguous, this will throw an exception unless begin_acquisition() has been called. To prevent image tearing when working with USB3 cameras, the size of each buffer should be equal to ((unsigned int) (bufferSize + 1024 - 1) / 1024) * 1024 where 1024 is the USB3 packet size.

get_buffer_total_size(self)

Gets the total size of all the user memory buffers (in bytes).

This will throw an exception if user memory buffer has not been set.

get_gui_xml(self): Retrieves the GUI XML from the camera, that can be passed into the Spinnaker GUI framework.

get_max_packet_size(self): Returns the largest packet size that can be safely used on the interface that the device is connected to.

get_next_image(self, timeout=None, uint64_t stream_id=0)

Gets the next image that was received by the transport layer.

Parameters

timeout – Optional timeout in seconds. If not provided, it may wait indefinitely until an image becomes available. If provided, if it times out before an image is available it returns None.
stream_id – The stream to grab the image. Most cameras support one stream so the default stream_id is 0 but if a camera supports multiple streams you can input the stream ID to select from which stream to grab images.

Returns

An Image or None if it timed out. If the image data was incomplete, a ValueError is raised.

Warning

Make sure to call release() as quickly as possible after getting the image. Because until the image is released, the camera cannot re-use the buffer. So, if too many buffers are held, the camera may run out of buffers in which to store images.

get_node_map(self)

Gets the NodeMap that is generated from a GenICam XML file.

The camera must be initialized by a call to init_cam() first before the node map can be successfully acquired.

Returns: A NodeMap.

get_num_data_streams(self): Returns the number of streams that a device supports.

get_num_images_in_use(self): Returns the number of images that are currently in use.

get_tl_dev_node_map(self)

Gets the NodeMap that is generated from a GenICam XML file for the GenTL Device module.

The camera does not need to be initialized with init_cam() before acquiring this node map.

Returns: A NodeMap.

get_tl_stream_node_map(self)

Gets the NodeMap that is generated from a GenICam XML file for the GenTL Stream module.

The camera does not need to be initialized with init_cam() before acquiring this node map.

Returns: A NodeMap.

get_unique_id(self)

This returns a unique id string that identifies the camera.

This e.g. could be the device hardware identifier on the interface etc.

init_cam(self)

Initializes a camera, allowing for much more interaction, including more properties.

This is required before images can be acquired.

is_init(self): Checks whether a camera is currently initialized.

is_streaming(self): Checks whether a camera is currently streaming.

is_valid(self): Checks whether a camera is still valid for use.

read_port(self, uint64_t address, size_t num_bytes)

Reads a remote port on a physical Camera. This function can be used to read registers on the camera.

Parameters

address – A 64 bit address to a register on the camera.
num_bytes – Number of bytes to read.

Returns

An bytes object with the read bytes.

Warning

Only perform direct read/write to a register if the register isn’t supported in the device nodemap. Otherwise the camera and nodemap may be left in an undefined state after the register read/write.

release(self)

Releases the camera’s resources, including the nodes.

Once called, non of the pre-listed node are valid and other camera methods should not be called.

set_buffer_ownership(self, unicode ownership)

Sets data buffer ownership from a string from buffer_owner_names.

The data buffers can be owned by System or User. If the system owns the buffers, the memory required for the buffers are allocated and freed by the library. If user owns the buffers, the user is responsible for allocating and ultimately freeing the memory. By default, data buffers are owned by the library.

set_user_buffer(self, buffer)

Specify contiguous user allocated memory to use as data buffers.

To prevent image tearing when working with USB3 cameras, the size of the buffer should be equal to ((len(buffer) + 1024 - 1) // 1024) * 1024 where 1024 is the USB3 packet size.

Parameters: buffer – A memoryview such as an array, bytes, bytesarray etc.

set_user_buffers(self, buffers, uint64_t buffer_size)

Specify non-contiguous user allocated memory to use as data buffers.

Each buffer must have enough memory to hold one image. To prevent image tearing when working with USB3 cameras, the size of each buffer should be equal to ((len(buffer) + 1024 - 1) // 1024) * 1024 where 1024 is the USB3 packet size.

Parameters

buffers – A list of memoryviews such as arrays, bytes, bytesarrays etc. Each memoryview in the list will be a individual buffer.
buffer_size – The size of the smallest buffer in buffers in bytes. Individual buffer items can be larger, but not smaller.

tl_dev_nodes: tl_dev_nodes: rotpy.camera_nodes.TLDevNodes The pre-listed transport layer device nodes from TLDevNodes.

Use this property to get a pre-instantiated TLDevNodes because TLDevNodes is not user instantiable.

Note

Remember to check whether each of the pre-listed nodes are is_available(), is_readable(), is_writable() etc.

tl_stream_nodes: tl_stream_nodes: rotpy.camera_nodes.TLStreamNodes The pre-listed transport layer streaming nodes from TLStreamNodes.

Use this property to get a pre-instantiated TLStreamNodes because TLStreamNodes is not user instantiable.

Note

Remember to check whether each of the pre-listed nodes are is_available(), is_readable(), is_writable() etc.

write_port(self, uint64_t address, unsigned char[:] data)

Writes a remote port on a physical Camera. This function can be used to write registers on the camera.

Parameters

address – A 64 bit address to a register on the camera.
data – Bytes or memory view-convertible bytes to write.

Warning

Only perform direct read/write to a register if the register isn’t supported in the device nodemap. Otherwise the camera and nodemap may be left in an undefined state after the register read/write.