Drawing Functions

Overview

Drawing functions work with matrices/images of arbitrary depth. More…

// enums

enum cv::MarkerTypes;

// classes

class cv::LineIterator;

// global functions

void
cv::arrowedLine(
    InputOutputArray img,
    Point pt1,
    Point pt2,
    const Scalar& color,
    int thickness = 1,
    int line_type = 8,
    int shift = 0,
    double tipLength = 0.1
    );

void
cv::circle(
    InputOutputArray img,
    Point center,
    int radius,
    const Scalar& color,
    int thickness = 1,
    int lineType = LINE_8,
    int shift = 0
    );

bool
cv::clipLine(
    Size imgSize,
    Point& pt1,
    Point& pt2
    );

bool
cv::clipLine(
    Size2l imgSize,
    Point2l& pt1,
    Point2l& pt2
    );

bool
cv::clipLine(
    Rect imgRect,
    Point& pt1,
    Point& pt2
    );

void
cv::drawContours(
    InputOutputArray image,
    InputArrayOfArrays contours,
    int contourIdx,
    const Scalar& color,
    int thickness = 1,
    int lineType = LINE_8,
    InputArray hierarchy = noArray(),
    int maxLevel = INT_MAX,
    Point offset = Point()
    );

void
cv::drawMarker(
    Mat& img,
    Point position,
    const Scalar& color,
    int markerType = MARKER_CROSS,
    int markerSize = 20,
    int thickness = 1,
    int line_type = 8
    );

void
cv::ellipse(
    InputOutputArray img,
    Point center,
    Size axes,
    double angle,
    double startAngle,
    double endAngle,
    const Scalar& color,
    int thickness = 1,
    int lineType = LINE_8,
    int shift = 0
    );

void
cv::ellipse(
    InputOutputArray img,
    const RotatedRect& box,
    const Scalar& color,
    int thickness = 1,
    int lineType = LINE_8
    );

void
cv::ellipse2Poly(
    Point center,
    Size axes,
    int angle,
    int arcStart,
    int arcEnd,
    int delta,
    std::vector<Point>& pts
    );

void
cv::ellipse2Poly(
    Point2d center,
    Size2d axes,
    int angle,
    int arcStart,
    int arcEnd,
    int delta,
    std::vector<Point2d>& pts
    );

void
cv::fillConvexPoly(
    Mat& img,
    const Point* pts,
    int npts,
    const Scalar& color,
    int lineType = LINE_8,
    int shift = 0
    );

void
cv::fillConvexPoly(
    InputOutputArray img,
    InputArray points,
    const Scalar& color,
    int lineType = LINE_8,
    int shift = 0
    );

void
cv::fillPoly(
    Mat& img,
    const Point** pts,
    const int* npts,
    int ncontours,
    const Scalar& color,
    int lineType = LINE_8,
    int shift = 0,
    Point offset = Point()
    );

void
cv::fillPoly(
    InputOutputArray img,
    InputArrayOfArrays pts,
    const Scalar& color,
    int lineType = LINE_8,
    int shift = 0,
    Point offset = Point()
    );

Size
cv::getTextSize(
    const String& text,
    int fontFace,
    double fontScale,
    int thickness,
    int* baseLine
    );

void
cv::line(
    InputOutputArray img,
    Point pt1,
    Point pt2,
    const Scalar& color,
    int thickness = 1,
    int lineType = LINE_8,
    int shift = 0
    );

void
cv::polylines(
    Mat& img,
    const Point*const* pts,
    const int* npts,
    int ncontours,
    bool isClosed,
    const Scalar& color,
    int thickness = 1,
    int lineType = LINE_8,
    int shift = 0
    );

void
cv::polylines(
    InputOutputArray img,
    InputArrayOfArrays pts,
    bool isClosed,
    const Scalar& color,
    int thickness = 1,
    int lineType = LINE_8,
    int shift = 0
    );

void
cv::putText(
    InputOutputArray img,
    const String& text,
    Point org,
    int fontFace,
    double fontScale,
    Scalar color,
    int thickness = 1,
    int lineType = LINE_8,
    bool bottomLeftOrigin = false
    );

void
cv::rectangle(
    InputOutputArray img,
    Point pt1,
    Point pt2,
    const Scalar& color,
    int thickness = 1,
    int lineType = LINE_8,
    int shift = 0
    );

void
cv::rectangle(
    Mat& img,
    Rect rec,
    const Scalar& color,
    int thickness = 1,
    int lineType = LINE_8,
    int shift = 0
    );

Detailed Documentation

Drawing functions work with matrices/images of arbitrary depth. The boundaries of the shapes can be rendered with antialiasing (implemented only for 8-bit images for now). All the functions include the parameter color that uses an RGB value (that may be constructed with the Scalar constructor ) for color images and brightness for grayscale images. For color images, the channel ordering is normally Blue, Green, Red. This is what imshow, imread, and imwrite expect. So, if you form a color using the Scalar constructor, it should look like:

\[\texttt{Scalar} (blue \_ component, green \_ component, red \_ component[, alpha \_ component])\]

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 used color space. The whole image can be converted from BGR to RGB or to a different color space using cvtColor .

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. This means that the coordinates can be passed as fixed-point numbers encoded as integers. The number of fractional bits is specified by the 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 when rendering antialiased shapes.

The functions do not support alpha-transparency when the target image is 4-channel. In this case, the 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.

Global Functions

void
cv::arrowedLine(
    InputOutputArray img,
    Point pt1,
    Point pt2,
    const Scalar& color,
    int thickness = 1,
    int line_type = 8,
    int shift = 0,
    double tipLength = 0.1
    )

Draws a arrow segment pointing from the first point to the second one.

The function arrowedLine draws an arrow between pt1 and pt2 points in the image. See also cv::line.

Parameters:

img	Image.
pt1	The point the arrow starts from.
pt2	The point the arrow points to.
color	Line color.
thickness	Line thickness.
line_type	Type of the line, see cv::LineTypes
shift	Number of fractional bits in the point coordinates.
tipLength	The length of the arrow tip in relation to the arrow length

void
cv::circle(
    InputOutputArray img,
    Point center,
    int radius,
    const Scalar& color,
    int thickness = 1,
    int lineType = LINE_8,
    int shift = 0
    )

Draws a circle.

The function circle draws a simple or filled circle with a given center and radius.

Parameters:

img	Image where the circle is drawn.
center	Center of the circle.
radius	Radius of the circle.
color	Circle color.
thickness	Thickness of the circle outline, if positive. Negative thickness means that a filled circle is to be drawn.
lineType	Type of the circle boundary. See the line description.
shift	Number of fractional bits in the coordinates of the center and in the radius value.

bool
cv::clipLine(
    Size imgSize,
    Point& pt1,
    Point& pt2
    )

Clips the line against the image rectangle.

The function cv::clipLine calculates a part of the line segment that is entirely within the specified rectangle. it returns false if the line segment is completely outside the rectangle. Otherwise, it returns true .

Parameters:

imgSize	Image size. The image rectangle is Rect(0, 0, imgSize.width, imgSize.height) .
pt1	First line point.
pt2	Second line point.

bool
cv::clipLine(
    Size2l imgSize,
    Point2l& pt1,
    Point2l& pt2
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

imgSize	Image size. The image rectangle is Rect(0, 0, imgSize.width, imgSize.height) .
pt1	First line point.
pt2	Second line point.

bool
cv::clipLine(
    Rect imgRect,
    Point& pt1,
    Point& pt2
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

imgRect	Image rectangle.
pt1	First line point.
pt2	Second line point.

void
cv::drawContours(
    InputOutputArray image,
    InputArrayOfArrays contours,
    int contourIdx,
    const Scalar& color,
    int thickness = 1,
    int lineType = LINE_8,
    InputArray hierarchy = noArray(),
    int maxLevel = INT_MAX,
    Point offset = Point()
    )

Draws contours outlines or filled contours.

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\). The example below shows how to retrieve connected components from the binary image and label them: :

#include "opencv2/imgproc.hpp"
#include "opencv2/highgui.hpp"

using namespace cv;
using namespace std;

int main( int argc, char** argv )
{
    Mat src;
    // the first command-line parameter must be a filename of the binary
    // (black-n-white) image
    if( argc != 2 || !(src=imread(argv[1], 0)).data)
        return -1;

    Mat dst = Mat::zeros(src.rows, src.cols, CV_8UC3);

    src = src > 1;
    namedWindow( "Source", 1 );
    imshow( "Source", src );

    vector<vector<Point> > contours;
    vector<Vec4i> hierarchy;

    findContours( src, contours, hierarchy,
        RETR_CCOMP, CHAIN_APPROX_SIMPLE );

    // iterate through all the top-level contours,
    // draw each connected component with its own random color
    int idx = 0;
    for( ; idx >= 0; idx = hierarchy[idx][0] )
    {
        Scalar color( rand()&255, rand()&255, rand()&255 );
        drawContours( dst, contours, idx, color, FILLED, 8, hierarchy );
    }

    namedWindow( "Components", 1 );
    imshow( "Components", dst );
    waitKey(0);
}

Parameters:

image	Destination image.
contours	All the input contours. Each contour is stored as a point vector.
contourIdx	Parameter indicating a contour to draw. If it is negative, all the contours are drawn.
color	Color of the contours.
thickness	Thickness of lines the contours are drawn with. If it is negative (for example, thickness=CV_FILLED ), the contour interiors are drawn.
lineType	Line connectivity. See cv::LineTypes.
hierarchy	Optional information about hierarchy. It is only needed if you want to draw only some of the contours (see maxLevel ).
maxLevel	Maximal level for drawn contours. If it is 0, only the specified contour is drawn. If it is 1, the function draws the contour(s) and all the nested contours. If it is 2, the function draws the contours, all the nested contours, all the nested-to-nested contours, and so on. This parameter is only taken into account when there is hierarchy available.
offset	Optional contour shift parameter. Shift all the drawn contours by the specified \(\texttt{offset}=(dx,dy)\).

void
cv::drawMarker(
    Mat& img,
    Point position,
    const Scalar& color,
    int markerType = MARKER_CROSS,
    int markerSize = 20,
    int thickness = 1,
    int line_type = 8
    )

Draws a marker on a predefined position in an image.

The function drawMarker draws a marker on a given position in the image. For the moment several marker types are supported, see cv::MarkerTypes for more information.

Parameters:

img	Image.
position	The point where the crosshair is positioned.
color	Line color.
markerType	The specific type of marker you want to use, see cv::MarkerTypes
thickness	Line thickness.
line_type	Type of the line, see cv::LineTypes
markerSize	The length of the marker axis [default = 20 pixels]

void
cv::ellipse(
    InputOutputArray img,
    Point center,
    Size axes,
    double angle,
    double startAngle,
    double endAngle,
    const Scalar& color,
    int thickness = 1,
    int lineType = LINE_8,
    int shift = 0
    )

Draws a simple or thick elliptic arc or fills an ellipse sector.

The function cv::ellipse with more parameters draws an ellipse outline, a filled ellipse, an elliptic arc, or a filled ellipse sector. The drawing code uses general parametric form. 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 cv::ellipse2Poly and then render it with polylines or fill it with cv::fillPoly. If you use the first variant of the function and want to draw the whole ellipse, not an arc, pass startAngle=0 and endAngle=360. If startAngle is greater than endAngle, they are swapped. The figure below explains the meaning of the parameters to draw the blue arc.

Parameters:

img	Image.
center	Center of the ellipse.
axes	Half of the size of the ellipse main axes.
angle	Ellipse rotation angle in degrees.
startAngle	Starting angle of the elliptic arc in degrees.
endAngle	Ending angle of the elliptic arc in degrees.
color	Ellipse color.
thickness	Thickness of the ellipse arc outline, if positive. Otherwise, this indicates that a filled ellipse sector is to be drawn.
lineType	Type of the ellipse boundary. See the line description.
shift	Number of fractional bits in the coordinates of the center and values of axes.

void
cv::ellipse(
    InputOutputArray img,
    const RotatedRect& box,
    const Scalar& color,
    int thickness = 1,
    int lineType = LINE_8
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

img	Image.
box	Alternative ellipse representation via RotatedRect. This means that the function draws an ellipse inscribed in the rotated rectangle.
color	Ellipse color.
thickness	Thickness of the ellipse arc outline, if positive. Otherwise, this indicates that a filled ellipse sector is to be drawn.
lineType	Type of the ellipse boundary. See the line description.

void
cv::ellipse2Poly(
    Point center,
    Size axes,
    int angle,
    int arcStart,
    int arcEnd,
    int delta,
    std::vector<Point>& pts
    )

Approximates an elliptic arc with a polyline.

The function ellipse2Poly computes the vertices of a polyline that approximates the specified elliptic arc. It is used by cv::ellipse. If arcStart is greater than arcEnd, they are swapped.

Parameters:

center	Center of the arc.
axes	Half of the size of the ellipse main axes. See the ellipse for details.
angle	Rotation angle of the ellipse in degrees. See the ellipse for details.
arcStart	Starting angle of the elliptic arc in degrees.
arcEnd	Ending angle of the elliptic arc in degrees.
delta	Angle between the subsequent polyline vertices. It defines the approximation accuracy.
pts	Output vector of polyline vertices.

void
cv::ellipse2Poly(
    Point2d center,
    Size2d axes,
    int angle,
    int arcStart,
    int arcEnd,
    int delta,
    std::vector<Point2d>& pts
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

center	Center of the arc.
axes	Half of the size of the ellipse main axes. See the ellipse for details.
angle	Rotation angle of the ellipse in degrees. See the ellipse for details.
arcStart	Starting angle of the elliptic arc in degrees.
arcEnd	Ending angle of the elliptic arc in degrees.
delta	Angle between the subsequent polyline vertices. It defines the approximation accuracy.
pts	Output vector of polyline vertices.

void
cv::fillConvexPoly(
    Mat& img,
    const Point* pts,
    int npts,
    const Scalar& color,
    int lineType = LINE_8,
    int shift = 0
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void
cv::fillConvexPoly(
    InputOutputArray img,
    InputArray points,
    const Scalar& color,
    int lineType = LINE_8,
    int shift = 0
    )

Fills a convex polygon.

The function fillConvexPoly draws a filled convex polygon. This function is much faster than the function cv::fillPoly. It can fill not only convex polygons but any monotonic polygon without self-intersections, that is, a polygon whose contour intersects every horizontal line (scan line) twice at the most (though, its top-most and/or the bottom edge could be horizontal).

Parameters:

img	Image.
points	Polygon vertices.
color	Polygon color.
lineType	Type of the polygon boundaries. See the line description.
shift	Number of fractional bits in the vertex coordinates.

void
cv::fillPoly(
    Mat& img,
    const Point** pts,
    const int* npts,
    int ncontours,
    const Scalar& color,
    int lineType = LINE_8,
    int shift = 0,
    Point offset = Point()
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void
cv::fillPoly(
    InputOutputArray img,
    InputArrayOfArrays pts,
    const Scalar& color,
    int lineType = LINE_8,
    int shift = 0,
    Point offset = Point()
    )

Fills the area bounded by one or more polygons.

The function fillPoly fills an area bounded by several polygonal contours. The function can fill complex areas, for example, areas with holes, contours with self-intersections (some of their parts), and so forth.

Parameters:

img	Image.
pts	Array of polygons where each polygon is represented as an array of points.
color	Polygon color.
lineType	Type of the polygon boundaries. See the line description.
shift	Number of fractional bits in the vertex coordinates.
offset	Optional offset of all points of the contours.

Size
cv::getTextSize(
    const String& text,
    int fontFace,
    double fontScale,
    int thickness,
    int* baseLine
    )

Calculates the width and height of a text string.

The function getTextSize calculates and returns the size of a box that contains the specified text. That is, the following code renders some text, the tight box surrounding it, and the baseline: :

String text = "Funny text inside the box";
int fontFace = FONT_HERSHEY_SCRIPT_SIMPLEX;
double fontScale = 2;
int thickness = 3;

Mat img(600, 800, CV_8UC3, Scalar::all(0));

int baseline=0;
Size textSize = getTextSize(text, fontFace,
                            fontScale, thickness, &baseline);
baseline += thickness;

// center the text
Point textOrg((img.cols - textSize.width)/2,
              (img.rows + textSize.height)/2);

// draw the box
rectangle(img, textOrg + Point(0, baseline),
          textOrg + Point(textSize.width, -textSize.height),
          Scalar(0,0,255));
// ... and the baseline first
line(img, textOrg + Point(0, thickness),
     textOrg + Point(textSize.width, thickness),
     Scalar(0, 0, 255));

// then put the text itself
putText(img, text, textOrg, fontFace, fontScale,
        Scalar::all(255), thickness, 8);

Parameters:

text	Input text string.
fontFace	Font to use, see cv::HersheyFonts.
fontScale	Font scale factor that is multiplied by the font-specific base size.
thickness	Thickness of lines used to render the text. See putText for details.
baseLine	y-coordinate of the baseline relative to the bottom-most text point.

Returns:

The size of a box that contains the specified text.