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 CV_RGB
or 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:
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
. This feature is especially effective when rendering antialiased shapes.
Note
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.
Note
Draws a circle.
void circle
(Mat& img, Point center, int radius, const Scalar& color, int thickness=1, int lineType=8, int shift=0)¶
cv2.
circle
(img, center, radius, color[, thickness[, lineType[, shift]]]) → None¶
void cvCircle
(CvArr* img, CvPoint center, int radius, CvScalar color, int thickness=1, int line_type=8, int shift=0 )¶
cv.
Circle
(img, center, radius, color, thickness=1, lineType=8, shift=0) → None¶Parameters: |
|
---|
The function circle
draws a simple or filled circle with a given center and radius.
Clips the line against the image rectangle.
bool clipLine
(Size imgSize, Point& pt1, Point& pt2)¶
bool clipLine
(Rect imgRect, Point& pt1, Point& pt2)¶
cv2.
clipLine
(imgRect, pt1, pt2) → retval, pt1, pt2¶
int cvClipLine
(CvSize img_size, CvPoint* pt1, CvPoint* pt2)¶
cv.
ClipLine
(imgSize, pt1, pt2) -> (point1, point2)¶Parameters: |
|
---|
The functions clipLine
calculate a part of the line segment that is entirely within the specified rectangle.
They return false
if the line segment is completely outside the rectangle. Otherwise, they return true
.
Draws a simple or thick elliptic arc or fills an ellipse sector.
void ellipse
(Mat& img, Point center, Size axes, double angle, double startAngle, double endAngle, const Scalar& color, int thickness=1, int lineType=8, int shift=0)¶
void ellipse
(Mat& img, const RotatedRect& box, const Scalar& color, int thickness=1, int lineType=8)¶
cv2.
ellipse
(img, center, axes, angle, startAngle, endAngle, color[, thickness[, lineType[, shift]]]) → None¶
cv2.
ellipse
(img, box, color[, thickness[, lineType]]) → None
void cvEllipse
(CvArr* img, CvPoint center, CvSize axes, double angle, double start_angle, double end_angle, CvScalar color, int thickness=1, int line_type=8, int shift=0 )¶
cv.
Ellipse
(img, center, axes, angle, start_angle, end_angle, color, thickness=1, lineType=8, shift=0) → None¶
void cvEllipseBox
(CvArr* img, CvBox2D box, CvScalar color, int thickness=1, int line_type=8, int shift=0 )¶
cv.
EllipseBox
(img, box, color, thickness=1, lineType=8, shift=0) → None¶Parameters: |
|
---|
The functions ellipse
with less parameters draw an ellipse outline, a filled ellipse, an elliptic arc, or a filled ellipse sector.
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
ellipse2Poly()
and then render it with
polylines()
or fill it with
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
. The figure below explains the meaning of the parameters.
Figure 1. Parameters of Elliptic Arc
Approximates an elliptic arc with a polyline.
void ellipse2Poly
(Point center, Size axes, int angle, int arcStart, int arcEnd, int delta, vector<Point>& pts)¶
cv2.
ellipse2Poly
(center, axes, angle, arcStart, arcEnd, delta) → pts¶Parameters: |
|
---|
The function ellipse2Poly
computes the vertices of a polyline that approximates the specified elliptic arc. It is used by
ellipse()
.
Fills a convex polygon.
void fillConvexPoly
(Mat& img, const Point* pts, int npts, const Scalar& color, int lineType=8, int shift=0)¶
cv2.
fillConvexPoly
(img, points, color[, lineType[, shift]]) → None¶
void cvFillConvexPoly
(CvArr* img, const CvPoint* pts, int npts, CvScalar color, int line_type=8, int shift=0 )¶
cv.
FillConvexPoly
(img, pn, color, lineType=8, shift=0) → None¶Parameters: |
|
---|
The function fillConvexPoly
draws a filled convex polygon.
This function is much faster than the function 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).
Fills the area bounded by one or more polygons.
void fillPoly
(Mat& img, const Point** pts, const int* npts, int ncontours, const Scalar& color, int lineType=8, int shift=0, Point offset=Point() )¶
cv2.
fillPoly
(img, pts, color[, lineType[, shift[, offset]]]) → None¶
void cvFillPoly
(CvArr* img, CvPoint** pts, const int* npts, int contours, CvScalar color, int line_type=8, int shift=0 )¶
cv.
FillPoly
(img, polys, color, lineType=8, shift=0) → None¶Parameters: |
|
---|
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.
Calculates the width and height of a text string.
Size getTextSize
(const string& text, int fontFace, double fontScale, int thickness, int* baseLine)¶
cv2.
getTextSize
(text, fontFace, fontScale, thickness) → retval, baseLine¶
void cvGetTextSize
(const char* text_string, const CvFont* font, CvSize* text_size, int* baseline)¶
cv.
GetTextSize
(textString, font)-> (textSize, baseline)¶Parameters: |
|
---|
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);
Initializes font structure (OpenCV 1.x API).
void cvInitFont
(CvFont* font, int font_face, double hscale, double vscale, double shear=0, int thickness=1, int line_type=8 )¶Parameters: |
|
---|
The function initializes the font structure that can be passed to text rendering functions.
See also
Draws a line segment connecting two points.
void line
(Mat& img, Point pt1, Point pt2, const Scalar& color, int thickness=1, int lineType=8, int shift=0)¶
cv2.
line
(img, pt1, pt2, color[, thickness[, lineType[, shift]]]) → None¶
void cvLine
(CvArr* img, CvPoint pt1, CvPoint pt2, CvScalar color, int thickness=1, int line_type=8, int shift=0 )¶
cv.
Line
(img, pt1, pt2, color, thickness=1, lineType=8, shift=0) → None¶Parameters: |
|
---|
The function line
draws the line segment between pt1
and pt2
points in the image. The line is clipped by the image boundaries. For non-antialiased lines with integer coordinates, the 8-connected or 4-connected Bresenham algorithm is used. Thick lines are drawn with rounding endings.
Antialiased lines are drawn using Gaussian filtering. To specify the line color, you may use the macro CV_RGB(r, g, b)
.
Draws a arrow segment pointing from the first point to the second one.
void arrowedLine
(Mat& img, Point pt1, Point pt2, const Scalar& color, int thickness=1, int line_type=8, int shift=0, double tipLength=0.1)¶Parameters: |
|
---|
The function arrowedLine
draws an arrow between pt1
and pt2
points in the image. See also line()
.
LineIterator
¶Class for iterating pixels on a raster line.
class LineIterator
{
public:
// creates iterators for the line connecting pt1 and pt2
// the line will be clipped on the image boundaries
// the line is 8-connected or 4-connected
// If leftToRight=true, then the iteration is always done
// from the left-most point to the right most,
// not to depend on the ordering of pt1 and pt2 parameters
LineIterator(const Mat& img, Point pt1, Point pt2,
int connectivity=8, bool leftToRight=false);
// returns pointer to the current line pixel
uchar* operator *();
// move the iterator to the next pixel
LineIterator& operator ++();
LineIterator operator ++(int);
Point pos() const;
// internal state of the iterator
uchar* ptr;
int err, count;
int minusDelta, plusDelta;
int minusStep, plusStep;
};
The class 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 an effect (for example, with XOR operation).
The number of pixels along the line is stored in LineIterator::count
. The method LineIterator::pos
returns the current position in the image
// grabs pixels along the line (pt1, pt2)
// from 8-bit 3-channel image to the buffer
LineIterator it(img, pt1, pt2, 8);
LineIterator it2 = it;
vector<Vec3b> buf(it.count);
for(int i = 0; i < it.count; i++, ++it)
buf[i] = *(const Vec3b)*it;
// alternative way of iterating through the line
for(int i = 0; i < it2.count; i++, ++it2)
{
Vec3b val = img.at<Vec3b>(it2.pos());
CV_Assert(buf[i] == val);
}
Draws a simple, thick, or filled up-right rectangle.
void rectangle
(Mat& img, Point pt1, Point pt2, const Scalar& color, int thickness=1, int lineType=8, int shift=0)¶
void rectangle
(Mat& img, Rect rec, const Scalar& color, int thickness=1, int lineType=8, int shift=0 )¶
cv2.
rectangle
(img, pt1, pt2, color[, thickness[, lineType[, shift]]]) → None¶
void cvRectangle
(CvArr* img, CvPoint pt1, CvPoint pt2, CvScalar color, int thickness=1, int line_type=8, int shift=0 )¶
cv.
Rectangle
(img, pt1, pt2, color, thickness=1, lineType=8, shift=0) → None¶Parameters: |
|
---|
The function rectangle
draws a rectangle outline or a filled rectangle whose two opposite corners are pt1
and pt2
, or r.tl()
and r.br()-Point(1,1)
.
Draws several polygonal curves.
void polylines
(Mat& img, const Point** pts, const int* npts, int ncontours, bool isClosed, const Scalar& color, int thickness=1, int lineType=8, int shift=0 )¶
void polylines
(InputOutputArray img, InputArrayOfArrays pts, bool isClosed, const Scalar& color, int thickness=1, int lineType=8, int shift=0 )¶
cv2.
polylines
(img, pts, isClosed, color[, thickness[, lineType[, shift]]]) → None¶
void cvPolyLine
(CvArr* img, CvPoint** pts, const int* npts, int contours, int is_closed, CvScalar color, int thickness=1, int line_type=8, int shift=0 )¶
cv.
PolyLine
(img, polys, is_closed, color, thickness=1, lineType=8, shift=0) → None¶Parameters: |
|
---|
The function polylines
draws one or more polygonal curves.
Draws a text string.
void putText
(Mat& img, const string& text, Point org, int fontFace, double fontScale, Scalar color, int thickness=1, int lineType=8, bool bottomLeftOrigin=false )¶
cv2.
putText
(img, text, org, fontFace, fontScale, color[, thickness[, lineType[, bottomLeftOrigin]]]) → None¶
void cvPutText
(CvArr* img, const char* text, CvPoint org, const CvFont* font, CvScalar color)¶
cv.
PutText
(img, text, org, font, color) → None¶Parameters: |
|
---|
The function putText
renders the specified text string in the image.
Symbols that cannot be rendered using the specified font are
replaced by question marks. See
getTextSize()
for a text rendering code example.