OpenCV reference manual (C++ part only for now) is now produced directly from RST, not from TeX.

modules/core/doc/clustering.rst

@@ -0,0 +1,138 @@
+Clustering
+==========
+
+.. highlight:: cpp
+
+
+
+.. index:: kmeans
+
+
+cv::kmeans
+----------
+
+`id=0.0672046481842 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/kmeans>`__
+
+
+
+
+.. cfunction:: double kmeans( const Mat\& samples, int clusterCount, Mat\& labels,               TermCriteria termcrit, int attempts,               int flags, Mat* centers )
+
+    Finds the centers of clusters and groups the input samples around the clusters.
+
+
+
+
+    
+    :param samples: Floating-point matrix of input samples, one row per sample 
+    
+    
+    :param clusterCount: The number of clusters to split the set by 
+    
+    
+    :param labels: The input/output integer array that will store the cluster indices for every sample 
+    
+    
+    :param termcrit: Specifies maximum number of iterations and/or accuracy (distance the centers can move by between subsequent iterations) 
+    
+    
+    :param attempts: How many times the algorithm is executed using different initial labelings. The algorithm returns the labels that yield the best compactness (see the last function parameter) 
+    
+    
+    :param flags: It can take the following values: 
+         
+            * **KMEANS_RANDOM_CENTERS** Random initial centers are selected in each attempt 
+            
+            * **KMEANS_PP_CENTERS** Use kmeans++ center initialization by Arthur and Vassilvitskii 
+            
+            * **KMEANS_USE_INITIAL_LABELS** During the first (and possibly the only) attempt, the
+                function uses the user-supplied labels instaed of computing them from the initial centers. For the second and further attempts, the function will use the random or semi-random centers (use one of  ``KMEANS_*_CENTERS``  flag to specify the exact method) 
+            
+            
+    
+    
+    :param centers: The output matrix of the cluster centers, one row per each cluster center 
+    
+    
+    
+The function 
+``kmeans``
+implements a k-means algorithm that finds the
+centers of 
+``clusterCount``
+clusters and groups the input samples
+around the clusters. On output, 
+:math:`\texttt{labels}_i`
+contains a 0-based cluster index for
+the sample stored in the 
+:math:`i^{th}`
+row of the 
+``samples``
+matrix.
+
+The function returns the compactness measure, which is computed as
+
+
+.. math::
+
+    \sum _i  \| \texttt{samples} _i -  \texttt{centers} _{ \texttt{labels} _i} \| ^2 
+
+
+after every attempt; the best (minimum) value is chosen and the
+corresponding labels and the compactness value are returned by the function.
+Basically, the user can use only the core of the function, set the number of
+attempts to 1, initialize labels each time using some custom algorithm and pass them with
+(
+``flags``
+=
+``KMEANS_USE_INITIAL_LABELS``
+) flag, and then choose the best (most-compact) clustering.
+
+
+.. index:: partition
+
+
+cv::partition
+-------------
+
+`id=0.0923567235062 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/partition>`__
+
+
+
+
+.. cfunction:: template<typename _Tp, class _EqPredicate> int
+
+
+
+.. cfunction:: partition( const vector<_Tp>\& vec, vector<int>\& labels,               _EqPredicate predicate=_EqPredicate())
+
+    Splits an element set into equivalency classes.
+
+
+
+
+
+    
+    :param vec: The set of elements stored as a vector 
+    
+    
+    :param labels: The output vector of labels; will contain as many elements as  ``vec`` . Each label  ``labels[i]``  is 0-based cluster index of  ``vec[i]`` 
+    
+    
+    :param predicate: The equivalence predicate (i.e. pointer to a boolean function of two arguments or an instance of the class that has the method  ``bool operator()(const _Tp& a, const _Tp& b)`` . The predicate returns true when the elements are certainly if the same class, and false if they may or may not be in the same class 
+    
+    
+    
+The generic function 
+``partition``
+implements an 
+:math:`O(N^2)`
+algorithm for
+splitting a set of 
+:math:`N`
+elements into one or more equivalency classes, as described in 
+http://en.wikipedia.org/wiki/Disjoint-set_data_structure
+. The function
+returns the number of equivalency classes.
+
+

modules/core/doc/core.rst

@@ -0,0 +1,15 @@
+******************
+Core Functionality
+******************
+
+.. toctree::
+    :maxdepth: 2
+
+    basic_structures
+    operations_on_arrays
+    dynamic_structures
+    drawing_functions
+    xml_yaml_persistence
+    clustering
+    utility_and_system_functions_and_macros
+

modules/core/doc/drawing_functions.rst

@@ -0,0 +1,770 @@
+Drawing Functions
+=================
+
+.. highlight:: cpp
+
+
+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 a rgb value (that may be constructed
+with 
+``CV_RGB``
+or the  :ref:`Scalar`  constructor 
+) for color
+images and brightness for grayscale images. For color images the order channel
+is normally 
+*Blue, Green, Red*
+, this is what 
+:func:`imshow`
+, 
+:func:`imread`
+and 
+:func:`imwrite`
+expect
+, so if you form a color using 
+:ref:`Scalar`
+constructor, it should look like:
+
+
+.. math::
+
+    \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 
+: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 
+:math:`\texttt{Point}(x,y)\rightarrow\texttt{Point2f}(x*2^{-shift},y*2^{-shift})`
+. This feature is especially effective wehn 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.
+
+
+.. index:: circle
+
+
+cv::circle
+----------
+
+`id=0.143685141364 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/circle>`__
+
+
+
+
+.. cfunction:: void circle(Mat\& img, Point center, int radius,            const Scalar\& color, int thickness=1,            int lineType=8, int shift=0)
+
+    Draws a circle
+
+
+
+
+
+    
+    :param img: Image where the circle is drawn 
+    
+    
+    :param center: Center of the circle 
+    
+    
+    :param radius: Radius of the circle 
+    
+    
+    :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 lineType: Type of the circle boundary, see  :func:`line`  description 
+    
+    
+    :param shift: Number of fractional bits in the center coordinates and radius value 
+    
+    
+    
+The function 
+``circle``
+draws a simple or filled circle with a
+given center and radius.
+
+
+.. index:: clipLine
+
+
+cv::clipLine
+------------
+
+`id=0.715949286846 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/clipLine>`__
+
+
+
+
+.. cfunction:: bool clipLine(Size imgSize, Point\& pt1, Point\& pt2)
+
+
+
+.. cfunction:: bool clipLine(Rect imgRect, Point\& pt1, Point\& pt2)
+
+    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 pt1: The first line point 
+    
+    
+    :param pt2: The second line point 
+    
+    
+    
+The functions 
+``clipLine``
+calculate a part of the line
+segment which is entirely within the specified rectangle.
+They return 
+``false``
+if the line segment is completely outside the rectangle and 
+``true``
+otherwise.
+
+
+
+.. index:: ellipse
+
+
+cv::ellipse
+-----------
+
+`id=0.0631091216884 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/ellipse>`__
+
+
+
+
+.. cfunction:: 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)
+
+
+
+.. cfunction:: 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.
+
+
+
+
+
+    
+    :param img: The image 
+    
+    
+    :param center: Center of the ellipse 
+    
+    
+    :param axes: Length of the ellipse axes 
+    
+    
+    :param angle: The ellipse rotation angle in degrees 
+    
+    
+    :param startAngle: Starting 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 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 lineType: Type of the ellipse boundary, see  :func:`line`  description 
+    
+    
+    :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
+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 
+:func:`ellipse2Poly`
+and then render 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
+explains the meaning of the parameters.
+
+Parameters of Elliptic Arc
+
+
+
+.. image:: ../../pics/ellipse.png
+
+
+
+
+.. index:: ellipse2Poly
+
+
+cv::ellipse2Poly
+----------------
+
+`id=0.644340648167 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/ellipse2Poly>`__
+
+
+
+
+.. cfunction:: void ellipse2Poly( Point center, Size axes, int angle,                   int startAngle, int endAngle, int delta,                   vector<Point>\& pts )
+
+    Approximates an elliptic arc with a polyline
+
+
+
+
+
+    
+    :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 endAngle: Ending angle of the elliptic arc in degrees 
+    
+    
+    :param delta: Angle between the subsequent polyline vertices. It defines the approximation accuracy. 
+    
+    
+    :param pts: The output vector of polyline vertices 
+    
+    
+    
+The function 
+``ellipse2Poly``
+computes the vertices of a polyline that approximates the specified elliptic arc. It is used by 
+:func:`ellipse`
+.
+
+
+.. index:: fillConvexPoly
+
+
+cv::fillConvexPoly
+------------------
+
+`id=0.345453533071 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/fillConvexPoly>`__
+
+
+
+
+.. cfunction:: void fillConvexPoly(Mat\& img, const Point* pts, int npts,                    const Scalar\& color, int lineType=8,                    int shift=0)
+
+    Fills a convex polygon.
+
+
+
+
+
+    
+    :param img: Image 
+    
+    
+    :param pts: The polygon vertices 
+    
+    
+    :param npts: The number of polygon vertices 
+    
+    
+    :param color: Polygon color 
+    
+    
+    :param lineType: Type of the polygon boundaries, see  :func:`line`  description 
+    
+    
+    :param shift: The number of fractional bits in the vertex coordinates 
+    
+    
+    
+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,
+i.e., 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).
+
+
+.. index:: fillPoly
+
+
+cv::fillPoly
+------------
+
+`id=0.00272984452496 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/fillPoly>`__
+
+
+
+
+.. cfunction:: 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
+
+
+
+
+
+    
+    :param img: Image 
+    
+    
+    :param pts: Array of polygons, each represented as an array of points 
+    
+    
+    :param npts: The array of polygon vertex counters 
+    
+    
+    :param ncontours: The number of contours that bind the filled region 
+    
+    
+    :param color: Polygon color 
+    
+    
+    :param lineType: Type of the polygon boundaries, see  :func:`line`  description 
+    
+    
+    :param shift: The number of fractional bits in the vertex coordinates 
+    
+    
+    
+The function 
+``fillPoly``
+fills an area bounded by several
+polygonal contours. The function can fills complex areas, for example,
+areas with holes, contours with self-intersections (some of thier parts), and so forth.
+
+
+.. index:: getTextSize
+
+
+cv::getTextSize
+---------------
+
+`id=0.364618843078 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/getTextSize>`__
+
+
+
+
+.. cfunction:: Size getTextSize(const string\& text, int fontFace,                 double fontScale, int thickness,                 int* baseLine)
+
+    Calculates the width and height of a text string.
+
+
+
+
+
+    
+    :param text: The 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 
+    
+    
+    
+The function 
+``getTextSize``
+calculates and returns size of the box that contain the specified text.
+That is, the following code will render some text, the tight box surrounding it and the baseline:
+
+
+
+
+::
+
+
+    
+    // Use "y" to show that the baseLine is about
+    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);
+    
+
+..
+
+
+.. index:: line
+
+
+cv::line
+--------
+
+`id=0.645160739861 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/line>`__
+
+
+
+
+.. cfunction:: 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
+
+
+
+
+
+    
+    :param img: The image 
+    
+    
+    :param pt1: First point of the line segment 
+    
+    
+    :param pt2: Second point of the line segment 
+    
+    
+    :param color: Line color 
+    
+    
+    :param thickness: Line thickness 
+    
+    
+    :param lineType: Type of the line:
+           
+        
+                
+            * **8** (or omitted) 8-connected line. 
+            
+               
+            * **4** 4-connected line. 
+            
+               
+            * **CV_AA** antialiased line. 
+            
+               
+            
+    
+    
+    :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
+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, the user may use the macro
+``CV_RGB(r, g, b)``
+.
+
+
+
+.. index:: LineIterator
+
+.. _LineIterator:
+
+LineIterator
+------------
+
+`id=0.913176469223 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/LineIterator>`__
+
+.. ctype:: 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);
+    
+        // 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 some effect (e.g. with XOR operation).
+
+The number of pixels along the line is store in 
+``LineIterator::count``
+.
+
+
+
+
+::
+
+
+    
+    // grabs pixels along the line (pt1, pt2)
+    // from 8-bit 3-channel image to the buffer
+    LineIterator it(img, pt1, pt2, 8);
+    vector<Vec3b> buf(it.count);
+    
+    for(int i = 0; i < it.count; i++, ++it)
+        buf[i] = *(const Vec3b)*it;
+    
+
+..
+
+
+.. index:: rectangle
+
+
+cv::rectangle
+-------------
+
+`id=0.494030339931 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/rectangle>`__
+
+
+
+
+.. cfunction:: void rectangle(Mat\& img, Point pt1, Point pt2,               const Scalar\& color, int thickness=1,               int lineType=8, int shift=0)
+
+    Draws a simple, thick, or filled up-right rectangle.
+
+
+
+
+
+    
+    :param img: Image 
+    
+    
+    :param pt1: One of the rectangle's vertices 
+    
+    
+    :param pt2: Opposite to  ``pt1``  rectangle vertex 
+    
+    
+    :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 lineType: Type of the line, see  :func:`line`  description 
+    
+    
+    :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``
+.
+               
+
+
+.. index:: polylines
+
+
+cv::polylines
+-------------
+
+`id=0.550422277453 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/polylines>`__
+
+
+
+
+.. cfunction:: 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
+
+
+
+
+
+    
+    :param img: The image 
+    
+    
+    :param pts: Array of polygonal curves 
+    
+    
+    :param npts: Array of polygon vertex counters 
+    
+    
+    :param ncontours: The 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 color: Polyline color 
+    
+    
+    :param thickness: Thickness of the polyline edges 
+    
+    
+    :param lineType: Type of the line segments, see  :func:`line`  description 
+    
+    
+    :param shift: The number of fractional bits in the vertex coordinates 
+    
+    
+    
+The function 
+``polylines``
+draws one or more polygonal curves.
+
+
+.. index:: putText
+
+
+cv::putText
+-----------
+
+`id=0.164290316532 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/putText>`__
+
+
+
+
+.. cfunction:: 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
+
+
+
+
+
+    
+    :param img: The image 
+    
+    
+    :param text: The text string to be drawn 
+    
+    
+    :param org: The 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`` ,
+           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 color: The text color 
+    
+    
+    :param thickness: Thickness of the lines used to draw the text 
+    
+    
+    :param lineType: The 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 
+    
+    
+    
+The function 
+``putText``
+renders the specified text string in the image.
+Symbols that can not be rendered using the specified font are
+replaced by question marks. See 
+:func:`getTextSize`
+for a text rendering code example.
+

modules/core/doc/dynamic_structures.rst

@@ -0,0 +1,6 @@
+Dynamic Structures
+==================
+
+.. highlight:: cpp
+
+

modules/core/doc/intro.rst

@@ -0,0 +1,248 @@
+************
+Introduction
+************
+
+.. highlight:: cpp
+
+OpenCV (Open Source Computer Vision Library: http://opencv.willowgarage.com/wiki/) is open-source BSD-licensed library that includes several hundreds computer vision algorithms. It is very popular in the Computer Vision community. Some people call it “de-facto standard” API. The document aims to specify the stable parts of the library, as well as some abstract interfaces for high-level interfaces, with the final goal to make it an official standard.
+
+API specifications in the document use the standard C++ (http://www.open-std.org/jtc1/sc22/wg21/) and the standard C++ library.
+
+The current OpenCV implementation has a modular structure (i.e. the binary package includes several shared or static libraries), where we have:
+
+ * **core** - the compact module defining basic data structures, including the dense multi-dimensional array ``Mat``, and basic functions, used by all other modules.
+ * **imgproc** - image processing module that includes linear and non-linear image filtering, geometrical image transformations (resize, affine and perspective warping, generic table-based remap), color space conversion, histograms etc.
+ * **video** - video analysis module that includes motion estimation, background subtraction and object tracking algorithms.
+ * **calib3d** - basic multiple-view geometry algorithms, single and stereo camera calibration, object pose estimation, stereo correspondence algorithms, elements of 3d reconstruction.
+ * **features2d** - salient feature detectors, descriptors and the descriptor matchers.
+ * **objdetect** - detection of objects, instances of the predefined classes (e.g faces, eyes, mugs, people, cars etc.)
+ * **highgui** - easy-to-use interface to video capturing, image and video codecs APIs, as well as simple UI capabilities.
+ * **gpu** - GPU-accelerated algorithms from different OpenCV modules.
+ * ... some other helper modules, such as FLANN and Google test wrappers, Python bindings etc.
+
+Although the alternative implementations of the proposed standard may be structured differently, the proposed standard draft is organized by the functionality groups that reflect the decomposition of the library by modules.
+
+Below are the other main concepts of the OpenCV API, implied everywhere in the document.
+
+The API Concepts
+================
+
+*"cv"* namespace
+----------------
+
+All the OpenCV classes and functions are placed into *"cv"* namespace. Therefore, to access this functionality from your code, use 
+``cv::`` specifier or ``using namespace cv;`` directive:
+
+.. code-block:: c
+    
+    #include "opencv2/core/core.hpp"
+    ...
+    cv::Mat H = cv::findHomography(points1, points2, CV_RANSAC, 5);
+    ...
+
+or
+
+::
+    
+    #include "opencv2/core/core.hpp"
+    using namespace cv;
+    ...
+    Mat H = findHomography(points1, points2, CV_RANSAC, 5 );
+    ...
+
+It is probable that some of the current or future OpenCV external names conflict with STL
+or other libraries, in this case use explicit namespace specifiers to resolve the name conflicts:
+
+::
+    
+    Mat a(100, 100, CV_32F);
+    randu(a, Scalar::all(1), Scalar::all(std::rand()));
+    cv::log(a, a);
+    a /= std::log(2.);
+
+
+Automatic Memory Management
+---------------------------
+
+OpenCV handles all the memory automatically.
+
+First of all, ``std::vector``, ``Mat`` and other data structures used by the functions and methods have destructors that deallocate the underlying memory buffers when needed.
+
+Secondly, in the case of ``Mat`` this *when needed* means that the destructors do not always deallocate the buffers, they take into account possible data sharing. That is, destructor decrements the reference counter, associated with the matrix data buffer, and the buffer is deallocated if and only if the reference counter reaches zero, that is, when no other structures refer to the same buffer. Similarly, when ``Mat`` instance is copied, not actual data is really copied; instead, the associated with it reference counter is incremented to memorize that there is another owner of the same data. There is also ``Mat::clone`` method that creates a full copy of the matrix data. Here is the example
+
+::
+    
+    // create a big 8Mb matrix
+    Mat A(1000, 1000, CV_64F);
+    
+    // create another header for the same matrix;
+    // this is instant operation, regardless of the matrix size.
+    Mat B = A;
+    // create another header for the 3-rd row of A; no data is copied either
+    Mat C = B.row(3);
+    // now create a separate copy of the matrix
+    Mat D = B.clone();
+    // copy the 5-th row of B to C, that is, copy the 5-th row of A 
+    // to the 3-rd row of A.
+    B.row(5).copyTo(C);
+    // now let A and D share the data; after that the modified version
+    // of A is still referenced by B and C.
+    A = D;
+    // now make B an empty matrix (which references no memory buffers),
+    // but the modified version of A will still be referenced by C,
+    // despite that C is just a single row of the original A
+    B.release(); 
+                 
+    // finally, make a full copy of C. In result, the big modified
+    // matrix will be deallocated, since it's not referenced by anyone
+    C = C.clone();
+
+Therefore, ``Mat`` and other basic structures use is simple. But what about high-level classes or even user data types that have been created without automatic memory management in mind? For them OpenCV offers ``Ptr<>`` template class, which is similar to the ``std::shared_ptr`` from C++ TR1. That is, instead of using plain pointers::
+
+   T* ptr = new T(...);
+
+one can use::
+
+   Ptr<T> ptr = new T(...);
+
+That is, ``Ptr<T> ptr`` incapsulates a pointer to ``T`` instance and a reference counter associated with the pointer. See ``Ptr`` description for details.
+
+
+.. todo::
+
+  Should we replace Ptr<> with the semi-standard shared_ptr<>?
+
+Automatic Allocation of the Output Data
+---------------------------------------
+
+OpenCV does not only deallocate the memory automatically, it can also allocate memory for the output function parameters automatically most of the time. That is, if a function has one or more input arrays (``cv::Mat`` instances) and some output arrays, the output arrays automatically allocated or reallocated. The size and type of the output arrays are determined from the input arrays' size and type. If needed, the functions take extra parameters that help to figure out the output array properties.
+
+Here is the example: ::
+    
+    #include "cv.h"
+    #include "highgui.h"
+    
+    using namespace cv;
+    
+    int main(int, char**)
+    {
+        VideoCapture cap(0);
+        if(!cap.isOpened()) return -1;
+    
+        Mat frame, edges;
+        namedWindow("edges",1);
+        for(;;)
+        {
+            cap >> frame;
+            cvtColor(frame, edges, CV_BGR2GRAY);
+            GaussianBlur(edges, edges, Size(7,7), 1.5, 1.5);
+            Canny(edges, edges, 0, 30, 3);
+            imshow("edges", edges);
+            if(waitKey(30) >= 0) break;
+        }
+        return 0;
+    }
+..
+
+The array ``frame`` is automatically allocated by ``>>`` operator, since the video frame resolution and bit-depth is known to the video capturing module. The array ``edges`` is automatically allocated by ``cvtColor`` function. It will have the same size and the bit-depth as the input array, and the number of channels will be 1, because we passed the color conversion code ``CV_BGR2GRAY`` (that means color to grayscale conversion). Note that ``frame`` and ``edges`` will be allocated only once during the first execution of the loop body, since all the next video frames will have the same resolution (unless user somehow changes the video resolution, in this case the arrays will be automatically reallocated).
+
+The key component of this technology is the method ``Mat::create``. It takes the desired array size and type. If the array already has the specified size and type, the method does nothing. Otherwise, it releases the previously allocated data, if any (this part involves decrementing the reference counter and comparing it with zero), and then allocates a new buffer of the required size. Most functions call this ``Mat::create`` method for each output array and so the automatic output data allocation is implemented.
+
+Some notable exceptions from this scheme are ``cv::mixChannels``, ``cv::RNG::fill`` and a few others functions and methods. They are not able to allocate the output array, so the user has to do that in advance.
+
+
+Saturation Arithmetics
+----------------------
+
+As computer vision library, OpenCV deals a lot with image pixels that are often encoded in a compact 8- or 16-bit per channel form and thus have a limited value range. Furthermore, certain operations on images, like color space conversions, brightness/contrast adjustments, sharpening, complex interpolation (bi-cubic, Lanczos) can produce values out of the available range. If we just store the lowest 8 (16) bit of the result, that will result in some visual artifacts and may affect the further image analysis. To solve this problem, we use so-called *saturation* arithmetics, e.g. to store ``r``, a result of some operation, to 8-bit image, we find the nearest value within 0..255 range: 
+
+.. math::
+
+    I(x,y)= \min ( \max (\textrm{round}(r), 0), 255) 
+
+The similar rules are applied to 8-bit signed and 16-bit signed and unsigned types. This semantics is used everywhere in the library. In C++ code it is done using ``saturate_cast<>`` functions that resembler the standard C++ cast operations. Here is the implementation of the above formula::
+
+    I.at<uchar>(y, x) = saturate_cast<uchar>(r);
+
+where ``cv::uchar`` is OpenCV's 8-bit unsigned integer type. In optimized SIMD code we use specialized instructions, like SSE2' ``paddusb``, ``packuswb`` etc. to achieve exactly the same behavior as in C++ code.
+
+
+Fixed Pixel Types. Limited Use of Templates
+-------------------------------------------
+
+Templates is a great feature of C++ that enables implementation of very powerful, efficient and yet safe data structures and algorithms. However, the extensive use of templates may dramatically increase compile time and code size. Besides, it is difficult to separate interface and implementation when templates are used exclusively, which is fine for basic algorithms, but not good for computer vision libraries, where a single algorithm may span a thousands lines of code. Because of this, and also to simplify development of bindings for other languages, like Python, Java, Matlab, that do not have templates at all or have limited template capabilities, we prefer polymorphism and runtime dispatching over templates. In the places where runtime dispatching would be too slow (like pixel access operators), impossible (generic Ptr<> implementation) or just very inconvenient (saturate_cast<>()) we introduce small template classes, methods and functions. Everywhere else we prefer not to use templates.
+
+Because of this, there is a limited fixed set of primitive data types that the library can operate on. That is, an array elements should have one of the following types:
+
+  * 8-bit unsigned integer (uchar)
+  * 8-bit signed integer (schar)
+  * 16-bit unsigned integer (ushort)
+  * 16-bit signed integer (short)
+  * 32-bit signed integer (int)
+  * 32-bit floating-point number (float)
+  * 64-bit floating-point number (double)
+  * a tuple of several elements, where all elements have the same type (one of the above). Array, which elements are such tuples, are called multi-channel arrays, as opposite to the single-channel arrays, which elements are scalar values. The maximum possible number of channels is defined by ``CV_CN_MAX`` constant (which is not smaller than 32).
+  
+.. todo::
+  Need we extend the above list? Shouldn't we throw away 8-bit signed (schar)?
+  
+For these basic types there is enumeration::
+
+  enum { CV_8U=0, CV_8S=1, CV_16U=2, CV_16S=3, CV_32S=4, CV_32F=5, CV_64F=6 };
+  
+Multi-channel (``n``-channel) types can be specified using ``CV_8UC1`` ... ``CV_64FC4`` constants (for number of channels from 1 to 4), or using ``CV_8UC(n)`` ... ``CV_64FC(n)`` or ``CV_MAKETYPE(CV_8U, n)`` ... ``CV_MAKETYPE(CV_64F, n)`` macros when the number of channels is more than 4 or unknown at compile time.
+
+.. note::
+  ``CV_32FC1 == CV_32F``, ``CV_32FC2 == CV_32FC(2) == CV_MAKETYPE(CV_32F, 2)`` and ``CV_MAKETYPE(depth, n) == ((x&7)<<3) + (n-1)``, that is, the type constant is formed from the ``depth``, taking the lowest 3 bits, and the number of channels minus 1, taking the next ``log2(CV_CN_MAX)`` bits.
+
+Here are some examples::
+
+   Mat mtx(3, 3, CV_32F); // make 3x3 floating-point matrix
+   Mat cmtx(10, 1, CV_64FC2); // make 10x1 2-channel floating-point
+                              // matrix (i.e. 10-element complex vector)
+   Mat img(Size(1920, 1080), CV_8UC3); // make 3-channel (color) image
+                                       // of 1920 columns and 1080 rows.
+   Mat grayscale(image.size(), CV_MAKETYPE(image.depth(), 1)); // make 1-channel image of
+                                                               // the same size and same
+                                                               // channel type as img
+
+Arrays, which elements are more complex, can not be constructed or processed using OpenCV. Furthermore, each function or method can handle only a subset of all possible array types. Usually, the more complex is the algorithm, the smaller is the supported subset of formats. Here are some typical examples of such limitations:
+
+  * The face detection algorithm only works with 8-bit grayscale or color images.
+  * Linear algebra functions and most of the machine learning algorithms work with floating-point arrays only.
+  * Basic functions, such as ``cv::add``, support all types, except for ``CV_8SC(n)``.
+  * Color space conversion functions support 8-bit unsigned, 16-bit unsigned and 32-bit floating-point types.
+
+The subset of supported types for each functions has been defined from practical needs. All this information about supported types can be put together into a special table. In different implementations of the standard the tables may look differently, for example, on embedded platforms double-precision floating-point type (``CV_64F``) may be unavailable.
+
+.. todo::
+  Should we include such a table into the standard?
+  Should we specify minimum "must-have" set of supported formats for each functions?
+
+
+Error handling
+--------------
+
+OpenCV uses exceptions to signal about the critical errors. When the input data has correct format and within the specified value range, but the algorithm can not succeed for some reason (e.g. the optimization algorithm did not converge), it returns a special error code (typically, just a boolean variable).
+
+The exceptions can be instances of ``cv::Exception`` class or its derivatives. In its turn, ``cv::Exception`` is a derivative of std::exception, so it can be gracefully handled in the code using other standard C++ library components.
+
+The exception is typically thrown using ``CV_Error(errcode, description)`` macro, or its printf-like ``CV_Error_(errcode, printf-spec, (printf-args))`` variant, or using ``CV_Assert(condition)`` macro that checks the condition and throws exception when it is not satisfied. For performance-critical code there is ``CV_DbgAssert(condition)`` that is only retained in Debug configuration. Thanks to the automatic memory management, all the intermediate buffers are automatically deallocated in the case of sudden error; user only needs to put a try statement to catch the exceptions, if needed:
+
+::
+  
+    try
+    {
+        ... // call OpenCV
+    }
+    catch( cv::Exception& e )
+    {
+        const char* err_msg = e.what();
+        std::cout << "exception caught: " << err_msg << std::endl;
+    }
+
+
+Multi-threading and reenterability
+----------------------------------
+
+The current OpenCV implementation is fully reenterable, and so should be any alternative implementation targeted for multi-threaded environments. That is, the same function, the same *constant* method of a class instance, or the same *non-constant* method of different class instances can be called from different threads. Also, the same ``cv::Mat`` can be used in different threads, because the reference-counting operations use the architecture-specific atomic instructions.

modules/core/doc/utility_and_system_functions_and_macros.rst

@@ -0,0 +1,568 @@
+Utility and System Functions and Macros
+=======================================
+
+.. highlight:: cpp
+
+
+
+.. index:: alignPtr
+
+
+cv::alignPtr
+------------
+
+`id=0.732441674276 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/alignPtr>`__
+
+
+
+
+.. cfunction:: template<typename _Tp> _Tp* alignPtr(_Tp* ptr, int n=sizeof(_Tp))
+
+    Aligns pointer to the specified number of bytes
+
+
+
+
+
+    
+    :param ptr: The aligned pointer 
+    
+    
+    :param n: The alignment size; must be a power of two 
+    
+    
+    
+The function returns the aligned pointer of the same type as the input pointer:
+
+
+.. math::
+
+    \texttt{(\_Tp*)(((size\_t)ptr + n-1) \& -n)} 
+
+
+
+.. index:: alignSize
+
+
+cv::alignSize
+-------------
+
+`id=0.0293178300141 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/alignSize>`__
+
+
+
+
+.. cfunction:: size_t alignSize(size_t sz, int n)
+
+    Aligns a buffer size to the specified number of bytes
+
+
+
+
+
+    
+    :param sz: The buffer size to align 
+    
+    
+    :param n: The alignment size; must be a power of two 
+    
+    
+    
+The function returns the minimum number that is greater or equal to 
+``sz``
+and is divisble by 
+``n``
+:
+
+
+.. math::
+
+    \texttt{(sz + n-1) \& -n} 
+
+
+
+.. index:: allocate
+
+
+cv::allocate
+------------
+
+`id=0.672857293821 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/allocate>`__
+
+
+
+
+.. cfunction:: template<typename _Tp> _Tp* allocate(size_t n)
+
+    Allocates an array of elements
+
+
+
+
+
+    
+    :param n: The number of elements to allocate 
+    
+    
+    
+The generic function 
+``allocate``
+allocates buffer for the specified number of elements. For each element the default constructor is called.
+
+
+
+.. index:: deallocate
+
+
+cv::deallocate
+--------------
+
+`id=0.907199792708 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/deallocate>`__
+
+
+
+
+.. cfunction:: template<typename _Tp> void deallocate(_Tp* ptr, size_t n)
+
+    Allocates an array of elements
+
+
+
+
+
+    
+    :param ptr: Pointer to the deallocated buffer 
+    
+    
+    :param n: The number of elements in the buffer 
+    
+    
+    
+The generic function 
+``deallocate``
+deallocates the buffer allocated with 
+:func:`allocate`
+. The number of elements must match the number passed to 
+:func:`allocate`
+.
+
+
+.. index:: CV_Assert
+
+.. _CV_Assert:
+
+CV_Assert
+---------
+
+`id=0.132247699783 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/CV_Assert>`__
+
+
+
+
+.. cfunction:: CV_Assert(expr)
+
+    Checks a condition at runtime.
+
+
+
+
+
+
+::
+
+
+    
+    #define CV_Assert( expr ) ...
+    #define CV_DbgAssert(expr) ...
+    
+
+..
+
+
+
+    
+    :param expr: The checked expression 
+    
+    
+    
+The macros 
+``CV_Assert``
+and 
+``CV_DbgAssert``
+evaluate the specified expression and if it is 0, the macros raise an error (see 
+:func:`error`
+). The macro 
+``CV_Assert``
+checks the condition in both Debug and Release configurations, while 
+``CV_DbgAssert``
+is only retained in the Debug configuration.
+
+
+.. index:: error
+
+
+cv::error
+---------
+
+`id=0.274198769781 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/error>`__
+
+
+
+
+.. cfunction:: void error( const Exception\& exc )
+
+
+
+.. cfunction:: \#define CV_Error( code, msg ) <...>
+
+
+
+.. cfunction:: \#define CV_Error_( code, args ) <...>
+
+    Signals an error and raises the exception
+
+
+
+
+
+    
+    :param exc: The exception to throw 
+    
+    
+    :param code: The error code, normally, a negative value. The list of pre-defined error codes can be found in  ``cxerror.h`` 
+    
+    
+    :param msg: Text of the error message 
+    
+    
+    :param args: printf-like formatted error message in parantheses 
+    
+    
+    
+The function and the helper macros 
+``CV_Error``
+and 
+``CV_Error_``
+call the error handler. Currently, the error handler prints the error code (
+``exc.code``
+), the context (
+``exc.file``
+, 
+``exc.line``
+and the error message 
+``exc.err``
+to the standard error stream 
+``stderr``
+. In Debug configuration it then provokes memory access violation, so that the execution stack and all the parameters can be analyzed in debugger. In Release configuration the exception 
+``exc``
+is thrown.
+
+The macro 
+``CV_Error_``
+can be used to construct the error message on-fly to include some dynamic information, for example:
+
+
+
+
+::
+
+
+    
+    // note the extra parentheses around the formatted text message
+    CV_Error_(CV_StsOutOfRange,
+        ("the matrix element (
+        i, j, mtx.at<float>(i,j)))
+    
+
+..
+
+
+.. index:: Exception
+
+.. _Exception:
+
+Exception
+---------
+
+`id=0.792198322059 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/Exception>`__
+
+.. ctype:: Exception
+
+
+
+The exception class passed to error
+
+
+
+
+::
+
+
+    
+    class  Exception
+    {
+    public:
+        // various constructors and the copy operation
+        Exception() { code = 0; line = 0; }
+        Exception(int _code, const string& _err,
+                  const string& _func, const string& _file, int _line);
+        Exception(const Exception& exc);
+        Exception& operator = (const Exception& exc);
+    
+        // the error code
+        int code;
+        // the error text message
+        string err;
+        // function name where the error happened
+        string func;
+        // the source file name where the error happened
+        string file;
+        // the source file line where the error happened
+        int line;
+    };
+    
+
+..
+
+The class 
+``Exception``
+encapsulates all or almost all the necessary information about the error happened in the program. The exception is usually constructed and thrown implicitly, via 
+``CV_Error``
+and 
+``CV_Error_``
+macros, see 
+:func:`error`
+.
+
+
+
+.. index:: fastMalloc
+
+
+cv::fastMalloc
+--------------
+
+`id=0.913748026438 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/fastMalloc>`__
+
+
+
+
+.. cfunction:: void* fastMalloc(size_t size)
+
+    Allocates aligned memory buffer
+
+
+
+
+
+    
+    :param size: The allocated buffer size 
+    
+    
+    
+The function allocates buffer of the specified size and returns it. When the buffer size is 16 bytes or more, the returned buffer is aligned on 16 bytes.
+
+
+.. index:: fastFree
+
+
+cv::fastFree
+------------
+
+`id=0.486348253472 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/fastFree>`__
+
+
+
+
+.. cfunction:: void fastFree(void* ptr)
+
+    Deallocates memory buffer
+
+
+
+
+
+    
+    :param ptr: Pointer to the allocated buffer 
+    
+    
+    
+The function deallocates the buffer, allocated with 
+:func:`fastMalloc`
+.
+If NULL pointer is passed, the function does nothing.
+
+
+.. index:: format
+
+
+cv::format
+----------
+
+`id=0.359045522761 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/format>`__
+
+
+
+
+.. cfunction:: string format( const char* fmt, ... )
+
+    Returns a text string formatted using printf-like expression
+
+
+
+
+
+    
+    :param fmt: The printf-compatible formatting specifiers 
+    
+    
+    
+The function acts like 
+``sprintf``
+, but forms and returns STL string. It can be used for form the error message in 
+:func:`Exception`
+constructor.
+
+
+.. index:: getNumThreads
+
+
+cv::getNumThreads
+-----------------
+
+`id=0.665594834701 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/getNumThreads>`__
+
+
+
+
+.. cfunction:: int getNumThreads()
+
+    Returns the number of threads used by OpenCV
+
+
+
+The function returns the number of threads that is used by OpenCV.
+
+See also: 
+:func:`setNumThreads`
+, 
+:func:`getThreadNum`
+.
+
+
+
+.. index:: getThreadNum
+
+
+cv::getThreadNum
+----------------
+
+`id=0.835208450402 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/getThreadNum>`__
+
+
+
+
+.. cfunction:: int getThreadNum()
+
+    Returns index of the currently executed thread
+
+
+
+The function returns 0-based index of the currently executed thread. The function is only valid inside a parallel OpenMP region. When OpenCV is built without OpenMP support, the function always returns 0.
+
+See also: 
+:func:`setNumThreads`
+, 
+:func:`getNumThreads`
+.
+
+
+.. index:: getTickCount
+
+
+cv::getTickCount
+----------------
+
+`id=0.682548115061 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/getTickCount>`__
+
+
+
+
+.. cfunction:: int64 getTickCount()
+
+    Returns the number of ticks
+
+
+
+The function returns the number of ticks since the certain event (e.g. when the machine was turned on).
+It can be used to initialize 
+:func:`RNG`
+or to measure a function execution time by reading the tick count before and after the function call. See also the tick frequency.
+
+
+.. index:: getTickFrequency
+
+
+cv::getTickFrequency
+--------------------
+
+`id=0.85013360741 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/getTickFrequency>`__
+
+
+
+
+.. cfunction:: double getTickFrequency()
+
+    Returns the number of ticks per second
+
+
+
+The function returns the number of ticks per second.
+That is, the following code computes the execution time in seconds.
+
+
+
+::
+
+
+    
+    double t = (double)getTickCount();
+    // do something ...
+    t = ((double)getTickCount() - t)/getTickFrequency();
+    
+
+..
+
+
+.. index:: setNumThreads
+
+
+cv::setNumThreads
+-----------------
+
+`id=0.215563071229 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/setNumThreads>`__
+
+
+
+
+.. cfunction:: void setNumThreads(int nthreads)
+
+    Sets the number of threads used by OpenCV
+
+
+
+
+
+    
+    :param nthreads: The number of threads used by OpenCV 
+    
+    
+    
+The function sets the number of threads used by OpenCV in parallel OpenMP regions. If 
+``nthreads=0``
+, the function will use the default number of threads, which is usually equal to the number of the processing cores.
+
+See also: 
+:func:`getNumThreads`
+, 
+:func:`getThreadNum`

modules/core/doc/xml_yaml_persistence.rst

@@ -0,0 +1,203 @@
+XML/YAML Persistence
+====================
+
+.. highlight:: cpp
+
+
+
+.. index:: FileStorage
+
+.. _FileStorage:
+
+FileStorage
+-----------
+
+`id=0.36488878292 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/FileStorage>`__
+
+.. ctype:: FileStorage
+
+
+
+The XML/YAML file storage class
+
+
+
+
+::
+
+
+    
+    class FileStorage
+    {
+    public:
+        enum { READ=0, WRITE=1, APPEND=2 };
+        enum { UNDEFINED=0, VALUE_EXPECTED=1, NAME_EXPECTED=2, INSIDE_MAP=4 };
+        // the default constructor
+        FileStorage();
+        // the constructor that opens the file for reading
+        // (flags=FileStorage::READ) or writing (flags=FileStorage::WRITE)
+        FileStorage(const string& filename, int flags);
+        // wraps the already opened CvFileStorage*
+        FileStorage(CvFileStorage* fs);
+        // the destructor; closes the file if needed
+        virtual ~FileStorage();
+    
+        // opens the specified file for reading (flags=FileStorage::READ)
+        // or writing (flags=FileStorage::WRITE)
+        virtual bool open(const string& filename, int flags);
+        // checks if the storage is opened
+        virtual bool isOpened() const;
+        // closes the file
+        virtual void release();
+    
+        // returns the first top-level node
+        FileNode getFirstTopLevelNode() const;
+        // returns the root file node
+        // (it's the parent of the first top-level node)
+        FileNode root(int streamidx=0) const;
+        // returns the top-level node by name
+        FileNode operator[](const string& nodename) const;
+        FileNode operator[](const char* nodename) const;
+    
+        // returns the underlying CvFileStorage*
+        CvFileStorage* operator *() { return fs; }
+        const CvFileStorage* operator *() const { return fs; }
+        
+        // writes the certain number of elements of the specified format
+        // (see DataType) without any headers
+        void writeRaw( const string& fmt, const uchar* vec, size_t len );
+        
+        // writes an old-style object (CvMat, CvMatND etc.)
+        void writeObj( const string& name, const void* obj );
+    
+        // returns the default object name from the filename
+        // (used by cvSave() with the default object name etc.)
+        static string getDefaultObjectName(const string& filename);
+    
+        Ptr<CvFileStorage> fs;
+        string elname;
+        vector<char> structs;
+        int state;
+    };
+    
+
+..
+
+
+.. index:: FileNode
+
+.. _FileNode:
+
+FileNode
+--------
+
+`id=0.228849909258 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/FileNode>`__
+
+.. ctype:: FileNode
+
+
+
+The XML/YAML file node class
+
+
+
+
+::
+
+
+    
+    class CV_EXPORTS FileNode
+    {
+    public:
+        enum { NONE=0, INT=1, REAL=2, FLOAT=REAL, STR=3,
+            STRING=STR, REF=4, SEQ=5, MAP=6, TYPE_MASK=7,
+            FLOW=8, USER=16, EMPTY=32, NAMED=64 };
+        FileNode();
+        FileNode(const CvFileStorage* fs, const CvFileNode* node);
+        FileNode(const FileNode& node);
+        FileNode operator[](const string& nodename) const;
+        FileNode operator[](const char* nodename) const;
+        FileNode operator[](int i) const;
+        int type() const;
+        int rawDataSize(const string& fmt) const;
+        bool empty() const;
+        bool isNone() const;
+        bool isSeq() const;
+        bool isMap() const;
+        bool isInt() const;
+        bool isReal() const;
+        bool isString() const;
+        bool isNamed() const;
+        string name() const;
+        size_t size() const;
+        operator int() const;
+        operator float() const;
+        operator double() const;
+        operator string() const;
+    
+        FileNodeIterator begin() const;
+        FileNodeIterator end() const;
+    
+        void readRaw( const string& fmt, uchar* vec, size_t len ) const;
+        void* readObj() const;
+    
+        // do not use wrapper pointer classes for better efficiency
+        const CvFileStorage* fs;
+        const CvFileNode* node;
+    };
+    
+
+..
+
+
+.. index:: FileNodeIterator
+
+.. _FileNodeIterator:
+
+FileNodeIterator
+----------------
+
+`id=0.575104633905 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/FileNodeIterator>`__
+
+.. ctype:: FileNodeIterator
+
+
+
+The XML/YAML file node iterator class
+
+
+
+
+::
+
+
+    
+    class CV_EXPORTS FileNodeIterator
+    {
+    public:
+        FileNodeIterator();
+        FileNodeIterator(const CvFileStorage* fs,
+            const CvFileNode* node, size_t ofs=0);
+        FileNodeIterator(const FileNodeIterator& it);
+        FileNode operator *() const;
+        FileNode operator ->() const;
+    
+        FileNodeIterator& operator ++();
+        FileNodeIterator operator ++(int);
+        FileNodeIterator& operator --();
+        FileNodeIterator operator --(int);
+        FileNodeIterator& operator += (int);
+        FileNodeIterator& operator -= (int);
+    
+        FileNodeIterator& readRaw( const string& fmt, uchar* vec,
+                                   size_t maxCount=(size_t)INT_MAX );
+    
+        const CvFileStorage* fs;
+        const CvFileNode* container;
+        CvSeqReader reader;
+        size_t remaining;
+    };
+    
+
+..
+