songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rephrasing and restructuring (mainly in I/O parts).

This commit is contained in:
Shai Hirsch 2001-06-19 15:50:47 +00:00
parent fbffa41056
commit be7eb71c08
14 changed files with 454 additions and 354 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
Packages/Planar_map/doc_tex/Planar_map/Planar_map_ref/File_header.tex
View File

@ -11,16 +11,21 @@
%%RefPage: end of header, begin of main body
% +------------------------------------------------------------------------+
\renewcommand{\ccRefPageBegin}{\begin{ccAdvanced}}
\renewcommand{\ccRefPageEnd}{\end{ccAdvanced}}
%File_header
\begin{ccRefClass}{File_header}
\ccCreationVariable{file_header}
\ccDefinition
Generally, the \ccRefName \/ class contains configurations the user defines before using the I/O functions.
These configurations concern the verbose flag, writing a file with or without comments, etc.
The class is the base class of the classes \ccc{Pm_file_scanner} and \ccc{Pm_file_writer}.
The list of parameters for \ccRefName\/ is as follows:
Generally, the \ccRefName \/ class defines and sets parameters that
should be defined while using the I/O functions. This configuration
includes the verbose flag, a flag that controls writing a file with or
without comments, etc. The class is the base class of the classes
\ccc{Pm_file_scanner} and \ccc{Pm_file_writer}. The list of
parameters for \ccRefName\/ is as follows:
\begin{itemize}
\item {\bf verbose } define a verbose format for printing the \ccc{Planar map}. This flag is set by default to false.
@ -51,53 +56,58 @@ When creating a \ccRefName \/ object, the user sets the parameters as needed.
{constructs \ccRefName\ with \ccc{v} vertices \ccc{h} halfedges and \ccc{f} faces, the other parameters can also be set by the user, otherwise they are set to their default values.}
\ccConstructor{File_header(const File_header& file_header);}
{copy constructor.}
{copy construction.}
\ccModifiers
\ccThree{size_t}{file_header.set_number_of_verticesaaa(size_t n);}{}
\ccMethod{void set_verbose(bool b);}{sets the verbose flag to b.}
\ccGlue
\ccMethod{void set_ascii(bool b);} {sets the ascii flag to b.}
\ccMethod{void set_no_comments(bool b);} \ccGlue{sets the no\_comments flag to b.}
\ccMethod{void set_index_offset(int i);} \ccGlue{sets index\_offset to i.}
\ccMethod{void set_colors(bool b);} \ccGlue{sets the colors flag to b.}
\ccMethod{void set_dimension(int i);} \ccGlue{sets the dimension to i.}
\ccMethod{void set_number_of_vertices(size_t n);} \ccGlue{sets the number of vertices to n.}
\ccMethod{void set_number_of_halfedges(size_t n);} \ccGlue{sets the number of halfedges to n.}
\ccMethod{void set_number_of_faces(size_t n);} \ccGlue{sets the number of faces to n.}
\ccGlue
\ccMethod{void set_no_comments(bool b);}{sets the no\_comments flag to b.}
\ccGlue
\ccMethod{void set_index_offset(int i);}{sets index\_offset to i.}
\ccGlue
\ccMethod{void set_colors(bool b);}{sets the colors flag to b.}
\ccGlue
\ccMethod{void set_dimension(int i);}{sets the dimension to i.}
\ccGlue
\ccMethod{void set_number_of_vertices(size_t n);}{sets the number of vertices to n.}
\ccGlue
\ccMethod{void set_number_of_halfedges(size_t n);}{sets the number of halfedges to n.}
\ccGlue
\ccMethod{void set_number_of_faces(size_t n);}{sets the number of faces to n.}
\ccAccessFunctions
%\ccGlueBegin
\ccMethod{bool verbose();} \ccGlue{returns true if the format is verbose.}
\ccMethod{bool ascii();} \ccGlue{returns true if the format is given by ascii.}
\ccMethod{bool no_comments();} \ccGlue{returns true if the format is defined without comments.}
\ccMethod{bool comments();} \ccGlue{returns true if the format is defined with comments.}
\ccMethod{int index_offset();} \ccGlue{returns the offset defined for the indices in the format.}
\ccMethod{bool has_colors();} \ccGlue{returns true if the format presents the \ccc{Planar map} by colors.}
\ccMethod{int dimension();} \ccGlue{returns the dimension defined by the format.}
\ccMethod{size_t number_of_vertices();} \ccGlue{returns the number of vertices defined by the format.}
\ccMethod{size_t number_of_halfedges();} \ccGlue{returns the number of halfedges defined by the format.}
\ccMethod{size_t number_of_faces();} \ccGlue{returns the number of faces defined by the format.}
\ccMethod{bool verbose();}{returns true if the format is verbose.}
\ccGlue
\ccMethod{bool ascii();}{returns true if the format is given by ascii.}
\ccGlue
\ccMethod{bool no_comments();}{returns true if the format is defined without comments.}
\ccGlue
\ccMethod{bool comments();}{returns true if the format is defined with comments.}
\ccGlue
\ccMethod{int index_offset();}{returns the offset defined for the indices in the format.}
\ccGlue
\ccMethod{bool has_colors();}{returns true if the format presents the \ccc{Planar map} by colors.}
\ccGlue
\ccMethod{int dimension();}{returns the dimension defined by the format.}
\ccGlue
\ccMethod{size_t number_of_vertices();}{returns the number of vertices defined by the format.}
\ccGlue
\ccMethod{size_t number_of_halfedges();}{returns the number of halfedges defined by the format.}
\ccGlue
\ccMethod{size_t number_of_faces();}{returns the number of faces defined by the format.}
%\ccGlueEnd
\end{ccRefClass} % File_header
\renewcommand{\ccRefPageBegin}{}
\renewcommand{\ccRefPageEnd}{}
% +------------------------------------------------------------------------+
%%RefPage: end of main body, begin of footer
\ccRefPageEnd

6
Packages/Planar_map/doc_tex/Planar_map/Planar_map_ref/Pm_drawer.tex
View File

@ -11,6 +11,9 @@
%%RefPage: end of header, begin of main body
% +------------------------------------------------------------------------+
\renewcommand{\ccRefPageBegin}{\begin{ccAdvanced}}
\renewcommand{\ccRefPageEnd}{\end{ccAdvanced}}
%Pm_file_writer
\begin{ccRefClass}{Pm_drawer<Planar_map, Window>}
@ -67,6 +70,9 @@ Wherever the handles appear in function parameter lists, the appropriate iterato
\end{ccRefClass} % Pm_file_writer
\renewcommand{\ccRefPageBegin}{}
\renewcommand{\ccRefPageEnd}{}
% +------------------------------------------------------------------------+
%%RefPage: end of main body, begin of footer
\ccRefPageEnd

7
Packages/Planar_map/doc_tex/Planar_map/Planar_map_ref/Pm_file_scanner.tex
View File

@ -10,6 +10,8 @@
%%RefPage: end of header, begin of main body
% +------------------------------------------------------------------------+
\renewcommand{\ccRefPageBegin}{\begin{ccAdvanced}}
\renewcommand{\ccRefPageEnd}{\end{ccAdvanced}}
%Pm_file_scanner
\begin{ccRefClass}{Pm_file_scanner<Planar_map>}
@ -28,6 +30,8 @@ This class is templated with \ccc{Planar map}, and hence the user can work with
\ccTypes
\ccTwo{Pm_file_scanner<Planar_map>::D_halfedge_bla}{}
\ccNestedType{Traits}{Representation of a bounded curve.}
\ccNestedType{Point}{A type to hold the location of a vertex in the plane.}
\ccNestedType{X_curve}{A type to hold an $x$-monotone curve in the plane.}
@ -61,6 +65,9 @@ does not update its halfedge with the curve.}
\end{ccRefClass} % Pm_file_scanner
\renewcommand{\ccRefPageBegin}{}
\renewcommand{\ccRefPageEnd}{}
% +------------------------------------------------------------------------+
%%RefPage: end of main body, begin of footer
\ccRefPageEnd

6
Packages/Planar_map/doc_tex/Planar_map/Planar_map_ref/Pm_file_writer.tex
View File

@ -11,6 +11,9 @@
%%RefPage: end of header, begin of main body
% +------------------------------------------------------------------------+
\renewcommand{\ccRefPageBegin}{\begin{ccAdvanced}}
\renewcommand{\ccRefPageEnd}{\end{ccAdvanced}}
%Pm_file_writer
\begin{ccRefClass}{Pm_file_writer<Planar_map>}
@ -107,6 +110,9 @@ comments are defined only if the comments flag is set to true:
\end{ccRefClass} % Pm_file_writer
\renewcommand{\ccRefPageBegin}{}
\renewcommand{\ccRefPageEnd}{}
% +------------------------------------------------------------------------+
%%RefPage: end of main body, begin of footer
\ccRefPageEnd

2
Packages/Planar_map/doc_tex/Planar_map/Planar_map_ref/draw_pm.tex
View File

@ -28,6 +28,8 @@ a templated parameter, he may call this function with any graphic
stream he chooses as long as functions for writing the geometric
components are provided in his graphic stream.
\ccInclude{CGAL/IO/draw_pm.h}
\end{ccRefFunction} % writer_pm
% +------------------------------------------------------------------------+

281
Packages/Planar_map/doc_tex/Planar_map/Planar_map_ref/intro.tex
View File

@ -68,6 +68,156 @@ There are several supplied traits classes for the \ccc{Arrangement} which the us
These classes are described at the end of Chapter \ref{I1_ChapterArrangement_2}
(\ccc{2D Arrangements}).
\subsection*{I/O functions}
The \ccc{Planar Map} package supports I/O functions, which include reading a planar map representation from
the standard input or writing it to the standard output,
and also sending a planar map to a graphic stream.
The motivation for using I/O functions is not only to be able to draw
the planar map to a window for instance,
but also to be capable to save planar maps in a text file
and reload it from a text file when needed.
The format of the output file is defined in a way the reading function
will be able to construct the planar map by updating directly the
\ccc{Dcel} without using the insertion functions of the \ccc{Planar
map}. Consequently, the reading function constructs the planar map
very efficiently. Obviously, for very big maps or for repetitive use
of the same map it would be exteremly faster to build the map only
once (incrementaly or via a sweep line utility), save it and reload
the ready map when necessary.
Reading a planar map from the standard input or printing it to the
standard output may be done simply with the \ccc{Extractor} (\ccc{ >>
}) and \ccc{Insertor} (\ccc{ << }) operators defined for
\ccc{Planar_map_2}, respectively.
\ccInclude{CGAL/IO/Pm_iostream.h}
The ability of sending the \ccc{Planar map}
into a graphic stream as \ccStyle{leda_window}, Postscript file or
Geomview is also provided, users simply have to apply the Insertor
operator on the graphic stream and their planar map instance.
\begin{ccAdvanced}
\subsection*{I/O for User Defined Planar Maps and the I/O Format}
Users may wish to add their own attributes planar map components. If
those attributes are to be written as part of the planar map
representation (respectively, are to be re-read later) a specialized
reader (scanner) class (writer class, resp.) should be defined for the special
planar map. This is done preferably by making it a sub class of the class
\ccStyle{Pm_file_scanner} (\ccStyle{Pm_file_writer}, resp.) and
overriding all the relevant function for scanning (writing, resp.) the
changed components.
After the definition of the inherited class users have to call the function
\ccStyle{read} of \ccc{Planar map} (resp., the global function \ccStyle{write_pm} ) with the inherited class as a parameter.
The same goes for extending the output graphic streams to include
additional attributes only for this purpose a new \ccc{drawer}\/ class
has to be defined. This is done preferably by making this class
inherit the class
\ccStyle{Pm_drawer}. In order to send the special planar map to the graphic stream one should call the global function \ccStyle{draw_pm}
with this class and their planar map as parameters.
\paragraph{Format}
\ccRefLabel{Pm_IO_format}
The chosen format does not follow an existing standard format.
Generally, the format contains lists of the components of a planar map
followed by each other. For each component we write its associative
geometric information and some topological information in order to be
able to update the \ccc{Dcel} efficiently. The format is detailed
below.
\begin{enumerate}
\item The data begins with a line of three integer values specifying the number of vertices,
halfedges and faces in the planar map.
\item The vertices list: each component in the vertices list contains the point of its associative vertex.
\item The halfedges list: each halfedge component is written by an index indicating the vertex origin
of the halfedge, and a curve specifying the halfedge's curve.
\item The faces list: each component in the faces list contains its outer boundary,
if the face is bounded, and a list of its holes which can be empty in case the face
has no holes. The format of the outer boundary is the number of halfedges of its connected
component followed by the indices indicating the halfedges of that component, those indices
have the same order of the halfedges on the connected component.
The format of the list of the holes is first the number of holes followed by the connected
components per each hole, the format of each connected components resembles the format
of the outer boundary specified above.
\item Lines begining with '\#' serve as comments and are ignored.
\item The format does not differentiate between spaces and new lines,
except new lines which belong to commented lines.
And hence, writing the planar in one single line having no comments is also considered legal.
If users would like to keep the commented lines, they may write all the
components between two consecutive commented lines in one single line.
\end{enumerate}
The current format may not be comfortable for a user to read because
of the extensive use of indices. The user can print a planar map in a
verbose format (shorthand for verbose mode format). The skeleton fo
the verbose format is the same. However, in order for the output to be
clearer for a human reader points and halfedges are explicitly written
rather than being represented by indices. Also the direction of the
halfedges are printed in a more convenient way to read. This verbose
format cannot be scanned by the reading functions of
\ccc{Planar_map_2}.
\ccExample
The example below presents a representation of a planar map containing
one triangle with the coordinates {\em (0,0)}, {\em (1,1)} and {\em
(2,0)}. The \ccc{Planar_map_2} instance that was used to produce this
example was templated with the \ccStyle{Pm_segment_exact_traits}
class, which in turn was templated with the representation class
\ccStyle{Cartesian<leda_rational>}. The first line specifys that the
planar map has three vertices, six halfedges, and 2 faces (the
triangle and the unbounded face). The list of vertices each
represented by its associated point follows, as shown in the output
example. The next list is the one of halfedges, each component is
represented by its index (0,1 or 2) in the vertices list and its
associated segment. The faces list is presented next. It starts with
the \ccStyle{unbounded face} having one hole which is the triangle,
this connected component specifies that the hole has three halfedges
with the indices 4, 0 and 3. The next face presenting the triangle is
written in the same manner.
\ccIncludeExampleCode{Planar_map/example9.cin}
\subsection*{Example of User Defined I/O Functions}
\label{PM_sec:example10}
The following program demonstrates the usage of I/O functions while users have
an additional attribute in their planar map.
The attribute chosen here is adding an associative color to each vertex.
First the program extends the \ccc{Dcel} to maintain this attribute.
Second, the program extends the \ccc{Pm_file_writer} class to handle the newly
defined vertex.
It simply overrides the functions for writing a vertex to print the color of the vertex as well.
Finally, the main function defines an empty \ccc{Planar map},
reads it from the standard input stream, and then set all vertices colors. It then defines an object of its extended writer class and
parameterize the function \ccc{write_pm} with that object.
\ccIncludeExampleCode{Planar_map/example10.C}
The input of the program is a text file presenting the \ccc{Planar map}:
\ccIncludeExampleCode{Planar_map/example10.cin}
The output is the \ccc{Planar map} written in both formats, non verbose and verbose. In addition the two lists
(non verbose and verbose) of halfedges are written.
\ccIncludeExampleCode{Planar_map/example10.cout}
More details are given in sections
\ccc{File_header}\lcTex{
(\ccRefPage{CGAL::File_header})},
\ccc{Pm_file_scanner<Planar_map>}\lcTex{
(\ccRefPage{CGAL::Pm_file_scanner<Planar_map>})},
\ccc{Pm_file_writer<Planar_map>}\lcTex{
(\ccRefPage{CGAL::Pm_file_writer<Planar_map>})} and
\ccc{Pm_drawer<Planar_map>}\lcTex{
(\ccRefPage{CGAL::Pm_drawer<Planar_map, Window>})}.
\end{ccAdvanced}
\begin{ccAdvanced}
\subsection*{Point Location Strategies}
@ -183,137 +333,6 @@ additional functions, namely to model the \ccc{Pm_bounding_box_traits} concept
%% add \ccInheritFrom{Pm_bounding_box_base<Planar_map>} to each
%% of these classes
\end{ccAdvanced}
\begin{ccAdvanced}
\subsection*{I/O functions}
The \ccc{Planar map} package supports I/O functions, which include reading a planar map representation from
the standard input or writing it to the standard output,
and also sending a planar map to a graphic stream.
The motivation for using I/O functions is not only to be able to draw
the planar map to a window for instance,
but also to be capable to save planar maps in a text file by writing it
and reloading it from a text file by reading it.
The format of the output file is defined in a way the reading function will be
able to constructs the planar map by updating directly the \ccc{Dcel} without
using the insertion functions of the \ccc{Planar map}.
Consequently, the reading function constructs the planar map very
efficiently, and hence users who would like to save their planar map and reload
it have to construct their planar map by the insertion functions only once,
after saving the planar map to a text file it can be reloaded very efficiently
when needed.
When users would like to read their planar map from the standard input or print
it to the standard output, they may simply use the \ccc{Extractor} (\ccc{ >> })
and \ccc{Insertor} (\ccc{ << }) operators defined for \ccc{Planar map}
respectively.
If users add attributes to their planar map components, reading (resp. writing) planar map would
be done by inheriting the class \ccStyle{Pm_file_scanner} (resp. \ccStyle{Pm_file_writer} )
and overriding all the relevant function for scanning (resp. writing)
the planar map components.
After the definition of the inherited class users have to call the function
\ccStyle{read} of \ccc{Planar map} (resp. the global function \ccStyle{write_pm} ) with the inherited class as a parameter.
The ability of sending the \ccc{Planar map} into a graphic stream as
\ccStyle{leda_window}, Postscript file or Geomview is also provided,
users simply have to use the Insertor operator operated on the graphic stream and their planar map.
When users would like to add attributes to their planar map components and
send their planar maps to a graphic stream, they have to inherit the class
\ccStyle{Pm_drawer} and then call the global function \ccStyle{draw_pm}
with this class and their planar map as parameters.
\paragraph{Format}
\ccRefLabel{Pm_IO_format}
The chosen format does not follow an existing standard format.
Generally, the format contains lists of the components of
\ccc{Planar map} followed by each other,
and for each component we write its associative geometric information and
some topological information in order to be able to update
the \ccc{Dcel} efficiently. The format is detailed below:
\begin{enumerate}
\item The data begins with a line of three integer values specifying the number of vertices,
halfedges and faces the \ccc{Planar map} has.
\item The vertices list: each component in the vertices list contains the point of its associative vertex.
\item The halfedges list: each halfedge component is written by an index indicating the vertex origin
of the halfedge, and a curve specifying the halfedge's curve.
\item The faces list: each component in the faces list contains its outer boundary,
if the face is bounded, and a list of its holes which can be empty in case the face
has no holes. The format of the outer boundary is the number of halfedges of its connected
component followed by the indices indicating the halfedges of that component, those indices
have the same order of the halfedges on the connected component.
The format of the list of the holes is first the number of holes followed by the connected
components per each hole, the format of each connected components resembles the format
of the outer boundary specified above.
\item Lines begining with '\#' serve as comments and are ignored.
\item The format does not differentiate between spaces and new lines,
except new lines which belong to commented lines.
And hence, writing the planar in one single line having no comments is also considered legal.
If users would like to keep the commented lines, they may write all the
components between two consecutive commented lines in one single line.
\end{enumerate}
\ccExample {of usage in I/O functions}
\ccIncludeExampleCode{Planar_map/example9.cin}
The example above presents a planar map containing one triangle with the coordinates
{\em (0,0)}, {\em (1,1)} and {\em (2,0)}.
The \ccc{Planar map} instance that was used to produce this example was templated
with the \ccStyle{Pm_segment_exact_traits} class, which was templated with the representation
class \ccStyle{Cartesian<leda_rational>}.
The first line specifying that the planar map has three vertices, six halfedges,
and 2 faces (the triangle and the unbounded face).
The list of vertices each represented by its associated point follows, as shown in the
output example.
The next list is the one of halfedges, each component is represented by one
index (between 0 to 2) of the vertices
list and its associated segment.
The faces list is presented next. It starts with the \ccStyle{unbounded face}
having one hole which is the triangle, this connected component specifies that the hole has three halfedges with
the indices 4, 0 and 3. The next face presenting the triangle is written in the same way.
The current format may not be comfortable for a user to read, because the usage of indices.
There is a possibility to define a verbose format which contains instead of
indices, the components themselves, and hence the user has the option to have a format which is easy for human to read.
This format cannot be scanned by the reading functions of \ccc {Planar map}.
\ccExample {of user defined I/O functions}
\label{PM_sec:example10}
The following program demonstrates the usage of I/O functions while users have
an additional attribute in their planar map.
The attribute chosen here is adding color to a \ccStyle{Vertex}.
First the program extends the \ccc{Dcel} to that maintain attribute.
Second, the program extends the \ccc{Pm_file_writer} class to handle the newly
defined \ccStyle{vertex}.
It simply overrides the functions for writing a vertex to print the color of the vertex as well.
Finally, the main function defines an empty \ccc{Planar map},
reads it from the standard input stream, and then set all vertices colors. It then defines an object of its extended writer class and
parameterize the function \ccc{write_pm} with that object.
\ccIncludeExampleCode{Planar_map/example10.C}
The input of the program is a text file presenting the \ccc{Planar map}:
\ccIncludeExampleCode{Planar_map/example10.cin}
The output is the \ccc{Planar map} written in both formats, non verbose and verbose. In addition the two lists
(non verbose and verbose) of halfedges are written.
\ccIncludeExampleCode{Planar_map/example10.cout}
More details are given in sections
\ccc{File_header}\lcTex{
(\ccRefPage{CGAL::File_header})},
\ccc{Pm_file_scanner<Planar_map>}\lcTex{
(\ccRefPage{CGAL::Pm_file_scanner<Planar_map>})},
\ccc{Pm_file_writer<Planar_map>}\lcTex{
(\ccRefPage{CGAL::Pm_file_writer<Planar_map>})} and
\ccc{Pm_drawer<Planar_map>}\lcTex{
(\ccRefPage{CGAL::Pm_drawer<Planar_map>})}.
\end{ccAdvanced}
\begin{ccTexOnly}

14
Packages/Planar_map/doc_tex/Planar_map/planar.tex
View File

@ -196,25 +196,25 @@ returned the curve : 20 50 180 50
\subsection{Example of IO functions}
\label{PM_sec:example9}
The following program demonstrates the usage of I/O functions provided for \ccc{Planar_map}.
First the program demonstrates a trivial use of the I/O functions: it defines an empty \ccc{Planar map},
reads the \ccc{Planar map} text from the standard input stream, and then prints the resulting \ccc{Planar map}
The following program demonstrates the use of I/O functions provided for planar maps. %\ccc{Planar_map}.
First the program demonstrates a trivial use of the I/O functions: it defines an empty instance of \ccc{Planar_map_2},
reads the planar map representation text from the standard input stream, and then prints the resulting planar map
to the standard output stream.
Second, it presents the usage of the verbose format, by defining \ccc{Pm_file_writer} with the verbose flag set to true,
and then calls the function \ccc{write_pm}.
A use of the interface of the class \ccc{Pm_file_writer} is also presented, by calling to its function
\ccStyle{write_halfedges} which prints all the halfedges of the map.
In addition, the program presents the operators writing the resulting \ccc{Planar map} to graphic streams in commented lines.
The comments can be removed if the user has LEDA installed.
In addition, the program presents the operators writing the resulting \ccc{Planar map} to graphic streams in commented lines
(The comments can be removed if the user has LEDA installed).
\ccIncludeExampleCode{Planar_map/example9.C}
The input of the program is a text file presenting the \ccc{Planar map}. This text file is exactly the same as the first block in the
The input of the program is a text file which holds the planar map representation in a special format (which is presented in the reference pages of the the \ccc{Planar Map} package. This representation apears as the first block in the
output file.
%\ccIncludeExampleCode{Planar_map/example9.cin}
The output is the \ccc{Planar map} written in both formats, non verbose and verbose. In addition the two lists
The output is the \ccc{Planar map} includes both formats, non verbose and verbose. In addition the two lists
(non verbose and verbose) of halfedges are written.
\ccIncludeExampleCode{Planar_map/example9.cout}

88
Packages/Planar_map/doc_tex/basic/Planar_map/Planar_map_ref/File_header.tex
View File

@ -11,16 +11,21 @@
%%RefPage: end of header, begin of main body
% +------------------------------------------------------------------------+
\renewcommand{\ccRefPageBegin}{\begin{ccAdvanced}}
\renewcommand{\ccRefPageEnd}{\end{ccAdvanced}}
%File_header
\begin{ccRefClass}{File_header}
\ccCreationVariable{file_header}
\ccDefinition
Generally, the \ccRefName \/ class contains configurations the user defines before using the I/O functions.
These configurations concern the verbose flag, writing a file with or without comments, etc.
The class is the base class of the classes \ccc{Pm_file_scanner} and \ccc{Pm_file_writer}.
The list of parameters for \ccRefName\/ is as follows:
Generally, the \ccRefName \/ class defines and sets parameters that
should be defined while using the I/O functions. This configuration
includes the verbose flag, a flag that controls writing a file with or
without comments, etc. The class is the base class of the classes
\ccc{Pm_file_scanner} and \ccc{Pm_file_writer}. The list of
parameters for \ccRefName\/ is as follows:
\begin{itemize}
\item {\bf verbose } define a verbose format for printing the \ccc{Planar map}. This flag is set by default to false.
@ -51,53 +56,58 @@ When creating a \ccRefName \/ object, the user sets the parameters as needed.
{constructs \ccRefName\ with \ccc{v} vertices \ccc{h} halfedges and \ccc{f} faces, the other parameters can also be set by the user, otherwise they are set to their default values.}
\ccConstructor{File_header(const File_header& file_header);}
{copy constructor.}
{copy construction.}
\ccModifiers
\ccThree{size_t}{file_header.set_number_of_verticesaaa(size_t n);}{}
\ccMethod{void set_verbose(bool b);}{sets the verbose flag to b.}
\ccGlue
\ccMethod{void set_ascii(bool b);} {sets the ascii flag to b.}
\ccMethod{void set_no_comments(bool b);} \ccGlue{sets the no\_comments flag to b.}
\ccMethod{void set_index_offset(int i);} \ccGlue{sets index\_offset to i.}
\ccMethod{void set_colors(bool b);} \ccGlue{sets the colors flag to b.}
\ccMethod{void set_dimension(int i);} \ccGlue{sets the dimension to i.}
\ccMethod{void set_number_of_vertices(size_t n);} \ccGlue{sets the number of vertices to n.}
\ccMethod{void set_number_of_halfedges(size_t n);} \ccGlue{sets the number of halfedges to n.}
\ccMethod{void set_number_of_faces(size_t n);} \ccGlue{sets the number of faces to n.}
\ccGlue
\ccMethod{void set_no_comments(bool b);}{sets the no\_comments flag to b.}
\ccGlue
\ccMethod{void set_index_offset(int i);}{sets index\_offset to i.}
\ccGlue
\ccMethod{void set_colors(bool b);}{sets the colors flag to b.}
\ccGlue
\ccMethod{void set_dimension(int i);}{sets the dimension to i.}
\ccGlue
\ccMethod{void set_number_of_vertices(size_t n);}{sets the number of vertices to n.}
\ccGlue
\ccMethod{void set_number_of_halfedges(size_t n);}{sets the number of halfedges to n.}
\ccGlue
\ccMethod{void set_number_of_faces(size_t n);}{sets the number of faces to n.}
\ccAccessFunctions
%\ccGlueBegin
\ccMethod{bool verbose();} \ccGlue{returns true if the format is verbose.}
\ccMethod{bool ascii();} \ccGlue{returns true if the format is given by ascii.}
\ccMethod{bool no_comments();} \ccGlue{returns true if the format is defined without comments.}
\ccMethod{bool comments();} \ccGlue{returns true if the format is defined with comments.}
\ccMethod{int index_offset();} \ccGlue{returns the offset defined for the indices in the format.}
\ccMethod{bool has_colors();} \ccGlue{returns true if the format presents the \ccc{Planar map} by colors.}
\ccMethod{int dimension();} \ccGlue{returns the dimension defined by the format.}
\ccMethod{size_t number_of_vertices();} \ccGlue{returns the number of vertices defined by the format.}
\ccMethod{size_t number_of_halfedges();} \ccGlue{returns the number of halfedges defined by the format.}
\ccMethod{size_t number_of_faces();} \ccGlue{returns the number of faces defined by the format.}
\ccMethod{bool verbose();}{returns true if the format is verbose.}
\ccGlue
\ccMethod{bool ascii();}{returns true if the format is given by ascii.}
\ccGlue
\ccMethod{bool no_comments();}{returns true if the format is defined without comments.}
\ccGlue
\ccMethod{bool comments();}{returns true if the format is defined with comments.}
\ccGlue
\ccMethod{int index_offset();}{returns the offset defined for the indices in the format.}
\ccGlue
\ccMethod{bool has_colors();}{returns true if the format presents the \ccc{Planar map} by colors.}
\ccGlue
\ccMethod{int dimension();}{returns the dimension defined by the format.}
\ccGlue
\ccMethod{size_t number_of_vertices();}{returns the number of vertices defined by the format.}
\ccGlue
\ccMethod{size_t number_of_halfedges();}{returns the number of halfedges defined by the format.}
\ccGlue
\ccMethod{size_t number_of_faces();}{returns the number of faces defined by the format.}
%\ccGlueEnd
\end{ccRefClass} % File_header
\renewcommand{\ccRefPageBegin}{}
\renewcommand{\ccRefPageEnd}{}
% +------------------------------------------------------------------------+
%%RefPage: end of main body, begin of footer
\ccRefPageEnd

6
Packages/Planar_map/doc_tex/basic/Planar_map/Planar_map_ref/Pm_drawer.tex
View File

@ -11,6 +11,9 @@
%%RefPage: end of header, begin of main body
% +------------------------------------------------------------------------+
\renewcommand{\ccRefPageBegin}{\begin{ccAdvanced}}
\renewcommand{\ccRefPageEnd}{\end{ccAdvanced}}
%Pm_file_writer
\begin{ccRefClass}{Pm_drawer<Planar_map, Window>}
@ -67,6 +70,9 @@ Wherever the handles appear in function parameter lists, the appropriate iterato
\end{ccRefClass} % Pm_file_writer
\renewcommand{\ccRefPageBegin}{}
\renewcommand{\ccRefPageEnd}{}
% +------------------------------------------------------------------------+
%%RefPage: end of main body, begin of footer
\ccRefPageEnd

7
Packages/Planar_map/doc_tex/basic/Planar_map/Planar_map_ref/Pm_file_scanner.tex
View File

@ -10,6 +10,8 @@
%%RefPage: end of header, begin of main body
% +------------------------------------------------------------------------+
\renewcommand{\ccRefPageBegin}{\begin{ccAdvanced}}
\renewcommand{\ccRefPageEnd}{\end{ccAdvanced}}
%Pm_file_scanner
\begin{ccRefClass}{Pm_file_scanner<Planar_map>}
@ -28,6 +30,8 @@ This class is templated with \ccc{Planar map}, and hence the user can work with
\ccTypes
\ccTwo{Pm_file_scanner<Planar_map>::D_halfedge_bla}{}
\ccNestedType{Traits}{Representation of a bounded curve.}
\ccNestedType{Point}{A type to hold the location of a vertex in the plane.}
\ccNestedType{X_curve}{A type to hold an $x$-monotone curve in the plane.}
@ -61,6 +65,9 @@ does not update its halfedge with the curve.}
\end{ccRefClass} % Pm_file_scanner
\renewcommand{\ccRefPageBegin}{}
\renewcommand{\ccRefPageEnd}{}
% +------------------------------------------------------------------------+
%%RefPage: end of main body, begin of footer
\ccRefPageEnd

6
Packages/Planar_map/doc_tex/basic/Planar_map/Planar_map_ref/Pm_file_writer.tex
View File

@ -11,6 +11,9 @@
%%RefPage: end of header, begin of main body
% +------------------------------------------------------------------------+
\renewcommand{\ccRefPageBegin}{\begin{ccAdvanced}}
\renewcommand{\ccRefPageEnd}{\end{ccAdvanced}}
%Pm_file_writer
\begin{ccRefClass}{Pm_file_writer<Planar_map>}
@ -107,6 +110,9 @@ comments are defined only if the comments flag is set to true:
\end{ccRefClass} % Pm_file_writer
\renewcommand{\ccRefPageBegin}{}
\renewcommand{\ccRefPageEnd}{}
% +------------------------------------------------------------------------+
%%RefPage: end of main body, begin of footer
\ccRefPageEnd

2
Packages/Planar_map/doc_tex/basic/Planar_map/Planar_map_ref/draw_pm.tex
View File

@ -28,6 +28,8 @@ a templated parameter, he may call this function with any graphic
stream he chooses as long as functions for writing the geometric
components are provided in his graphic stream.
\ccInclude{CGAL/IO/draw_pm.h}
\end{ccRefFunction} % writer_pm
% +------------------------------------------------------------------------+

281
Packages/Planar_map/doc_tex/basic/Planar_map/Planar_map_ref/intro.tex
View File

@ -68,6 +68,156 @@ There are several supplied traits classes for the \ccc{Arrangement} which the us
These classes are described at the end of Chapter \ref{I1_ChapterArrangement_2}
(\ccc{2D Arrangements}).
\subsection*{I/O functions}
The \ccc{Planar Map} package supports I/O functions, which include reading a planar map representation from
the standard input or writing it to the standard output,
and also sending a planar map to a graphic stream.
The motivation for using I/O functions is not only to be able to draw
the planar map to a window for instance,
but also to be capable to save planar maps in a text file
and reload it from a text file when needed.
The format of the output file is defined in a way the reading function
will be able to construct the planar map by updating directly the
\ccc{Dcel} without using the insertion functions of the \ccc{Planar
map}. Consequently, the reading function constructs the planar map
very efficiently. Obviously, for very big maps or for repetitive use
of the same map it would be exteremly faster to build the map only
once (incrementaly or via a sweep line utility), save it and reload
the ready map when necessary.
Reading a planar map from the standard input or printing it to the
standard output may be done simply with the \ccc{Extractor} (\ccc{ >>
}) and \ccc{Insertor} (\ccc{ << }) operators defined for
\ccc{Planar_map_2}, respectively.
\ccInclude{CGAL/IO/Pm_iostream.h}
The ability of sending the \ccc{Planar map}
into a graphic stream as \ccStyle{leda_window}, Postscript file or
Geomview is also provided, users simply have to apply the Insertor
operator on the graphic stream and their planar map instance.
\begin{ccAdvanced}
\subsection*{I/O for User Defined Planar Maps and the I/O Format}
Users may wish to add their own attributes planar map components. If
those attributes are to be written as part of the planar map
representation (respectively, are to be re-read later) a specialized
reader (scanner) class (writer class, resp.) should be defined for the special
planar map. This is done preferably by making it a sub class of the class
\ccStyle{Pm_file_scanner} (\ccStyle{Pm_file_writer}, resp.) and
overriding all the relevant function for scanning (writing, resp.) the
changed components.
After the definition of the inherited class users have to call the function
\ccStyle{read} of \ccc{Planar map} (resp., the global function \ccStyle{write_pm} ) with the inherited class as a parameter.
The same goes for extending the output graphic streams to include
additional attributes only for this purpose a new \ccc{drawer}\/ class
has to be defined. This is done preferably by making this class
inherit the class
\ccStyle{Pm_drawer}. In order to send the special planar map to the graphic stream one should call the global function \ccStyle{draw_pm}
with this class and their planar map as parameters.
\paragraph{Format}
\ccRefLabel{Pm_IO_format}
The chosen format does not follow an existing standard format.
Generally, the format contains lists of the components of a planar map
followed by each other. For each component we write its associative
geometric information and some topological information in order to be
able to update the \ccc{Dcel} efficiently. The format is detailed
below.
\begin{enumerate}
\item The data begins with a line of three integer values specifying the number of vertices,
halfedges and faces in the planar map.
\item The vertices list: each component in the vertices list contains the point of its associative vertex.
\item The halfedges list: each halfedge component is written by an index indicating the vertex origin
of the halfedge, and a curve specifying the halfedge's curve.
\item The faces list: each component in the faces list contains its outer boundary,
if the face is bounded, and a list of its holes which can be empty in case the face
has no holes. The format of the outer boundary is the number of halfedges of its connected
component followed by the indices indicating the halfedges of that component, those indices
have the same order of the halfedges on the connected component.
The format of the list of the holes is first the number of holes followed by the connected
components per each hole, the format of each connected components resembles the format
of the outer boundary specified above.
\item Lines begining with '\#' serve as comments and are ignored.
\item The format does not differentiate between spaces and new lines,
except new lines which belong to commented lines.
And hence, writing the planar in one single line having no comments is also considered legal.
If users would like to keep the commented lines, they may write all the
components between two consecutive commented lines in one single line.
\end{enumerate}
The current format may not be comfortable for a user to read because
of the extensive use of indices. The user can print a planar map in a
verbose format (shorthand for verbose mode format). The skeleton fo
the verbose format is the same. However, in order for the output to be
clearer for a human reader points and halfedges are explicitly written
rather than being represented by indices. Also the direction of the
halfedges are printed in a more convenient way to read. This verbose
format cannot be scanned by the reading functions of
\ccc{Planar_map_2}.
\ccExample
The example below presents a representation of a planar map containing
one triangle with the coordinates {\em (0,0)}, {\em (1,1)} and {\em
(2,0)}. The \ccc{Planar_map_2} instance that was used to produce this
example was templated with the \ccStyle{Pm_segment_exact_traits}
class, which in turn was templated with the representation class
\ccStyle{Cartesian<leda_rational>}. The first line specifys that the
planar map has three vertices, six halfedges, and 2 faces (the
triangle and the unbounded face). The list of vertices each
represented by its associated point follows, as shown in the output
example. The next list is the one of halfedges, each component is
represented by its index (0,1 or 2) in the vertices list and its
associated segment. The faces list is presented next. It starts with
the \ccStyle{unbounded face} having one hole which is the triangle,
this connected component specifies that the hole has three halfedges
with the indices 4, 0 and 3. The next face presenting the triangle is
written in the same manner.
\ccIncludeExampleCode{Planar_map/example9.cin}
\subsection*{Example of User Defined I/O Functions}
\label{PM_sec:example10}
The following program demonstrates the usage of I/O functions while users have
an additional attribute in their planar map.
The attribute chosen here is adding an associative color to each vertex.
First the program extends the \ccc{Dcel} to maintain this attribute.
Second, the program extends the \ccc{Pm_file_writer} class to handle the newly
defined vertex.
It simply overrides the functions for writing a vertex to print the color of the vertex as well.
Finally, the main function defines an empty \ccc{Planar map},
reads it from the standard input stream, and then set all vertices colors. It then defines an object of its extended writer class and
parameterize the function \ccc{write_pm} with that object.
\ccIncludeExampleCode{Planar_map/example10.C}
The input of the program is a text file presenting the \ccc{Planar map}:
\ccIncludeExampleCode{Planar_map/example10.cin}
The output is the \ccc{Planar map} written in both formats, non verbose and verbose. In addition the two lists
(non verbose and verbose) of halfedges are written.
\ccIncludeExampleCode{Planar_map/example10.cout}
More details are given in sections
\ccc{File_header}\lcTex{
(\ccRefPage{CGAL::File_header})},
\ccc{Pm_file_scanner<Planar_map>}\lcTex{
(\ccRefPage{CGAL::Pm_file_scanner<Planar_map>})},
\ccc{Pm_file_writer<Planar_map>}\lcTex{
(\ccRefPage{CGAL::Pm_file_writer<Planar_map>})} and
\ccc{Pm_drawer<Planar_map>}\lcTex{
(\ccRefPage{CGAL::Pm_drawer<Planar_map, Window>})}.
\end{ccAdvanced}
\begin{ccAdvanced}
\subsection*{Point Location Strategies}
@ -183,137 +333,6 @@ additional functions, namely to model the \ccc{Pm_bounding_box_traits} concept
%% add \ccInheritFrom{Pm_bounding_box_base<Planar_map>} to each
%% of these classes
\end{ccAdvanced}
\begin{ccAdvanced}
\subsection*{I/O functions}
The \ccc{Planar map} package supports I/O functions, which include reading a planar map representation from
the standard input or writing it to the standard output,
and also sending a planar map to a graphic stream.
The motivation for using I/O functions is not only to be able to draw
the planar map to a window for instance,
but also to be capable to save planar maps in a text file by writing it
and reloading it from a text file by reading it.
The format of the output file is defined in a way the reading function will be
able to constructs the planar map by updating directly the \ccc{Dcel} without
using the insertion functions of the \ccc{Planar map}.
Consequently, the reading function constructs the planar map very
efficiently, and hence users who would like to save their planar map and reload
it have to construct their planar map by the insertion functions only once,
after saving the planar map to a text file it can be reloaded very efficiently
when needed.
When users would like to read their planar map from the standard input or print
it to the standard output, they may simply use the \ccc{Extractor} (\ccc{ >> })
and \ccc{Insertor} (\ccc{ << }) operators defined for \ccc{Planar map}
respectively.
If users add attributes to their planar map components, reading (resp. writing) planar map would
be done by inheriting the class \ccStyle{Pm_file_scanner} (resp. \ccStyle{Pm_file_writer} )
and overriding all the relevant function for scanning (resp. writing)
the planar map components.
After the definition of the inherited class users have to call the function
\ccStyle{read} of \ccc{Planar map} (resp. the global function \ccStyle{write_pm} ) with the inherited class as a parameter.
The ability of sending the \ccc{Planar map} into a graphic stream as
\ccStyle{leda_window}, Postscript file or Geomview is also provided,
users simply have to use the Insertor operator operated on the graphic stream and their planar map.
When users would like to add attributes to their planar map components and
send their planar maps to a graphic stream, they have to inherit the class
\ccStyle{Pm_drawer} and then call the global function \ccStyle{draw_pm}
with this class and their planar map as parameters.
\paragraph{Format}
\ccRefLabel{Pm_IO_format}
The chosen format does not follow an existing standard format.
Generally, the format contains lists of the components of
\ccc{Planar map} followed by each other,
and for each component we write its associative geometric information and
some topological information in order to be able to update
the \ccc{Dcel} efficiently. The format is detailed below:
\begin{enumerate}
\item The data begins with a line of three integer values specifying the number of vertices,
halfedges and faces the \ccc{Planar map} has.
\item The vertices list: each component in the vertices list contains the point of its associative vertex.
\item The halfedges list: each halfedge component is written by an index indicating the vertex origin
of the halfedge, and a curve specifying the halfedge's curve.
\item The faces list: each component in the faces list contains its outer boundary,
if the face is bounded, and a list of its holes which can be empty in case the face
has no holes. The format of the outer boundary is the number of halfedges of its connected
component followed by the indices indicating the halfedges of that component, those indices
have the same order of the halfedges on the connected component.
The format of the list of the holes is first the number of holes followed by the connected
components per each hole, the format of each connected components resembles the format
of the outer boundary specified above.
\item Lines begining with '\#' serve as comments and are ignored.
\item The format does not differentiate between spaces and new lines,
except new lines which belong to commented lines.
And hence, writing the planar in one single line having no comments is also considered legal.
If users would like to keep the commented lines, they may write all the
components between two consecutive commented lines in one single line.
\end{enumerate}
\ccExample {of usage in I/O functions}
\ccIncludeExampleCode{Planar_map/example9.cin}
The example above presents a planar map containing one triangle with the coordinates
{\em (0,0)}, {\em (1,1)} and {\em (2,0)}.
The \ccc{Planar map} instance that was used to produce this example was templated
with the \ccStyle{Pm_segment_exact_traits} class, which was templated with the representation
class \ccStyle{Cartesian<leda_rational>}.
The first line specifying that the planar map has three vertices, six halfedges,
and 2 faces (the triangle and the unbounded face).
The list of vertices each represented by its associated point follows, as shown in the
output example.
The next list is the one of halfedges, each component is represented by one
index (between 0 to 2) of the vertices
list and its associated segment.
The faces list is presented next. It starts with the \ccStyle{unbounded face}
having one hole which is the triangle, this connected component specifies that the hole has three halfedges with
the indices 4, 0 and 3. The next face presenting the triangle is written in the same way.
The current format may not be comfortable for a user to read, because the usage of indices.
There is a possibility to define a verbose format which contains instead of
indices, the components themselves, and hence the user has the option to have a format which is easy for human to read.
This format cannot be scanned by the reading functions of \ccc {Planar map}.
\ccExample {of user defined I/O functions}
\label{PM_sec:example10}
The following program demonstrates the usage of I/O functions while users have
an additional attribute in their planar map.
The attribute chosen here is adding color to a \ccStyle{Vertex}.
First the program extends the \ccc{Dcel} to that maintain attribute.
Second, the program extends the \ccc{Pm_file_writer} class to handle the newly
defined \ccStyle{vertex}.
It simply overrides the functions for writing a vertex to print the color of the vertex as well.
Finally, the main function defines an empty \ccc{Planar map},
reads it from the standard input stream, and then set all vertices colors. It then defines an object of its extended writer class and
parameterize the function \ccc{write_pm} with that object.
\ccIncludeExampleCode{Planar_map/example10.C}
The input of the program is a text file presenting the \ccc{Planar map}:
\ccIncludeExampleCode{Planar_map/example10.cin}
The output is the \ccc{Planar map} written in both formats, non verbose and verbose. In addition the two lists
(non verbose and verbose) of halfedges are written.
\ccIncludeExampleCode{Planar_map/example10.cout}
More details are given in sections
\ccc{File_header}\lcTex{
(\ccRefPage{CGAL::File_header})},
\ccc{Pm_file_scanner<Planar_map>}\lcTex{
(\ccRefPage{CGAL::Pm_file_scanner<Planar_map>})},
\ccc{Pm_file_writer<Planar_map>}\lcTex{
(\ccRefPage{CGAL::Pm_file_writer<Planar_map>})} and
\ccc{Pm_drawer<Planar_map>}\lcTex{
(\ccRefPage{CGAL::Pm_drawer<Planar_map>})}.
\end{ccAdvanced}
\begin{ccTexOnly}

14
Packages/Planar_map/doc_tex/basic/Planar_map/planar.tex
View File

@ -196,25 +196,25 @@ returned the curve : 20 50 180 50
\subsection{Example of IO functions}
\label{PM_sec:example9}
The following program demonstrates the usage of I/O functions provided for \ccc{Planar_map}.
First the program demonstrates a trivial use of the I/O functions: it defines an empty \ccc{Planar map},
reads the \ccc{Planar map} text from the standard input stream, and then prints the resulting \ccc{Planar map}
The following program demonstrates the use of I/O functions provided for planar maps. %\ccc{Planar_map}.
First the program demonstrates a trivial use of the I/O functions: it defines an empty instance of \ccc{Planar_map_2},
reads the planar map representation text from the standard input stream, and then prints the resulting planar map
to the standard output stream.
Second, it presents the usage of the verbose format, by defining \ccc{Pm_file_writer} with the verbose flag set to true,
and then calls the function \ccc{write_pm}.
A use of the interface of the class \ccc{Pm_file_writer} is also presented, by calling to its function
\ccStyle{write_halfedges} which prints all the halfedges of the map.
In addition, the program presents the operators writing the resulting \ccc{Planar map} to graphic streams in commented lines.
The comments can be removed if the user has LEDA installed.
In addition, the program presents the operators writing the resulting \ccc{Planar map} to graphic streams in commented lines
(The comments can be removed if the user has LEDA installed).
\ccIncludeExampleCode{Planar_map/example9.C}
The input of the program is a text file presenting the \ccc{Planar map}. This text file is exactly the same as the first block in the
The input of the program is a text file which holds the planar map representation in a special format (which is presented in the reference pages of the the \ccc{Planar Map} package. This representation apears as the first block in the
output file.
%\ccIncludeExampleCode{Planar_map/example9.cin}
The output is the \ccc{Planar map} written in both formats, non verbose and verbose. In addition the two lists
The output is the \ccc{Planar map} includes both formats, non verbose and verbose. In addition the two lists
(non verbose and verbose) of halfedges are written.
\ccIncludeExampleCode{Planar_map/example9.cout}