# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

# vision.OpticalFlow System object

Package: vision

Estimate object velocities

## Description

The `OpticalFlow` System object™ estimates object velocities from one image or video frame to another. It uses either the Horn-Schunck or the Lucas-Kanade method.

 Note:   Starting in R2016b, instead of using the `step` method to perform the operation defined by the System object, you can call the object with arguments, as if it were a function. For example, ```y = step(obj,x)``` and `y = obj(x)` perform equivalent operations.

## Construction

`opticalFlow = vision.OpticalFlow` returns an optical flow System object, `opticalFlow`. This object estimates the direction and speed of object motion from one image to another or from one video frame to another.

`opticalFlow = vision.OpticalFlow(Name,Value)` returns an optical flow System object, `H`, with each specified property set to the specified value. You can specify additional name-value pair arguments in any order as (`Name1`, `Value1`,...,`NameN`,`ValueN`).

Code Generation Support
Supports Code Generation: No
Code Generation Support, Usage Notes, and Limitations.

### To estimate velocity:

1. Define and set up your text inserter using the constructor.

2. Call the `step` method with the input image, `I`, the optical flow object, `opticalFlow`, and any optional properties. See the syntax below for using the `step` method.

`VSQ = step(opticalFlow,I)` computes the optical flow of input image, `I`, from one video frame to another, and returns `VSQ`, specified as a matrix of velocity magnitudes.

`V = step(opticalFlow,I)` computes the optical flow of input image. `I`, from one video frame to another, and returns `V`, specified as a complex matrix of horizontal and vertical components. This applies when you set the `OutputValue` property to '`Horizontal and vertical components in complex form`'.

`[...] = step(opticalFlow,I1,I2)` computes the optical flow of the input image `I1`, using `I2` as a reference frame. This applies when you set the `ReferenceFrameSource` property to '`Input port`'.

`[..., IMV] = step(opticalFlow,I)` outputs the delayed input image, `IMV`. The delay is equal to the latency introduced by the computation of the motion vectors. This property applies when you set the `Method` property to '`Lucas-Kanade`', the `TemporalGradientFilter` property to '`Derivative of Gaussian`', and the `MotionVectorImageOutputport` property to `true`.

## Properties

 `Method` Optical flow computation algorithm Specify the algorithm to compute the optical flow as one of `Horn-Schunck` | `Lucas-Kanade`. Default: `Horn-Schunck` `ReferenceFrameSource` Source of reference frame for optical flow calculation Specify computing optical flow as one of `Property` | `Input port`. When you set this property to `Property`, you can use the `ReferenceFrameDelay` property to determine a previous frame with which to compare. When you set this property to `Input port`, supply an input image for comparison. This property applies when you set the `Method` property to `Horn-Schunck`. This property also applies when you set the `Method` property to `Lucas-Kanade` and the `TemporalGradientFilter` property to `Difference filter [-1 1]`. Default: `Property` `ReferenceFrameDelay` Number of frames between reference frame and current frame Specify the number of frames between the reference and current frame as a positive scalar integer. This property applies when you set the `ReferenceFrameSource` property to `Current frame and N-th frame back`. Default: `1` `Smoothness` Expected smoothness of optical flow Specify the smoothness factor as a positive scalar number. If the relative motion between the two images or video frames is large, specify a large positive scalar value. If the relative motion is small, specify a small positive scalar value. This property applies when you set the `Method` property to `Horn-Schunck`. This property is tunable. Default: `1` `IterationTerminationCondition` Condition to stop iterative solution computation Specify when the optical flow iterative solution stops. Specify as one of `Maximum iteration count` | `Velocity difference threshold` | `Either` . This property applies when you set the `Method` property to `Horn-Schunck`. Default: `Maximum iteration count` `MaximumIterationCount` Maximum number of iterations to perform Specify the maximum number of iterations to perform in the optical flow iterative solution computation as a positive scalar integer. This property applies when you set the `Method` property to `Horn-Schunck` and the `IterationTerminationCondition` property to either `Maximum iteration count` or `Either`. This property is tunable. Default: `10` `VelocityDifferenceThreshold` Velocity difference threshold Specify the velocity difference threshold to stop the optical flow iterative solution computation as a positive scalar number. This property applies when you set the `Method` property to `Horn-Schunck` and the `IterationTerminationCondition` property to either `Maximum iteration count` or `Either`. This property is tunable. Default: `eps` `OutputValue` Form of velocity output Specify the velocity output as one of `Magnitude-squared` | `Horizontal and vertical components in complex form`. Default: `Magnitude-squared` `TemporalGradientFilter` Temporal gradient filter used by Lucas-Kanade algorithm Specify the temporal gradient filter used by the Lucas-Kanade algorithm as one of ```Difference filter [-1 1]``` | `Derivative of Gaussian`. This property applies when you set the `Method` property to `Lucas-Kanade`. Default: `Difference filter [-1 1]` `BufferedFramesCount` Number of frames to buffer for temporal smoothing Specify the number of frames to buffer for temporal smoothing as an odd integer from `3` to `31`, both inclusive. This property determines characteristics such as the standard deviation and the number of filter coefficients of the Gaussian filter used to perform temporal filtering. This property applies when you set the `Method` property to `Lucas-Kanade` and the `TemporalGradientFilter` property to `Derivative of Gaussian`. Default: `3` `ImageSmoothingFilterStandardDeviation` Standard deviation for image smoothing filter Specify the standard deviation for the Gaussian filter used to smooth the image using spatial filtering. Use a positive scalar number. This property applies when you set the `Method` property to `Lucas-Kanade` and the `TemporalGradientFilter` property to `Derivative of Gaussian`. Default: `1.5` `GradientSmoothingFilterStandardDeviation` Standard deviation for gradient smoothing filter Specify the standard deviation for the filter used to smooth the spatiotemporal image gradient components. Use a positive scalar number. This property applies when you set the `Method` property to `Lucas-Kanade` and the `TemporalGradientFilter` property to `Derivative of Gaussian`. Default: `1` `DiscardIllConditionedEstimates` Discard normal flow estimates when constraint equation is ill-conditioned When the optical flow constraint equation is ill conditioned, set this property to `true` so that the motion vector is set to `0`. This property applies when you set the `Method` property to `Lucas-Kanade` and the `TemporalGradientFilter` property to `Derivative of Gaussian`. This property is tunable. Default: `false` `MotionVectorImageOutputport` Return image corresponding to motion vectors Set this property to `true` to output the image that corresponds to the motion vector being output by the System object. This property applies when you set the `Method` property to `Lucas-Kanade` and the `TemporalGradientFilter` property to `Derivative of Gaussian`. Default: `false` `NoiseReductionThreshold` Threshold for noise reduction Specify the motion threshold between each image or video frame as a positive scalar number. The higher the number, the less small movements impact the optical flow calculation. This property applies when you set the `Method` property to `Lucas-Kanade`. This property is tunable. Default: `0.0039`

## Methods

 step Estimate direction and speed of object motion between video frames
Common to All System Objects
`clone`

Create System object with same property values

`getNumInputs`

Expected number of inputs to a System object

`getNumOutputs`

Expected number of outputs of a System object

`isLocked`

Check locked states of a System object (logical)

`release`

Allow System object property value changes

## Examples

expand all

Set up objects.

```videoReader = vision.VideoFileReader('viptraffic.avi','ImageColorSpace','Intensity','VideoOutputDataType','uint8'); converter = vision.ImageDataTypeConverter; opticalFlow = vision.OpticalFlow('ReferenceFrameDelay', 1); opticalFlow.OutputValue = 'Horizontal and vertical components in complex form'; shapeInserter = vision.ShapeInserter('Shape','Lines','BorderColor','Custom', 'CustomBorderColor', 255); videoPlayer = vision.VideoPlayer('Name','Motion Vector'); ```

Convert the image to single precision, then compute optical flow for the video. Generate coordinate points and draw lines to indicate flow. Display results.

```while ~isDone(videoReader) frame = step(videoReader); im = step(converter, frame); of = step(opticalFlow, im); lines = videooptflowlines(of, 20); if ~isempty(lines) out = step(shapeInserter, im, lines); step(videoPlayer, out); end end ```

Close the video reader and player

```release(videoPlayer); release(videoReader);```

## Algorithms

expand all

To compute the optical flow between two images, you must solve the following optical flow constraint equation:

`${I}_{x}u+{I}_{y}v+{I}_{t}=0$`

.

• ${I}_{x}$, ${I}_{y}$, and ${I}_{t}$ are the spatiotemporal image brightness derivatives.

• u is the horizontal optical flow.

• v is the vertical optical flow.

## References

[1] Barron, J.L., D.J. Fleet, S.S. Beauchemin, and T.A. Burkitt. Performance of optical flow techniques. CVPR, 1992.