![]() |
PVCAM
3.9.x
Programmable Virtual Camera Access Method library
|
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.
A typical acquisition cycle consists of the following steps:
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.
Some trigger, shutter and clearing options only apply to multiple-frame acquisitions.
The following has to be taken into account when creating and configuring acquisition buffer size:
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.
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: