diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Arrangement_on_surface_2.txt b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Arrangement_on_surface_2.txt index 4585d9fd3b3..c4249afaa67 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Arrangement_on_surface_2.txt +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Arrangement_on_surface_2.txt @@ -5407,6 +5407,34 @@ identification curve is drawn as a gray tube. \cgalExample{Arrangement_on_surface_2/spherical_insert.cpp} +Use the `Arr_geodesic_arc_on_sphere_traits_2::Construct_point_2`, +`Arr_geodesic_arc_on_sphere_traits_2::Construct_x_monotone_curve_2`, +and `Arr_geodesic_arc_on_sphere_traits_2::Construct_curve_2` functors +to construct a point, an \f$X\f$-monotone curve and a curve objects, +respectively. Observe that an \f$X\f$-monotone curve cannot intersect +the identification curve in its interior. A curve can be constructed +from either (i) two endpoints, (ii) two endpoints and a normal, or +(iii) a normal. The two endpoints determine the plane. The normal +determines the orientation of the plane and the final arc (whether it +is the minor arc or the major arc). If the normal is not provided, the +minor arc is constructed. If a curve is constructed and only the +normal is provided a full great circle is constructed. If an +\f$X\f$-monotone curve is constructed and only the normal is provided +an arc that resembles a full circle is constructed; this arc has one +endpoint that lies on the identification curve; this point is +considered both the source and target (and also the left and right) +point of the arc. See \cgalFigureRef{aos_fig-right_hand_rule} for an +illustration of the right-hand rule, which depicts the relation +between the arc and the normal. + + +\cgalFigureBegin{aos_fig-right_hand_rule,right_hand_rule.png} +To use the right hand rule, point your right thumb in the direction of +the normal and curl your fingers in the direction of the arc starting +with source pendpoint and endding at the target endpoint. +\cgalFigureEnd + + \subsection arr_ssecmeta_tr Traits-Class Decorators diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_geodesic_arc_on_sphere_traits_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_geodesic_arc_on_sphere_traits_2.h index e375b142e38..4f599f66a41 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_geodesic_arc_on_sphere_traits_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_geodesic_arc_on_sphere_traits_2.h @@ -359,20 +359,29 @@ namespace CGAL { * \param[in] q the second endpoint. * \pre p and q must not coincide. * \pre p and q cannot be antipodal. + * \pre The constructed minor arc does not intersect the identification + * curve in its interior. */ X_monotone_curve_2 operator()(const Point_2& p, const Point_2& q); /*! Construct a full great circle from a normal to a plane. + * Observe that the constrcted arc has one endpoint that lies on + * the identification curve. This point is considered both the source and + * target (and also the left and right) point of the arc. * \param normal the normal to the plane containing the great circle. * \pre the plane is not vertical. */ X_monotone_curve_2 operator()(const Direction_3& normal); - /*! Construct a geodesic arc from two endpoints contained in a plane. + /*! Construct a geodesic arc from two endpoints and a normal to the plane + * containing the arc. The two endpoints determine the plane. The normal + * determines the orientation of the plane and the final arc (whether its + * the minor arc or the major arc). The right-hand rule can be used + * to select the appropriate normal. * \param[in] p the first endpoint. * \param[in] q the second endpoint. - * \param[in] normal the normal to the plane containing the arc. - * \pre Both endpoints lie on the given plane. + * \param[in] normal the normal to the oriented plane containing the arc. + * \pre Both endpoints lie on the given oriented plane. */ X_monotone_curve_2 operator()(const Point_2& p, const Point_2& q, const Direction_3& normal); diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/fig/right_hand_rule.png b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/fig/right_hand_rule.png new file mode 100644 index 00000000000..3beebbf7b19 Binary files /dev/null and b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/fig/right_hand_rule.png differ