Retrieving Image Data from Camera

After the camera has been initialized and the camera features determined and set appropriately, it is ready for streaming and capturing image data.

Starting the Video Stream

Before images can be captured, video image data must be streaming from the camera to the host computer. Call PxLSetStreamState set to START_STREAM, to take the camera out of an idle (“stopped”) or paused state and open the video stream.  After this call, the camera can send image data to the host computer, either continuously or as Frame-on-Demand (triggered) depending on the camera settings.

Starting the Image Preview (Optional)

When the video stream is running, the image data can be previewed on the monitor prior to image capture, although this is not necessary for capture.  To start the image preview, call PxLSetPreviewState set to START_PREVIEW.

Capturing a Single-Frame Image

Once the stream is started, the software driver will collect and buffer frame data as it arrives at the host. Call PxLGetNextFrame to transfer the oldest frame to a user-specified buffer on the host computer.  Because the frame data is buffered, this may be repeated continually.  However, depending on the system speed, some incoming data can be lost if the frame rate is too high for the system to keep up.

Note: If the camera is using a hardware trigger, a call to PxLGetNextFrame will not return until a trigger has been received. If using a software trigger, the camera will wait until a call to PxLGetNextFrame before capturing the image. 

Capturing Image Data in a Separate Thread

Image data can also be processed using the PxLSetCallback function. The user-defined call back function will be called each time the driver receives new image data from the camera. The call back routine will be processed in a separate thread from the one that called PxLSetCallback.  The call back routine should be very efficient so that it can process image data quickly.

The callback function can be called at a number of points in the driver process.  Specifically: 

• just before a frame is displayed in the preview.

• just before formatted video data is returned from PxLFormatImage.

• just before a frame is saved to disk in PxLFormatClip, or

• just after a raw frame is received by the driver.

Captured Image Data Format

The data in the buffer will be in a format defined by the Pixel Format the camera is using. The Pixel Format can be found by querying the PixelFormat element of the Frame Descriptor structure that is returned by PxLGetNextFrame or to a call back routine.  A detailed description of the possible image data formats is contained in Image Data Formats.

Capturing a Video Clip

Use the same methods as for capturing a single–frame image, with the following changes:

• Instead of calling PxLGetNextFrame, call PxLGetClip to capture multiple frames into a PixeLINK data stream file.

Note: A Hardware-triggered Frame-on-demand video capture will require multiple trigger signals to be received before the function can complete. A software-triggered Frame-on-Demand video capture is similar to, but slower than, an Internally Triggered Free-Running Continuous Video capture. PxLGetClip will issue the software triggers automatically by calling PxLGetNextFrame the required number of times. These function calls are slower than using the internal trigger.  

• Call PxLFormatClip to convert the PixeLINK data stream file into an end-user format (.avi).

Changes to Camera Settings

In general, changes to camera settings are applied to the next frame.  The only exception occurs when the camera is performing a Frame-on-Demand capture, that is a acquisition using a hardware or software trigger. 

With a Frame-on-Demand capture:

• The camera is in a “wait state” while waiting for a trigger.  Any requests to change camera settings received during the wait state are acted upon immediately, but while the changes are being enabled, the camera video stream is stopped momentarily, activating a “busy signal.”  While this busy signal is active, trigger signals are ignored.  When the changes in camera settings are complete, the busy signal is deactivated, the video stream is restored to its previous state, and the camera is left in the wait state ready to respond to the trigger.