Working with Image Data in MATLAB Workspace

Understanding Image Data

The illustrations in this documentation show the video stream and the contents of the memory buffer as a sequence of individual frames. In reality, each frame is a multidimensional array. For more information about using multidimensional arrays, see Multidimensional Arrays. The following figure illustrates the format of an individual frame.

Format of an Individual Frame

The following sections describe how the toolbox

This section also describes several ways to view acquired image data.

Determining the Dimensions of Image Data

The video format used by the image acquisition device is the primary determinant of the width, height, and the number of bands in each image frame. Image acquisition devices typically support multiple video formats. You select the video format when you create the video input object (described in Specifying the Video Format). The video input object stores the video format in the VideoFormat property.

The video input object stores the video resolution in the VideoResolution property.

Each image frame is three dimensional; however, the video format determines the number of bands in the third dimension. For color video formats, such as RGB, each image frame has three bands: one each for the red, green, and blue data. Other video formats, such as the grayscale RS170 standard, have only a single band. The video input object stores the size of the third dimension in the NumberOfBands property.

Note

Because devices typically express video resolution as width-by-height, the toolbox uses this convention for the VideoResolution property. However, when data is brought into the MATLAB^® workspace, the image frame dimensions are listed in reverse order, height-by-width, because MATLAB expresses matrix dimensions as row-by-column.

ROIs and Image Dimensions

When you specify a region-of-interest (ROI) in the image being captured, the dimensions of the ROI determine the dimensions of the image frames returned. The VideoResolution property specifies the dimensions of the image data being provided by the device; the ROIPosition property specifies the dimensions of the image frames being logged. See the ROIPosition property reference page for more information.

Video Format and Image Dimensions

The following example illustrates how video format affects the size of the image frames returned.

Select a video format — Use the imaqhwinfo function to view the list of video formats supported by your image acquisition device. This example shows the video formats supported by a Matrox^® Orion frame grabber. The formats are industry standard, such as RS170, NTSC, and PAL. These standards define the image resolution.
```
info = imaqhwinfo('matrox');

info.DeviceInfo.SupportedFormats

ans = 
  Columns 1 through 4

    'M_RS170'    'M_RS170_VIA_RGB'    'M_CCIR'    'M_CCIR_VIA_RGB'    

  Columns 5 through 8

'M_NTSC'    'M_NTSC_RGB'      'M_NTSC_YC'    'M_PAL' 

  Columns 9 through 10

'M_PAL_RGB'    'M_PAL_YC'
```
Create an image acquisition object — This example creates a video input object for a Matrox image acquisition device using the default video format, RS170. 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);
```
View the video format and video resolution properties — The toolbox creates the object with the default video format. This format defines the video resolution.
```
vid.VideoFormat

ans =

   M_RS170

vid.VideoResolution

ans =

   [640 480]
```
Bring a single frame into the workspace — Call the getsnapshot function to bring a frame into the workspace.
```
frame = getsnapshot(vid);
```
The dimensions of the returned data reflect the image resolution and the value of the NumberOfBands property.
```
vid.NumberOfBands
ans =

   1

size(frame)

ans =

   480 640
```
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.
Bring multiple frames into the workspace — Call the getdata function to bring multiple image frames into the MATLAB workspace.
```
data = getdata(vid,10);
```
The getdata function brings 10 frames of data into the workspace. Note that the returned data is a four-dimensional array: each frame is three-dimensional and the nth frame is indicated by the fourth dimension.
```
size(data)

ans =

   480 640 1 10
```
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
```

Determining the Data Type of Image Frames

By default, the toolbox returns image frames in the data type used by the image acquisition device. If there is no MATLAB data type that matches the object's native data type, getdata chooses a MATLAB data type that preserves numerical accuracy. For example, in RGB 555 format, each color component is expressed in 5-bits. getdata returns each color as a uint8 value.

You can specify the data type you want getdata to use for the returned data. For example, you can specify that getdata return image frames as an array of class double. To see a list of all the data types supported, see the getdata reference page.

The following example illustrates the data type of returned image data.

Create an image acquisition object — This example creates a video input object for a Matrox 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('matrox',1);
```
Bring a single frame into the workspace — Call the getsnapshot function to bring a frame into the workspace.
```
frame = getsnapshot(vid);
```
View the class of the returned data — Use the class function to determine the data type used for the returned image data.
```
class(frame)

ans =

  uint8
```
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 Acquired Data

Once you bring the data into the MATLAB workspace, you can view it as you would any other image in MATLAB.

The Image Acquisition Toolbox™ software includes a function, imaqmontage, that you can use to view all the frames of a multiframe image array in a single MATLAB image object. imaqmontage arranges the frames so that they roughly form a square. imaqmontage can be useful for visually comparing multiple frames.

MATLAB includes two functions, image and imagesc, that display images in a figure window. Both functions create a MATLAB image object to display the frame. You can use image object properties to control aspects of the display. The imagesc function automatically scales the input data.

The Image Processing Toolbox™ software includes an additional display routine called imshow. Like image and imagesc, this function creates a MATLAB image object. However, imshow also automatically sets various image object properties to optimize the display.