Replace Object

This commit is contained in:
Efi Fogel 2012-02-12 21:46:05 +00:00
parent e25e73a5f5
commit 26cb83f92c
11 changed files with 183 additions and 96 deletions

View File

@ -162,8 +162,8 @@ segments, as depicted in Figure~\ref{arr_fig:ex_24}, while maintaining
the curve history. The example demonstrates the usage of the special
traversal functions. It also shows how to issue point-location queries
on the resulting arrangement, using the auxiliary function
\ccc{point_location_query()} defined in the header file
\ccc{point_location_utils.h} (see also Section~\ref{arr_ssec:pl}).
\ccc{locate_point()} defined in the header file
\ccc{point_location_utils.h}; see also Section~\ref{arr_ssec:pl}.
\ccIncludeExampleCode{Arrangement_on_surface_2/curve_history.cpp}

View File

@ -19,16 +19,18 @@ The \ccc{Arrangement_2} class template does not support point-location
queries directly, as the arrangement representation is decoupled from
the geometric algorithms that operate on it. The \emph{2D Arrangements}
package includes a set of classe templates that are capable of
answering such queries; all are models of the concept
answering such queries; all are models of the concept
\ccc{ArrangementPointLocation_2}. Each model employs a different
algorithm or \emph{strategy} for answering queries. A model of this
concept must define the \ccc{locate()} member function, which accepts an
input query-point and returns a polymorphic object representing the
arrangement cell that contains this point. The returned object, which is
of type \ccc{CGAL::Object}, can be assigned to a \ccc{Face_const_handle},
a \ccc{Halfedge_const_handle}, or a \ccc{Vertex_const_handle}, depending
on whether the query point is located inside a face, on an edge, or on a
vertex.
concept must define the \ccc{locate()} member function, which accepts
an input query-point and returns an object that represents the
arrangement cell that contains this point. This object is is type
\ccc{Arr_point_location_result<Arrangement_2>::Type}---a discriminated
union container of the bounded types \ccc{Vertex_const_handle},
\ccc{Halfedge_const_handle}, or \ccc{Face_const_handle}. Depending on
whether the query point is located inside a face, on an edge, or on a
vertex, the appropriate handle can be obtained With \emph{value retrieval}
by \ccc{boost::get} as demonstrated in the example below.
Note that the handles returned by the \ccc{locate()} functionss are
non-mutable (\ccc{const}). If necessary, such handles may
@ -68,9 +70,9 @@ The function template \ccc{locate_point()} calls an instance of the
function template \ccc{print_point_location()}, which inserts the
result of the query into the standard output-stream. It is listed
below, and defined in the header file \ccc{point_location_utils.h}.
Observe how the function \ccc{assign()} is used to cast the
resulting \ccc{CGAL::Object} into a handle to an arrangement feature.
The point-location object \ccc{pl} is assumed to be already attached
Observe how the function \ccc{boost::get()} is used to cast the
resulting object into a handle to an arrangement feature. The
point-location object \ccc{pl} is assumed to be already attached
to an arrangement.
\begin{alltt}
@ -91,13 +93,13 @@ print_point_location
const Face_const_handle* f;
std::cout << "The point (" << q << ") is located ";
if (f = boost::get<Face_const_handle>(&(*obj))) // located inside a face
if (f = boost::get<Face_const_handle>(&obj)) // located inside a face
std::cout << "inside "
<< (((*f)->is_unbounded()) ? "the unbounded" : "a bounded")
<< " face." << std::endl;
else if (e = boost::get<Halfedge_const_handle>(&(*obj))) // located on an edge
else if (e = boost::get<Halfedge_const_handle>(&obj)) // located on an edge
std::cout << "on an edge: " << (*e)->curve() << std::endl;
else if (v = boost::get<Vertex_const_handle>(&(*obj))) // located on a vertex
else if (v = boost::get<Vertex_const_handle>(&obj)) // located on a vertex
std::cout << "on " << (((*v)->is_isolated()) ? "an isolated" : "a")
<< " vertex: " << (*v)->point() << std::endl;
else CGAL_error_msg("Invalid object.");
@ -249,14 +251,15 @@ that it hits a vertex, or that the arrangement does not have any
vertex or edge lying directly above (or below) the query point.
All point-location classes listed in the previous section are also
models of the \ccc{ArrangementVerticalRayShoot_2} concept. That is, t
hey all have member functions called \ccc{ray_shoot_up(q)} and
models of the \ccc{ArrangementVerticalRayShoot_2} concept. That is,
they all have member functions called \ccc{ray_shoot_up(q)} and
\ccc{ray_shoot_down(q)} that accept a query point $q$. These functions
output a polymorphic object of type \ccc{CGAL::Object}, which wraps a
\ccc{Halfedge_const_handle}, a \ccc{Vertex_const_handle}, or a
\ccc{Face_const_handle} object. The latter type is used for the
unbounded face of the arrangement, in case there is no edge or
vertex lying directly above (or below) $q$.
output an object of type type
\ccc{Arr_point_location_result<Arrangement_2>::Type}---a discriminated
union container of the bounded types \ccc{Vertex_const_handle},
\ccc{Halfedge_const_handle}, or \ccc{Face_const_handle}. The latter type
is used for the unbounded face of the arrangement, in case there is no
edge or vertex lying directly above (or below) $q$.
The function template \ccc{vertical_ray_shooting_query()} listed
below accepts a vertical ray-shooting object, the type of which
@ -288,12 +291,12 @@ void shoot_vertical_ray(const RayShoot& vrs,
const Face_const_handle* f;
std::cout << "Shooting up from (" << q << ") : ";
if (v = boost::get<Vertex_const_handle>(&(*obj))) // we hit a vertex
if (v = boost::get<Vertex_const_handle>(&obj)) // we hit a vertex
std::cout << "hit " << (((*v)->is_isolated()) ? "an isolated" : "a")
<< " vertex: " << (*v)->point() << std::endl;
else if (e = boost::get<Halfedge_const_handle>(&(*obj))) // we hit an edge
else if (e = boost::get<Halfedge_const_handle>(&obj)) // we hit an edge
std::cout << "hit an edge: " << (*e)->curve() << std::endl;
else if (f = boost::get<Face_const_handle>(&(*obj))) \{ // we hit nothing
else if (f = boost::get<Face_const_handle>(&obj)) \{ // we hit nothing
CGAL_assertion((*f)->is_unbounded());
std::cout << "hit nothing." << std::endl;
\}
@ -332,7 +335,7 @@ Alternatively, the \emph{2D Arrangement} package includes a free
query points as its input and sweeps through the arrangement to
locate all query points in one pass. The function outputs the query
results as pairs, where each pair consists of a query point
and a polymorphic object \ccc{CGAL::Object}, which represents the
and a discriminated union container, which represents the
cell containing the point; see Section~\ref{arr_ssec:pl}. The output
pairs are sorted in increasing $xy$-lexicographical order of the
query point.

View File

@ -55,8 +55,16 @@ insertions of curves and not deletions of them.
\ccInclude{CGAL/Arr_landmarks_point_location.h}
\ccIsModel
\ccc{ArrangementPointLocation_2} \\
\ccc{ArrangementVerticalRayShoot_2}
%============
\ccc{ArrangementPointLocation_2}\\
\ccc{ArrangementVerticalRayShoot_2}
\ccSeeAlso
%============
\ccRefConceptPage{ArrangementPointLocation_2}\\
\ccRefConceptPage{ArrangementVerticalRayShoot_2}\\
\ccRefIdfierPage{CGAL::Arr_point_location_result<Arrangement>}\\
\ccRefIdfierPage{CGAL_ARR_POINT_LOCATION_VERSION}
\end{ccRefClass}

View File

@ -13,8 +13,7 @@
\ccDefinition
%============
The \ccRefName\ class implements a naive algorithm that traverses
The \ccRefName{} class implements a naive algorithm that traverses
all the vertices and halfedges in the arrangement in search for an
answer to a point-location query.
The query time is therefore linear in the complexity of the arrangement.
@ -24,9 +23,17 @@ time-consuming process when applied to dense arrangements.
\ccInclude{CGAL/Arr_naive_point_location.h}
\ccIsModel
\ccc{ArrangementPointLocation_2} \\
\ccc{ArrangementVerticalRayShoot_2}
%============
\ccc{ArrangementPointLocation_2} \\
\ccc{ArrangementVerticalRayShoot_2}
\ccSeeAlso
%============
\ccRefConceptPage{ArrangementPointLocation_2}\\
\ccRefConceptPage{ArrangementVerticalRayShoot_2}\\
\ccRefIdfierPage{CGAL::Arr_point_location_result<Arrangement>}\\
\ccRefIdfierPage{CGAL_ARR_POINT_LOCATION_VERSION}
\end{ccRefClass}
\ccRefPageEnd

View File

@ -13,12 +13,22 @@
\ccDefinition
%============
A model of the \ccRefName\ concept can be attached to an \ccc{Arrangement_2}
instance and answer point-location queries on this arrangement. Namely, given
a \ccc{Arrangement_2::Point_2} object, representing a point in the plane,
it returns the arrangement cell containing it. In the general case, the
query point is contained inside an arrangement face, but in degenerate
situations it may lie on an edge or coincide with an arrangement vertex.
A model of the \ccRefName{} concept can answer point-location queries on
an arrangement attched to it. Namely, given a \ccc{Arrangement_2::Point_2}
object, representing a point in the plane, it returns the arrangement cell
containing it. In the general case, the query point is contained inside an
arrangement face, but in degenerate situations it may lie on an edge or
coincide with an arrangement vertex.
\paragraph{A note on Backwards compatibility}
The \ccc{locate} member function used to return \ccc{CGAL::Object} up to
\cgal{} version~3.9. Starting with \cal{} version~4.0 the return type
is determined by a metafunction. To preserve backwards compatibility
\ccc{CGAL::Object} can be constructed from the new return types
implicitly, but switching to the new style is recommended. To enable
the old style without any overhead, the macro
\ccc{CGAL_ARR_POINT_LOCATION_VERSION} can be defined to 1 before any
\cgal{} header is included.
\ccTypes
%=======
@ -33,19 +43,17 @@ situations it may lie on an edge or coincide with an arrangement vertex.
\ccConstructor{ArrangementPointLocation_2();}{default constructor.}
\ccConstructor{ArrangementPointLocation_2 (const Arrangement_2& arr);}
\ccConstructor{ArrangementPointLocation_2(const Arrangement_2& arr);}
{constructs a point-location object \ccVar{} attached to the given
arrangement \ccc{arr}.}
\ccQueryFunctions
%================
\ccThree{Object}{locate}{}
\ccMethod{Object locate (const Point_2& q) const;}
\ccThree{Arr_point_location_result<Arrangement_2>::Type}{locate}{}
\ccMethod{Arr_point_location_result<Arrangement_2>::Type locate(const Point_2& q) const;}
{locates the arrangement cell that contains the query point \ccc{q}
and returns a handle for this cell.
The function returns an \ccc{Object} instance that wraps either of the
following types:
and returns a discriminated union container of the following bounded
types:
\begin{itemize}
\item \ccc{Arrangement_2::Face_const_handle}, in case \ccc{q} is
contained inside an arrangement face;
@ -54,24 +62,31 @@ situations it may lie on an edge or coincide with an arrangement vertex.
\item \ccc{Arrangement_2::Vertex_const_handle}, in case \ccc{q} coincides
with an arrangement vertex.
\end{itemize}
\ccPrecond{\ccVar{} is attached to a valid arrangement instance.}}
\ccPrecond{\ccVar{} is attached to a valid arrangement object.}}
\ccOperations
%============
\ccMethod{void attach (const Arrangement_2& arr);}
\ccMethod{void attach(const Arrangement_2& arr);}
{attaches \ccVar{} to the given arrangement \ccc{arr}.}
\ccMethod{void detach ();}
\ccMethod{void detach();}
{detaches \ccVar{} from the arrangement it is currently attached to.}
\ccHasModels
%===========
\ccc{Arr_naive_point_location<Arrangement>}\\
\ccc{Arr_walk_along_a_line_point_location<Arrangement>} \\
\ccc{Arr_walk_along_line_point_location<Arrangement>} \\
\ccc{Arr_trapezoid_ric_point_location<Arrangement>}\\
\ccc{Arr_landmarks_point_location<Arrangement,Generator>}\\
\ccc{Arr_landmarks_point_location<Arrangement,Generator>}
\ccSeeAlso
%===========
\ccRefIdfierPage{CGAL::Arr_naive_point_location<Arrangement>}\\
\ccRefIdfierPage{CGAL::Arr_walk_along_line_point_location<Arrangement>} \\
\ccRefIdfierPage{CGAL::Arr_trapezoid_ric_point_location<Arrangement>}\\
\ccRefIdfierPage{CGAL::Arr_landmarks_point_location<Arrangement,Generator>}\\
\ccRefIdfierPage{CGAL::Arr_point_location_result<Arrangement>}\\
\ccRefIdfierPage{CGAL_ARR_POINT_LOCATION_VERSION}
\end{ccRefConcept}

View File

@ -13,7 +13,6 @@
\ccDefinition
%============
The \ccRefName\ class implements the incremental randomized algorithm
introduced by Mulmuley~\cite{m-fppa-90} as presented by
Seidel~\cite{s-sfira-91} (see also~\cite[Chapter~6]{bkos-cgaa-00}).
@ -34,8 +33,16 @@ is relatively large.
\ccInclude{CGAL/Arr_trapezoid_ric_point_location.h}
\ccIsModel
\ccc{ArrangementPointLocation_2} \\
\ccc{ArrangementVerticalRayShoot_2}
%============
\ccc{ArrangementPointLocation_2}\\
\ccc{ArrangementVerticalRayShoot_2}
\ccSeeAlso
%============
\ccRefConceptPage{ArrangementPointLocation_2}\\
\ccRefConceptPage{ArrangementVerticalRayShoot_2}\\
\ccRefIdfierPage{CGAL::Arr_point_location_result<Arrangement>}
\ccRefIdfierPage{CGAL_ARR_POINT_LOCATION_VERSION}
\end{ccRefClass}

View File

@ -13,19 +13,30 @@
\ccDefinition
%============
A model of the \ccRefName\ concept can be attached to an \ccc{Arrangement_2}
instance and answer vertical ray-shooting queries on this arrangement.
Namely, given a \ccc{Arrangement_2::Point_2} object, representing a point in
the plane, it returns the arrangement feature (edge or vertex) that lies
A model of the \ccRefName{} concept can answer vertical ray-shooting
queries on an arrangement attached to it. Namely, given a
\ccc{Arrangement_2::Point_2} object, representing a point in the plane,
it returns the arrangement feature (edge or vertex) that lies
strictly above it (or below it). By ``strictly'' we mean that if the
query point lies on an arrangement edge (or on an arrangement vertex) this
edge will {\em not} be the query result, but the feature lying above or
below it. (An exception to this rule is the degenerate situation where the
query point lies in the interior of a vertical edge.) Note that it may happen
that the query point lies above the upper envelope (or below the lower
envelope) of the arrangement, so that the vertical ray emanating from it
may go to infinity without hitting any arrangement feature on its way. In this
case the unbounded face is returned.
query point lies on an arrangement edge (or on an arrangement vertex)
this edge will \emph{not} be the query result, but the feature lying
above or below it. (An exception to this rule is the degenerate case
where the query point lies in the interior of a vertical edge.) Note
that it may happen that the query point lies above the upper envelope
(or below the lower envelope) of the arrangement, and the vertical ray
emanating from the query point goes to infinity without hitting any
arrangement feature on its way. In this case the unbounded face is
returned.
\paragraph{A note on Backwards compatibility}
The \ccc{ray_shoot_up} and \ccc{ray_shoot_down} member functions used
to return \ccc{CGAL::Object} up to \cgal{} version~3.9. Starting with
\cal{} version~4.0 the return type is determined by a metafunction. To
preserve backwards compatibility \ccc{CGAL::Object} can be constructed
from the new return types implicitly, but switching to the new style
is recommended. To enable the old style without any overhead, the macro
\ccc{CGAL_ARR_POINT_LOCATION_VERSION} can be defined to 1 before any
\cgal{} header is included.
\ccTypes
%=======
@ -47,12 +58,12 @@ case the unbounded face is returned.
\ccQueryFunctions
%================
\ccMethod{Object ray_shoot_up (const Point_2& q) const;}
\ccThree{Arr_point_location_result<Arrangement_2>::Type}{locate}{}
\ccMethod{Arr_point_location_result<Arrangement_2>::Type ray_shoot_up(const Point_2& q) const;}
{locates the arrangement feature that is first hit by an upward-directed
vertical ray emanating from the query point \ccc{q},
and returns a handle for this feature.
The function returns an \ccc{Object} instance that is a wrapper for
one of the following types:
and returns a handle for this feature. The function returns a
discriminated union container of the following bounded types:
\begin{itemize}
\item \ccc{Arrangement_2::Halfedge_const_handle}, in case the vertical
ray hits an arrangement edge;
@ -64,12 +75,11 @@ case the unbounded face is returned.
\end{itemize}
\ccPrecond{\ccVar{} is attached to a valid arrangement instance.}}
\ccMethod{Object ray_shoot_down (const Point_2& q) const;}
\ccMethod{Arr_point_location_result<Arrangement_2>::Type ray_shoot_down (const Point_2& q) const;}
{locates the arrangement feature that is first hit by a downward-directed
vertical ray emanating from the query point \ccc{q},
and returns a handle for this feature.
The function returns an \ccc{Object} instance that is a wrapper for
one of the following types:
and returns a handle for this feature. The function returns a
discriminated union container of the following bounded types:
\begin{itemize}
\item \ccc{Arrangement_2::Halfedge_const_handle}, in case the vertical
ray hits an arrangement edge;
@ -92,11 +102,19 @@ case the unbounded face is returned.
\ccHasModels
%===========
\ccc{Arr_naive_point_location<Arrangement>}\\
\ccc{Arr_walk_along_a_line_point_location<Arrangement>} \\
\ccc{Arr_walk_along_line_point_location<Arrangement>} \\
\ccc{Arr_trapezoid_ric_point_location<Arrangement>}\\
\ccc{Arr_landmarks_point_location<Arrangement,Generator>}\\
\ccc{Arr_landmarks_point_location<Arrangement,Generator>}
\ccSeeAlso
%===========
\ccRefIdfierPage{CGAL::Arr_naive_point_location<Arrangement>}\\
\ccRefIdfierPage{CGAL::Arr_walk_along_line_point_location<Arrangement>} \\
\ccRefIdfierPage{CGAL::Arr_trapezoid_ric_point_location<Arrangement>}\\
\ccRefIdfierPage{CGAL::Arr_landmarks_point_location<Arrangement,Generator>}\\
\ccRefIdfierPage{CGAL::Arr_point_location_result<Arrangement>}\\
\ccRefIdfierPage{CGAL_ARR_POINT_LOCATION_VERSION}
\end{ccRefConcept}

View File

@ -13,8 +13,7 @@
\ccDefinition
%============
The \ccRefName\ class implements a very simple point-location (and
The \ccRefName{} class implements a very simple point-location (and
vertical ray-shooting) strategy that improves the naive one.
The algorithm considers an imaginary vertical ray emanating from the
query point, and simulates a walk along the zone of this ray, starting
@ -34,8 +33,16 @@ of issued queries is not large.
\ccInclude{CGAL/Arr_walk_along_line_point_location.h}
\ccIsModel
\ccc{ArrangementPointLocation_2} \\
\ccc{ArrangementVerticalRayShoot_2}
%============
\ccc{ArrangementPointLocation_2}\\
\ccc{ArrangementVerticalRayShoot_2}
\ccSeeAlso
%============
\ccRefConceptPage{ArrangementPointLocation_2}\\
\ccRefConceptPage{ArrangementVerticalRayShoot_2}\\
\ccRefIdfierPage{CGAL::Arr_point_location_result<Arrangement>}\\
\ccRefIdfierPage{CGAL_ARR_POINT_LOCATION_VERSION}
\end{ccRefClass}

View File

@ -7,30 +7,45 @@
The function \ccRefName{} performs a batched point-location operation on a
given arrangement. It accepts a range of query points, and locates each
point in the arrangement. The query results are returned through the output
iterator. Each result is given as a pair of the query point and an object
representing the arrangement feature that contains it, namely an
\ccc{Object} that may be either \ccc{Face_const_handle},
\ccc{Halfedge_const_handle}, or \ccc{Vertex_const_hanlde}. The resulting
iterator. Each query result is given as a pair of the query point and an
object representing the arrangement feature that contains it, namely a
discriminated union container of the bounded types\ccc{Face_const_handle},
\ccc{Halfedge_const_handle}, and \ccc{Vertex_const_hanlde}. The resulting
pairs in the output sequence are sorted in increasing $xy$-lexicographical
order of the query points. The function returns a past-the-end iterator of
the output sequence.
\paragraph{A note on Backwards compatibility}
The function \ccRefName{} used to return \ccc{CGAL::Object} up to
\cgal{} version~3.9. Starting with \cal{} version~4.0 the return type
is determined by a metafunction. To preserve backwards compatibility
\ccc{CGAL::Object} can be constructed from the new return types
implicitly, but switching to the new style is recommended. To enable
the old style without any overhead, the macro
\ccc{CGAL_ARR_POINT_LOCATION_VERSION} can be defined to 1 before any
\cgal{} header is included.
\ccInclude{CGAL/Arr_batched_point_location.h}
\ccGlobalFunction{template<typename Traits, typename Dcel,
typename PointsIterator, typename OutputIterator>
OutputIterator locate (const Arrangement_2<Traits,Dcel>& arr,
PointsIterator points_begin,
PointsIterator points_end,
OutputIterator oi);}
typename inputIterator, typename OutputIterator>
OutputIterator locate (const Arrangement_2<Traits,Dcel>& arr,
inputIterator points_begin,
inputIterator points_end,
OutputIterator oi);}
\ccRequirements
\begin{itemize}
\item \ccc{InputIterator::value_type} must be \ccc{Traits::Point_2}.
\item \ccc{OutputIterator::value_type} must be
\ccc{std::pair<Traits::Point_2,Object>}.
\item \ccc{InputIterator::value_type} must be \ccc{Arrangement_2::Point_2}.
\item \ccc{*OutputIterator} must be convertible to
\ccc{std::pair<Arrangement_2::Point_2,Arr_point_location_result<Arrangement_2>::Type>}.
\end{itemize}
\ccSeeAlso
%============
\ccRefIdfierPage{CGAL::Arr_point_location_result<Arrangement>}\\
\ccRefIdfierPage{CGAL_ARR_POINT_LOCATION_VERSION}
\end{ccRefFunction}
\ccRefPageEnd

View File

@ -130,7 +130,8 @@ implemented as peripheral classes or as free (global) functions.
\ccRefIdfierPage{CGAL::Arr_naive_point_location<Arrangement>}\\
\ccRefIdfierPage{CGAL::Arr_walk_along_line_point_location<Arrangement>}\\
\ccRefIdfierPage{CGAL::Arr_trapezoid_ric_point_location<Arrangement>}\\
\ccRefIdfierPage{CGAL::Arr_landmarks_point_location<Arrangement,Generator>}
\ccRefIdfierPage{CGAL::Arr_landmarks_point_location<Arrangement,Generator>}\\
\ccRefIdfierPage{CGAL::Arr_point_location_result<Arrangement>}\\
\subsection*{Tags}
@ -161,3 +162,7 @@ implemented as peripheral classes or as free (global) functions.
\ccc{CGAL::operator>>}
{\lcRawHtml{<A HREF="Function_operator--.html">(go there)</A>}
\lcTex{\dotfill page~\pageref{ref_arr_operator_rightshift}}}
\subsection*{Macros}
\ccRefIdfierPage{CGAL_ARR_POINT_LOCATION_VERSION}

View File

@ -69,6 +69,8 @@
\input{Arrangement_on_surface_2_ref/Arr_extended_dcel_text_formatter.tex}
\input{Arrangement_on_surface_2_ref/Arr_point_location.tex}
\input{Arrangement_on_surface_2_ref/Arr_vertical_ray_shoot.tex}
\input{Arrangement_on_surface_2_ref/Arr_point_location_version.tex}
\input{Arrangement_on_surface_2_ref/Arr_point_location_result.tex}
\input{Arrangement_on_surface_2_ref/Arr_naive_point_location.tex}
\input{Arrangement_on_surface_2_ref/Arr_walk_along_a_line_point_location.tex}
\input{Arrangement_on_surface_2_ref/Arr_trapezoid_ric_point_location.tex}