Technical Application Notes
Click an item to read from the list below.

Technical Application Notes


 

 

Using the Sequencer Feature with Blackfly S

Subject

Technical Application Note TAN2016003: Using the Sequencer

10608

Applicable Products

  • Blackfly S

Application Note Description

This document provides an overview of the Sequencer function in the Blackfly S camera.

The sequencer allows you to control the acquisition parameters of an image sequence. This includes defining the camera feature settings as well as when the camera transitions from one sequence to the next.

One application of the sequencer is in the creation of high dynamic range images where your image source has dramatically different light and shadow in the same scene. Another application might be to examine multiple pieces of a larger image as separate entities with different exposures. An astronomy application could increase the camera's dynamic range by capturing multiple images with different settings, then adding and averaging them. A scientific application could use a filter wheel in front of the lens and adjust the camera's settings every time the wheel rotates.

With sequencer, each image can have its own defined feature set. Blackfly S allows up to 8 sequencer sets.

Example Sequencer Sets
Sequencer
Set
ImageExposure
(ms)
Gain
(dB)
Width
(pixels)
Height
(pixels)
0 1 50 1 80 80
1 2 100 2 160 160
2 3 150 3 320 240
3 4 200 4 640 480
4 5 600 5 1920 1080
 

The sequencer settings are not saved to a user set and therefore not retained over a power cycle of the camera.

A key advantage to the Sequencer is that it does not sacrifice time to change feature properties and the camera can maintain a high frame rate while imaging.

These are the steps to setup and run sequencer. The following sections provide more detail.

Step 1—Enable Features

Step 2—Enter Configuration Mode

Step 3—Configure Sequencer Sets

Step 4—Exit Configuration Mode

Step 5—Execute Sequencer

 

This document uses the SpinView application and Spinnaker C++ QuickSpin API code snippets to demonstrate the configuration and execution of the sequencer. The Spinnaker SDK provides a Sequencer example using the API to achieve a similar effect.

Features

The feature settings used in a sequencer set are a combination of the features specifically configured for the set and what was active when the set was saved. Because many of the camera features are dependently linked to each other, settings may be saved to a set that are outside of the sequencer configuration.

Sequencer features can be classified as follows:

Direct—direct features are those you define as being part of the set with specified values which may vary from one set to another and are independently recorded for each set. Examples include: exposure time, gain, resolution, and offset.

FeatureBFS-U3-13Y3BFS-U3-32S4BFS-U3-51S5
Exposure Time
Gain
Width    
Height    
Offset Y    
Offset X    

Implied—implied features are those that are dependent on the direct features. Their settings are recorded for each set. While you do not define their values as part of the set, they are included so that their values are valid. They can be modified during the configuration of a set, but are locked during sequencer operation.

Fixed—fixed features are those that are the preconditions to implied or direct features. These settings are recorded to guarantee the sequenced features are valid. Fixed features have a single value for the entire sequence. This is locked during sequencer configuration and operation. Examples of features that are locked include: chunk data, trigger mode, pixel format and binning, and color transformation.

Forced—forced features are those whose settings are predefined. These are automatic features that if enabled would control other features and invalidate the settings. They are forced into the Off (manual) mode during sequencer operation. During sequencer configuration, they are modifiable, to allow you to achieve the desired conditions which can then be recorded for later operation. All auto algorithm features are turned off when using sequencer, even for those features that are not directly configured (for example, auto white balance).

Non-sequenced—non-sequenced are features that are not controlled or affected by the sequencer.

Sequencer

Step 1—Enable Features

Direct features that are defined as part of sequencer set configuration must be enabled prior to entering configuration mode. By default, the sequencer is set to have all features enabled.

To enable a sequencer feature

  1. With the camera connected, in the SpinView application, open the Features pane.
  2. Expand the Sequencer Control category.
  3. From the Sequencer Feature Selector, select the feature to enable.
  4. Click on Sequencer Feature Enable.
  5. Repeat for all features required.

Spinnaker C++ QuickSpin API

// Select Sequencer feature
cam->SequencerFeatureSelector.SetValue(SequencerFeatureSelector_ExposureTime);

// Enable selected Sequencer feature
cam->SequencerFeatureEnable.SetValue(true);

As some of the features used in the sequencer are not directly defined in the sequencer sets, they should be defined outside of sequencer configuration. As their definition might have an impact on the validity of the sequencer set, they should be defined prior to entering the configuration mode.

Features that are fixed, include:

  • Chunk data, both what is included in the chunk data and whether or not it is enabled.
  • Trigger mode
  • Image format controls such as pixel format and binning.
  • Color transformation

As auto algorithms are turned off during sequencing, manual values for some features, such as white balance, may be needed.

Step 2—Enter Configuration Mode

Once direct features have been enabled, and fixed features defined, you can enter the Sequencer Configuration Mode to define the sequencer sets. In order to enter Sequencer Configuration Mode, the Sequencer Mode must be Off. By default, both the Sequencer Mode and the Sequencer Configuration Mode are set to Off.

To enter configuration mode

  1. Ensure the Sequencer Mode is Off.
  2. Turn the Sequencer Configuration Mode to On.

Spinnaker C++ QuickSpin API

// Turn on Sequencer configuration mode
cam->SequencerConfigurationMode = SequencerConfigurationMode_On;

When you enter the configuration mode, the camera determines which features are implied and fixed and locks them from being modified. If you find you need to adjust a fixed feature, exit the configuration mode by turning it to Off. Make any modifications and enter the configuration mode again.

Step 3—Configure Sequencer Sets

The Configuration Mode allows you to define the features to be used for each sequencer set, as well as the transitions between them. Blackfly S supports up to 8 sequencer set definitions. You must define a minimum of 2.

To configure a sequencer set

    1. In the Sequencer Set Selector enter the number of the set. Sequencer sets are numbered 0 through 7.

Spinnaker C++ QuickSpin API

// Select Sequencer set
cam->SequencerSetSelector = 0;

      1. From the Sequencer Feature Selector, choose a feature to define. Available features are:
FeatureBFS-U3-13Y3BFS-U3-32S4BFS-U3-51S5
Exposure Time
Gain
Width    
Height    
Offset Y    
Offset X    

Spinnaker C++ QuickSpin API

// Select Sequencer feature
cam->SequencerFeatureSelector.SetValue(SequencerFeatureSelector_ExposureTime);

    1. Set the definition of the feature. Feature definitions are done in their own control categories of the Features pane.

Spinnaker C++ QuickSpin API

// Define value for Sequencer feature
cam->ExposureAuto = ExposureAuto_Off;
cam->ExposureMode = ExposureMode_Timed;
cam->ExposureTime = 998;

    1. If required, select another feature and repeat as needed.
    2. From the Sequencer Trigger Source and Sequencer Trigger, define the trigger condition.

Spinnaker C++ QuickSpin API

// Define the Sequencer trigger condition
cam->SequencerTriggerSource = equencerTriggerSource_FrameStart;
cam->SequencerTriggerActivation = SequencerTriggerActivation_RisingEdge;

    1. In the Sequencer Set Next field, enter the sequencer set that follows the current one.

Spinnaker C++ QuickSpin API

// Define the Sequencer trigger condition
cam->SequencerSetNext = 1;

    1. Execute the Sequencer Set Save to save your definition. When you save a set, the camera checks that all the settings are valid and displays the results of this check in the Sequencer Set Valid field. If the sequencer set is not valid, adjust your settings and save again.

Spinnaker C++ QuickSpin API

// Save the current Sequencer set
cam->SequencerSetSave.Execute();

// Verify the current Sequencer set is valid
CEnumerationPtr ptrSequencerSetValid = nodeMap.GetNode("SequencerSetValid");
CEnumEntryPtr ptrSequencerSetValidYes = ptrSequencerSetValid->GetEntryByName("Yes");
if (!IsAvailable(ptrSequencerSetValid) || !IsReadable(ptrSequencerSetValid))
{
cout << "Unable to validate sequencer set (node retrieval). Aborting..." << endl << endl;
return -1;
}

 

Other previously saved sequencer sets may become invalid when a set is saved with a new configuration.

  • Repeat from step 1 until all required sets are defined.
  • In the Sequencer Set Start field, enter the set that you want to run first.

Spinnaker C++ QuickSpin API

// Define the starting Sequencer set (defaults to 0)
cam->SequencerSetStart = 0;

Once a sequencer set has been defined and is valid, it can be loaded as the active set. This is similar to user set loading except that if affects a much smaller range of features. Loading a sequencer set is useful when you want to configure multiple sets with very similar features.

To copy from an existing sequencer set

    1. In the Sequencer Set Selector field, enter the set from which you want to copy.
    2. Execute Sequencer Set Load. This loads all the settings of the selected set into the camera.

Spinnaker C++ QuickSpin API

// Select Sequencer set
cam->SequencerSetSelector = 1;
cam->SequencerSetLoad.Execute();

  1. In the Sequencer Set Selector field, enter the set you wish to define.
  2. Modify the features and/or transitions.
  3. Execute the Sequencer Set Save to save your definition.

Step 4—Exit Configuration Mode

Once you have defined and saved your sequencer sets you must exit the configuration mode to enable the sequencer to run. Exiting configuration mode performs a final validation on the sequencer configuration settings.

To exit configuration mode

    1. Turn the Sequencer Configuration Mode to Off.
Spinnaker C++ QuickSpin API

// Turn on Sequencer configuration mode
cam->SequencerConfigurationMode = SequencerConfigurationMode_Off;

    1. Verify the Sequencer Configuration Valid field is Yes. If it is No, enter the configuration mode again to adjust your settings.
Spinnaker C++ QuickSpin API

// Validate the Sequencer configuration

CEnumerationPtr ptrSequencerConfigurationValid = nodeMap.GetNode("SequencerConfigurationValid");
CEnumEntryPtr ptrSequencerConfigurationValidYes = ptrSequencerConfigurationValid->GetEntryByName("Yes");
if (!IsAvailable(ptrSequencerConfigurationValidYes) || !IsReadable(ptrSequencerConfigurationValidYes))
{
cout << "Unable to validate sequencer configuration (enum entry retrieval). Aborting..." << endl << endl;
return -1;
}

 

If you have an invalid configuration, the sequencer discards the invalid settings when you enter configuration mode.

Step 5—Execute Sequencer

Once you have a valid configuration you can execute the sequencer. The camera cannot be streaming when you execute a sequencer session.

To execute sequencer

  1. Ensure the Sequencer Configuration Mode is Off.
  2. Turn the Sequencer Mode to On. This locks all sequenced features (direct, implied, fixed, and forced) and loads the starting sequencer set.
  3. Start image acquisition. The sequencer transitions from set to set according to your path definitions. The Sequencer Set Active field displays the current set.
  4. To end the sequencer session, turn Sequencer Mode to Off. The camera is left in the same state as defined by the current sequencer set.
 

During sequencer execution, all sequenced features (direct, implied, fixed, and forced) are locked as their values are driven by the sequencer. However, you can change any features that are not locked as per normal operation.

Programming the Sequencer

The Spinnaker SDK provides a Sequencer example to assist in programming the sequencer for your application. The example is available for C++, C#, and C source code.

The Spinnaker SDK is available from the Point Grey Downloads site.

Source code examples are in:

C:\Program Files\Point Grey Research\Spinnaker\src