[FFmpeg-devel] [PATCH] doc/filters/find_rect: extend documentation

[Stefano Sabatini]

Document metadata entries set by the filter, extend and clarify
options, add additional example showing how to extract the generated
data.

Fix issue:
http://trac.ffmpeg.org/ticket/8766
---
 doc/filters.texi | 41 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/doc/filters.texi b/doc/filters.texi
index 1980fa6888..11406cb076 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -13768,7 +13768,29 @@ value.
 
 @section find_rect
 
-Find a rectangular object
+Find a rectangular object in the input video.
+
+The object to search for must be specified as a gray8 image specified with the
+ at option{object} option.
+
+If the input video contains multiple instances of the object, the filter will
+find only one of them.
+
+When an object is found, the following metadata entries are set in the matching
+frame:
+ at table @option
+ at item lavfi.rect.w
+width of object
+
+ at item lavfi.rect.h
+height of object
+
+ at item lavfi.rect.x
+x position of object
+
+ at item lavfi.rect.y
+y position of object
+ at end table
 
 It accepts the following options:
 
@@ -13777,7 +13799,12 @@ It accepts the following options:
 Filepath of the object image, needs to be in gray8.
 
 @item threshold
-Detection threshold, default is 0.5.
+Detection threshold, expressed as a decimal number in the range 0-1.
+
+A threshold value of 0.01 means only exact matches, a threshold of 0.99 means
+almost everything matches.
+
+Default value is 0.5.
 
 @item mipmaps
 Number of mipmaps, default is 3.
@@ -13797,6 +13824,16 @@ Cover a rectangular object by the supplied image of a given video using @command
 @example
 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
 @end example
+
+ at item
+Find the position of an object in each frame using @command{ffprobe} and write
+it to a log file:
+ at example
+ffprobe -f lavfi movie=test.mp4,find_rect=object=object.pgm:threshold=0.3 \
+  -show_entries frame=pkt_pts_time:frame_tags=lavfi.rect.x,lavfi.rect.y \
+  -of csv -o find_rect.csv
+ at end example
+
 @end itemize
 
 @section floodfill
-- 
2.25.1