Bringing Image Data into the MATLAB Workspace

Overview

The toolbox provides three ways to move frames from the memory buffer into the MATLAB^® workspace:

Removing multiple frames from the buffer — To move a specified number of frames from the memory buffer into the workspace, use the getdata function. The getdata function removes the frames from the memory buffer as it moves them into the workspace. The function blocks the MATLAB command line until all the requested frames are available, or until a timeout value expires. For more information, see Moving Multiple Frames into the Workspace.
Viewing the most recently acquired frames in the buffer — To bring the most recently acquired frames in the memory buffer into the workspace without removing them from the buffer, use the peekdata function. When returning frames, peekdata starts with the most recently acquired frame and works backward in the memory buffer. In contrast, getdata starts at the beginning of the buffer, returning the oldest acquired frame first. peekdata does not block the command line and is not guaranteed to return all the frames you request. For more information, see Viewing Frames in the Memory Buffer.
Bringing a single frame of data into the workspace — As a convenience, the toolbox provides the getsnapshot function, which returns a single frame of data into the MATLAB workspace. Because the getsnapshot function does not require starting the object or triggering an acquisition, it is the easiest way to bring image data into the workspace. getsnapshot is independent of the memory buffer; it can return a frame even if the memory buffer is empty, and the frame returned does not affect the value of the FramesAvailable property. For more information, see Bringing a Single Frame into the Workspace. For an example of using getsnapshot, see the Image Acquisition Toolbox™ example Acquiring a Single Image in a Loop in the Examples list at the top of the Image Acquisition Toolbox main Documentation Center page, or open the file demoimaq_GetSnapshot.m in the MATLAB Editor.

Moving Multiple Frames into the Workspace

To move multiple frames of data from the memory buffer into the MATLAB workspace, use the getdata function. By default, getdata retrieves the number of frames specified in the FramesPerTrigger property but you can specify any number. See the getdata reference page for complete information about this function.

Note

When the getdata function moves frames from the memory buffer into the workspace, it removes the frames from the memory buffer.

In this figure, getdata is called at T₁ with a request for 15 frames but only six frames are available in the memory buffer. getdata blocks until the specified number of frames becomes available, at T₂, at which point getdata moves the frames into the MATLAB workspace and returns control to the command prompt.

getdata Blocks Until Frames Become Available

Acquiring 10 Seconds of Image Data

This example shows how you can configure an approximate time-based acquisition using the FramesPerTrigger property:

Create an image acquisition object — This example creates a video input object for a Windows^® image acquisition device. To run this example on your system, use the imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code.
```
vid = videoinput('winvideo',1);
```
Configure properties — To acquire 10 seconds of data, determine the frame rate of your image acquisition device and then multiply the frame rate by the number of seconds of data you want to acquire. The product of this multiplication is the value of the FramesPerTrigger property.
For this example, assume a frame rate of 30 frames per second (fps). Multiplying 30 by 10, you need to set the FramesPerTrigger property to the value 300.
```
vid.FramesPerTrigger = 300;
```
Start the image acquisition object — Call the start function to start the image acquisition object.
```
start(vid)
```
The object executes an immediate trigger and begins acquiring frames of data. The start function returns control to the command line immediately but the object continues logging the data to the memory buffer. After logging the specified number of frames, the object stops running.
Bring the acquired data into the workspace — To verify that you acquired the amount of data you wanted, use the optional getdata syntax that returns the timestamp of every frame acquired. The difference between the first timestamp and the last timestamp should approximate the amount of data you expected.
```
[data time] = getdata(vid,300);

elapsed_time = time(300) - time(1)

     10.0467
```
Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them.
```
delete(vid)
clear vid
```

Viewing Frames in the Memory Buffer

To view sample frames from the memory buffer without removing them, use the peekdata function.

The peekdata function always returns the most recently acquired frames in the memory buffer. For example, if you request three frames, peekdata returns the most recently acquired frame in the buffer at the time of the request and the two frames that immediately precede it.

The following figure illustrates this process. The command peekdata(vid,3) is called at three different times (T₁, T₂, and T₃). The shaded frames indicate the frames returned by peekdata at each call. (peekdata returns frames without removing them from the memory buffer.)

Note in the figure that, at T₃, only two frames have become available since the last call to peekdata. In this case, peekdata returns only the two frames, with a warning that it returned less data than was requested.

Frames Returned by peekdata

Note

The peekdata function does not return any data while running if in disk logging mode.

The following example illustrates how to use peekdata:

Create an image acquisition object — This example creates a video input object for a Data Translation^® image acquisition device. To run this example on your system, use the imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code.
```
vid = videoinput('dt',1);
```
Configure properties — For this example, configure a manual trigger. You must use the triggerconfig function to specify the trigger type.
```
triggerconfig(vid,'manual')
```
In addition, configure a large enough acquisition to allow several calls to peekdata before it finishes.
```
vid.FramesPerTrigger = 300;
```
Start the image acquisition object — Call the start function to start the image acquisition object.
```
start(vid)
```
The video object is now running but not logging.
```
isrunning(vid)

ans =

     1

islogging(vid)

ans =

     0
```
Use peekdata to view frames before a trigger — If you call peekdata before you trigger the acquisition, peekdata can only return a single frame of data because data logging has not been initiated and the memory buffer is empty. If more than one frame is requested, peekdata issues a warning that it is returning fewer than the requested number of frames.
```
pdata = peekdata(vid,50);
Warning: PEEKDATA could not return all the frames requested.
```
Verify that peekdata returned a single frame. A single frame of data should have the same width and height as specified by the ROIPosition property and the same number of bands, as specified by the NumberOfBands property. In this example, the video format of the data is RGB so the value of the NumberOfBands property is 3.
```
whos
  Name        Size                   Bytes  Class

  pdata       96x128x3               36864  uint8 array
  vid          1x1                    1060  videoinput object
```
Verify that the object has not acquired any frames.
```
vid.FramesAcquired
ans = 
	0
```
Trigger the acquisition — Call the trigger function to trigger an acquisition.
```
trigger(vid)
```
The object begins logging frames to the memory buffer.
View the most recently acquired frames — While the acquisition is in progress, call peekdata several times to view the latest frames in the memory buffer. Depending on the number of frames you request, and the timing of these requests, peekdata might return fewer than the number of frames you specify.
```
pdata = peekdata(vid,50);
```
To verify that peekdata returned the frames you requested, check the dimensions of pdata. peekdata returns a four-dimensional array of frames, where the last dimension indicates the number of frames returned.
```
whos
  Name        Size                  Bytes   Class

  pdata       4-D                 1843200   uint8 array
  vid         1x1                    1060   videoinput object

size(pdata)

ans =

    96   128     3    50
```
Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them.
```
delete(vid)
clear vid
```

Bringing a Single Frame into the Workspace

To bring a single frame of image data into the MATLAB workspace, use the getsnapshot function. You can call the getsnapshot function at any time after object creation.

This example illustrates how simple it is to use the getsnapshot function.

Create an image acquisition object — This example creates a video input object for a Matrox^® device. To run this example on your system, use the imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code.
```
vid = videoinput('matrox',1);
```
Bring a frame into the workspace — Call the getsnapshot function to bring a frame into the workspace. Note that you do not need to start the video input object before calling the getsnapshot function.
```
frame = getsnapshot(vid);
```
The getsnapshot function returns an image of the same width and height as specified by the ROIPosition property and the same number of bands as specified by the NumberOfBands property. In this example, the video format of the data is RGB so the value of the NumberOfBands property is 3.
```
whos
  Name        Size                   Bytes  Class

  frame      96x128x3                36864  uint8 array
  vid         1x1                     1060  videoinput object
```
Note that the frame returned by getsnapshot is not removed from the memory buffer, if frames are stored there, and does not affect the value of the FramesAvailable property.
Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them.
```
delete(vid)
clear vid 
```

For an example of using getsnapshot, see the Image Acquisition Toolbox example Acquiring a Single Image in a Loop in the Examples list at the top of the Image Acquisition Toolbox main Documentation Center page, or open the file demoimaq_GetSnapshot.m in the MATLAB Editor.