opencv/doc/cxcore_drawing_functions.tex

   1 \section{Drawing Functions}
   2
   3 Drawing functions work with matrices/images of arbitrary depth.
   4 The boundaries of the shapes can be rendered with antialiasing (implemented only for 8-bit images for now).
   5 All the functions include the parameter color that uses a rgb value (that may be constructed
   6 with \texttt{CV\_RGB} \cvC{macro or the \cvCppCross{cvScalar} function}
   7 \cvCpp{or the \cross{Scalar} constructor}) for color
   8 images and brightness for grayscale images. For color images the order channel
   9 is normally \emph{Blue, Green, Red}, this is what \cvCppCross{imshow}, \cvCppCross{imread} and \cvCppCross{imwrite} expect
  10 \ifCpp
  11 , so if you form a color using \cross{Scalar} constructor, it should look like:
  12 \[\texttt{Scalar}(blue\_component, green\_component, red\_component[, alpha\_component])\]
  13 \fi
  14 \ifC
  15 , so if you form a color using \cvCppCross{cvScalar}, it should look like:
  16 \[\texttt{cvScalar}(blue\_component, green\_component, red\_component[, alpha\_component])\]
  17 \fi
  18
  19 If you are using your own image rendering and I/O functions, you can use any channel ordering, the drawing functions process each channel independently and do not depend on the channel order or even on the color space used. The whole image can be converted from BGR to RGB or to a different color space using \cvCppCross{cvtColor}.
  20
  21 If a drawn figure is partially or completely outside the image, the drawing functions clip it. Also, many drawing functions can handle pixel coordinates specified with sub-pixel accuracy, that is, the coordinates can be passed as fixed-point numbers, encoded as integers. The number of fractional bits is specified by the \texttt{shift} parameter and the real point coordinates are calculated as $\texttt{Point}(x,y)\rightarrow\texttt{Point2f}(x*2^{-shift},y*2^{-shift})$. This feature is especially effective wehn rendering antialiased shapes.
  22
  23 Also, note that the functions do not support alpha-transparency - when the target image is 4-channnel, then the \texttt{color[3]} is simply copied to the repainted pixels. Thus, if you want to paint semi-transparent shapes, you can paint them in a separate buffer and then blend it with the main image.
  24
  25 \ifCPy
  26
  27 \cvCPyFunc{Circle}
  28 Draws a circle.
  29
  30 \cvdefC{void cvCircle( \par CvArr* img,\par CvPoint center,\par int radius,\par CvScalar color,\par int thickness=1,\par int lineType=8,\par int shift=0 );}
  31 \cvdefPy{Circle(img,center,radius,color,thickness=1,lineType=8,shift=0)-> None}
  32
  33 \begin{description}
  34 \cvarg{img}{Image where the circle is drawn}
  35 \cvarg{center}{Center of the circle}
  36 \cvarg{radius}{Radius of the circle}
  37 \cvarg{color}{Circle color}
  38 \cvarg{thickness}{Thickness of the circle outline if positive, otherwise this indicates that a filled circle is to be drawn}
  39 \cvarg{lineType}{Type of the circle boundary, see \cross{Line} description}
  40 \cvarg{shift}{Number of fractional bits in the center coordinates and radius value}
  41 \end{description}
  42
  43 The function draws a simple or filled circle with a
  44 given center and radius.
  45
  46 \cvCPyFunc{ClipLine}
  47 Clips the line against the image rectangle.
  48
  49 \cvdefC{int cvClipLine( \par CvSize imgSize,\par CvPoint* pt1,\par CvPoint* pt2 );}
  50 \cvdefPy{ClipLine(imgSize, pt1, pt2) -> (clipped\_pt1, clipped\_pt2)}
  51 \begin{description}
  52 \cvarg{imgSize}{Size of the image}
  53 \cvarg{pt1}{First ending point of the line segment. \cvC{It is modified by the function.}}
  54 \cvarg{pt2}{Second ending point of the line segment. \cvC{It is modified by the function.}}
  55 \end{description}
  56
  57 The function calculates a part of the line segment which is entirely within the image.
  58 \cvC{It returns 0 if the line segment is completely outside the image and 1 otherwise.}
  59 \cvPy{If the line segment is outside the image, it returns None. If the line segment is inside the image it returns a new pair of points.}
  60
  61 \cvCPyFunc{DrawContours}
  62 Draws contour outlines or interiors in an image.
  63
  64 \cvdefC{
  65 void cvDrawContours( \par CvArr *img,\par CvSeq* contour,\par CvScalar external\_color,\par CvScalar hole\_color,\par int max\_level,\par int thickness=1,\par int lineType=8 );
  66 }
  67 \cvdefPy{DrawContours(img,contour,external\_color,hole\_color,max\_level,thickness=1,lineType=8,offset=(0,0))-> None}
  68
  69 \begin{description}
  70 \cvarg{img}{Image where the contours are to be drawn. As with any other drawing function, the contours are clipped with the ROI.}
  71 \cvarg{contour}{Pointer to the first contour}
  72 \cvarg{external\_color}{Color of the external contours}
  73 \cvarg{hole\_color}{Color of internal contours (holes)}
  74 \cvarg{max\_level}{Maximal level for drawn contours. If 0, only
  75 \texttt{contour} is drawn. If 1, the contour and all contours following
  76 it on the same level are drawn. If 2, all contours following and all
  77 contours one level below the contours are drawn, and so forth. If the value
  78 is negative, the function does not draw the contours following after
  79 \texttt{contour} but draws the child contours of \texttt{contour} up
  80 to the $|\texttt{max\_level}|-1$ level.}
  81 \cvarg{thickness}{Thickness of lines the contours are drawn with.
  82 If it is negative (For example, =CV\_FILLED), the contour interiors are
  83 drawn.}
  84 \cvarg{lineType}{Type of the contour segments, see \cross{Line} description}
  85 \end{description}
  86
  87 The function draws contour outlines in the image if $\texttt{thickness} \ge 0$ or fills the area bounded by the contours if $ \texttt{thickness}<0$.
  88
  89 \ifC
  90 Example: Connected component detection via contour functions
  91
  92 \begin{lstlisting}
  93 #include "cv.h"
  94 #include "highgui.h"
  95
  96 int main( int argc, char** argv )
  97 {
  98     IplImage* src;
  99     // the first command line parameter must be file name of binary
 100     // (black-n-white) image
 101     if( argc == 2 && (src=cvLoadImage(argv[1], 0))!= 0)
 102     {
 103         IplImage* dst = cvCreateImage( cvGetSize(src), 8, 3 );
 104         CvMemStorage* storage = cvCreateMemStorage(0);
 105         CvSeq* contour = 0;
 106
 107         cvThreshold( src, src, 1, 255, CV_THRESH_BINARY );
 108         cvNamedWindow( "Source", 1 );
 109         cvShowImage( "Source", src );
 110
 111         cvFindContours( src, storage, &contour, sizeof(CvContour),
 112            CV_RETR_CCOMP, CV_CHAIN_APPROX_SIMPLE );
 113         cvZero( dst );
 114
 115         for( ; contour != 0; contour = contour->h_next )
 116         {
 117             CvScalar color = CV_RGB( rand()&255, rand()&255, rand()&255 );
 118             /* replace CV_FILLED with 1 to see the outlines */
 119             cvDrawContours( dst, contour, color, color, -1, CV_FILLED, 8 );
 120         }
 121
 122         cvNamedWindow( "Components", 1 );
 123         cvShowImage( "Components", dst );
 124         cvWaitKey(0);
 125     }
 126 }
 127 \end{lstlisting}
 128 \fi
 129
 130 \cvCPyFunc{Ellipse}
 131 Draws a simple or thick elliptic arc or an fills ellipse sector.
 132
 133 \cvdefC{void cvEllipse( \par CvArr* img,\par CvPoint center,\par CvSize axes,\par double angle,\par double start\_angle,\par double end\_angle,\par CvScalar color,\par int thickness=1,\par int lineType=8,\par int shift=0 );}
 134 \cvdefPy{Ellipse(img,center,axes,angle,start\_angle,end\_angle,color,thickness=1,lineType=8,shift=0)-> None}
 135
 136 \begin{description}
 137 \cvarg{img}{The image}
 138 \cvarg{center}{Center of the ellipse}
 139 \cvarg{axes}{Length of the ellipse axes}
 140 \cvarg{angle}{Rotation angle}
 141 \cvarg{start\_angle}{Starting angle of the elliptic arc}
 142 \cvarg{end\_angle}{Ending angle of the elliptic arc.}
 143 \cvarg{color}{Ellipse color}
 144 \cvarg{thickness}{Thickness of the ellipse arc outline if positive, otherwise this indicates that a filled ellipse sector is to be drawn}
 145 \cvarg{lineType}{Type of the ellipse boundary, see \cross{Line} description}
 146 \cvarg{shift}{Number of fractional bits in the center coordinates and axes' values}
 147 \end{description}
 148
 149 The function draws a simple or thick elliptic
 150 arc or fills an ellipse sector. The arc is clipped by the ROI rectangle.
 151 A piecewise-linear approximation is used for antialiased arcs and
 152 thick arcs. All the angles are given in degrees. The picture below
 153 explains the meaning of the parameters.
 154
 155 Parameters of Elliptic Arc
 156
 157 \includegraphics[width=0.5\textwidth]{pics/ellipse.png}
 158
 159 \cvCPyFunc{EllipseBox}
 160
 161 Draws a simple or thick elliptic arc or fills an ellipse sector.
 162
 163 \cvdefC{void cvEllipseBox( \par CvArr* img, \par CvBox2D box, \par CvScalar color,
 164                    \par int thickness=1, \par int lineType=8, \par int shift=0 );}
 165 \cvdefPy{EllipseBox(img,box,color,thickness=1,lineType=8,shift=0)-> None}
 166
 167 \begin{description}
 168 \cvarg{img}{Image}
 169 \cvarg{box}{The enclosing box of the ellipse drawn}
 170 \cvarg{thickness}{Thickness of the ellipse boundary}
 171 \cvarg{lineType}{Type of the ellipse boundary, see \cross{Line} description}
 172 \cvarg{shift}{Number of fractional bits in the box vertex coordinates}
 173 \end{description}
 174
 175 The function draws a simple or thick ellipse outline, or fills an ellipse. The functions provides a convenient way to draw an ellipse approximating some shape; that is what \cross{CamShift} and \cross{FitEllipse} do. The ellipse drawn is clipped by ROI rectangle. A piecewise-linear approximation is used for antialiased arcs and thick arcs.
 176
 177 \cvCPyFunc{FillConvexPoly}
 178 Fills a convex polygon.
 179
 180 \cvdefC{
 181 void cvFillConvexPoly( \par CvArr* img,\par CvPoint* pts,\par int npts,\par CvScalar color,\par int lineType=8,\par int shift=0 );}
 182 \cvdefPy{FillConvexPoly(img,pn,color,lineType=8,shift=0)-> None}
 183
 184 \begin{description}
 185 \cvarg{img}{Image}
 186 \ifC
 187 \cvarg{pts}{Array of pointers to a single polygon}
 188 \cvarg{npts}{Polygon vertex counter}
 189 \else
 190 \cvarg{pn}{List of coordinate pairs}
 191 \fi
 192 \cvarg{color}{Polygon color}
 193 \cvarg{lineType}{Type of the polygon boundaries, see \cross{Line} description}
 194 \cvarg{shift}{Number of fractional bits in the vertex coordinates}
 195 \end{description}
 196
 197 The function fills a convex polygon's interior.
 198 This function is much faster than the function \texttt{cvFillPoly}
 199 and can fill not only convex polygons but any monotonic polygon,
 200 i.e., a polygon whose contour intersects every horizontal line (scan
 201 line) twice at the most.
 202
 203
 204 \cvCPyFunc{FillPoly}
 205 Fills a polygon's interior.
 206
 207 \cvdefC{
 208 void cvFillPoly( \par CvArr* img,\par CvPoint** pts,\par int* npts,\par int contours,\par CvScalar color,\par int lineType=8,\par int shift=0 );
 209 }
 210 \cvdefPy{FillPoly(img,polys,color,lineType=8,shift=0)-> None}
 211
 212 \begin{description}
 213 \cvarg{img}{Image}
 214 \ifC
 215 \cvarg{pts}{Array of pointers to polygons}
 216 \cvarg{npts}{Array of polygon vertex counters}
 217 \cvarg{contours}{Number of contours that bind the filled region}
 218 \fi
 219 \ifPy
 220 \cvarg{polys}{List of lists of (x,y) pairs.  Each list of points is a polygon.}
 221 \fi
 222 \cvarg{color}{Polygon color}
 223 \cvarg{lineType}{Type of the polygon boundaries, see \cross{Line} description}
 224 \cvarg{shift}{Number of fractional bits in the vertex coordinates}
 225 \end{description}
 226
 227
 228 The function fills an area bounded by several
 229 polygonal contours. The function fills complex areas, for example,
 230 areas with holes, contour self-intersection, and so forth.
 231
 232 \cvCPyFunc{GetTextSize}
 233 Retrieves the width and height of a text string.
 234
 235 \cvdefC{
 236 void cvGetTextSize( \par const char* textString,\par const CvFont* font,\par CvSize* textSize,\par int* baseline );}
 237 \cvdefPy{GetTextSize(textString,font)-> (textSize,baseline)}
 238
 239 \begin{description}
 240 \cvarg{font}{Pointer to the font structure}
 241 \cvarg{textString}{Input string}
 242 \cvarg{textSize}{Resultant size of the text string. Height of the text does not include the height of character parts that are below the baseline.}
 243 \cvarg{baseline}{y-coordinate of the baseline relative to the bottom-most text point}
 244 \end{description}
 245
 246 The function calculates the dimensions of a rectangle to enclose a text string when a specified font is used.
 247
 248 \cvCPyFunc{InitFont}
 249 Initializes font structure.
 250
 251 \cvdefC{
 252 void cvInitFont( \par CvFont* font,\par int fontFace,\par double hscale,\par double vscale,\par double shear=0,\par int thickness=1,\par int lineType=8 );}
 253 \cvdefPy{InitFont(fontFace,hscale,vscale,shear=0,thickness=1,lineType=8)-> font}
 254
 255 \begin{description}
 256 \cvarg{font}{Pointer to the font structure initialized by the function}
 257 \cvarg{fontFace}{Font name identifier. Only a subset of Hershey fonts \url{http://sources.isc.org/utils/misc/hershey-font.txt} are supported now:
 258  \begin{description}
 259  \cvarg{CV\_FONT\_HERSHEY\_SIMPLEX}{normal size sans-serif font}
 260  \cvarg{CV\_FONT\_HERSHEY\_PLAIN}{small size sans-serif font}
 261  \cvarg{CV\_FONT\_HERSHEY\_DUPLEX}{normal size sans-serif font (more complex than \par \texttt{CV\_FONT\_HERSHEY\_SIMPLEX})}
 262  \cvarg{CV\_FONT\_HERSHEY\_COMPLEX}{normal size serif font}
 263  \cvarg{CV\_FONT\_HERSHEY\_TRIPLEX}{normal size serif font (more complex than \texttt{CV\_FONT\_HERSHEY\_COMPLEX})}
 264  \cvarg{CV\_FONT\_HERSHEY\_COMPLEX\_SMALL}{smaller version of \texttt{CV\_FONT\_HERSHEY\_COMPLEX}}
 265  \cvarg{CV\_FONT\_HERSHEY\_SCRIPT\_SIMPLEX}{hand-writing style font}
 266  \cvarg{CV\_FONT\_HERSHEY\_SCRIPT\_COMPLEX}{more complex variant of \texttt{CV\_FONT\_HERSHEY\_SCRIPT\_SIMPLEX}}
 267  \end{description}
 268  The parameter can be composited from one of the values above and an optional \texttt{CV\_FONT\_ITALIC} flag, which indicates italic or oblique font.}
 269 \cvarg{hscale}{Horizontal scale.  If equal to \texttt{1.0f}, the characters have the original width depending on the font type. If equal to \texttt{0.5f}, the characters are of half the original width.}
 270 \cvarg{vscale}{Vertical scale. If equal to \texttt{1.0f}, the characters have the original height depending on the font type. If equal to \texttt{0.5f}, the characters are of half the original height.}
 271 \cvarg{shear}{Approximate tangent of the character slope relative to the vertical line.  A zero value means a non-italic font, \texttt{1.0f} means about a 45 degree slope, etc.}
 272 \cvarg{thickness}{Thickness of the text strokes}
 273 \cvarg{lineType}{Type of the strokes, see \cross{Line} description}
 274 \end{description}
 275
 276 The function initializes the font structure that can be passed to text rendering functions.
 277
 278
 279 \cvCPyFunc{InitLineIterator}
 280 Initializes the line iterator.
 281
 282 \cvdefC{
 283 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 );
 284 }
 285 \cvdefPy{InitLineIterator(image, pt1, pt2, connectivity=8, left\_to\_right=0) -> None}
 286
 287 \begin{description}
 288 \cvarg{image}{Image to sample the line from}
 289 \cvarg{pt1}{First ending point of the line segment}
 290 \cvarg{pt2}{Second ending point of the line segment}
 291 \cvC{\cvarg{line\_iterator}{Pointer to the line iterator state structure}}
 292 \cvarg{connectivity}{The scanned line connectivity, 4 or 8.}
 293 \cvarg{left\_to\_right}{
 294 If ($ \texttt{left\_to\_right} = 0 $ ) then the line is scanned in the specified order, from \texttt{pt1} to \texttt{pt2}.
 295 If ($ \texttt{left\_to\_right} \ne 0$) the line is scanned from left-most point to right-most.}
 296 \end{description}
 297
 298 The function initializes the line
 299 iterator and returns the number of pixels between the two end points.
 300 Both points must be inside the image. After the iterator has been
 301 initialized, all the points on the raster line that connects the
 302 two ending points may be retrieved by successive calls of
 303 \texttt{CV\_NEXT\_LINE\_POINT} point. The points on the line are
 304 calculated one by one using a 4-connected or 8-connected Bresenham
 305 algorithm.
 306
 307 \ifC
 308 % Example: Using line iterator to calculate the sum of pixel values along the color line
 309
 310 \begin{lstlisting}
 311
 312 CvScalar sum_line_pixels( IplImage* image, CvPoint pt1, CvPoint pt2 )
 313 {
 314     CvLineIterator iterator;
 315     int blue_sum = 0, green_sum = 0, red_sum = 0;
 316     int count = cvInitLineIterator( image, pt1, pt2, &iterator, 8, 0 );
 317
 318     for( int i = 0; i < count; i++ ){
 319         blue_sum += iterator.ptr[0];
 320         green_sum += iterator.ptr[1];
 321         red_sum += iterator.ptr[2];
 322         CV_NEXT_LINE_POINT(iterator);
 323
 324         /* print the pixel coordinates: demonstrates how to calculate the
 325                                                         coordinates */
 326         {
 327         int offset, x, y;
 328         /* assume that ROI is not set, otherwise need to take it
 329                                                 into account. */
 330         offset = iterator.ptr - (uchar*)(image->imageData);
 331         y = offset/image->widthStep;
 332         x = (offset - y*image->widthStep)/(3*sizeof(uchar)
 333                                         /* size of pixel */);
 334         printf("(%d,%d)\n", x, y );
 335         }
 336     }
 337     return cvScalar( blue_sum, green_sum, red_sum );
 338 }
 339
 340 \end{lstlisting}
 341 \fi
 342
 343 \cvCPyFunc{Line}
 344 Draws a line segment connecting two points.
 345
 346 \cvdefC{
 347 void cvLine( \par CvArr* img,\par CvPoint pt1,\par CvPoint pt2,\par CvScalar color,\par int thickness=1,\par int lineType=8,\par int shift=0 );
 348 }
 349 \cvdefPy{Line(img,pt1,pt2,color,thickness=1,lineType=8,shift=0)-> None}
 350
 351 \begin{description}
 352 \cvarg{img}{The image}
 353 \cvarg{pt1}{First point of the line segment}
 354 \cvarg{pt2}{Second point of the line segment}
 355 \cvarg{color}{Line color}
 356 \cvarg{thickness}{Line thickness}
 357 \cvarg{lineType}{Type of the line:
 358   \begin{description}
 359   \cvarg{8}{(or omitted) 8-connected line.}
 360   \cvarg{4}{4-connected line.}
 361   \cvarg{CV\_AA}{antialiased line.}
 362   \end{description}}
 363 \cvarg{shift}{Number of fractional bits in the point coordinates}
 364 \end{description}
 365
 366 The function draws the line segment between
 367 \texttt{pt1} and \texttt{pt2} points in the image. The line is
 368 clipped by the image or ROI rectangle. For non-antialiased lines
 369 with integer coordinates the 8-connected or 4-connected Bresenham
 370 algorithm is used. Thick lines are drawn with rounding endings.
 371 Antialiased lines are drawn using Gaussian filtering. To specify
 372 the line color, the user may use the macro
 373 \texttt{CV\_RGB( r, g, b )}.
 374
 375 \cvCPyFunc{PolyLine}
 376 Draws simple or thick polygons.
 377
 378 \cvdefC{
 379 void cvPolyLine( \par CvArr* img,\par CvPoint** pts,\par int* npts,\par int contours,\par int is\_closed,\par CvScalar color,\par int thickness=1,\par int lineType=8,\par int shift=0 );}
 380 \cvdefPy{PolyLine(img,polys,is\_closed,color,thickness=1,lineType=8,shift=0)-> None}
 381
 382 \begin{description}
 383 \ifC
 384 \cvarg{pts}{Array of pointers to polygons}
 385 \cvarg{npts}{Array of polygon vertex counters}
 386 \cvarg{contours}{Number of contours that bind the filled region}
 387 \fi
 388 \ifPy
 389 \cvarg{polys}{List of lists of (x,y) pairs.  Each list of points is a polygon.}
 390 \fi
 391 \cvarg{img}{Image}
 392 \cvarg{is\_closed}{Indicates whether the polylines must be drawn
 393 closed. If closed, the function draws the line from the last vertex
 394 of every contour to the first vertex.}
 395 \cvarg{color}{Polyline color}
 396 \cvarg{thickness}{Thickness of the polyline edges}
 397 \cvarg{lineType}{Type of the line segments, see \cross{Line} description}
 398 \cvarg{shift}{Number of fractional bits in the vertex coordinates}
 399 \end{description}
 400
 401 The function draws single or multiple polygonal curves.
 402
 403 \cvCPyFunc{PutText}
 404 Draws a text string.
 405
 406 \cvdefC{
 407 void cvPutText( \par CvArr* img,\par const char* text,\par CvPoint org,\par const CvFont* font,\par CvScalar color );}
 408 \cvdefPy{PutText(img,text,org,font,color)-> None}
 409
 410 \begin{description}
 411 \cvarg{img}{Input image}
 412 \cvarg{text}{String to print}
 413 \cvarg{org}{Coordinates of the bottom-left corner of the first letter}
 414 \cvarg{font}{Pointer to the font structure}
 415 \cvarg{color}{Text color}
 416 \end{description}
 417
 418
 419 The function renders the text in the image with
 420 the specified font and color. The printed text is clipped by the ROI
 421 rectangle. Symbols that do not belong to the specified font are
 422 replaced with the symbol for a rectangle.
 423
 424 \cvCPyFunc{Rectangle}
 425 Draws a simple, thick, or filled rectangle.
 426
 427 \cvdefC{void cvRectangle( \par CvArr* img,\par CvPoint pt1,\par CvPoint pt2,\par CvScalar color,\par int thickness=1,\par int lineType=8,\par int shift=0 );}
 428 \cvdefPy{Rectangle(img,pt1,pt2,color,thickness=1,lineType=8,shift=0)-> None}
 429
 430 \begin{description}
 431 \cvarg{img}{Image}
 432 \cvarg{pt1}{One of the rectangle's vertices}
 433 \cvarg{pt2}{Opposite rectangle vertex}
 434 \cvarg{color}{Line color (RGB) or brightness (grayscale image)}
 435 \cvarg{thickness}{Thickness of lines that make up the rectangle. Negative values, e.g., CV\_FILLED, cause the function to draw a filled rectangle.}
 436 \cvarg{lineType}{Type of the line, see \cross{Line} description}
 437 \cvarg{shift}{Number of fractional bits in the point coordinates}
 438 \end{description}
 439
 440 The function draws a rectangle with two opposite corners \texttt{pt1} and \texttt{pt2}.
 441
 442 \cvfunc{CV\_RGB}\label{CV_RGB}
 443 Constructs a color value.
 444
 445 \cvdefC{\#define CV\_RGB( r, g, b )  cvScalar( (b), (g), (r) )}
 446 \cvdefPy{CV\_RGB(red,grn,blu)->CvScalar}
 447
 448 \begin{description}
 449 \cvarg{red}{Red component}
 450 \cvarg{grn}{Green component}
 451 \cvarg{blu}{Blue component}
 452 \end{description}
 453
 454 \fi
 455
 456 \ifCpp
 457
 458 \cvCppFunc{circle}
 459 Draws a circle
 460
 461 \cvdefCpp{
 462 void circle(Mat\& img, Point center, int radius,\par
 463             const Scalar\& color, int thickness=1,\par
 464             int lineType=8, int shift=0);
 465 }
 466 \begin{description}
 467 \cvarg{img}{Image where the circle is drawn}
 468 \cvarg{center}{Center of the circle}
 469 \cvarg{radius}{Radius of the circle}
 470 \cvarg{color}{Circle color}
 471 \cvarg{thickness}{Thickness of the circle outline if positive; negative thickness means that a filled circle is to be drawn}
 472 \cvarg{lineType}{Type of the circle boundary, see \cvCppCross{line} description}
 473 \cvarg{shift}{Number of fractional bits in the center coordinates and radius value}
 474 \end{description}
 475
 476 The function \texttt{circle} draws a simple or filled circle with a
 477 given center and radius.
 478
 479 \cvCppFunc{clipLine}
 480 Clips the line against the image rectangle
 481
 482 \cvdefCpp{
 483 bool clipLine(Size imgSize, Point\& pt1, Point\& pt2);\newline
 484 bool clipLine(Rect imgRect, Point\& pt1, Point\& pt2);\newline
 485 }
 486 \begin{description}
 487 \cvarg{imgSize}{The image size; the image rectangle will be \texttt{Rect(0, 0, imgSize.width, imgSize.height)}}
 488 \cvarg{imgSize}{The image rectangle}
 489 \cvarg{pt1}{The first line point}
 490 \cvarg{pt2}{The second line point}
 491 \end{description}
 492
 493 The functions \texttt{clipLine} calculate a part of the line
 494 segment which is entirely within the specified rectangle.
 495 They return \texttt{false} if the line segment is completely outside the rectangle and \texttt{true} otherwise.
 496
 497
 498 \cvCppFunc{ellipse}
 499 Draws a simple or thick elliptic arc or an fills ellipse sector.
 500
 501 \cvdefCpp{
 502 void ellipse(Mat\& img, Point center, Size axes,\par
 503              double angle, double startAngle, double endAngle,\par
 504              const Scalar\& color, int thickness=1,\par
 505              int lineType=8, int shift=0);\newline
 506 void ellipse(Mat\& img, const RotatedRect\& box, const Scalar\& color,\par
 507              int thickness=1, int lineType=8);\newline
 508 }
 509 \begin{description}
 510 \cvarg{img}{The image}
 511 \cvarg{center}{Center of the ellipse}
 512 \cvarg{axes}{Length of the ellipse axes}
 513 \cvarg{angle}{The ellipse rotation angle in degrees}
 514 \cvarg{startAngle}{Starting angle of the elliptic arc in degrees}
 515 \cvarg{endAngle}{Ending angle of the elliptic arc in degrees}
 516 \cvarg{box}{Alternative ellipse representation via a \cross{RotatedRect}, i.e. the function draws an ellipse inscribed in the rotated rectangle}
 517 \cvarg{color}{Ellipse color}
 518 \cvarg{thickness}{Thickness of the ellipse arc outline if positive, otherwise this indicates that a filled ellipse sector is to be drawn}
 519 \cvarg{lineType}{Type of the ellipse boundary, see \cvCppCross{line} description}
 520 \cvarg{shift}{Number of fractional bits in the center coordinates and axes' values}
 521 \end{description}
 522
 523 The functions \texttt{ellipse} with less parameters draw an ellipse outline, a filled ellipse, an elliptic
 524 arc or a filled ellipse sector.
 525 A piecewise-linear curve is used to approximate the elliptic arc boundary. If you need more control of the ellipse rendering, you can retrieve the curve using \cvCppCross{ellipse2Poly} and then render it with \cvCppCross{polylines} or fill it with \cvCppCross{fillPoly}. If you use the first variant of the function and want to draw the whole ellipse, not an arc, pass \texttt{startAngle=0} and \texttt{endAngle=360}. The picture below
 526 explains the meaning of the parameters.
 527
 528 Parameters of Elliptic Arc
 529
 530 \includegraphics[width=0.5\textwidth]{pics/ellipse.png}
 531
 532 \cvCppFunc{ellipse2Poly}
 533 Approximates an elliptic arc with a polyline
 534
 535 \cvdefCpp{
 536 void ellipse2Poly( Point center, Size axes, int angle,\par
 537                    int startAngle, int endAngle, int delta,\par
 538                    vector<Point>\& pts );\newline
 539 }
 540 \begin{description}
 541 \cvarg{center}{Center of the arc}
 542 \cvarg{axes}{Half-sizes of the arc. See \cvCppCross{ellipse}}
 543 \cvarg{angle}{Rotation angle of the ellipse in degrees. See \cvCppCross{ellipse}}
 544 \cvarg{startAngle}{Starting angle of the elliptic arc in degrees}
 545 \cvarg{endAngle}{Ending angle of the elliptic arc in degrees}
 546 \cvarg{delta}{Angle between the subsequent polyline vertices. It defines the approximation accuracy.}
 547 \cvarg{pts}{The output vector of polyline vertices}
 548 \end{description}
 549
 550 The function \texttt{ellipse2Poly} computes the vertices of a polyline that approximates the specified elliptic arc. It is used by \cvCppCross{ellipse}.
 551
 552 \cvCppFunc{fillConvexPoly}
 553 Fills a convex polygon.
 554
 555 \cvdefCpp{
 556 void fillConvexPoly(Mat\& img, const Point* pts, int npts,\par
 557                     const Scalar\& color, int lineType=8,\par
 558                     int shift=0);\newline
 559 }
 560 \begin{description}
 561 \cvarg{img}{Image}
 562 \cvarg{pts}{The polygon vertices}
 563 \cvarg{npts}{The number of polygon vertices}
 564 \cvarg{color}{Polygon color}
 565 \cvarg{lineType}{Type of the polygon boundaries, see \cvCppCross{line} description}
 566 \cvarg{shift}{The number of fractional bits in the vertex coordinates}
 567 \end{description}
 568
 569 The function \texttt{fillConvexPoly} draws a filled convex polygon.
 570 This function is much faster than the function \texttt{fillPoly}
 571 and can fill not only convex polygons but any monotonic polygon without self-intersections,
 572 i.e., a polygon whose contour intersects every horizontal line (scan
 573 line) twice at the most (though, its top-most and/or the bottom edge could be horizontal).
 574
 575 \cvCppFunc{fillPoly}
 576 Fills the area bounded by one or more polygons
 577
 578 \cvdefCpp{void fillPoly(Mat\& img, const Point** pts, \par
 579               const int* npts, int ncontours,\par
 580               const Scalar\& color, int lineType=8,\par
 581               int shift=0, Point offset=Point() );}
 582 \begin{description}
 583 \cvarg{img}{Image}
 584 \cvarg{pts}{Array of polygons, each represented as an array of points}
 585 \cvarg{npts}{The array of polygon vertex counters}
 586 \cvarg{ncontours}{The number of contours that bind the filled region}
 587 \cvarg{color}{Polygon color}
 588 \cvarg{lineType}{Type of the polygon boundaries, see \cvCppCross{line} description}
 589 \cvarg{shift}{The number of fractional bits in the vertex coordinates}
 590 \end{description}
 591
 592 The function \texttt{fillPoly} fills an area bounded by several
 593 polygonal contours. The function can fills complex areas, for example,
 594 areas with holes, contours with self-intersections (some of thier parts), and so forth.
 595
 596 \cvCppFunc{getTextSize}
 597 Calculates the width and height of a text string.
 598
 599 \cvdefCpp{Size getTextSize(const string\& text, int fontFace,\par
 600                  double fontScale, int thickness,\par
 601                  int* baseLine);\newline}
 602 \begin{description}
 603 \cvarg{text}{The input text string}
 604 \cvarg{fontFace}{The font to use; see \cvCppCross{putText}}
 605 \cvarg{fontScale}{The font scale; see \cvCppCross{putText}}
 606 \cvarg{thickness}{The thickness of lines used to render the text; see \cvCppCross{putText}}
 607 \cvarg{baseLine}{The output parameter - y-coordinate of the baseline relative to the bottom-most text point}
 608 \end{description}
 609
 610 The function \texttt{getTextSize} calculates and returns size of the box that contain the specified text.
 611 That is, the following code will render some text, the tight box surrounding it and the baseline:
 612
 613 \begin{lstlisting}
 614 // Use "y" to show that the baseLine is about
 615 string text = "Funny text inside the box";
 616 int fontFace = FONT_HERSHEY_SCRIPT_SIMPLEX;
 617 double fontScale = 2;
 618 int thickness = 3;
 619
 620 Mat img(600, 800, CV_8UC3, Scalar::all(0));
 621
 622 int baseline=0;
 623 Size textSize = getTextSize(text, fontFace,
 624                             fontScale, thickness, &baseline);
 625 baseline += thickness;
 626
 627 // center the text
 628 Point textOrg((img.cols - textSize.width)/2,
 629               (img.rows + textSize.height)/2);
 630
 631 // draw the box
 632 rectangle(img, textOrg + Point(0, baseline),
 633           textOrg + Point(textSize.width, -textSize.height),
 634           Scalar(0,0,255));
 635 // ... and the baseline first
 636 line(img, textOrg + Point(0, thickness),
 637      textOrg + Point(textSize.width, thickness),
 638      Scalar(0, 0, 255));
 639
 640 // then put the text itself
 641 putText(img, text, textOrg, fontFace, fontScale,
 642         Scalar::all(255), thickness, 8);
 643 \end{lstlisting}
 644
 645
 646 \cvCppFunc{line}
 647 Draws a line segment connecting two points
 648
 649 \cvdefCpp{void line(Mat\& img, Point pt1, Point pt2, const Scalar\& color,\par
 650           int thickness=1, int lineType=8, int shift=0);\newline}
 651 \begin{description}
 652 \cvarg{img}{The image}
 653 \cvarg{pt1}{First point of the line segment}
 654 \cvarg{pt2}{Second point of the line segment}
 655 \cvarg{color}{Line color}
 656 \cvarg{thickness}{Line thickness}
 657 \cvarg{lineType}{Type of the line:
 658   \begin{description}
 659   \cvarg{8}{(or omitted) 8-connected line.}
 660   \cvarg{4}{4-connected line.}
 661   \cvarg{CV\_AA}{antialiased line.}
 662   \end{description}}
 663 \cvarg{shift}{Number of fractional bits in the point coordinates}
 664 \end{description}
 665
 666 The function \texttt{line} draws the line segment between
 667 \texttt{pt1} and \texttt{pt2} points in the image. The line is
 668 clipped by the image boundaries. For non-antialiased lines
 669 with integer coordinates the 8-connected or 4-connected Bresenham
 670 algorithm is used. Thick lines are drawn with rounding endings.
 671 Antialiased lines are drawn using Gaussian filtering. To specify
 672 the line color, the user may use the macro
 673 \texttt{CV\_RGB(r, g, b)}.
 674
 675
 676 \cvclass{LineIterator}
 677 Class for iterating pixels on a raster line
 678
 679 \begin{lstlisting}
 680 class LineIterator
 681 {
 682 public:
 683     // creates iterators for the line connecting pt1 and pt2
 684     // the line will be clipped on the image boundaries
 685     // the line is 8-connected or 4-connected
 686     // If leftToRight=true, then the iteration is always done
 687     // from the left-most point to the right most,
 688     // not to depend on the ordering of pt1 and pt2 parameters
 689     LineIterator(const Mat& img, Point pt1, Point pt2,
 690                  int connectivity=8, bool leftToRight=false);newline
 691     // returns pointer to the current line pixel
 692     uchar* operator *();newline
 693     // move the iterator to the next pixel
 694     LineIterator& operator ++();newline
 695     LineIterator operator ++(int);newline
 696
 697     // internal state of the iterator
 698     uchar* ptr;newline
 699     int err, count;newline
 700     int minusDelta, plusDelta;newline
 701     int minusStep, plusStep;newline
 702 };
 703 \end{lstlisting}
 704
 705 The class \texttt{LineIterator} is used to get each pixel of a raster line. It can be treated as versatile implementation of the Bresenham algorithm, where you can stop at each pixel and do some extra processing, for example, grab pixel values along the line, or draw a line with some effect (e.g. with XOR operation).
 706
 707 The number of pixels along the line is store in \texttt{LineIterator::count}.
 708
 709 \begin{lstlisting}
 710 // grabs pixels along the line (pt1, pt2)
 711 // from 8-bit 3-channel image to the buffer
 712 LineIterator it(img, pt1, pt2, 8);
 713 vector<Vec3b> buf(it.count);
 714
 715 for(int i = 0; i < it.count; i++, ++it)
 716     buf[i] = *(const Vec3b)*it;
 717 \end{lstlisting}
 718
 719
 720 \cvCppFunc{rectangle}
 721 Draws a simple, thick, or filled up-right rectangle.
 722
 723 \cvdefCpp{void rectangle(Mat\& img, Point pt1, Point pt2,\par
 724                const Scalar\& color, int thickness=1,\par
 725                int lineType=8, int shift=0);}
 726 \begin{description}
 727 \cvarg{img}{Image}
 728 \cvarg{pt1}{One of the rectangle's vertices}
 729 \cvarg{pt2}{Opposite to \texttt{pt1} rectangle vertex}
 730 \cvarg{color}{Rectangle color or brightness (grayscale image)}
 731 \cvarg{thickness}{Thickness of lines that make up the rectangle. Negative values, e.g. \texttt{CV\_FILLED}, mean that the function has to draw a filled rectangle.}
 732 \cvarg{lineType}{Type of the line, see \cvCppCross{line} description}
 733 \cvarg{shift}{Number of fractional bits in the point coordinates}
 734 \end{description}
 735
 736 The function \texttt{rectangle} draws a rectangle outline or a filled rectangle, which two opposite corners are \texttt{pt1} and \texttt{pt2}.
 737
 738
 739 \cvCppFunc{polylines}
 740 Draws several polygonal curves
 741
 742 \cvdefCpp{void polylines(Mat\& img, const Point** pts, const int* npts,\par
 743                int ncontours, bool isClosed, const Scalar\& color,\par
 744                int thickness=1, int lineType=8, int shift=0 );\newline}
 745 \begin{description}
 746 \cvarg{img}{The image}
 747 \cvarg{pts}{Array of polygonal curves}
 748 \cvarg{npts}{Array of polygon vertex counters}
 749 \cvarg{ncontours}{The number of curves}
 750 \cvarg{isClosed}{Indicates whether the drawn polylines are closed or not. If they are closed, the function draws the line from the last vertex of each curve to its first vertex}
 751 \cvarg{color}{Polyline color}
 752 \cvarg{thickness}{Thickness of the polyline edges}
 753 \cvarg{lineType}{Type of the line segments, see \cvCppCross{line} description}
 754 \cvarg{shift}{The number of fractional bits in the vertex coordinates}
 755 \end{description}
 756
 757 The function \texttt{polylines} draws one or more polygonal curves.
 758
 759 \cvCppFunc{putText}
 760 Draws a text string
 761
 762 \cvdefCpp{void putText( Mat\& img, const string\& text, Point org,\par
 763               int fontFace, double fontScale, Scalar color,\par
 764               int thickness=1, int lineType=8,\par
 765               bool bottomLeftOrigin=false );}
 766 \begin{description}
 767 \cvarg{img}{The image}
 768 \cvarg{text}{The text string to be drawn}
 769 \cvarg{org}{The bottom-left corner of the text string in the image}
 770 \cvarg{fontFace}{The font type, one of \texttt{FONT\_HERSHEY\_SIMPLEX}, \texttt{FONT\_HERSHEY\_PLAIN},
 771  \texttt{FONT\_HERSHEY\_DUPLEX}, \texttt{FONT\_HERSHEY\_COMPLEX}, \texttt{FONT\_HERSHEY\_TRIPLEX},
 772  \texttt{FONT\_HERSHEY\_COMPLEX\_SMALL}, \texttt{FONT\_HERSHEY\_SCRIPT\_SIMPLEX} or \texttt{FONT\_HERSHEY\_SCRIPT\_COMPLEX},
 773    where each of the font id's can be combined with \texttt{FONT\_HERSHEY\_ITALIC} to get the slanted letters.}
 774 \cvarg{fontScale}{The font scale factor that is multiplied by the font-specific base size}
 775 \cvarg{thickness}{Thickness of the lines used to draw the text}
 776 \cvarg{lineType}{The line type; see \texttt{line} for details}
 777 \cvarg{bottomLeftOrigin}{When true, the image data origin is at the bottom-left corner, otherwise it's at the top-left corner}
 778 \end{description}
 779
 780 The function \texttt{putText} draws a text string in the image.
 781 Symbols that can not be rendered using the specified font are
 782 replaced question marks. See \cvCppCross{getTextSize} for a text rendering code example.
 783
 784 \fi