generic-library/opencv
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Purpose: updated the core chapter

Browse Source
This commit is contained in:
Elena Fedotova 2011-04-10 20:54:37 +00:00
parent cc1624b06a
commit 77cdc746a5
1 changed files with 123 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

241
modules/core/doc/drawing_functions.rst
View File

@ -5,29 +5,32 @@ Drawing Functions
Drawing functions work with matrices/images of arbitrary depth. 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). 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 a rgb value (that may be constructed All the functions include the parameter ``color`` that uses an RGB value (that may be constructed
with ``CV_RGB`` or the :ref:`Scalar` constructor with ``CV_RGB`` or the :ref:`Scalar` constructor
) for color ) for color
images and brightness for grayscale images. For color images the order channel images and brightness for grayscale images. For color images, the order?? channel
is normally is normally
*Blue, Green, Red* *Blue, Green, Red*.
, this is what This is what
:func:`imshow`,:func:`imread` and :func:`imshow`,
:func:`imwrite` expect :func:`imread`, and
, so if you form a color using :func:`imwrite` expect.
So, if you form a color using the
:ref:`Scalar` constructor, it should look like: :ref:`Scalar` constructor, it should look like:
.. math:: .. math::
\texttt{Scalar} (blue \_ component, green \_ component, red \_ component[, alpha \_ component]) \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 color space used. The whole image can be converted from BGR to RGB or to a different color space using 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
:func:`cvtColor` . :func:`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, that is, 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 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
:math:`\texttt{Point}(x,y)\rightarrow\texttt{Point2f}(x*2^{-shift},y*2^{-shift})` . This feature is especially effective wehn rendering antialiased shapes. :math:`\texttt{Point}(x,y)\rightarrow\texttt{Point2f}(x*2^{-shift},y*2^{-shift})` . This feature is especially effective when rendering antialiased shapes.
Also, note that the functions do not support alpha-transparency - when the target image is 4-channnel, then 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**:
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.
.. index:: circle .. index:: circle
@ -35,24 +38,23 @@ circle
---------- ----------
.. c:function:: void circle(Mat& img, Point center, int radius, const Scalar& color, int thickness=1, int lineType=8, int shift=0) .. c:function:: void circle(Mat& img, Point center, int radius, const Scalar& color, int thickness=1, int lineType=8, int shift=0)
Draws a circle Draws a circle.
:param img: Image where the circle is drawn :param img: Image where the circle is drawn.
:param center: Center of the circle :param center: Center of the circle.
:param radius: Radius of the circle :param radius: Radius of the circle.
:param color: Circle color :param color: Circle color.
:param thickness: Thickness of the circle outline if positive; negative thickness means that a filled circle is to be drawn :param thickness: Thickness of the circle outline if positive. Negative thickness means that a filled circle is to be drawn.
:param lineType: Type of the circle boundary, see :func:`line` description :param lineType: Type of the circle boundary. See :func:`line` description.
:param shift: Number of fractional bits in the center coordinates and radius value :param shift: Number of fractional bits in the center?? coordinates, and radius value.
The function ``circle`` draws a simple or filled circle with a The function ``circle`` draws a simple or filled circle with a given center and radius.
given center and radius.
.. index:: clipLine .. index:: clipLine
@ -62,17 +64,18 @@ clipLine
.. c:function:: bool clipLine(Rect imgRect, Point& pt1, Point& pt2) .. c:function:: bool clipLine(Rect imgRect, Point& pt1, Point& pt2)
Clips the line against the image rectangle Clips the line against the image rectangle.
:param imgSize: The image size; the image rectangle will be ``Rect(0, 0, imgSize.width, imgSize.height)`` :param imgSize: The image rectangle :param imgSize: Image size. The image rectangle is ``Rect(0, 0, imgSize.width, imgSize.height)`` .
:param imgSize: Image rectangle.
:param pt1: The first line point :param pt1: The first line point.
:param pt2: The second line point :param pt2: The second line point.
The functions ``clipLine`` calculate a part of the line The functions ``clipLine`` calculate a part of the line segment which is entirely within the specified rectangle.
segment which is entirely within the specified rectangle. They return ``false`` if the line segment is completely outside the rectangle. Otherwise, it returns ``true`` .
They return ``false`` if the line segment is completely outside the rectangle and ``true`` otherwise.
.. index:: ellipse .. index:: ellipse
@ -82,39 +85,37 @@ ellipse
.. c:function:: void ellipse(Mat& img, const RotatedRect& box, const Scalar& color, int thickness=1, int lineType=8) .. c:function:: void ellipse(Mat& img, const RotatedRect& box, const Scalar& color, int thickness=1, int lineType=8)
Draws a simple or thick elliptic arc or an fills ellipse sector. Draws a simple or thick elliptic arc or fills an ellipse sector.
:param img: The image :param img: Image.
:param center: Center of the ellipse :param center: Center of the ellipse.
:param axes: Length of the ellipse axes :param axes: Length of the ellipse axes.
:param angle: The ellipse rotation angle in degrees :param angle: Ellipse rotation angle in degrees.
:param startAngle: Starting angle of the elliptic arc in degrees :param startAngle: Starting angle of the elliptic arc in degrees.
:param endAngle: Ending angle of the elliptic arc in degrees :param endAngle: Ending angle of the elliptic arc in degrees.
:param box: Alternative ellipse representation via a :ref:`RotatedRect` , i.e. the function draws an ellipse inscribed in the rotated rectangle :param box: Alternative ellipse representation via :ref:`RotatedRect` . This means that the function draws an ellipse inscribed in the rotated rectangle.
:param color: Ellipse color :param color: Ellipse color.
:param thickness: Thickness of the ellipse arc outline if positive, otherwise this indicates that a filled ellipse sector is to be drawn :param thickness: Thickness of the ellipse arc outline, if positive. Otherwise, this indicates that a filled ellipse sector is to be drawn.
:param lineType: Type of the ellipse boundary, see :func:`line` description :param lineType: Type of the ellipse boundary. See :func:`line` description.
:param shift: Number of fractional bits in the center coordinates and axes' values :param shift: Number of fractional bits in the center?? coordinates and axes' values.
The functions ``ellipse`` with less parameters draw an ellipse outline, a filled ellipse, an elliptic The functions ``ellipse`` with less parameters draw an ellipse outline, a filled ellipse, an elliptic arc, or a filled ellipse sector.
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 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
:func:`ellipse2Poly` and then render it with :func:`ellipse2Poly` and then render it with
:func:`polylines` or fill it with :func:`polylines` or fill it with
:func:`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 picture below :func:`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 picture below explains the meaning of the parameters.
explains the meaning of the parameters.
Parameters of Elliptic Arc **Figure 1. Parameters of Elliptic Arc**
.. image:: pics/ellipse.png .. image:: pics/ellipse.png
@ -124,17 +125,21 @@ ellipse2Poly
---------------- ----------------
.. c:function:: void ellipse2Poly( Point center, Size axes, int angle, int startAngle, int endAngle, int delta, vector<Point>& pts ) .. c:function:: void ellipse2Poly( Point center, Size axes, int angle, int startAngle, int endAngle, int delta, vector<Point>& pts )
Approximates an elliptic arc with a polyline Approximates an elliptic arc with a polyline.
:param center: Center of the arc :param center: Center of the arc.
:param axes: Half-sizes of the arc. See :func:`ellipse` :param angle: Rotation angle of the ellipse in degrees. See :func:`ellipse` :param startAngle: Starting angle of the elliptic arc in degrees :param axes: Half-sizes of the arc. See :func:`ellipse` for details.
:param angle: Rotation angle of the ellipse in degrees. See :func:`ellipse` for details.
:param startAngle: Starting angle of the elliptic arc in degrees.
:param endAngle: Ending angle of the elliptic arc in degrees :param endAngle: Ending angle of the elliptic arc in degrees.
:param delta: Angle between the subsequent polyline vertices. It defines the approximation accuracy. :param delta: Angle between the subsequent polyline vertices. It defines the approximation accuracy.
:param pts: The output vector of polyline vertices :param pts: Output vector of polyline vertices.
The function ``ellipse2Poly`` computes the vertices of a polyline that approximates the specified elliptic arc. It is used by The function ``ellipse2Poly`` computes the vertices of a polyline that approximates the specified elliptic arc. It is used by
:func:`ellipse` . :func:`ellipse` .
@ -147,22 +152,21 @@ fillConvexPoly
Fills a convex polygon. Fills a convex polygon.
:param img: Image :param img: Image.
:param pts: The polygon vertices :param pts: Polygon vertices.
:param npts: The number of polygon vertices :param npts: Number of polygon vertices.
:param color: Polygon color :param color: Polygon color.
:param lineType: Type of the polygon boundaries, see :func:`line` description :param lineType: Type of the polygon boundaries. See :func:`line` description.
:param shift: The number of fractional bits in the vertex coordinates :param shift: Number of fractional bits in the vertex coordinates.
The function ``fillConvexPoly`` draws a filled convex polygon. The function ``fillConvexPoly`` draws a filled convex polygon.
This function is much faster than the function ``fillPoly`` and can fill not only convex polygons but any monotonic polygon without self-intersections, This function is much faster than the function ``fillPoly`` . It can fill not only convex polygons but any monotonic polygon without self-intersections,
i.e., a polygon whose contour intersects every horizontal line (scan 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).
line) twice at the most (though, its top-most and/or the bottom edge could be horizontal).
.. index:: fillPoly .. index:: fillPoly
@ -170,24 +174,23 @@ fillPoly
------------ ------------
.. c:function:: void fillPoly(Mat& img, const Point** pts, const int* npts, int ncontours, const Scalar& color, int lineType=8, int shift=0, Point offset=Point() ) .. c:function:: void fillPoly(Mat& img, const Point** pts, const int* npts, int ncontours, const Scalar& color, int lineType=8, int shift=0, Point offset=Point() )
Fills the area bounded by one or more polygons Fills the area bounded by one or more polygons.
:param img: Image :param img: Image.
:param pts: Array of polygons, each represented as an array of points :param pts: Array of polygons where each polygon is represented as an array of points.
:param npts: The array of polygon vertex counters :param npts: Array of polygon vertex counters.
:param ncontours: The number of contours that bind the filled region :param ncontours: Number of contours that bind the filled region.
:param color: Polygon color :param color: Polygon color.
:param lineType: Type of the polygon boundaries, see :func:`line` description :param lineType: Type of the polygon boundaries. See :func:`line` description.
:param shift: The number of fractional bits in the vertex coordinates :param shift: Number of fractional bits in the vertex coordinates.
The function ``fillPoly`` fills an area bounded by several The function ``fillPoly`` fills an area bounded by several polygonal contours. The function can fill complex areas, for example,
polygonal contours. The function can fills complex areas, for example,
areas with holes, contours with self-intersections (some of thier parts), and so forth. areas with holes, contours with self-intersections (some of thier parts), and so forth.
.. index:: getTextSize .. index:: getTextSize
@ -198,12 +201,18 @@ getTextSize
Calculates the width and height of a text string. Calculates the width and height of a text string.
:param text: The input text string :param text: Input text string.
:param fontFace: The font to use; see :func:`putText` :param fontScale: The font scale; see :func:`putText` :param thickness: The thickness of lines used to render the text; see :func:`putText` :param baseLine: The output parameter - y-coordinate of the baseline relative to the bottom-most text point :param fontFace: Font to use. See :func:`putText` for details.
:param fontScale: Font scale. See :func:`putText` for details.
:param thickness: Thickness of lines used to render the text. See :func:`putText` for details.
:param baseLine: Output parameter - y-coordinate of the baseline relative to the bottom-most text point.
The function ``getTextSize`` calculates and returns size of the box that contain the specified text. The function ``getTextSize`` calculates and returns the size of a box that contains the specified text.
That is, the following code will render some text, the tight box surrounding it and the baseline: :: That is, the following code renders some text, the tight box surrounding it, and the baseline: ::
// Use "y" to show that the baseLine is about // Use "y" to show that the baseLine is about
string text = "Funny text inside the box"; string text = "Funny text inside the box";
@ -241,17 +250,17 @@ line
-------- --------
.. c:function:: void line(Mat& img, Point pt1, Point pt2, const Scalar& color, int thickness=1, int lineType=8, int shift=0) .. c:function:: void line(Mat& img, Point pt1, Point pt2, const Scalar& color, int thickness=1, int lineType=8, int shift=0)
Draws a line segment connecting two points Draws a line segment connecting two points.
:param img: The image :param img: Image.
:param pt1: First point of the line segment :param pt1: The first point of the line segment.
:param pt2: Second point of the line segment :param pt2: The second point of the line segment.
:param color: Line color :param color: Line color.
:param thickness: Line thickness :param thickness: Line thickness.
:param lineType: Type of the line: :param lineType: Type of the line:
@ -261,14 +270,10 @@ line
* **CV_AA** antialiased line. * **CV_AA** antialiased line.
:param shift: Number of fractional bits in the point coordinates :param shift: Number of fractional bits in the point coordinates.
The function ``line`` draws the line segment between ``pt1`` and ``pt2`` points in the image. The line is 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.
clipped by the image boundaries. For non-antialiased lines Antialiased lines are drawn using Gaussian filtering. To specify the line color, you may use the macro ``CV_RGB(r, g, b)`` .
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, the user may use the macro ``CV_RGB(r, g, b)`` .
.. index:: LineIterator .. index:: LineIterator
@ -304,9 +309,9 @@ Class for iterating pixels on a raster line ::
int minusStep, plusStep; 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 some effect (e.g. with XOR operation). 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 store in ``LineIterator::count`` . :: The number of pixels along the line is stored in ``LineIterator::count`` . ::
// grabs pixels along the line (pt1, pt2) // grabs pixels along the line (pt1, pt2)
// from 8-bit 3-channel image to the buffer // from 8-bit 3-channel image to the buffer
@ -324,21 +329,21 @@ rectangle
Draws a simple, thick, or filled up-right rectangle. Draws a simple, thick, or filled up-right rectangle.
:param img: Image :param img: Image.
:param pt1: One of the rectangle's vertices :param pt1: One of the rectangle's vertices.
:param pt2: Opposite to ``pt1`` rectangle vertex :param pt2: Opposite to ``pt1`` rectangle vertex.
:param color: Rectangle color or brightness (grayscale image) :param color: Rectangle color or brightness (grayscale image).
:param thickness: Thickness of lines that make up the rectangle. Negative values, e.g. ``CV_FILLED`` , mean that the function has to draw a filled rectangle. :param thickness: Thickness of lines that make up the rectangle. Negative values, like ``CV_FILLED`` , mean that the function has to draw a filled rectangle.
:param lineType: Type of the line, see :func:`line` description :param lineType: Type of the line. See :func:`line` description.
:param shift: Number of fractional bits in the point coordinates :param shift: Number of fractional bits in the point coordinates.
The function ``rectangle`` draws a rectangle outline or a filled rectangle, which two opposite corners are ``pt1`` and ``pt2`` . The function ``rectangle`` draws a rectangle outline or a filled rectangle whose two opposite corners are ``pt1`` and ``pt2`` .
.. index:: polylines .. index:: polylines
@ -346,25 +351,25 @@ polylines
------------- -------------
.. c:function:: 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 ) .. c:function:: 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 )
Draws several polygonal curves Draws several polygonal curves.
:param img: The image :param img: Image.
:param pts: Array of polygonal curves :param pts: Array of polygonal curves.
:param npts: Array of polygon vertex counters :param npts: Array of polygon vertex counters.
:param ncontours: The number of curves :param ncontours: Number of curves.
:param 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 :param isClosed: Flag indicating whether the drawn polylines are closed or not. If they are closed, the function draws a line from the last vertex of each curve to its first vertex.
:param color: Polyline color :param color: Polyline color.
:param thickness: Thickness of the polyline edges :param thickness: Thickness of the polyline edges.
:param lineType: Type of the line segments, see :func:`line` description :param lineType: Type of the line segments. See :func:`line` description.
:param shift: The number of fractional bits in the vertex coordinates :param shift: Number of fractional bits in the vertex coordinates.
The function ``polylines`` draws one or more polygonal curves. The function ``polylines`` draws one or more polygonal curves.
@ -374,29 +379,29 @@ putText
----------- -----------
.. c:function:: void putText( Mat& img, const string& text, Point org, int fontFace, double fontScale, Scalar color, int thickness=1, int lineType=8, bool bottomLeftOrigin=false ) .. c:function:: void putText( Mat& img, const string& text, Point org, int fontFace, double fontScale, Scalar color, int thickness=1, int lineType=8, bool bottomLeftOrigin=false )
Draws a text string Draws a text string.
:param img: The image :param img: Image.
:param text: The text string to be drawn :param text: Text string to be drawn.
:param org: The bottom-left corner of the text string in the image :param org: Bottom-left corner of the text string in the image.
:param fontFace: The font type, one of ``FONT_HERSHEY_SIMPLEX`` , ``FONT_HERSHEY_PLAIN`` , ``FONT_HERSHEY_DUPLEX`` , ``FONT_HERSHEY_COMPLEX`` , ``FONT_HERSHEY_TRIPLEX`` , ``FONT_HERSHEY_COMPLEX_SMALL`` , ``FONT_HERSHEY_SCRIPT_SIMPLEX`` or ``FONT_HERSHEY_SCRIPT_COMPLEX`` , :param fontFace: Font type. One of ``FONT_HERSHEY_SIMPLEX`` , ``FONT_HERSHEY_PLAIN`` , ``FONT_HERSHEY_DUPLEX`` , ``FONT_HERSHEY_COMPLEX`` , ``FONT_HERSHEY_TRIPLEX`` , ``FONT_HERSHEY_COMPLEX_SMALL`` , ``FONT_HERSHEY_SCRIPT_SIMPLEX`` , or ``FONT_HERSHEY_SCRIPT_COMPLEX`` ,
where each of the font id's can be combined with ``FONT_HERSHEY_ITALIC`` to get the slanted letters. where each of the font ID's can be combined with ``FONT_HERSHEY_ITALIC`` to get the slanted letters.
:param fontScale: The font scale factor that is multiplied by the font-specific base size :param fontScale: Font scale factor that is multiplied by the font-specific base size.
:param color: The text color :param color: Text color.
:param thickness: Thickness of the lines used to draw the text :param thickness: Thickness of the lines used to draw a text.
:param lineType: The line type; see ``line`` for details :param lineType: Line type. See ``line`` for details.
:param bottomLeftOrigin: When true, the image data origin is at the bottom-left corner, otherwise it's at the top-left corner :param bottomLeftOrigin: When true, the image data origin is at the bottom-left corner. Otherwise, it is at the top-left corner.
The function ``putText`` renders the specified text string in the image. The function ``putText`` renders the specified text string in the image.
Symbols that can not be rendered using the specified font are Symbols that cannot be rendered using the specified font are
replaced by question marks. See replaced by question marks. See
:func:`getTextSize` for a text rendering code example. :func:`getTextSize` for a text rendering code example.