InitLineIterator, describe return type and add doctests

git-svn-id: https://code.ros.org/svn/opencv/trunk@2948 73c94f0f-984f-4a5f-82bc-2d8db8d8ee08

diff --git a/opencv/doc/cxcore_drawing_functions.tex b/opencv/doc/cxcore_drawing_functions.tex
index d7a679a3c8e6d1c0b8aa215b6a8678aa0c7177a5..9bb0ef2a0631acea457589c50ed0927d618a3ded 100644 (file)
--- a/opencv/doc/cxcore_drawing_functions.tex
+++ b/opencv/doc/cxcore_drawing_functions.tex
@@ -282,7 +282,7 @@ Initializes the line iterator.
 \cvdefC{
 int cvInitLineIterator( \par const CvArr* image,\par CvPoint pt1,\par CvPoint pt2,\par CvLineIterator* line\_iterator,\par int connectivity=8,\par int left\_to\_right=0 );
 }
-\cvdefPy{InitLineIterator(image, pt1, pt2, connectivity=8, left\_to\_right=0) -> None}
+\cvdefPy{InitLineIterator(image, pt1, pt2, connectivity=8, left\_to\_right=0) -> line\_iterator}
 
 \begin{description}
 \cvarg{image}{Image to sample the line from}
@@ -293,19 +293,57 @@ int cvInitLineIterator( \par const CvArr* image,\par CvPoint pt1,\par CvPoint pt
 \cvarg{left\_to\_right}{
 If ($ \texttt{left\_to\_right} = 0 $ ) then the line is scanned in the specified order, from \texttt{pt1} to \texttt{pt2}.
 If ($ \texttt{left\_to\_right} \ne 0$) the line is scanned from left-most point to right-most.}
+\cvPy{\cvarg{line\_iterator}{Iterator over the pixels of the line}}
 \end{description}
 
+\ifC
 The function initializes the line
 iterator and returns the number of pixels between the two end points.
-Both points must be inside the image. After the iterator has been
+Both points must be inside the image.
+After the iterator has been
 initialized, all the points on the raster line that connects the
 two ending points may be retrieved by successive calls of
-\texttt{CV\_NEXT\_LINE\_POINT} point. The points on the line are
+\texttt{CV\_NEXT\_LINE\_POINT} point.
+\fi
+\ifPy
+The function returns an iterator over the pixels connecting the two points.
+\fi
+
+The points on the line are
 calculated one by one using a 4-connected or 8-connected Bresenham
 algorithm.
 
+\ifPy
+Example: Using line iterator to calculate the sum of pixel values along a color line
+
+\begin{lstlisting}
+>>> import cv
+>>> img = cv.LoadImageM("building.jpg", cv.CV_LOAD_IMAGE_COLOR)
+>>> li = cv.InitLineIterator(img, (100, 100), (125, 150))
+>>> red_sum = 0
+>>> green_sum = 0
+>>> blue_sum = 0
+>>> for (r, g, b) in li:
+...     red_sum += r
+...     green_sum += g
+...     blue_sum += b
+>>> print red_sum, green_sum, blue_sum
+10935.0 9496.0 7946.0
+\end{lstlisting}
+
+or more concisely using \href{http://docs.python.org/library/functions.html\#zip}{zip}:
+
+\begin{lstlisting}
+>>> import cv
+>>> img = cv.LoadImageM("building.jpg", cv.CV_LOAD_IMAGE_COLOR)
+>>> li = cv.InitLineIterator(img, (100, 100), (125, 150))
+>>> print [sum(c) for c in zip(*li)]
+[10935.0, 9496.0, 7946.0]
+\end{lstlisting}
+\fi
+
 \ifC
-% Example: Using line iterator to calculate the sum of pixel values along the color line
+Example: Using line iterator to calculate the sum of pixel values along the color line.
 
 \begin{lstlisting}
 

diff --git a/opencv/interfaces/python/api b/opencv/interfaces/python/api
index 2bc4bd144def2f91ebe2208e32c3fe5598f36566..69502d387efc85b87f54f87732da3b479765696b 100644 (file)
--- a/opencv/interfaces/python/api
+++ b/opencv/interfaces/python/api
@@ -1761,10 +1761,11 @@ GetMinMaxHistValue min_value,max_value,min_idx,max_idx /doconly
   CvScalar max_value /O
   ints min_idx /O
   ints max_idx /O
-InitLineIterator /doconly
+InitLineIterator line_iterator /doconly
   CvArr image
   CvPoint pt1
   CvPoint pt2
+  int line_iterator /O
   int connectivity 8
   int left_to_right 0
 LoadImageM /doconly