Managing Memory Usage

Memory Usage

The first time it needs to allocate memory to store an image frame, the toolbox determines the total amount of memory it has available to store acquired image frames. By default, the toolbox sets this value, called the frame memory limit, to equal all the physical memory that is available when the toolbox is first accessed.

Image data can require a lot of memory. For example, even a relatively small (96-by-128) 24-bit color image requires almost 37 K bytes for each frame.


  Name        Size                   Bytes  Class 

rgb_image    96x128x3                36864  uint8 array

Monitoring Memory Usage

The toolbox includes a utility function, called imaqmem, that provides information about the toolbox's current memory usage.

The imaqmem function returns a structure that contains several memory usage statistics including the total amount of physical memory available, the amount of physical memory currently in use, and a value, called the memory load, that characterizes the current memory usage.

To illustrate, this example calls imaqmem and then uses the frame memory limit and the current frame memory usage statistics to calculate how much memory is left for image frame storage.

out = imaqmem;
mem_left = out.FrameMemoryLimit - out.FrameMemoryUsed;

To see an example of using a callback function to monitor memory usage, see Monitoring Memory Usage.

Modifying the Frame Memory Limit

To enable your image acquisition application to work with more image frames, you might want to increase the frame memory limit. Using the imaqmem function you can determine the current frame memory limit and specify a new one. The following example illustrates this process.

  1. Determine the current frame memory limit — This example calls the imaqmem function, requesting the value of the FrameMemoryLimit field.

    out = imaqmem('FrameMemoryLimit')
    out =
  2. Set the frame memory limit to a new value — When you call imaqmem with a numeric argument, it sets the FrameMemoryLimit field to the value.

  3. Verify the frame memory limit setting — Call imaqmem again, requesting the value of the FrameMemoryLimit field.

    out = imaqmem('FrameMemoryLimit')
    out =

Freeing Memory

At times, while acquiring image data, you might want to delete some or all of the frames that are stored in memory. Using the flushdata function, you can delete all the frames currently stored in memory or only those frames associated with the execution of a trigger.

The following example illustrates how to use flushdata to delete all the frames in memory or one trigger's worth of frames.

  1. 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);
  2. Configure properties — For this example, configure an acquisition of five frames per trigger and, to show the effect of flushdata, configure multiple triggers using the TriggerRepeat property.

    vid.FramesPerTrigger = 5
    vid.TriggerRepeat = 2;
  3. Start the image acquisition object — Call the start function to start the image acquisition object.


    The object executes an immediate trigger, acquires five frames of data, and repeats this trigger two more times. After logging the specified number of frames, the object stops running.

    To verify that the object acquired data, view the value of the FramesAvailable property. This property reports how many frames are currently stored in the memory buffer.

    ans =
  4. Delete a trigger's worth of image data — Call the flushdata function, specifying the mode 'triggers'. This deletes the frames associated with the oldest trigger.


    The following figure shows the frames acquired before and after the call to flushdata. Note how flushdata deletes the frames associated with the oldest trigger.

    To verify that the object deleted the frames, view the value of the FramesAvailable property.

    ans =
  5. Empty the entire memory buffer — Calling flushdata without specifying the mode deletes all the frames stored in memory.


    To verify that the object deleted the frames, view the value of the FramesAvailable property.

    ans =
  6. Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them.

    clear vid
Was this topic helpful?