Image Acquisition Functions

PVCAM provides two main image acquisition modes: a sequence acquisition and a continuous (circular buffer) acquisition. In both these modes the image collection process is identical: based on current camera configuration, PVCAM tells the application how large frame buffer to allocate. The application then allocates the frame buffer and passes it back to PVCAM when starting the acquisition. The behavior of these two acquisition modes, however, is slightly different.

With sequence acquisition, the application specifies the desired number of frames to acquire, and then starts the acquisition. The camera internally counts the frames and automatically stops the acquisition once the desired number of frames is transferred. This mode is useful when acquiring one frame or short bursts of frames. In most situations this mode is also more reliable as there are no buffer overwrites involved - a large buffer is allocated for the entire sequence of frames before the acquisition. When external hardware signals are involved, this mode also ensures that the number of pulses on the external signals corresponds to the number of frames acquired - the camera knows the desired number of frames and stops signaling when all the frames are acquired.

With continuous acquisition, the application does not specify the number of frames to acquire, instead, the application allocates a reasonably sized circular buffer and initiates the acquisition. The camera is acquiring freely until the application aborts the acquisition. The application is also responsible for collecting the incoming frames as fast as possible to avoid buffer overruns and thus lost frames. The size of the circular buffer - the number of frames the buffer can hold - is completely under the control of the application, however, since the buffer acts as a load leveling entity, it is recommended that the buffer is large enough to hold at least 500ms of acquisition. This will ensure that the frames are reliably delivered even if the operating system becomes momentarily less responsive. While the application can count the incoming frames and abort the acquisition once the desired number of frames is delivered (emulating the sequence mode), it is not guaranteed that the camera will acquire exactly the number of frames the application counted - with fast acquisitions and in-camera buffers involved, the camera may already be acquiring and hardware-signaling the N+5th frame while the application just received the Nth frame.

Available Functions

• State-changing functions:
  • pl_exp_setup_seq - configures the sequence acquisition
  • pl_exp_setup_cont - configures the continuous acquisition
  • pl_exp_start_seq - starts the sequence acquisition
  • pl_exp_start_cont - starts the continuous acquisition
  • pl_exp_abort - stops the currently running acquisition
  • pl_exp_finish_seq - finishes internal processing after the sequence acquisition completes
• Callback-related functions:
  • pl_cam_register_callback_ex3 - registers or replaces a callback handler function for a given event
  • pl_cam_deregister_callback - unregisters the callback handler function for a given callback event
  • pl_exp_get_latest_frame_ex - returns a pointer to the newest frame in buffer
  • pl_exp_get_oldest_frame_ex - returns a pointer to the oldest frame in buffer
  • pl_exp_unlock_oldest_frame - allows PVCAM to overwrite the oldest frame in the buffer with a new data
• Polling-related functions:
  • pl_exp_check_status - provides current readout status and number of bytes transferred during the sequence acquisition
  • pl_exp_check_cont_status_ex - provides current readout status and number of bytes transferred during the continuous acquisition

Acquisition Configuration

A typical acquisition cycle consists of the following steps:

• Set PVCAM parameters via pl_set_param function (more on this in Parameter Access Functions chapter).
• Apply current settings and new parameter values to the hardware by calling pl_exp_setup_seq or pl_exp_setup_cont. As input to these functions:
  • specify the region(s) to be collected by filling the rgn_type structure (see Multiple ROI Acquisition chapter if more than one region is needed)
  • specify the exposure time
  • specify exposure- and expose out- modes (see Exposure Modes chapter)
• Start the acquisition by calling pl_exp_start_seq or pl_exp_start_cont with a pre-allocated buffer
• Monitor the progress of data collection:
  • by use of callback handlers (recommended)
  • or by calling pl_exp_check_status or pl_exp_check_cont_status in a polling loop
  • for details read Polling versus Callbacks
• Aborting acquisition is possible at any time by calling pl_exp_abort.
  • Sequence acquisition stops automatically at the end of the sequence, but pl_exp_finish_seq should be called before a new acquisition is started.
  • Continuous acquisition can also be interrupted by calling pl_exp_stop_cont. Internally, its functionality is identical to pl_exp_abort.

When configuring an acquisition, the following settings affect the camera behavior before and during the exposure and readout. All the settings combinations are described in detail in Exposure Loops chapter.

• PARAM_CLEAR_MODE parameter determines if and when the sensor is cleared of charge. Modern sCMOS cameras handle clearing internally (see Clear Modes chapter).
• PARAM_SHTR_OPEN_MODE parameter determines if and when the shutter opens. Since modern cameras are not equipped with physical shutters, this parameter controls the Shutter Out signal behavior on the camera trigger port.
• Exposure start mode as defined by PL_EXPOSURE_MODES constants that determine whether an API call or an external trigger starts the exposure. Passed as an argument to pl_exp_setup_seq or pl_exp_setup_cont functions.
• Expose out behavior as defined by PL_EXPOSE_OUT_MODES constants that determine the behavior of the Expose Out trigger signal during the acquisition. The value is combined with exposure start mode and passed as an argument in the pl_exp_setup_seq or pl_exp_setup_cont functions.

Some trigger, shutter and clearing options only apply to multiple-frame acquisitions.

Buffer Size and Frame Count Limitations

The following has to be taken into account when creating and configuring acquisition buffer size:

• Currently, the maximum allowed buffer size passed into pl_exp_start_seq and pl_exp_start_cont is:
  • 4GB with USB interface on both Windows and Linux platforms
  • 4GB with PCIe interface on Linux
  • 2GB with PCIe interface on Windows
• the maximum number of images to acquire passed to pl_exp_setup_seq is given by by the size of buffer divided by the size of one frame with the upper limit of 65,535 frames
• in continuous mode, the total number of frames the circular buffer can hold before the oldest frame is overwritten with the latest frame, is given by the buffer size divided by the size of one frame

Sequence Acquisition

Sequence is a programmed series of exposures started by a single command. In the basic scenario, after the setup is called, camera takes a series of exposures where each exposure is captured with the same acquisition settings.

In most acquisition modes, new setup must be loaded to the camera if an acquisition parameter needs to be modified. In Variable Timed Mode (VTM), exposure_time can be modified for the next sequence (see PARAM_EXP_TIME). Please note the VTM mode is a camera-specific feature that has been replaced with SMART streaming.

Note

Refer to the Image Sequence code sample to obtain more information on Image Sequences.

Continuous Acquisition

Continuous or circular buffer mode is a special case of acquisition. In a sequence, the number of frames to acquire has to be specified and a buffer large enough to hold all the frames has to be allocated prior to starting the acquisition. In circular buffer mode, the camera will keep acquiring frames until stopped by the user.

This mode is often used when imaging events without prior knowledge of their time occurrence, or when "focus loop" needs to be implemented.

With circular buffer, the data is written to the buffer sequentially until the end of buffer is reached. Afterwards, writing continues from the beginning of the buffer overwriting the previously saved image data.

Circular buffer also acts as a load-leveling mechanism between the camera and the application. If the application cannot temporarily keep up with camera, the circular buffer will hold the incoming frames and deliver them to the application in a burst once the application is unblocked. Since the CPU availability is not guaranteed by the OS, the buffering is particularly useful with high speed cameras. For reliable frame delivery the circular buffer size allowing storage of at least one second of acquisition is recommended.

With a frame of 512x512 pixels, 2 bytes per pixel and acquisition running at 400FPS this translates to a buffer size of approx. 200MB (512x512x2x400). Note the actual frame size always needs to be obtained from pl_exp_setup_seq or pl_exp_setup_cont calls as additional metadata or specific alignment may affect the size of one frame.

PARAM_FRAME_BUFFER_SIZE can be used to retrieve the recommended buffer size for the current acquisition.

A buffer allocated by the application needs to be passed into pl_exp_start_cont to serve as a circular buffer for the incoming data. Depending on the circular buffer "overwrite" mode, buffer overrun may be flagged as an error.

An example of circular buffer setup using callbacks:

• pl_cam_register_callback is called to register a handler for EOF camera events. This only needs to be done once as the handling function pointer is retained by PVCAM.
• pl_exp_setup_cont(CIRC_OVERWRITE) - The circular buffer mode is selected.
• pl_get_param(PARAM_FRAME_BUFFER_SIZE, ATTR_DEFAULT) is called to retrieve the recommended size in bytes for the currently configured acquisition. (optional)
• Circular buffer allocation by the application takes place here.
• pl_exp_start_cont - Continuous data acquisition is started.
• Image data starts arriving in the buffer.
• For each new frame delivered to the buffer, the previously registered callback routine is called by PVCAM to notify the application.
• pl_exp_get_latest_frame is called by the application from within the callback routine to get the pointer to the latest unretrieved frame in the circular buffer.
• If multiple frame notifications are queued in PVCAM, the handling routine will be called again as soon as the current handler exits.
• Data is processed by the application (display, storage etc.).
• pl_exp_abort or pl_exp_stop_cont is called to stop the acquisition.

Note

Please, refer to the Live Image Callbacks code sample to obtain more information on Continuous Acquisition usage.