\ccRefPageBegin

\begin{ccRefConcept}{EnvelopeTraits_3}

\ccDefinition
% ===========

This concept defines the minimal set of geometric predicates and
operations needed to compute the envelope of a set of arbitrary
surfaces in $\reals^3$. It refines the arrangement-traits concept.
In addition to the \ccc{Point_2}, \ccc{X_monotone_curve_2} and
\ccc{Curve_2} types defined in the arrangement-traits concept, it
also defines the types \ccc{Surface_3} and \ccc{Xy_monotone_surface_3}
types, which represent arbitrary surfaces and $xy$-monotone surfaces,
respectively, and support some constructions and predicates on these
types. Note however, that these operations usually involve the
projection of 3D objects onto the $xy$-plane.

\ccRefines
\ccc{ArrangementTraits_2}

\ccTypes
% ======

\ccNestedType{Surface_3}
{represents an arbitrary surface in $\reals^3$.}
\ccGlue
\ccNestedType{Xy_monotone_surface_3}
{represents a weakly $xy$-monotone surface in $\reals^3$.}

\ccHeading{Functor Types}
% =======================

\ccThree{Compare_y_at_x_2}{}{\hspace*{14cm}}
\ccThreeToTwo

\ccNestedType{Make_xy_monotone_3}
{provides the operator (templated by the \ccc{OutputIterator} type)~:
 \begin{itemize}
 \item \ccc{OutputIterator operator() (Surface_3 S, bool is_lower,
                                       OutputIterator oi)} \\
 which subdivides the given surface \ccc{S} into $xy$-monotone parts
 and inserts them into the output iterator. The value of
 \ccc{is_lower} indicates whether we compute the lower or the upper
 envelope, so that $xy$-monotone surfaces that are irrelevant to the
 lower-envelope (resp. upper-envelope) computation may be discarded.
 The value-type of \ccc{OutputIterator} is \ccc{Xy_monotone_surface_3}.
 The operator returns a past-the-end iterator for the output sequence.
 \end{itemize}}

\ccNestedType{Construct_projected_boundary_curves_2}
{provides the operator (templated by the \ccc{OutputIterator} type)~:
 \begin{itemize}
 \item \ccc{OutputIterator operator() (Xy_monotone_surface_3 s, OutputIterator oi)} \\
 which computes all planar curves that form the projection of the
 boundary of the given $xy$-monotone surface $s$ onto the $xy$-plane,
 and inserts them into the output iterator. 
 The value-type of \ccc{OutputIterator} is \ccc{Curve_2}.
 The operator returns a past-the-end iterator for the output sequence.
 \end{itemize}}
 
\ccNestedType{Construct_projected_intersections_2}
{provides the operator (templated by the \ccc{OutputIterator} type)~:
 \begin{itemize}
 \item \ccc{OutputIterator operator() (Xy_monotone_surface_3 s1,
                                       Xy_monotone_surface_3 s2,
                                       OutputIterator oi)} \\
 which computes the projection of the intersections of the
 $xy$-monotone surfaces \ccc{s1} and \ccc{s2} onto the $xy$-plane,
 and inserts them into the output iterator.
 The value-type of \ccc{OutputIterator} is \ccc{CGAL::Object}, where
 each \ccc{Object} either wraps a \ccc{pair<Curve_2,Multiplicity>}
 instance, which represents a projected intersection curve with its
 multiplicity (in case the multiplicity is undefined or not known, it
 should be set to $0$) or an \ccc{Point_2} instance, representing the
 projected image of a degenerate intersection (the projection of an
 isolated intersection point, or of a vertical intersection curve).
 The operator returns a past-the-end iterator for the output sequence.
 \end{itemize}}

\ccNestedType{Compare_z_at_xy_3}
{provides the operators~:
 \begin{itemize}
 \item \ccc{Comparison_result operator() (Point_2 p,
                                          Xy_monotone_surface_3 s1,
                                          Xy_monotone_surface_3 s2)}\\
 which determines the relative $z$-order of the two given $xy$-monotone
 surfaces at the $xy$-coordinates of the point \ccc{p}, with the
 precondition that both surfaces are defined over \ccc{p}. Namely, it
 returns the comparison result of $s_1(p)$ and $s_2(p)$.
%
 \item \ccc{Comparison_result operator() (X_monotone_curve_2 c,
                                          Xy_monotone_surface_3 s1,
                                          Xy_monotone_surface_3 s2)}\\
 which determines the relative $z$-order of the two given $xy$-monotone
 surfaces over the interior of a given $x$-monotone curve $c$, with the
 precondition that $c$ is fully contained in the $xy$-definition range
 of both $s_1$ and $s_2$, and that the surfaces do not intersect over
 $c$. The functor should therefore return the comparison result of
 $s_1(p')$ and $s_2(p')$ for some point $p'$ in the interior of $c$.
 \end{itemize}}

\ccNestedType{Compare_z_at_xy_above_3}
{provides the operator~:
 \begin{itemize}
 \item \ccc{Comparison_result operator() (X_monotone_curve_2 c,
                                          Xy_monotone_surface_3 s1,
                                          Xy_monotone_surface_3 s2)}\\
 which determines the relative $z$-order of the two given $xy$-monotone
 surfaces immediately above their projected intersection curve
 $c$ (a planar point $p$ is {\em above} an $x$-monotone curve $c$ if it
 is in the $x$-range of $c$, and lies to its left when the curve is
 traversed from its $xy$-lexicographically smaller endpoint to its
 larger endpoint). We have the precondition that both surfaces are
 defined ``above'' $c$, and their relative $z$-order is the same for
 some small enough neighborhood of points above $c$.
 \end{itemize}}

\ccNestedType{Compare_z_at_xy_below_3}
{provides the operator~:
 \begin{itemize}
 \item \ccc{Comparison_result operator() (X_monotone_curve_2 c,
                                          Xy_monotone_surface_3 s1,
                                          Xy_monotone_surface_3 s2)}\\
 which determines the relative $z$-order of the two given $xy$-monotone
 surfaces immediately below their projected intersection curve
 $c$ (a planar point $p$ is {\em below} an $x$-monotone curve $c$ if it
 is in the $x$-range of $c$, and lies to its right when the curve is
 traversed from its $xy$-lexicographically smaller endpoint to its
 larger endpoint). We have the precondition that both surfaces are
 defined ``below'' $c$, and their relative $z$-order is the same for
 some small enough neighborhood of points below $c$.
 \end{itemize}}

\ccCreation
\ccCreationVariable{traits}
% =========================

\ccThree{EnvelopeTraits_3~~~}{}{\hspace*{8cm}}
\ccThreeToTwo

\ccConstructor{EnvelopeTraits_3();}{default constructor.}
\ccGlue
\ccConstructor{EnvelopeTraits_3(EnvelopeTraits_3 other);}
{copy constructor.}
\ccGlue
\ccMethod{EnvelopeTraits_3 operator=(other);}{assignment operator.}

\ccHeading{Accessing Functor Objects}
%====================================

\ccThree{Construct_projected_boundary_curves_2~~~}{}{\hspace*{7cm}}
\ccThreeToTwo

\ccMethod{Make_xy_monotone_3 make_xy_monotone_3_object();}
{}
\ccGlue
\ccMethod{Construct_projected_boundary_curves_2 construct_projected_boundary_curves_2_object();}
{}
\ccGlue
\ccMethod{Construct_projected_intersections_2 construct_projected_intersections_2_object();}
{}
\ccGlue
\ccMethod{Compare_z_at_xy_3 compare_z_at_xy_3_object();}
{}
\ccGlue
\ccMethod{Compare_z_at_xy_above_3 compare_z_at_xy_above_3_object();}
{}
\ccGlue
\ccMethod{Compare_z_at_xy_below_3 compare_z_at_xy_below_3_object();}
{}

\ccHasModels
%===========
\ccc{CGAL::Envelope_triangle_traits_3<Kernel>}\\
\ccc{CGAL::Envelope_sphere_traits_3<ConicTraits>}\\
\ccc{CGAL::Env_surface_data_traits_2<Traits,XyData,SData,Cnv>}

\end{ccRefConcept}

\ccRefPageEnd