From 010ff53cbc653f1210f635b49e06cad2b5db649c Mon Sep 17 00:00:00 2001 From: Fernando Cacciola Date: Tue, 27 Nov 2007 22:06:55 +0000 Subject: [PATCH] Simplified API documentation --- .../Straight_skeleton_user.tex | 12 +++++ .../doc_tex/Straight_skeleton_2_ref/main.tex | 9 ++-- ...set_polygons_from_polygon_with_holes_2.cpp | 8 ++- .../Create_straight_skeleton_2.cpp | 15 ++---- ...ght_skeleton_from_polygon_with_holes_2.cpp | 10 ++-- .../include/CGAL/Create_offset_polygons_2.h | 54 ++++++------------- .../include/CGAL/Create_straight_skeleton_2.h | 38 ++++--------- .../CGAL/Straight_skeleton_builder_2.h | 1 - .../CGAL/Straight_skeleton_converter_2.h | 4 +- 9 files changed, 56 insertions(+), 95 deletions(-) diff --git a/Straight_skeleton_2/doc_tex/Straight_skeleton_2/Straight_skeleton_user.tex b/Straight_skeleton_2/doc_tex/Straight_skeleton_2/Straight_skeleton_user.tex index 458286548c6..1a229697b1b 100644 --- a/Straight_skeleton_2/doc_tex/Straight_skeleton_2/Straight_skeleton_user.tex +++ b/Straight_skeleton_2/doc_tex/Straight_skeleton_2/Straight_skeleton_user.tex @@ -361,6 +361,18 @@ Contour vertices have time zero. The straight skeleton data structure is defined by the \ccc{StraightSkeleton_2} concept and modeled in the \ccc{Straight_skeleton_2} class. +The simplest way to construct a straight skeleton is via the free functions \ccc{create_interior_straight_skeleton_2} and \ccc{create_exterior_straight_skeleton_2}, as shown in the following example: + +\ccIncludeExampleCode{Straight_skeleton_2/Create_straight_skeleton_2.cpp} + +The input to these functions is the polygon, which can be given as an iterator pair or directly as a \ccc{Polygon_2} object. In the case of the exterior skeleton, a maximum offset must be specfied as well (see the ref manual details on this max offset parameter). + +If \ccc{Polygon_with_holes_2} is used, you can pass an instance of that directly to the function creating the interior skeleton, as shown below. Notice that a different header must be included in this case. + +\ccIncludeExampleCode{Straight_skeleton_2/Create_straight_skeleton_2.cpp} + +\subsection{Low level API} + The straight skeleton construction algorithm is encapsulated in the class \ccc{Straight_skeleton_builder_2} which is parameterized on a geometric traits (class diff --git a/Straight_skeleton_2/doc_tex/Straight_skeleton_2_ref/main.tex b/Straight_skeleton_2/doc_tex/Straight_skeleton_2_ref/main.tex index 196066de87b..7319d45c23c 100644 --- a/Straight_skeleton_2/doc_tex/Straight_skeleton_2_ref/main.tex +++ b/Straight_skeleton_2/doc_tex/Straight_skeleton_2_ref/main.tex @@ -26,11 +26,10 @@ \input{Straight_skeleton_2_ref/Straight_skeleton_builder_traits_2.tex} \input{Straight_skeleton_2_ref/Straight_skeleton_builder_2.tex} \input{Straight_skeleton_2_ref/Dummy_straight_skeleton_builder_2_visitor.tex} -\input{Straight_skeleton_2_ref/Create_offset_polygon_2.tex} -\input{Straight_skeleton_2_ref/Arrange_offset_polygon_2.tex} -\input{Straight_skeleton_2_ref/Create_interior_skeleton_and_offset_polygon_2.tex} -\input{Straight_skeleton_2_ref/Create_exterior_skeleton_and_offset_polygon_2.tex} -\input{Straight_skeleton_2_ref/Create_offset_polygon_2.tex} +\input{Straight_skeleton_2_ref/Create_offset_polygons_2.tex} +\input{Straight_skeleton_2_ref/Arrange_offset_polygons_2.tex} +\input{Straight_skeleton_2_ref/Create_interior_skeleton_and_offset_polygons_2.tex} +\input{Straight_skeleton_2_ref/Create_exterior_skeleton_and_offset_polygons_2.tex} \input{Straight_skeleton_2_ref/Polygon_offset_builder_traits_2.tex} \input{Straight_skeleton_2_ref/Polygon_offset_builder_2.tex} \input{Straight_skeleton_2_ref/Compute_outer_frame_margin.tex} diff --git a/Straight_skeleton_2/examples/Straight_skeleton_2/Create_skeleton_and_offset_polygons_from_polygon_with_holes_2.cpp b/Straight_skeleton_2/examples/Straight_skeleton_2/Create_skeleton_and_offset_polygons_from_polygon_with_holes_2.cpp index 7357f0d8e0c..ea7c77d4bb4 100644 --- a/Straight_skeleton_2/examples/Straight_skeleton_2/Create_skeleton_and_offset_polygons_from_polygon_with_holes_2.cpp +++ b/Straight_skeleton_2/examples/Straight_skeleton_2/Create_skeleton_and_offset_polygons_from_polygon_with_holes_2.cpp @@ -49,13 +49,11 @@ int main() poly.add_hole( hole ) ; - double lOffset = 1 ; + double lOffset = 0.2 ; - PolygonPtrVector inner_offset_polygons = CGAL::create_interior_skeleton_and_offset_polygons_2(lOffset,poly); - PolygonPtrVector outer_offset_polygons = CGAL::create_exterior_skeleton_and_offset_polygons_2(lOffset,poly); + PolygonPtrVector offset_polygons = CGAL::create_interior_skeleton_and_offset_polygons_2(lOffset,poly); - print_polygons(inner_offset_polygons); - print_polygons(outer_offset_polygons); + print_polygons(offset_polygons); return 0; } diff --git a/Straight_skeleton_2/examples/Straight_skeleton_2/Create_straight_skeleton_2.cpp b/Straight_skeleton_2/examples/Straight_skeleton_2/Create_straight_skeleton_2.cpp index 34ed255cea3..7458c7593da 100644 --- a/Straight_skeleton_2/examples/Straight_skeleton_2/Create_straight_skeleton_2.cpp +++ b/Straight_skeleton_2/examples/Straight_skeleton_2/Create_straight_skeleton_2.cpp @@ -1,9 +1,3 @@ -#include -#include -#include -#include -#include - #include #include @@ -33,15 +27,16 @@ int main() poly.push_back( Point(-1,1) ) ; poly.push_back( Point(-12,0) ) ; - // You can pass the polygon via a pointer-iterator pair, or directly, as below + // You can pass the polygon via a pointer-iterator pair SsPtr iss = CGAL::create_interior_straight_skeleton_2(poly.vertices_begin(), poly.vertices_end()); - print_straight_skeleton(*iss); + // Or you can pass the polygon directly, as below. - // To create an exterior straight skeleton you need to specify a maximum offset + // To create an exterior straight skeleton you need to specify a maximum offset. double lMaxOffset = 5 ; - SsPtr oss = CGAL::create_exterior_straight_skeleton_2(lMaxOffset,poly ); + SsPtr oss = CGAL::create_exterior_straight_skeleton_2(lMaxOffset, poly); + print_straight_skeleton(*iss); print_straight_skeleton(*oss); return 0; diff --git a/Straight_skeleton_2/examples/Straight_skeleton_2/Create_straight_skeleton_from_polygon_with_holes_2.cpp b/Straight_skeleton_2/examples/Straight_skeleton_2/Create_straight_skeleton_from_polygon_with_holes_2.cpp index 3c8f659bb38..3111acf2c2d 100644 --- a/Straight_skeleton_2/examples/Straight_skeleton_2/Create_straight_skeleton_from_polygon_with_holes_2.cpp +++ b/Straight_skeleton_2/examples/Straight_skeleton_2/Create_straight_skeleton_from_polygon_with_holes_2.cpp @@ -1,9 +1,3 @@ -#include -#include -#include -#include -#include - #include #include @@ -47,6 +41,8 @@ int main() poly.add_hole( hole ) ; SsPtr iss = CGAL::create_interior_straight_skeleton_2(poly); - + + print_straight_skeleton(*iss); + return 0; } diff --git a/Straight_skeleton_2/include/CGAL/Create_offset_polygons_2.h b/Straight_skeleton_2/include/CGAL/Create_offset_polygons_2.h index deb6e017255..2141cc810de 100755 --- a/Straight_skeleton_2/include/CGAL/Create_offset_polygons_2.h +++ b/Straight_skeleton_2/include/CGAL/Create_offset_polygons_2.h @@ -52,7 +52,7 @@ create_offset_polygons_2 ( FT aOffset, Skeleton const& aSs, K const& k, Tag_fals OutPolygonPtrVector rR ; - boost::shared_ptr lConvertedSs = convert_straight_skeleton(aSs); + boost::shared_ptr lConvertedSs = convert_straight_skeleton_2(aSs); OffsetBuilder ob( *lConvertedSs ); ob.construct_offset_contours(aOffset, std::back_inserter(rR) ) ; @@ -136,8 +136,8 @@ create_interior_skeleton_and_offset_polygons_2 ( FT aOffset ) { return create_offset_polygons_2(aOffset - ,CGAL_SS_i::dereference( create_interior_straight_skeleton_2(vertices_begin(aOuterBoundary) - ,vertices_end (aOuterBoundary) + ,CGAL_SS_i::dereference( create_interior_straight_skeleton_2(CGAL_SS_i::vertices_begin(aOuterBoundary) + ,CGAL_SS_i::vertices_end (aOuterBoundary) ,aHolesBegin ,aHolesEnd ,ssk @@ -170,15 +170,11 @@ create_interior_skeleton_and_offset_polygons_2 ( FT aOffset template std::vector< boost::shared_ptr > inline -create_interior_skeleton_and_offset_polygons_2 ( FT aOffset - , Polygon const& aOuterBoundary - , OfK const& ofk - , SsK const& ssk - ) +create_interior_skeleton_and_offset_polygons_2 ( FT aOffset, Polygon const& aPoly, OfK const& ofk, SsK const& ssk ) { std::vector no_holes ; return create_interior_skeleton_and_offset_polygons_2(aOffset - ,aOuterBoundary + ,aPoly ,no_holes.begin() ,no_holes.end() ,ofk @@ -189,14 +185,11 @@ create_interior_skeleton_and_offset_polygons_2 ( FT aOffset template std::vector< boost::shared_ptr > inline -create_interior_skeleton_and_offset_polygons_2 ( FT aOffset - , Polygon const& aOuterBoundary - , OfK const& ofk - ) +create_interior_skeleton_and_offset_polygons_2 ( FT aOffset, Polygon const& aPoly, OfK const& ofk ) { std::vector no_holes ; return create_interior_skeleton_and_offset_polygons_2(aOffset - ,aOuterBoundary + ,aPoly ,no_holes.begin() ,no_holes.end() ,ofk @@ -207,27 +200,20 @@ create_interior_skeleton_and_offset_polygons_2 ( FT aOffset template std::vector< boost::shared_ptr > inline -create_interior_skeleton_and_offset_polygons_2 ( FT aOffset, Polygon const& aOuterBoundary ) +create_interior_skeleton_and_offset_polygons_2 ( FT aOffset, Polygon const& aPoly ) { - return create_interior_skeleton_and_offset_polygons_2(aOffset - ,aOuterBoundary - ,typename Polygon::Traits() - ); + return create_interior_skeleton_and_offset_polygons_2(aOffset, aPoly, typename Polygon::Traits() ); } template std::vector< boost::shared_ptr > inline -create_exterior_skeleton_and_offset_polygons_2 ( FT aOffset - , Polygon const& aOuterBoundary - , OfK const& ofk - , SsK const& ssk - ) +create_exterior_skeleton_and_offset_polygons_2 ( FT aOffset, Polygon const& aPoly, OfK const& ofk , SsK const& ssk) { return create_offset_polygons_2(aOffset ,CGAL_SS_i::dereference(create_exterior_straight_skeleton_2(aOffset - ,vertices_begin(aOuterBoundary) - ,vertices_end (aOuterBoundary) + ,CGAL_SS_i::vertices_begin(aPoly) + ,CGAL_SS_i::vertices_end (aPoly) ,ssk ) ) @@ -238,13 +224,10 @@ create_exterior_skeleton_and_offset_polygons_2 ( FT aOffset template std::vector< boost::shared_ptr > inline -create_exterior_skeleton_and_offset_polygons_2 ( FT aOffset - , Polygon const& aOuterBoundary - , OfK const& ofk - ) +create_exterior_skeleton_and_offset_polygons_2 ( FT aOffset, Polygon const& aPoly, OfK const& ofk ) { return create_exterior_skeleton_and_offset_polygons_2(aOffset - ,aOuterBoundary + ,aPoly ,ofk ,Exact_predicates_inexact_constructions_kernel() ); @@ -254,14 +237,9 @@ create_exterior_skeleton_and_offset_polygons_2 ( FT aOffset template std::vector< boost::shared_ptr > inline -create_exterior_skeleton_and_offset_polygons_2 ( FT aOffset - , Polygon const& aOuterBoundary - ) +create_exterior_skeleton_and_offset_polygons_2 ( FT aOffset, Polygon const& aOuterBoundary ) { - return create_exterior_skeleton_and_offset_polygons_2(aOffset - ,aOuterBoundary - ,typename Polygon::Traits() - ); + return create_exterior_skeleton_and_offset_polygons_2(aOffset, aOuterBoundary, typename Polygon::Traits() ); } diff --git a/Straight_skeleton_2/include/CGAL/Create_straight_skeleton_2.h b/Straight_skeleton_2/include/CGAL/Create_straight_skeleton_2.h index 4dd989df2b0..4a3e6d75cfc 100755 --- a/Straight_skeleton_2/include/CGAL/Create_straight_skeleton_2.h +++ b/Straight_skeleton_2/include/CGAL/Create_straight_skeleton_2.h @@ -43,17 +43,6 @@ template inline typename Polygon_2::Vertex_const_iterator vertices_end( Polygon_2 const& aPoly ) { return aPoly.vertices_end() ; } -template -inline Poly reverse_polygon ( Poly const& aPoly ) { return Poly( aPoly.rbegin(), aPoly.rend() ) ; } - -template -inline Polygon_2 reverse_polygon( Polygon_2 const& aPoly ) -{ - Polygon_2 r ( aPoly ) ; - r.reverse_orientation(); - return r ; -} - } template @@ -176,7 +165,7 @@ create_exterior_straight_skeleton_2 ( FT aMaxOffset if ( margin ) { - Bbox_2 bbox = bbox_2( aVerticesBegin, aVerticesEnd); + Bbox_2 bbox = bbox_2(aVerticesBegin, aVerticesEnd); FT fxmin = bbox.xmin() - *margin ; FT fxmax = bbox.xmax() + *margin ; @@ -190,13 +179,13 @@ create_exterior_straight_skeleton_2 ( FT aMaxOffset frame[2] = Point_2(fxmax,fymax) ; frame[3] = Point_2(fxmin,fymax) ; - typedef typename HoleIterator::value_type Hole ; + typedef std::vector Hole ; + + Hole lPoly(aVerticesBegin, aVerticesEnd); + std::reverse(lPoly.begin(), lPoly.end()); std::vector holes ; - - Hole lOuterContour(aVerticesBegin, aVerticesEnd); - - holes.push_back( reverse_polygon(lOuterContour) ) ; + holes.push_back(lPoly) ; rSkeleton = create_interior_straight_skeleton_2(frame, frame+4, holes.begin(), holes.end(), k ) ; } @@ -223,14 +212,11 @@ create_exterior_straight_skeleton_2 ( FT aMaxOffset template boost::shared_ptr< Straight_skeleton_2 > inline -create_exterior_straight_skeleton_2 ( FT aMaxOffset - , Polygon const& aOutContour - , K const& k - ) +create_exterior_straight_skeleton_2 ( FT aMaxOffset, Polygon const& aPoly, K const& k ) { return create_exterior_straight_skeleton_2(aMaxOffset - ,vertices_begin(aOutContour) - ,vertices_end (aOutContour) + ,CGAL_SS_i::vertices_begin(aPoly) + ,CGAL_SS_i::vertices_end (aPoly) ,k ); } @@ -238,12 +224,10 @@ create_exterior_straight_skeleton_2 ( FT aMaxOffset template boost::shared_ptr< Straight_skeleton_2 > inline -create_exterior_straight_skeleton_2 ( FT aMaxOffset - , Polygon const& aOutContour - ) +create_exterior_straight_skeleton_2 ( FT aMaxOffset, Polygon const& aPoly ) { return create_exterior_straight_skeleton_2(aMaxOffset - ,aOutContour + ,aPoly ,Exact_predicates_inexact_constructions_kernel() ); } diff --git a/Straight_skeleton_2/include/CGAL/Straight_skeleton_builder_2.h b/Straight_skeleton_2/include/CGAL/Straight_skeleton_builder_2.h index 42e29eb9a8f..3fddab2bc7e 100644 --- a/Straight_skeleton_2/include/CGAL/Straight_skeleton_builder_2.h +++ b/Straight_skeleton_2/include/CGAL/Straight_skeleton_builder_2.h @@ -102,7 +102,6 @@ struct Dummy_straight_skeleton_builder_2_visitor void on_error( char const* ) const {} } ; - template > class Straight_skeleton_builder_2 { diff --git a/Straight_skeleton_2/include/CGAL/Straight_skeleton_converter_2.h b/Straight_skeleton_2/include/CGAL/Straight_skeleton_converter_2.h index d43607e3fec..befc494def2 100644 --- a/Straight_skeleton_2/include/CGAL/Straight_skeleton_converter_2.h +++ b/Straight_skeleton_2/include/CGAL/Straight_skeleton_converter_2.h @@ -132,7 +132,7 @@ struct Straight_skeleton_converter_2 private : - Target_skeleton_ptr create_unconnected_copy ( Source_skeleton const& aSource ) + Target_skeleton_ptr create_unconnected_copy ( Source_skeleton const& aSource ) const { Target_skeleton_ptr rCopy ( new Target_skeleton ) ; @@ -185,7 +185,7 @@ private : return rCopy ; } - void connect_items ( Source_skeleton const& aSource, Target_skeleton& aTarget ) + void connect_items ( Source_skeleton const& aSource, Target_skeleton& aTarget ) const { Target_vertex_iterator tvit = aTarget.vertices_begin(); for ( Source_vertex_const_iterator svit = aSource.vertices_begin(); svit != aSource.vertices_end(); ++ svit, ++ tvit )