From e85a541e8ade28f08d854c1f4c71783f55cd567d Mon Sep 17 00:00:00 2001 From: Monique Teillaud Date: Thu, 3 Jan 2008 13:11:31 +0000 Subject: [PATCH] updates following the "general comments" in Efi's review --- .../doc_tex/Circular_kernel_3/CK.tex | 69 +++++++++++++------ .../BasicGeometricKernel.tex | 35 ---------- .../Circular_kernel_3_ref/CCircle_3.tex | 2 + .../Circular_kernel_3_ref/Circle_3.tex | 2 + .../GeomFunctorsOtherConstructions.tex | 4 +- .../Circular_kernel_3_ref/Intersect.tex | 6 +- .../Circular_kernel_3_ref/SphericalKernel.tex | 10 +-- .../doc_tex/Circular_kernel_3_ref/intro.tex | 4 +- .../doc_tex/Circular_kernel_3_ref/main.tex | 1 - 9 files changed, 62 insertions(+), 71 deletions(-) delete mode 100644 Circular_kernel_3/doc_tex/Circular_kernel_3_ref/BasicGeometricKernel.tex diff --git a/Circular_kernel_3/doc_tex/Circular_kernel_3/CK.tex b/Circular_kernel_3/doc_tex/Circular_kernel_3/CK.tex index f1299aef0e5..f70210085fb 100644 --- a/Circular_kernel_3/doc_tex/Circular_kernel_3/CK.tex +++ b/Circular_kernel_3/doc_tex/Circular_kernel_3/CK.tex @@ -1,22 +1,50 @@ \section{Introduction} -The goal of the 3D spherical kernel is to offer to the user a large set -of functionalities on spheres, circles and circular arcs in the 3D -space, in a similar way as what the 2D circular kernel package (see -Chapter~\ref{chapter-circular-kernel}) does in the plane. All the -choices (interface, robustness, representation, and so on) made here -are consistent with the choices made in the \cgal\ kernel, for which -we refer the user to the kernel manual. +The goal of the 3D spherical kernel is to offer to the user a large +set of functionalities on spheres, circles and circular arcs in the 3D +space. These functionalities require computing on algebraic numbers, +which motivates the creation of a new kernel concept extending the +\cgal\ \ccc{Kernel} concept, which is restricted to objects +and functionality in a \ccc{FieldNumberType}. + +All the choices (interface, robustness, representation, and so on) +made here are consistent with the choices made in the \cgal\ kernel, +for which we refer the user to the kernel manual +(Chapter~\ref{chapter-kernel-23}). + +\section{Spherical Kernel Objects\label{section-SK-objects}} + +New main geometric objects are introduced by \ccc{Spherical_kernel_3}: +circular arcs ((model of \ccc{SphericalKernel::CircularArc_3}), points +of circular arcs (model of \ccc{SphericalKernel::CircularArcPoint_3}), +and line segments (model of \ccc{SphericalKernel::LineArc_3}) whose +endpoints are points of this new type. + +\ccc{SphericalKernel::CircularArcPoint_3} is used in particular for +endpoints of arcs and intersection points between spheres, circles or +arcs. The coordinates of these points are algebraic numbers of degree +two. Therefore, general predicates offered by the \ccc{Kernel} on +\ccc{Point_3}, which have coordinates in a \ccc{FieldNumberType}, +would require heavy algebraic computations in algebraic extensions +of higher degrees and thus are not provided on +them, which explains the need for a new point type. + +A consistent set of predicates and constructions is offered on this +new type of points. The spherical kernel currently implements a set of +fundamental functionalities like intersection, comparisons, inclusion, +etc. More might be provided in the future, as long as only algebraic +numbers of degree two are used. \section{Software Design} The design of \ccc{Spherical_kernel_3} is similar to the design of -\ccc{Circular_kernel_2}. It has two template parameters: +\ccc{Circular_kernel_2} (see Chapter~\ref{chapter-circular-kernel}). +It has two template parameters: \begin{itemize} -\item {} the \ccc{LinearKernel}, from which the spherical kernel derives, -provides all elementary geometric objects like points, lines, spheres, and -elementary functionality on them. It must model the \cgal\ three -dimensional \ccc{Kernel} concept. +\item {} the first parameter must model the \cgal\ +three dimensional \ccc{Kernel} concept. The spherical kernel derives +from it, and it provides all elementary geometric objects like points, +lines, spheres, circles and elementary functionality on them. %The \cgal\ 2D Kernel can be used as parameter, %but the user may plug his own kernel %instead, as long as it follows the \cgal\ kernel concept. @@ -27,19 +55,16 @@ robustness of the package relies on the fact that the algebraic kernel provides exact computations on algebraic objects. \end{itemize} -The 3D spherical kernel uses the extensibility scheme presented in the -kernel manual (see Section~\ref{section-extensible-kernel}). -The types of \ccc{LinearKernel} are inherited -by the 3D spherical kernel and some types are taken from the -\ccc{AlgebraicKernelForSpheres} parameter. New main geometric objects are -introduced by \ccc{Spherical_kernel_3}: circles in 3D, circular arcs, -points of circular arcs (used in particular for endpoints of arcs and -intersection points between arcs), and line segments, whose endpoints -are points of this new type. +The 3D spherical kernel uses the extensibility scheme presented in the +kernel manual (see Section~\ref{section-extensible-kernel}). The types +of \ccc{Kernel} are inherited by the 3D spherical kernel and some +types are taken from the \ccc{AlgebraicKernelForSpheres} +parameter. \ccc{Spherical_kernel_3} introduces new geometric objects +as mentioned in Section~\ref{section-SK-objects}. In fact, the spherical kernel is documented as a concept, \ccc{SphericalKernel}. One model is currently provided: -\ccc{Spherical_kernel_3}. +\ccc{Spherical_kernel_3}. \section{Example} \textit{following example to be improved, and more examples and explanations to be added...} diff --git a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/BasicGeometricKernel.tex b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/BasicGeometricKernel.tex deleted file mode 100644 index 7a775c04fd7..00000000000 --- a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/BasicGeometricKernel.tex +++ /dev/null @@ -1,35 +0,0 @@ -\begin{ccRefConcept}{LinearKernel} - -\ccDefinition - -The geometric kernel parameter of \ccc{CGAL::Spherical_kernel_3} is -supposed to be a model of the \textit{(three-dimensional)} \ccc{Kernel} -concept, so that the spherical kernel provides all functionalities of a -\cgal\ kernel. - -%In fact, even though all types and operations of the -%\ccc{CGAL::Kernel} concept are required so that -%\ccc{CGAL::Circular_kernel_2} actually refines \ccc{CGAL::Kernel}, only -%the following types are explicitly used by \ccc{Circular_kernel_2} and -%can thus be considered as minimal requirements: - -%\ccNestedType{RT}{A model of \ccc{RingNumberType}.} -%\ccNestedType{FT}{A model of \ccc{FieldNumberType}.} \footnote{concept template...?} - -%\ccNestedType{Point_2}{A model of \ccc{Point_2}.} -%\ccNestedType{Line_2}{A model of \ccc{Line_2}.} -%\ccNestedType{Circle_2}{A model of \ccc{Circle_2}.} -%\ccNestedType{Object_2}{A model of \ccc{Object_2}.} - -%Note that all operations on these types are also required. - -\ccHasModels - -All \cgal\ kernels - -\ccSeeAlso - -\ccRefIdfierPage{Kernel}\\ -\ccRefIdfierPage{SphericalKernel} - -\end{ccRefConcept} diff --git a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/CCircle_3.tex b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/CCircle_3.tex index ce695948db3..c09c7ec9e7a 100644 --- a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/CCircle_3.tex +++ b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/CCircle_3.tex @@ -1,6 +1,8 @@ \begin{ccRefConcept}{SphericalKernel::Circle_3} +TO BE MOVED TO KERNEL + Concept for circles in 3D. \ccRefines diff --git a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/Circle_3.tex b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/Circle_3.tex index d6cbc304a2d..fa0f9b482ce 100644 --- a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/Circle_3.tex +++ b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/Circle_3.tex @@ -1,5 +1,7 @@ \begin{ccRefClass}{Circle_3} +TO BE MOVED TO KERNEL + \ccInclude{CGAL/Circle_3.h} \ccIsModel diff --git a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/GeomFunctorsOtherConstructions.tex b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/GeomFunctorsOtherConstructions.tex index 01de1bfed14..63b372384e2 100644 --- a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/GeomFunctorsOtherConstructions.tex +++ b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/GeomFunctorsOtherConstructions.tex @@ -1,7 +1,7 @@ \begin{ccRefFunctionObjectConcept}{SphericalKernel::ConstructRadicalPlane_3} \ccCreationVariable{fo} -\textbf{!!!!!!! could go to Kernel} +TO BE MOVED TO KERNEL An object \ccVar\ of this type must provide: @@ -21,6 +21,8 @@ The \textit{power} of \ccc{p} with respect to a sphere \ccc{s} centered at \begin{ccRefFunctionObjectConcept}{SphericalKernel::ConstructDiametralSphere_3} \ccCreationVariable{fo} +TO BE MOVED TO KERNEL + An object \ccVar\ of this type must provide: \ccMemberFunction{SphericalKernel::Sphere_3 diff --git a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/Intersect.tex b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/Intersect.tex index 75b34dab7e5..0d131329bdf 100644 --- a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/Intersect.tex +++ b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/Intersect.tex @@ -30,9 +30,7 @@ when this ordering is defined on the computed objects.} For the \textbf{first operator}, \ccc{Type1} and \ccc{Type2} can both be either -\textbf{!!!!!!! we coded here the intersection \ccc{Line_3}-\ccc{Line_3}, -since it was apparently forgotten in \ccc{CGAL::Kernel}, this code -should be moved there} +\textbf{!!!!!!! intersection \ccc{Line_3}-\ccc{Line_3} TO BE MOVED TO KERNEL} \begin{itemize} \item {} \ccc{SphericalKernel::Sphere_3}, @@ -62,7 +60,7 @@ line segments. For the \textbf{second operator}, \ccc{Type1}, \ccc{Type2} and \ccc{Type3} can be either -\textbf{!!!!!!! case of 3 planes is missing, again it should be in Kernel} +\textbf{!!!!!!! case of 3 planes TO BE MOVED TO KERNEL} \begin{itemize} \item {} \ccc{SphericalKernel::Sphere_3} or diff --git a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/SphericalKernel.tex b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/SphericalKernel.tex index ee5ce30bc25..f17132406a9 100644 --- a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/SphericalKernel.tex +++ b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/SphericalKernel.tex @@ -4,14 +4,14 @@ \ccc{Kernel} \ccHasModels -\ccc{CGAL::Spherical_kernel_3}\\ +\ccc{CGAL::Spherical_kernel_3}\\ \ccc{Exact_spherical_kernel_3} \ccTypes A model of \ccc{SphericalKernel} is supposed to provide some basic types -\ccNestedType{Linear_kernel}{Model of \ccc{LinearKernel}.} +\ccNestedType{Linear_kernel}{Model of \ccc{Kernel}.} \ccGlue \ccNestedType{Algebraic_kernel}{Model of \ccc{AlgebraicKernelForSpheres}.} @@ -37,7 +37,7 @@ and to define the following geometric objects \ccGlue \ccNestedType{Sphere_3}{Model of \ccc{Kernel::Sphere_3}.} -\ccNestedType{Circle_3}{Model of \ccc{SphericalKernel::Circle_3}.} +\ccNestedType{Circle_3}{Model of \ccc{Kernel::Circle_3}.} \ccGlue \ccNestedType{Line_arc_3}{Model of \ccc{SphericalKernel::LineArc_3}.} \ccGlue @@ -104,8 +104,8 @@ constructions and other functionalities. \ccGlue \ccNestedType{Construct_supporting_circle_3}{Model of \ccc{SphericalKernel::ConstructSupportingCircle_3}.} -\ccNestedType{Construct_diametral_sphere_3}{Model of \ccc{SphericalKernel::ConstructDiametralSphere_3}.} -\ccNestedType{Construct_radical_plane_3}{Model of \ccc{SphericalKernel::ConstructRadicalPlane_3}.\textbf{!!!!!!! could go to Kernel}} +\ccNestedType{Construct_diametral_sphere_3}{Model of \ccc{SphericalKernel::ConstructDiametralSphere_3}.TO BE MOVED TO KERNEL} +\ccNestedType{Construct_radical_plane_3}{Model of \ccc{SphericalKernel::ConstructRadicalPlane_3}. TO BE MOVED TO KERNEL} \ccNestedType{Construct_bbox_3}{Model of \ccc{SphericalKernel::ConstructBbox_3}.} diff --git a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/intro.tex b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/intro.tex index 3542b00605d..e4ab9f50328 100644 --- a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/intro.tex +++ b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/intro.tex @@ -7,8 +7,6 @@ \ccRefConceptPage{SphericalKernel} -\ccRefConceptPage{LinearKernel} - \subsubsection*{Functors} \ccRefConceptPage{SphericalKernel::ConstructPlane_3}\\ @@ -96,7 +94,7 @@ \ccRefIdfierPage{CGAL::Circular_arc_point_3} - \subsubsection*{Circles} + \subsubsection*{Circles - to be moved to Kernel} \ccRefIdfierPage{CGAL::Circle_3} diff --git a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/main.tex b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/main.tex index 9272f3dbe43..dc2129428f8 100644 --- a/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/main.tex +++ b/Circular_kernel_3/doc_tex/Circular_kernel_3_ref/main.tex @@ -4,7 +4,6 @@ % geometric kernels \input{Circular_kernel_3_ref/SphericalKernel} -\input{Circular_kernel_3_ref/BasicGeometricKernel} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % geometric objects