Spinnaker Python Programmer Guide
Spinnaker Python Programmer Guide
Revised 9/20/2023
Names and marks appearing on the products herein are either registered trademarks or trademarks of FLIR Systems, Inc. and/or its subsidiaries.
© 2015-2023 FLIR Integrated Imaging Solutions Inc. All rights reserved.
Logging 22
Names and marks appearing on the products herein are either registered trademarks or trademarks of FLIR Systems, Inc. and/or its subsidiaries.
© 2015-2023 FLIR Integrated Imaging Solutions Inc. All rights reserved.
Python Programmer's Guide Contents
Fundamentals of Spinnaker
Architecture of Spinnaker
Examples
Nodes
QuickSpin API
C# Graphical User Interface API
Camera XML
Recommended Development Environment
Instantiate Cameras
Popular Features in Spinnaker
Enumeration
Asynchronous Hardware Triggering
Setting Black Level
Setting Exposure Time
Setting Gain
Setting Gamma
Setting White Balance
Accessing Raw Bayer Data
Setting Number of Software Buffers
Basic Features
Event Handling
Grabbing Images
Image Pointer Class
Error Handling
Loading and Saving Images
Advanced Features
Chunk Data
Sequencer
Logic Block
Logging
Fundamentals of Spinnaker
Architecture of Spinnaker API
Spinnaker API is built around the GenICam standard, which offers a generic programming interface for
various cameras and interfaces. Spinnaker is an extension of GenAPI. Spinnaker provides quick and easy
access to your camera.
Spinnaker API includes two major components:
Image Acquisition—This is the acquisition engine that is responsible for setting up image buffers and
image grabbing.
Camera Configuration—This is the configuration engine that is responsible for controlling your camera.
This component consists of QuickSpin API, which is a wrapper that makes GenAPI easy to use.
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 3
Solutions Inc.
All rights reserved.
Examples
Included with the Spinnaker SDK are a number of source code examples to help you get started. These
examples are provided for C, C++, C#, and [Link] languages and are precompiled for your convenience.
The table below describes the available Spinnaker SDK examples.
How to get chunk data on an image, either from the nodemap or from the
ChunkData
image itself
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 4
Solutions Inc.
All rights reserved.
Spinnaker Example Description
EnumerationEvents Explore arrival and removal events on interfaces and the system
ImageEvents Image events shows how to acquire images using the image event handler.
LookupTable Configure lookup tables for the customization and control of individual pixels
Sequencer
(Blackfly S, Forge and Oryx Capture multiple images with different parameters in a sequence
only)
Graphical User Interface for evaluating and setting camera parameters using
SpinSimpleGUI_DirectShow
DirectShow
SpinSimpleGUI_MFC Graphical User Interface for evaluating and setting camera parameters
Nodes
Every GenICam compliant camera has an XML description file. The XML describes camera features, their
interdependencies, and all other information like availability, access control, and minimum and maximum
values. These features include Gain, Exposure Time, Image Format, and others. The elements of a camera
description file are represented as software objects called Nodes. A Node map is a list of nodes created
dynamically at run time.
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 5
Solutions Inc.
All rights reserved.
To access camera properties such as setting image width:
width->SetValue(new_width_val);
Most camera parameters (all items in camera.h) can be accessed using the QuickSpin API.
For parameters not handled by QuickSpin API, you can access them via GenICam API (GenAPI). GenAPI is
the generic programming interface for configuring all kinds of cameras. GenAPI is maintained by the
European Machine Vision Association.
Below is an example comparison of inquiring camera gain via GenAPI and QuickSpin API.
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 6
Solutions Inc.
All rights reserved.
CFloatPtr GainNode = [Link]("Gain");
Float GainVal = GainNode->GetValue();
[Link](cam);
ImageDrawingWindow AcquisitionDrawing =
[Link]();
[Link](cam);
[Link]();
[Link]();
[Link](cam);
CameraSelectionWindow camSelection =
[Link]();
[Link](true);
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 7
Solutions Inc.
All rights reserved.
//To show property grid window
[Link](cam);
PropertyGridWindow propWindow =
[Link]();
[Link](cam);
[Link]();
[Link](cam);
[Link]();
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 8
Solutions Inc.
All rights reserved.
Camera XML
The camera's XML file contains information such as feature naming, register mapping, and dependencies
between features. It is typical for GenICam-compliant software to cache the XML file for quicker access to
the camera's definition. Spinnaker caches the XML file in a binary format to achieve better performance.
Camera XML files are located in:
C:\ProgramData\Spinnaker\XML
Recommended Environment
Spinnaker supports the following list of operating systems and development environments.
Windows 7
OS Compatibility
Windows 8.1
(32- and 64-bit)
Windows 10
C
C++
Language Support C#
[Link]
Python
Visual Studio 2015
Visual Studio 2017
Compiler Support
Visual Studio 2019
Visual Studio 2022
Interface Support USB3 Vision 1.0
Instantiate Cameras
Before you can instantiate a camera, you must create and initialize a system object. The System Singleton
object is used to retrieve the list of interfaces (USB 3.1 or GigE) and cameras available. You must call
ReleaseInstance() at the end of your program to free up the system object.
Multiple cameras can only be instantiated one at a time.
cam_list = [Link]()
num_Cameras = cam_list.GetSize()
Instantiate multiple cameras (Python)
for i, cam in enumerate(cam_list):
[Link]()
# Release system
[Link]()
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 9
Solutions Inc.
All rights reserved.
Popular Features in Spinnaker
Enumeration
The snippet below detects the number of cameras connected and enumerates them from an index.
system = [Link]()
cam_list = [Link]()
num_cameras = cam_list.GetSize()
Spinnaker Python GenAPI for cam_idx in range(num_cameras):
cam = cam_list.GetByIndex(cam_idx)
[Link]()
[Link](PySpin.TriggerMode_On)
[Link](PySpin.TriggerActivation_RisingEdge)
node_trigger_mode = [Link](node_map.GetNode("TriggerMode"))
node_trigger_mode.SetIntValue(node_trigger_mode.GetEntryByName("On").GetValue())
node_trigger_source = [Link](node_map.GetNode("TriggerSource"))
node_trigger_source.SetIntValue(node_trigger_source.GetEntryByName
("Line0").GetValue())
Spinnaker Python node_trigger_selector = [Link](node_map.GetNode("TriggerSelector"))
GenAPI node_trigger_selector.SetIntValue(node_trigger_selector.GetEntryByName
("FrameStart").GetValue())
node_trigger_activation = [Link](node_map.GetNode
("TriggerActivation"))
node_trigger_activation.SetIntValue(node_trigger_activation.GetEntryByName
("RisingEdge").GetValue())
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 10
Solutions Inc.
All rights reserved.
Setting Black Level
BlackLevel is the GenICam feature that represents the DC offset that is applied to the video signal. This
example compares the mechanism used to set this feature in both environments.
node_black_level_selector = [Link](node_map.GetNode
("BlackLevelSelector"))
Spinnaker Python node_black_level_selector.SetIntValue(node_black_level_selector.GetEntryByName
GenAPI ("All").GetValue())
node_black_level = [Link](node_map.GetNode("BlackLevel"))
node_black_level.SetValue(1.5)
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 11
Solutions Inc.
All rights reserved.
Setting Gain
The following code snippet adjusts gain to 10.5 dB.
Setting Gamma
The following code snippet adjusts gamma to 1.5.
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 12
Solutions Inc.
All rights reserved.
Setting White Balance
The following code snippet adjusts the white balance's red and blue channels.
node_balance_white_auto = [Link](node_map.GetNode
("BalanceWhiteAuto"))
node_balance_white_auto.SetIntValue(node_balance_white_auto.GetEntryByName
("Off").GetValue())
node_balance_ratio_selector = [Link](node_map.GetNode
("BalanceRatioSelector"))
Spinnaker Python node_balance_ratio_selector.SetIntValue(node_balance_ratio_selector.GetEntryByName
GenAPI ("Blue").GetValue())
node_balance_ratio = [Link](node_map.GetNode("BalanceRatio"))
node_balance_ratio.SetValue(2)
node_balance_ratio_selector.SetIntValue(node_balance_ratio_selector.GetEntryByName
("Red").GetValue())
node_balance_ratio.SetValue(2)
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 13
Solutions Inc.
All rights reserved.
Accessing Raw Bayer Data
Raw image data can be accessed programmatically by converting the Spinnaker Image class to numpy
array using GetNDArray. In 8 bits per pixel modes such as BayerRG8, the first byte represents the pixel at
[row 0, column 0], the second byte at [row 0, column 1], and so on. The top left corner of the image data
represents row 0, column 0.
# Assuming image is 640 x 480 resolution. The current pixel format as well as
PixelColorFilter indicate the Bayer Tile Mapping for the camera. For example, BayerRG8 is
RGGB.
result_image = [Link]()
Spinnaker Python data = result_image.GetNDArray()
API
# Assuming image is 640 x 480
# data[0,0] = Row 0, Column 0 = red pixel (R)
# data[0,1] = Row 0, Column 1 = green pixel (G)
# data[1,0] = Row 1, Column 0 = green pixel (G)
# data[1,1] = Row 1, Column 1 = blue pixel (B)
s_node_map = [Link]()
node_stream_buffer_count_manual = [Link](s_node_map.GetNode
Spinnaker Python
("StreamBufferCountManual"))
API
buffer_count = node_stream_buffer_count_manual.GetValue()
node_stream_buffer_count_manual.SetValue(11)
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 14
Solutions Inc.
All rights reserved.
Basic Features
Event Handling
Spinnaker introduces two event classes: interface events and device events.
Interface Event
The interface event class is a new feature that is responsible for registering and deregistering user
defined interface events such as device arrival and removal.
class InterfaceEventHandler([Link]):
def OnDeviceArrival(self,camera):
node_map_tldevice = [Link]()
node_device_serial_number = [Link](node_map_tldevice.GetNode
(“DeviceSerialNumber”))
device_serial_number = node_device_serial_number.GetValue()
node_device_serial_number = [Link]
device_serial_number = node_device_serial_number.GetValue()
handler = InterfaceEventHandler()
interface_list = [Link]()
interface = interface_list.GetByIndex(0)
[Link](handler)
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 15
Solutions Inc.
All rights reserved.
Device Event
The device event class is responsible for registering and deregistering user defined device events such as
start or end of exposure.
node_event_notification_on.SetIntValue(node_event_notification_on.GetEntryByName
Device Event ("On").GetValue())
Python
# Once Exposure End Event is detected, the OnDeviceEvent function will be called
class DeviceEventHandler([Link]):
def OnDeviceEvent(self,eventname):
Grabbing Images
You can grab images using the GetNextImage() function. This function returns an image pointer for the
current image. The image pointer should be released whenever you are done with the image. Image
pointer, being a smart pointer, is automatically released when set to null or when out of scope.
result_image.Release()
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 16
Solutions Inc.
All rights reserved.
Grab Result
In almost all cases, you should check to see if the grabbed image has any errors. To do so, you need to
call getImageStatus().
class ImageStatus(Enum):
IMAGE_NO_ERROR = 0
# Image is returned from GetNextImage() call without any errors. */
IMAGE_CRC_CHECK_FAILED = 1
# Image failed CRC check.
IMAGE_INSUFFICIENT_SIZE = 2
# Image size is smaller than expected.
Available error IMAGE_MISSING_PACKETS = 3
enums # Image has missing packets
IMAGE_LEADER_BUFFER_SIZE_INCONSISTENT = 4
# Image leader is incomplete.
IMAGE_TRAILER_BUFFER_SIZE_INCONSISTENT = 5
# Image trailer is incomplete.
IMAGE_PACKETID_INCONSISTENT = 6
# Image has an inconsistent packet id.
IMAGE_DATA_INCOMPLETE = 7
# Image data is incomplete.
IMAGE_UNKNOWN_ERROR = 8
# Image has an unknown error.
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 17
Solutions Inc.
All rights reserved.
Image Pointer Class
The image pointer (ImagePtr) is a smart pointer that points to the image object. You can have multiple
image pointers pointing to the same object. Smart pointers automatically manage the life time of the
object that it points to. You can also re-use the same image pointer object.
Image pointer should always be assigned before using.
result_image = [Link]
duplicate_image = result_image
# Incorrect usage
Image Pointer
illegal_image = [Link]
INCORRECT Usage
illegal_image.Create(...)
Error Handling
Spinnaker Python uses a try except block for exception handling.
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 18
Solutions Inc.
All rights reserved.
Loading and Saving Images
Loading and saving a raw image (.raw) from disk into Spinnaker library can be achieved via Image class's
smart pointer.
offline_image_width = 1280
offline_image_height = 1024
offline_offset_x = 0
offline_offset_y = 0
offline_data = [Link](filename,dtype=[Link])
processor = [Link]()
result_image = [Link](load_image,PySpin.PixelFormat_Mono8)
# Save image
result_image.Save("[Link]")
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 19
Solutions Inc.
All rights reserved.
Advanced Features
Chunk Data
Chunk data is extra information that the camera can append to each image besides image data. Examples
of chunk data include frame counter, image width, image height and exposure time.
For a listing of chunk data information supported by your camera, please refer to the camera's Technical
Reference manual.
An image is comprised of:
n Leader
n Image Data
n Chunk Information (i.e., gain, exposure, image size)
n Trailer
[Link](PySpin.ChunkSelector_ExposureTime)
Python Enable
[Link](True)
Chunk Data
[Link](True)
Sequencer
The purpose of a sequencer is to allow you to programmatically control the acquisition parameters of an
image sequence. You can define not only how the images are captured (i.e. the camera feature settings)
but also when the camera transitions from one acquisition setting to another. This is akin to a state
machine diagram where the states correspond to the sequencer set feature settings, and the transition
among states corresponds to a particular event that triggers the state machine to move from one state to
another.
To configure sequencer on your camera, you can use SpinView's sequencer tab. Or, to programmatically
configure it, you can use the python Sequencer source code example that come along with Spinnaker
Python package.
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 20
Solutions Inc.
All rights reserved.
Logic Block
A Logic Block is a collection of combinatorial logic and latches that allows the user to create new, custom
signals inside the camera. Each Logic Block is comprised of 2 lookup tables (LUT) with programmable
inputs, truth tables and a flip flop output. There is a LUT for both the D input (Value LUT) and the enable
input (Enable LUT) of the flip flop. Both LUTs have 3 inputs and thus have 8 configuration bits for their
truth table.
For more information, see Using Logic Blocks.
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 21
Solutions Inc.
All rights reserved.
Logging
Spinnaker supports five levels of logging:
n Error—failures that are non-recoverable (this is the default level)
n Warning—failures that are recoverable without user intervention
n Notice—information about events such as camera arrival or disconnect, camera initialize, camera
start/stop, or modification of a feature
n Info—information about recurring events that are generated with every image
n Debug—information that can be used to troubleshoot the system
You can define the logging level that you want to monitor. Levels are inclusive, that is, if you monitor
debug level error, you also monitor all logging levels above it.
For a complete python example of Logging, please see Spinnaker python package source code examples.
By default, Spinnaker SDK's SpinView application saves all logging data to:
C:\ProgramData\Spinnaker\Logs
class LoggingEventHandler([Link]):
9/20/2023
©2015-2023 FLIR
Integrated Imaging Spinnaker Python Programmer's Guide 22
Solutions Inc.
All rights reserved.