Main Content

Starting and Stopping a Video Input Object

When you create a video input object, you establish a connection between MATLAB® and an image acquisition device. However, before you can acquire data from the device, you must start the object, using the start function.

start(vid);

When you start an object, you reserve the device for your exclusive use and lock the configuration. Thus, certain properties become read only while running.

An image acquisition object stops running when any of the following conditions is met:

  • The requested number of frames is acquired. This occurs when

    FramesAcquired = FramesPerTrigger * (TriggerRepeat + 1)

    where FramesAcquired, FramesPerTrigger, and TriggerRepeat are properties of the video input object. For information about these properties, see Acquiring Image Data.

  • A run-time error occurs.

  • The object's Timeout value is reached.

  • You issue the stop function.

When an object is started, the toolbox sets the object's Running property to 'on'. When an object is not running, the toolbox sets the object's Running property to 'off'; this state is called stopped.

The following figure illustrates how an object moves from a running to a stopped state.

Transitions from Running to Stopped States

The following example illustrates starting and stopping an object:

  1. Create an image acquisition object — This example creates a video input object for a webcam 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. Verify that the image is in a stopped state — Use the isrunning function to determine the current state of the video input object.

    isrunning(vid)
    
    ans =
    
         0
  3. Configure properties To illustrate object states, set the video input object's TriggerType property to 'Manual'. To set the value of certain trigger properties, including the TriggerType property, you must use the triggerconfig function. See Setting the Values of Trigger Properties for more information.

    triggerconfig(vid, 'Manual')

    Configure an acquisition that takes several seconds so that you can see the video input in logging state.

    vid.FramesPerTrigger = 100;
  4. Start the image acquisition object — Call the start function to start the image acquisition object.

    start(vid)
  5. Verify that the image is running but not logging — Use the isrunning and islogging functions to determine the current state of the video input object. With manual triggers, the video input object is in running state after being started but does not start logging data until a trigger executes.

    isrunning(vid)
    
    ans =
    
         1
    
    islogging(vid)
    
    ans =
    
         0
  6. Execute the manual trigger — Call the trigger function to execute the manual trigger.

    trigger(vid)

    While the acquisition is underway, check the logging state of the video input object.

    islogging(vid)
    
    ans =
    
         1

    After it acquires the specified number of frames, the video input object stops running.

    isrunning(vid)
    
    ans =
    
         0
  7. 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