Acquire Single Image in Loop Using getsnapshot

Set Up Acquisition Object

Most interaction with Image Acquisition Toolbox™ is done through a video input object. These objects are created with the videoinput command. This example uses a webcam that is accessed through the winvideo adaptor.

vidobj = videoinput('winvideo')

Summary of Video Input Object Using 'Microsoft® LifeCam Cinema(TM)'.

   Acquisition Source(s):  input1 is available.

  Acquisition Parameters:  'input1' is the current selected source.
                           10 frames per trigger using the selected source.
                           'YUY2_1280x720' video data to be logged upon START.
                           Grabbing first of every 1 frame(s).
                           Log data to 'memory' on trigger.

      Trigger Parameters:  1 'immediate' trigger(s) on START.

                  Status:  Waiting for START.
                           0 frames acquired since starting.
                           0 frames available for GETDATA.

Since the default video format of this camera is YUY2_1280x720, images are returned in the YCbCr color space. Change the color space to rgb by specifying the value of the ReturnedColorSpace property.

vidobj.ReturnedColorSpace = "rgb";

Acquire Frame

To acquire a single frame, use the getsnapshot function.

snapshot = getsnapshot(vidobj);

Display the frame in a figure window.

imagesc(snapshot)

Acquire Multiple Frames

A common task is to repeatedly acquire a single image, process it, and then store the result. To do this, call getsnapshot in a loop.

for i = 1:5
    snapshot = getsnapshot(vidobj);
    imagesc(snapshot);
end

Timing Implications

The getsnapshot function performs a lot of work when it is called. It must connect to the device, configure it, start the acquisition, acquire one frame, stop the acquisition, and then close the device. This means that the acquisition of one frame can take significantly longer than would be expected based on the frame rate of the camera. To illustrate this, call getsnapshot in a loop.

Measure the time to acquire 20 frames.

tic
for i = 1:20
    snapshot = getsnapshot(vidobj);
end

elapsedTime = toc

elapsedTime = 0.9685

Compute the time per frame and effective frame rate.

timePerFrame = elapsedTime/20

timePerFrame = 0.0484

effectiveFrameRate = 1/timePerFrame

effectiveFrameRate = 20.6510

The next example illustrates a more efficient way to perform the loop.

Use Manual Trigger Mode

You can avoid the overhead of getsnapshot described in the previous setting by using the manual triggering mode of the videoinput object. Manual triggering mode allows the toolbox to connect to and configure the device a single time without logging data to memory. This means that frames can be returned to MATLAB® with less of a delay.

Configure the object for manual trigger mode.

triggerconfig(vidobj, 'manual');

Now that the device is configured for manual triggering, call start. This causes the device to send data back to MATLAB, but does not log frames to memory at this point.

start(vidobj)

Measure the time to acquire 20 frames.

tic
for i = 1:20
    snapshot = getsnapshot(vidobj);
end

elapsedTime = toc

elapsedTime = 0.7926

Compute the time per frame and effective frame rate.

timePerFrame = elapsedTime/20

timePerFrame = 0.0396

effectiveFrameRate = 1/timePerFrame

effectiveFrameRate = 25.2339

Call the stop function to stop the device.

stop(vidobj)

You can see that the elapsed time using manual triggering is much smaller than the previous example.

Cleanup

Once the video input object is no longer needed, delete the associated variable.

delete(vidobj)