From dacd265424f8358b7444770dc57371bb8207cea6 Mon Sep 17 00:00:00 2001 From: Vadim Pisarevsky Date: Wed, 29 Jun 2011 22:04:43 +0000 Subject: [PATCH] propagated some more fixes from 2.3 branch to the trunk --- modules/imgproc/doc/planar_subdivisions.rst | 327 ++++++++++++++++++++ 1 file changed, 327 insertions(+) create mode 100644 modules/imgproc/doc/planar_subdivisions.rst diff --git a/modules/imgproc/doc/planar_subdivisions.rst b/modules/imgproc/doc/planar_subdivisions.rst new file mode 100644 index 0000000000..d6995e5dda --- /dev/null +++ b/modules/imgproc/doc/planar_subdivisions.rst @@ -0,0 +1,327 @@ +Planar Subdivisions (C API) +============================ + +.. highlight:: c + +CvSubdiv2D +---------- + +.. ocv:struct:: CvSubdiv2D + +Planar subdivision. + +:: + + #define CV_SUBDIV2D_FIELDS() \ + CV_GRAPH_FIELDS() \ + int quad_edges; \ + int is_geometry_valid; \ + CvSubdiv2DEdge recent_edge; \ + CvPoint2D32f topleft; \ + CvPoint2D32f bottomright; + + typedef struct CvSubdiv2D + { + CV_SUBDIV2D_FIELDS() + } + CvSubdiv2D; + +.. + +Planar subdivision is the subdivision of a plane into a set of +non-overlapped regions (facets) that cover the whole plane. The above +structure describes a subdivision built on a 2d point set, where the points +are linked together and form a planar graph, which, together with a few +edges connecting the exterior subdivision points (namely, convex hull points) +with infinity, subdivides a plane into facets by its edges. + +For every subdivision there exists a dual subdivision in which facets and +points (subdivision vertices) swap their roles, that is, a facet is +treated as a vertex (called a virtual point below) of the dual subdivision and +the original subdivision vertices become facets. On the picture below +original subdivision is marked with solid lines and dual subdivision +with dotted lines. + +.. image:: pics/subdiv.png + +OpenCV subdivides a plane into triangles using Delaunay's +algorithm. Subdivision is built iteratively starting from a dummy +triangle that includes all the subdivision points for sure. In this +case the dual subdivision is a Voronoi diagram of the input 2d point set. The +subdivisions can be used for the 3d piece-wise transformation of a plane, +morphing, fast location of points on the plane, building special graphs +(such as NNG,RNG) and so forth. + +CvQuadEdge2D +------------ + +.. ocv:struct:: CvQuadEdge2D + +Quad-edge of planar subdivision. + +:: + + /* one of edges within quad-edge, lower 2 bits is index (0..3) + and upper bits are quad-edge pointer */ + typedef long CvSubdiv2DEdge; + + /* quad-edge structure fields */ + #define CV_QUADEDGE2D_FIELDS() \ + int flags; \ + struct CvSubdiv2DPoint* pt[4]; \ + CvSubdiv2DEdge next[4]; + + typedef struct CvQuadEdge2D + { + CV_QUADEDGE2D_FIELDS() + } + CvQuadEdge2D; + +.. + +Quad-edge is a basic element of subdivision containing four edges (e, eRot, reversed e and reversed eRot): + +.. image:: pics/quadedge.png + +CvSubdiv2DPoint +--------------- + +.. ocv:struct:: CvSubdiv2DPoint + +Point of original or dual subdivision. + +:: + + #define CV_SUBDIV2D_POINT_FIELDS()\ + int flags; \ + CvSubdiv2DEdge first; \ + CvPoint2D32f pt; \ + int id; + + #define CV_SUBDIV2D_VIRTUAL_POINT_FLAG (1 << 30) + + typedef struct CvSubdiv2DPoint + { + CV_SUBDIV2D_POINT_FIELDS() + } + CvSubdiv2DPoint; + +.. + +* id + This integer can be used to index auxillary data associated with each vertex of the planar subdivision + +CalcSubdivVoronoi2D +------------------- +Calculates the coordinates of Voronoi diagram cells. + +.. ocv:cfunction:: void cvCalcSubdivVoronoi2D( CvSubdiv2D* subdiv ) +.. ocv:pyoldfunction:: cv.CalcSubdivVoronoi2D(subdiv)-> None + + :param subdiv: Delaunay subdivision, in which all the points are already added + +The function calculates the coordinates +of virtual points. All virtual points corresponding to some vertex of the +original subdivision form (when connected together) a boundary of the Voronoi +cell at that point. + +ClearSubdivVoronoi2D +-------------------- + +.. ocv:cfunction:: void cvClearSubdivVoronoi2D( CvSubdiv2D* subdiv ) +.. ocv:pyoldfunction:: cv.ClearSubdivVoronoi2D(subdiv)-> None + + Removes all virtual points. + + :param subdiv: Delaunay subdivision + +The function removes all of the virtual points. It +is called internally in +:ref:`CalcSubdivVoronoi2D` +if the subdivision +was modified after previous call to the function. + +CreateSubdivDelaunay2D +---------------------- +Creates an empty Delaunay triangulation. + +.. ocv:cfunction:: CvSubdiv2D* cvCreateSubdivDelaunay2D( CvRect rect, CvMemStorage* storage ) +.. ocv:pyoldfunction:: cv.CreateSubdivDelaunay2D(rect, storage)-> emptyDelaunayTriangulation + + :param rect: Rectangle that includes all of the 2d points that are to be added to the subdivision + + :param storage: Container for subdivision + +The function creates an empty Delaunay +subdivision, where 2d points can be added using the function +:ref:`SubdivDelaunay2DInsert` +. All of the points to be added must be within +the specified rectangle, otherwise a runtime error will be raised. + +Note that the triangulation is a single large triangle that covers the given rectangle. Hence the three vertices of this triangle are outside the rectangle +``rect`` +. + +FindNearestPoint2D +------------------ +Finds the closest subdivision vertex to the given point. + +.. ocv:cfunction:: CvSubdiv2DPoint* cvFindNearestPoint2D( CvSubdiv2D* subdiv, CvPoint2D32f pt ) +.. ocv:pyoldfunction:: cv.FindNearestPoint2D(subdiv, pt)-> point + + :param subdiv: Delaunay or another subdivision + + :param pt: Input point + +The function is another function that +locates the input point within the subdivision. It finds the subdivision vertex that +is the closest to the input point. It is not necessarily one of vertices +of the facet containing the input point, though the facet (located using +:ref:`Subdiv2DLocate` +) is used as a starting +point. The function returns a pointer to the found subdivision vertex. + +Subdiv2DEdgeDst +--------------- +Returns the edge destination. + +.. ocv:cfunction:: CvSubdiv2DPoint* cvSubdiv2DEdgeDst( CvSubdiv2DEdge edge ) +.. ocv:pyoldfunction:: cv.Subdiv2DEdgeDst(edge)-> point + + :param edge: Subdivision edge (not a quad-edge) + +The function returns the edge destination. The +returned pointer may be NULL if the edge is from dual subdivision and +the virtual point coordinates are not calculated yet. The virtual points +can be calculated using the function +:ref:`CalcSubdivVoronoi2D` +. + +Subdiv2DGetEdge +--------------- +Returns one of the edges related to the given edge. + +.. ocv:cfunction:: CvSubdiv2DEdge cvSubdiv2DGetEdge( CvSubdiv2DEdge edge, CvNextEdgeType type ) +.. ocv:pyoldfunction:: cv.Subdiv2DGetEdge(edge, type)-> CvSubdiv2DEdge + + :param edge: Subdivision edge (not a quad-edge) + + :param type: Specifies which of the related edges to return, one of the following: + + * **CV_NEXT_AROUND_ORG** next around the edge origin ( ``eOnext`` on the picture below if ``e`` is the input edge) + + * **CV_NEXT_AROUND_DST** next around the edge vertex ( ``eDnext`` ) + + * **CV_PREV_AROUND_ORG** previous around the edge origin (reversed ``eRnext`` ) + + * **CV_PREV_AROUND_DST** previous around the edge destination (reversed ``eLnext`` ) + + * **CV_NEXT_AROUND_LEFT** next around the left facet ( ``eLnext`` ) + + * **CV_NEXT_AROUND_RIGHT** next around the right facet ( ``eRnext`` ) + + * **CV_PREV_AROUND_LEFT** previous around the left facet (reversed ``eOnext`` ) + + * **CV_PREV_AROUND_RIGHT** previous around the right facet (reversed ``eDnext`` ) + +.. image:: pics/quadedge.png + +The function returns one of the edges related to the input edge. + +Subdiv2DNextEdge +---------------- +Returns next edge around the edge origin + +.. ocv:cfunction:: CvSubdiv2DEdge cvSubdiv2DNextEdge( CvSubdiv2DEdge edge ) +.. ocv:pyoldfunction:: cv.Subdiv2DNextEdge(edge)-> CvSubdiv2DEdge + + :param edge: Subdivision edge (not a quad-edge) + +The function returns the next edge around the edge origin: +``eOnext`` +on the picture above if +``e`` +is the input edge) + +Subdiv2DLocate +-------------- +Returns the location of a point within a Delaunay triangulation. + +.. ocv:cfunction:: CvSubdiv2DPointLocation cvSubdiv2DLocate( CvSubdiv2D* subdiv, CvPoint2D32f pt, CvSubdiv2DEdge* edge, CvSubdiv2DPoint** vertex=NULL ) +.. ocv:pyoldfunction:: cv.Subdiv2DLocate(subdiv, pt) -> (loc, where) + + :param subdiv: Delaunay or another subdivision + + :param pt: The point to locate + + :param edge: The output edge the point falls onto or right to + + :param vertex: Optional output vertex double pointer the input point coinsides with + +The function locates the input point within the subdivision. There are 5 cases: + +* + The point falls into some facet. The function returns + ``CV_PTLOC_INSIDE`` + and + ``*edge`` + will contain one of edges of the facet. + +* + The point falls onto the edge. The function returns + ``CV_PTLOC_ON_EDGE`` + and + ``*edge`` + will contain this edge. + +* + The point coincides with one of the subdivision vertices. The function returns + ``CV_PTLOC_VERTEX`` + and + ``*vertex`` + will contain a pointer to the vertex. + +* + The point is outside the subdivsion reference rectangle. The function returns + ``CV_PTLOC_OUTSIDE_RECT`` + and no pointers are filled. + +* + One of input arguments is invalid. A runtime error is raised or, if silent or "parent" error processing mode is selected, + ``CV_PTLOC_ERROR`` + is returnd. + +Subdiv2DRotateEdge +------------------ +Returns another edge of the same quad-edge. + +.. ocv:cfunction:: CvSubdiv2DEdge cvSubdiv2DRotateEdge( CvSubdiv2DEdge edge, int rotate ) +.. ocv:pyoldfunction:: cv.Subdiv2DRotateEdge(edge, rotate)-> CvSubdiv2DEdge + + :param edge: Subdivision edge (not a quad-edge) + + :param rotate: Specifies which of the edges of the same quad-edge as the input one to return, one of the following: + + * **0** the input edge ( ``e`` on the picture below if ``e`` is the input edge) + + * **1** the rotated edge ( ``eRot`` ) + + * **2** the reversed edge (reversed ``e`` (in green)) + + * **3** the reversed rotated edge (reversed ``eRot`` (in green)) + +The function returns one of the edges of the same quad-edge as the input edge. + +SubdivDelaunay2DInsert +---------------------- +Inserts a single point into a Delaunay triangulation. + +.. ocv:cfunction:: CvSubdiv2DPoint* cvSubdivDelaunay2DInsert( CvSubdiv2D* subdiv, CvPoint2D32f pt) +.. ocv:pyoldfunction:: cv.SubdivDelaunay2DInsert(subdiv, pt)-> point + + :param subdiv: Delaunay subdivision created by the function :ref:`CreateSubdivDelaunay2D` + + :param pt: Inserted point + +The function inserts a single point into a subdivision and modifies the subdivision topology appropriately. If a point with the same coordinates exists already, no new point is added. The function returns a pointer to the allocated point. No virtual point coordinates are calculated at this stage. +