Working with Image Data in the MATLAB Workspace :: Working with Acquired Image Data (Image Acquisition Toolbox™)

Learn more about Image Acquisition Toolbox

Working with Image Data in the MATLAB Workspace

On this page…
Understanding Image Data Determining the Dimensions of Image Data Determining the Data Type of Image Frames Specifying the Color Space Viewing Acquired Data

On this page…

Understanding Image Data

Determining the Dimensions of Image Data

Determining the Data Type of Image Frames

Specifying the Color Space

Viewing Acquired Data

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. The following figure illustrates the format of an individual frame.

Format of an Individual Frame

The following sections describes 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.

Industry-standard video formats, such as RS170 or PAL, include specifications of the image frame width and height, referred to as the image resolution. For example, the RS170 standard defines the width and height of the image frame as 640-by-480 pixels. Other devices, such as digital cameras, support the definition of many different, nonstandard image resolutions. 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.

Example: 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.
```
get(vid,'VideoFormat')

ans =

   M_RS170

get(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
```

Specifying the Color Space

For most image acquisition devices, the video format of the video stream determines the color space of the acquired image data, that is, the way color information is represented numerically.

For example, many devices represent colors as RGB values. In this color space, colors are represented as a combination of various intensities of red, green, and blue. Another color space, widely used for digital video, is the YCbCr color space. In this color space, luminance (brightness or intensity) information is stored as a single component (Y). Chrominance (color) information is stored as two color-difference components (Cb and Cr). Cb represents the difference between the blue component and a reference value. Cr represents the difference between the red component and a reference value.

The toolbox can return image data in grayscale, RGB, and YCbCr. To specify the color representation of the image data, set the value of the ReturnedColorSpace property. To display image frames using the image or imagesc functions, the data must use the RGB color space. Another MathWorks^® product, the Image Processing Toolbox software, includes functions that convert YCbCr data to RGB data, and vice versa.

Note Some devices that claim to support the YUV color space actually support the YCbCr color space. YUV is similar to YCbCr but not identical. The difference between YUV and YCbCr is the scaling factor applied to the result. YUV refers to a particular scaling factor used in composite NTSC and PAL formats. In most cases, you can specify the YCbCr color space for devices that support YUV.

The following example illustrates how to specify the color space of the returned image data.

Create an image acquisition object — This example creates a video input object for a generic 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);
```
View the default color space used for the data — The value of the ReturnedColorSpace property indicates the color space of the image data.
```
vid.ReturnedColorSpace

ans = 

rgb
```
Modify the color space used for the data — To change the color space of the returned image data, set the value of the ReturnedColorSpace property.
```
set(vid,'ReturnedColorSpace','grayscale')

ans = 

grayscale
```
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.

Bringing Image Data into the MATLAB Workspace

Retrieving Timing Information

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit

Products & Services	Solutions	Academia	Support	User Community	Company