Make the crop filters accept parametric expressions.
[ffmpeg.git] / doc / filters.texi
index 4b2ece1..1dc222a 100644 (file)
@@ -26,34 +26,101 @@ Below is a description of the currently available video filters.
 
 @section crop
 
-Crop the input video to @var{x}:@var{y}:@var{width}:@var{height}.
+Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}.
 
-@example
-./ffmpeg -i in.avi -vf "crop=0:0:0:240" out.avi
-@end example
+The parameters are expressions containing the following constants:
+
+@table @option
+@item E, PI, PHI
+the corresponding mathematical approximated values for e
+(euler number), pi (greek PI), PHI (golden ratio)
 
-@var{x} and @var{y} specify the position of the top-left corner of the
-output (non-cropped) area.
+@item x, y
+the computed values for @var{x} and @var{y}. They are evaluated for
+each new frame.
 
-The default value of @var{x} and @var{y} is 0.
+@item in_w, in_h
+the input width and heigth
+
+@item iw, ih
+same as @var{in_w} and @var{in_h}
+
+@item out_w, out_h
+the output (cropped) width and heigth
+
+@item ow, oh
+same as @var{out_w} and @var{out_h}
+
+@item n
+the number of input frame, starting from 0
+
+@item pos
+the position in the file of the input frame, NAN if unknown
 
-The @var{width} and @var{height} parameters specify the width and height
-of the output (non-cropped) area.
+@item t
+timestamp expressed in seconds, NAN if the input timestamp is unknown
 
-A value of 0 is interpreted as the maximum possible size contained in
-the area delimited by the top-left corner at position x:y.
+@end table
+
+The @var{out_w} and @var{out_h} parameters specify the expressions for
+the width and height of the output (cropped) video. They are
+evaluated just at the configuration of the filter.
+
+The default value of @var{out_w} is "in_w", and the default value of
+@var{out_h} is "in_h".
+
+The expression for @var{out_w} may depend on the value of @var{out_h},
+and the expression for @var{out_h} may depend on @var{out_w}, but they
+cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
+evaluated after @var{out_w} and @var{out_h}.
+
+The @var{x} and @var{y} parameters specify the expressions for the
+position of the top-left corner of the output (non-cropped) area. They
+are evaluated for each frame. If the evaluated value is not valid, it
+is approximated to the nearest valid value.
+
+The default value of @var{x} is "(in_w-out_w)/2", and the default
+value for @var{y} is "(in_h-out_h)/2", which set the cropped area at
+the center of the input image.
 
-For example the parameters:
+The expression for @var{x} may depend on @var{y}, and the expression
+for @var{y} may depend on @var{x}.
 
+Follow some examples:
 @example
-"crop=100:100:0:0"
-@end example
+# crop the central input area with size 100x100
+crop=100:100
 
-will delimit the rectangle with the top-left corner placed at position
-100:100 and the right-bottom corner corresponding to the right-bottom
-corner of the input image.
+# crop the central input area with size 2/3 of the input video
+"crop=2/3*in_w:2/3*in_h"
 
-The default value of @var{width} and @var{height} is 0.
+# crop the input video central square
+crop=in_h
+
+# delimit the rectangle with the top-left corner placed at position
+# 100:100 and the right-bottom corner corresponding to the right-bottom
+# corner of the input image.
+crop=in_w-100:in_h-100:100:100
+
+# crop 10 pixels from the lefth and right borders, and 20 pixels from
+# the top and bottom borders
+"crop=in_w-2*10:in_h-2*20"
+
+# keep only the bottom right quarter of the input image
+"crop=in_w/2:in_h/2:in_w/2:in_h/2"
+
+# crop height for getting Greek harmony
+"crop=in_w:1/PHI*in_w"
+
+# trembling effect
+"crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(n/10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(n/7)"
+
+# erratic camera effect depending on timestamp and position
+"crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(t*10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(t*13)"
+
+# set x depending on the value of y
+"crop=in_w/2:in_h/2:y:10+10*sin(n/10)"
+@end example
 
 @section fifo
 
@@ -81,6 +148,56 @@ The following command:
 
 will convert the input video to the format "yuv420p".
 
+@section frei0r
+
+Apply a frei0r effect to the input video.
+
+To enable compilation of this filter you need to install the frei0r
+header and configure FFmpeg with --enable-frei0r.
+
+The filter supports the syntax:
+@example
+@var{filter_name}:@var{param1}:@var{param2}:...:@var{paramN}
+@end example
+
+@var{filter_name} is the name to the frei0r effect to load. If the
+environment variable @env{FREI0R_PATH} is defined, the frei0r effect
+is searched in each one of the directories specified by the colon
+separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r
+paths, which are in this order: @file{HOME/.frei0r-1/lib/},
+@file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}.
+
+@var{param1}, @var{param2}, ... , @var{paramN} specify the parameters
+for the frei0r effect.
+
+A frei0r effect parameter can be a boolean (whose values are specified
+with "y" and "n"), a double, a color (specified by the syntax
+@var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
+numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
+description), a position (specified by the syntax @var{X}/@var{Y},
+@var{X} and @var{Y} being float numbers) and a string.
+
+The number and kind of parameters depend on the loaded effect. If an
+effect parameter is not specified the default value is set.
+
+Some examples follow:
+@example
+# apply the distort0r effect, set the first two double parameters
+frei0r=distort0r:0.5:0.01
+
+# apply the colordistance effect, takes a color as first parameter
+frei0r=colordistance:0.2/0.3/0.4
+frei0r=colordistance:violet
+frei0r=colordistance:0x112233
+
+# apply the perspective effect, specify the top left and top right
+# image positions
+frei0r=perspective:0.2/0.2:0.8/0.2
+@end example
+
+For more information see:
+@url{http://piksel.org/frei0r}
+
 @section hflip
 
 Flip the input video horizontally.
@@ -119,11 +236,11 @@ Apply smooth transform using libopencv.
 To enable this filter install libopencv library and headers and
 configure FFmpeg with --enable-libopencv.
 
-It accepts the following parameters:
+The filter accepts the following parameters:
 @var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}.
 
 @var{type} is the type of smooth filter to apply, and can be one of
-the following value: "blur", "blur_no_scale", "median", "gaussian",
+the following values: "blur", "blur_no_scale", "median", "gaussian",
 "bilateral". The default value is "gaussian".
 
 @var{param1}, @var{param2}, @var{param3}, and @var{param4} are
@@ -134,8 +251,8 @@ parameters whose meanings depend on smooth type. @var{param1} and
 The default value for @var{param1} is 3, the default value for the
 other parameters is 0.
 
-These parameters corresponds to the parameters assigned to the
-libopencv function @code{cvSmooth}. Refer the official libopencv
+These parameters correspond to the parameters assigned to the
+libopencv function @code{cvSmooth}. Refer to the official libopencv
 documentation for the exact meaning of the parameters:
 @url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}