@c This file is part of the Neper software package.
@c Copyright (C) 2003-2015 Romain Quey
@c See the COPYING file in the top-level directory.

@node Tessellation Module (-T)
@chapter Tessellation Module (-T)

@MT{} enables to generate @dfn{tessellations} of a bounded domain of
space, in 1D, 2D or 3D.
It also enables to generate @dfn{2-scale tessellations}, which are
tessellations for which each cell is in turn subdivided into a
tessellation.
@MT{} also enables to @dfn{regularize} the tessellations for
better-quality meshing. The tessellations are provided in scalar
(vector) or raster formats.

@dfn{Tessellation} is achieved
by using various kinds of @dfn{tessellation algorithms}:
@dfn{Voronoi tessellation}, @dfn{hardcore Voronoi tessellation},
@dfn{centroidal Voronoi tessellation} or
@dfn{Laguerre tessellation}. This enables to generate
a wide variety of morphologies.  The @dfn{seeds}
of the cells can be distributed randomly in the domain, which
leads to random equiaxed morphology, or else so as to get columnar,
bamboo, lamellar or regular morphologies (squares in 2D and cubes or truncated
octahedra in 3D).  The last possibility is to load a custom distribution of
seeds.  For Laguerre tessellations, the weight distribution
can be specified (@w{option @option{-weight}}).  Finally, the
tessellations can be scaled to get flat or elongated cells (@w{option
@option{-scale}}).

@dfn{2-scale tessellations} can be obtained by providing 2 levels of
tessellation information to the options using the @w{@samp{@SEPFRAC{}}
separator}.  Moreover, different option values can be assigned to the
second scale tessellations by collecting them, prefixed by the primary
tessellation cell number, in a file loaded using
@samp{@code{@@file_name}} (an example is provided in the Examples
section).

The @dfn{domain} of space in which the tessellation is created can be of
any convex shape. In 3D, cuboidal and cylindrical shapes are directly
supported while other morphologies can be defined from a set of planes
(@w{option @option{-domain}}).  Regarding the bounded nature of the
domain, three types of tessellation can be created: @dfn{standard
tessellations}, for which all seeds are located inside the domain,
@dfn{periodic tessellations}, whose cells show periodicity conditions at
the domain boundary, and @dfn{subdomain-type tessellations}, for which
seeds can be located inside or outside the domain (option
@option{-ttype}; periodic and subdomain tessellations are only available
in raster format).

@dfn{Crystal orientations} are also provided for the cells. The
orientations are randomly distributed according to a uniform
distribution, either in the 3D space or along a specific orientation
fibre (option @option{-ori}, which can be used in conjunction with
@option{-morpho}).  They can be provided according to different
descriptors (option @option{-oridescriptor}).

@dfn{Regularization} can be applied to the tessellations, which consists
in removing their small edges and faces (option @option{-regularization}).
This is a necessary step for getting good-quality meshes using @mM{}
(@pxref{Meshing Module (-M)}).

@dfn{Output files} describe the tessellation either are the scalar
format @file{.tess} or raster format @file{.tesr} (@pxref{File
Formats}).  Both are input files of @mM{} (@pxref{Meshing Module (-M)})
and @mV{} (@pxref{Visualization Module (-V)}).  Third-party software file
formats are also available.

@sp 1
Here is what a typical run of @mT{} looks like,

@sp 1
@c typical_start
@verbatim
    $ neper -T -n 10 -id 1 -reg 1
    ========================    N   e   p   e   r    =======================
    Info   : A software package for polycrystal generation and meshing.
    Info   : Version 2.0.0
    Info   : Built with: gsl libmatheval
    Info   : Loading initialization file `/foo/bar/.neperrc'...
    Info   : ---------------------------------------------------------------
    Info   : MODULE  -T loaded with arguments:
    Info   : [ini file]
    Info   : [com line] -n 10 -id 1 -reg 1
    Info   : ---------------------------------------------------------------
    Info   : Reading input data...
    Info   : Creating domain...
    Info   : Creating tessellation...
    Info   :   - Distributing seeds...
    Info   :   - Running tessellation...
    Info   : Regularizing tessellation...
    Info   :   - loop 2/2: 100% del=14
    Info   : Writing tessellation...
    Info   :     [o] Writing file `n10-id1.tess'...
    Info   :     [o] Wrote file `n10-id1.tess'.
    Info   : Elapsed time: 0.019 secs.
    ========================================================================
@end verbatim
@c typical_end

@section Arguments

@subsection Input Data

Options are detailed below for regular, 1-scale tessellations.  For
2-scale tessellations, combine the option argument values at
the 2 successive scales with @samp{@SEPFRAC{}}. An example is @option{-n
10@SEPFRAC{}10}.

@kindex -n
@inp{-n, integer or char_string,
Number of cells of the tessellation.
The argument can be a mathematical expression based on the @var{vol}
variable@comma{} which is the volume of the domain.
For regular morphologies (truncated octahedra@comma{} etc.@comma{} see
option @option{-morpho})@comma{} the argument must be the number of
cells along a dimension of the domain.
For lamella morphology@comma{} the argument must be of the form
@samp{w=@var{w}} where @code{@var{w}} is the (absolute) width of the lamellae.
,
any, none}

@kindex -id
@inp{-id, integer,
Identifier of the tessellation. It defines the seed used by the random
number generator to compute the positions (optionally weights) of the seeds.
,
any, @var{random}}

Is it also possible to load a tessellation or a raster tessellation from a file,

@kindex -loadtess
@inp{-loadtess, file_name,
Load a tessellation from a file.  Provide as argument the file name.
,
any, none}

@kindex -loadtesr
@inp{-loadtesr, file_name,
Load a raster tessellation from a file.  Provide as argument the file name.
To load only a subregion of a raster tessellation@comma{} use the
syntax
@samp{@var{file_name}:crop(@var{xmin}|@var{xmax}|@var{ymin}|@var{ymax}|@var{zmin}|@var{zmax})}@comma{}
where
@var{xmin}@comma{} @var{xmax}@comma{}
@var{ymin}@comma{} @var{ymax}@comma{}
@var{zmin} and @var{zmax} are the minimum and maximum positions along
@var{x}@comma{} @var{y} and @var{z}@comma{} respectively.
For 2D raster tessellations@comma{} the @var{z} boundaries can be omitted.
For 1D raster tessellations@comma{} the @var{y} and @var{z} boundaries can be omitted.
To scale the number of points of a raster tessellation@comma{} use the syntax
@samp{@var{file_name}:scale(@var{factor})}@comma{}
where @code{@var{factor}} is the
scaling factor@comma{} or
@samp{@var{file_name}:scale(@var{factor_x}|@var{factor_y}|@var{factor_z})}@comma{}
where @code{@var{factor_x}}@comma{} @code{@var{factor_y}} and
@code{@var{factor_z}} are the
scaling factor along @var{x}@comma{} @var{y} and @var{z}@comma{}
respectively.
For 2D raster tessellations@comma{} the @var{z} factor can be omitted.
For 1D raster tessellations@comma{} the @var{y} and @var{z} factors can be omitted.
,
any, none}

Finally, it is possible to load a set of points.  Points are used for
statistics only (option @option{-statpoint}) and should not be seen as
the seeds of the tessellation (to load particular seeds, use option
@option{-morpho}).

@kindex -loadpoint
@inp{-loadpoint, file_name,
Load points from a file.
See @ref{Position File} for the file format.
Provide as argument the file name.
,
any, none}

@subsection Tessellation Options

@opt{-dim, integer,
Specify the dimension of the tessellation.
,
1@comma{} 2 or 3, 3}

@opt{-domain, char_string,
Specify the type and size of the domain.
In 3D@comma{} for a cuboidal shape@comma{}
provide @samp{cube(@var{size_x},@var{size_y},@var{size_z})}
and for a cylindrical shape@comma{} provide
@samp{cylinder(@var{height},@var{diameter})}.
In 2D@comma{} for a rectangular shape@comma{} provide
@samp{square(@var{size_x},@var{size_y})} and for a
circular shape@comma{} provide @samp{circle(@var{radius})}.
In 1D@comma{} provide @samp{segment(@var{size_x})}.
To specify the number of
facets@comma{} @code{@var{facet_nb}}@comma{}
of a circle or cylinder domain@comma{} use
@samp{circle(@var{radius},@var{facet_nb})} or
@samp{cylinder(@var{height},@var{diameter},@var{facet_nb})}.
For an arbitrary 3D shape@comma{}
provide @samp{planes(@var{file_name})}@comma{}
where @code{@var{file_name}} is the name of a file containing the
total number of planes then@comma{} for each plane@comma{} the
4 parameters of its equation (@math{d}@comma{} @math{a}@comma{} @math{b}
and @math{c}@comma{} for an equation of the form @math{a@,x+b@,y+c@,z=d}). The
plane normal@comma{} @math{(a,@,b,@,c)}@comma{} must be an outgoing
vector of the domain.  For an arbitrary 2D shape@comma{} proceed in the
same way.
For a tessellation cell@comma{} provide
@samp{cell(@var{file_name}@comma{}@var{cell_id})}@comma{} where
@code{@var{file_name}} is the name of the tessellation file and
@code{@var{cell_id}} is the cell identifier.
,
see above list, cube(1@comma{}1@comma{}1) in 3D@comma{}
square(1@comma{}1) in 2D and segment(1) in 1D}

@kindex -morpho
@opt{-morpho, char_string,
Type of morphology of the cells. For random
tessellations@comma{} it can be either equiaxed
(@samp{equiaxed})@comma{}
columnar (@samp{columnar(@var{dir})}@comma{} where @code{@var{dir}} is
the columnar direction and can be
@samp{x}@comma{} @samp{y} or @samp{z})
or bamboo-like (@samp{bamboo(@var{dir})}@comma{} where @code{@var{dir}}
is the bamboo direction and can be
@samp{x}@comma{} @samp{y} or @samp{z}).
To get a lamella
morphology@comma{} provide @samp{lamella}.  Regular morphologies also
are available: squares (@samp{square}) in 2D@comma{} and cubes (@samp{cube}) and truncated
octahedra (@samp{tocta}) in 3D.  To load a particular set of seeds@comma{}
use the syntax
@samp{@@@var{file_name}} where @code{@var{file_name}} is the name of the
seed position file (see @ref{Position File}).
,
see above list, equiaxed}

@kindex -hardcore
@opt{-hardcore, real,
Use this option to get a hardcore tessellation.  Provide as
argument the radius of the exclusion sphere surrounding each of the
seeds.
,
any, 0}

@kindex -centroid
@opt{-centroid, logical,
Use this option to get a centroidal tessellation.  Note that the
generation of a centroidal tessellation
is based on Lloyd's algorithm and can be two to
three orders of magnitude as long as for the equivalent
tessellation.
See options @option{-centroidfact}@comma{}
@option{-centroidconv} and @option{-centroiditermax} for convergence
criteria.
,
0 or 1, 0}

@optsec{-centroidfact, real,
This option can be used with option @option{-morpho centroid}@comma{} to
specify the factor by which the seed positions are shifted between
their current positions and the centroid positions@comma{} at each
iteration.  (Lloyd's algorithm is obtained for a value of 1@comma{} but
a lower value can lead to faster convergence.)
,
0 to 1,0.5}

@optsec{-centroidconv, real,
This option can be used with option @option{-morpho centroid}@comma{} to
specify the maximum tolerance on the distance between the seeds
and the cell centroids.
The tolerance is relative to the average cell radius.
,
any > 0,0.02}

@optsec{-centroiditermax, integer,
This option can be used with option @option{-morpho centroid}@comma{} to
specify the maximum number of iterations.
,
any, 1000}

@opt{-weight, char_string,
Use this option to generate a Laguerre tessellation. To
define the weights associated to the seeds@comma{}
the first way is to load values from a file using the syntax
@samp{@@@var{file_name}}@comma{} where @code{@var{file_name}} is the
name of the file. The second way is to provide as argument an expression
for the distribution of the weight values. The current algorithm
generates the weights then distributes the seeds by
decreasing weight values.
As a weight also stands for the radius of a sphere of
exclusion@comma{} the algorithm may fail to distribute all seeds@comma{} in
which case an error is returned.
The expression is
a probability density function of the form
@w{@samp{@code{@var{function}(@var{param1}@comma{}@var{param2}@comma{}...)}}}.
The available functions are:
@w{@samp{@code{@w{@var{dirac}(@var{mean})}}}} for the Dirac
distribution@comma{}
@w{@samp{@code{@w{@var{gaussian}(@var{mean}@comma{}@var{sig})}}}} for
the Gaussian distribution of mean @dfn{@var{mean}} and standard deviation
@dfn{@var{sig}}@comma{}
@w{@samp{@code{@w{@var{flat}(@var{mean}@comma{}@var{radius})}}}} for
the flat distribution of mean @dfn{@var{mean}} and radius
@dfn{@var{radius}}@comma{}
@w{@samp{@code{@w{@var{bernoulli}(@var{val1}@comma{}@var{val2}@comma{}@var{p})}}}} for a Bernoulli-type distribution of probability
@dfn{@var{p}}@comma{} where @code{@var{val1}} is the value associated with
probability @math{1-p} and  @code{@var{val2}} is the value associated with
probability @math{p}.
The distributions can be truncated by passing a minimum and a maximum
value as parameter to the function:
@w{@samp{@code{@var{function}(@var{param1}@comma{}@var{param2}@comma{}...@comma{}@var{min}@comma{}@var{max})}}}.
It is also possible to provide a weighted sum of probability density
functions@comma{} which is particularly appropriate to get multimodal
distributions.  The argument must be of the form:
@w{@samp{@var{function1_weight}*@code{@var{function1}(...)}+@var{function2_weight}*@code{@var{function2}(...)}+...}}@comma{}
where @code{@var{functionid_weight}} is a real number representing the
additive weight of the distribution.
,
any, none}




@opt{-ttype, char_string,
Specify the type of tessellation.
@samp{@code{standard}} means that all seeds are located inside the
domain. @samp{@code{periodic}} means that cells show periodicity
conditions at the domain boundary.  For sem-periodicity@comma{}
provide @samp{@code{periodic(@var{dir})}}@comma{} where @samp{@var{dir}}
stands for the periodicity direction(s)@comma{} among @samp{x}@comma{}
@samp{y} and @samp{z}.  For several directions@comma{}
combine them with @samp{@SEPNODEP{}}. @samp{@code{subdomain}} means that
seeds can be located inside and outside the domain.
@samp{@code{periodic}} and @samp{@code{subdomain}} are only available
for raster tessellations (@option{-format tesr}).  , standard@comma{}
periodic or subdomain, standard}

@optsec{-randomize, real:integer,
This option can be used to randomize the positions of the seeds.
Provide as argument the radius of the sphere
(circle in 2D@comma{} segment in 1D) in which each position is
randomized@comma{} according to a uniform distribution@comma{} and an
identifier for the randomization@comma{} combined @w{with @samp{@SEPDEP{}}}.
,
any:any, none}

@optsec{-sort, char_string,
This option can be used to sort the tessellation cells (typically to
facilitate data post-processing).  Provide as argument the
mathematical expression used for sorting (@pxref{Mathematical and
Logical Expressions}).
, any, none}

@subsection Transformation Options

@opt{-scale, real:real:real,
Specify the factors in the x@comma{} y and z directions by which the
tessellation is to be scaled once generated.
In 2D@comma{} the @var{z} value can be omitted.
In 1D@comma{} the @var{y} and @var{z} values can be omitted.
,
any, none}

@opt{-clip, char_string(...),
Clip a tessellation by one or several planes.  For a scalar tessellation@comma{}
provide @samp{planes(@var{file_name})}@comma{}
where @code{@var{file_name}} is the name of a file containing the
total number of planes then@comma{} for each plane@comma{} the
4 parameters of its equation (@math{d}@comma{} @math{a}@comma{} @math{b}
and @math{c}@comma{} for an equation of the form @math{a@,x+b@,y+c@,z=d}). The
plane normal@comma{} @math{(a,@,b,@,c)}@comma{} must be an outgoing
vector of the clipped domain.
,
any, none}

@subsection Crystal Orientation Options

@opt{-ori, char_string,
Specify the type of crystal orientation distribution.
It can be either @samp{3D} for orientations in the 3D space@comma{}
or
@samp{fibre(@var{dir}@comma{}@var{coo_x}@comma{}@var{coo_y}@comma{}@var{coo_z})}
for orientations along a specific fibre (crystal direction
(@code{@var{coo_x}}@comma{} @code{@var{coo_y}}@comma{}
 @code{@var{coo_z}})
parallel to sample direction @code{@var{dir}}@comma{} where @code{@var{dir}}
can be @samp{x}@comma{} @samp{y}@comma{} or @samp{z}).
Crystal orientations are distributed randomly according to a uniform
distribution in the specified space.
,
3D or fibre(...), 3D}

@optsec{-oricrysym, char_string,
Specify the crystal symmetry.  This is used to reduce the domain
  of definition of the orientation descriptors.,
triclinic or cubic, triclinic}

@subsection Regularization Options

@opt{-regularization, logical,
Enable tessellation regularization. Regularization removes the small edges
and@comma{} indirectly@comma{} the small faces. In return@comma{}
faces can become non-planar (in 3D).  This is controlled by
options @option{-fmax}@comma{} @option{-sel} and @option{-mloop}.
Using regularization enables to get better-quality meshes using
@mM{} (@pxref{Meshing Module (-M)}).
,
0 or 1, 0}

@opt{-fmax, real,
Maximum allowed face flatness fault (in degrees). The flatness
fault is the maximum angle between the normals at two locations on a
face.,
0 to 180,20}

@optsectwo{-sel, -rsel, -sel or -rsel, real,
Absolute or relative small edge (maximum) length.
@code{rsel} is defined relative to the average cell size (volume in
3D@comma{} area in 2D and length in 1D).
The
default @code{-rsel 1} leads to a length of
0.25 for a unit volume cell in 3D@comma{}
0.125 for a unit area cell in 2D and
0.2 for a unit length cell in 1D.
The value also enables to avoid mesh refinement with
the default meshing parameters (@pxref{Meshing Module (-M)}).
It is also possible to specify values on a per-cell basis.
The first way is to use the syntax
@code{@var{default_sel}@SEPNODEP{}@var{cell_expr1}@SEPDEP{}@var{cell_sel1}@SEPNODEP{}@var{cell_expr2}@SEPDEP{}@var{cell_sel2}...}@comma{}
where @code{@var{default_sel}} is the default small edge length@comma{}
@code{@var{cell_expri}} is an expression defining the set of
@w{cells @var{i}} and @code{@var{cell_seli}} is the corresponding small
edge length.
@samp{@code{@var{cell_expri}}} can be any
expression based on variables provided in
@ref{Tessellation Keys}.
The expressions are processed one after the other. When processing
expression @code{@var{cell_expri}}@comma{} the matching cells
are assigned @code{@var{cell_seli}} as small edge length.
Typically@comma{} option @option{-rsel} should be passed the same argument than
option @option{-rcl} of @mM{}@comma{} see @ref{Meshing Module
(-M)}. The second way is to load values from an external file using
the syntax @samp{@@@var{file_name}}@comma{} where @code{@var{file_name}}
is the name of the file containing the length values.,
any,-rsel 1}

@optsec{-mloop, integer,
Maximum number of regularization loops.
During each loop@comma{} the small edges are considered in turn
from the shortest to the largest.
Regularization stops when the maximum number of loops is reached or no
edges are deleted within a loop.,
any,2}

@subsection Filtering Options

The following option can be used to clean up a raster tessellation. For
meshing of a 2D raster tessellation, make sure to use @option{-filter size}.

@opt{-filter, char_string,
Filter a raster tessellation.  The available filters
can be combined @w{with @samp{@SEPDEP}}.
Filter @samp{size} removes@comma{} for each cell@comma{}
the parts of a cell that are not
properly connected to the rest of the cell@comma{} namely@comma{} that do not
share with it at least a raster point edge for a 2D tessellation and a raster
point
face for a 3D tessellation.  Use argument @samp{size(@var{dim})} to
override the type of neighbouring@comma{} where @code{@var{dim}} is equal to 1
for edge and 2 for face.
Filter @samp{noise} removes points (or bunch of points) indexed 0 by
progressively collapsing them.
,
any, none}

@subsection Output Options

@opt{-o, file_name,
Specify the output file name.,
any, none}

@opt{-format, char_string,
Specify the format of the output file(s).
The available formats are the Neper @code{@samp{tess}} and
@code{@samp{tesr}}@comma{}
the Gmsh @code{@samp{geo}}@comma{} the Ply @code{@samp{ply}}@comma{} the
Wavefront @code{@samp{obj}} and the 3DEC @code{@samp{3dec}}.
Orientations for the cells can be obtained using @code{@samp{ori}} (see
also options starting by @code{@samp{-ori}}).
Combine the values @w{with @samp{@SEPNODEP}}.
,
tess@comma{} tesr@comma{} geo@comma{} ply@comma{} obj@comma{} 3dec@comma{} ori, tess}

@opt{-tesrformat, char_string,
Specify the format of the raster output file(s).
The available formats are ASCII (@samp{ascii})@comma{}
8-bit binary (@samp{binary8})@comma{}
16-bit binary (@samp{binary16})
and 32-bit binary (@samp{binary32}).
,
ascii@comma{} binary8@comma{} binary16@comma{} binary32, binary16}

@opt{-tesrsize, integer,
Specify the number of points of a raster tessellation along a direction of
the domain. In case of a domain of different lengths along the different
directions@comma{} the argument stands for the geometrical average of
the number of points along the different directions@comma{} so that the
raster points are as cubic as possible.
To specify different values along the x@comma{} y and z directions@comma{}
combine the values with @samp{@SEPDEP}.
,
any, 20}

@opt{-oridescriptor, char_string,
Select the orientation descriptor used in the @file{.tess}@comma{} @file{.tesr}
and @file{.ori} files. It can be Euler angles in
Bunge@comma{} Kocks or Roe convention (@code{e}@comma{}
@code{ek}@comma{} @code{er})@comma{} rotation matrix (@code{g})@comma{}
@w{axis /} angle or rotation (@code{rtheta})@comma{} Rodrigues vector
(@code{R}) or quaternion (@code{q}).,
above-mentioned values, e}

@opt{-oriformat, char_string,
Specify the format of the @file{.ori} output file. The available formats are:
the Neper-native @code{plain} (i.e.@: only the descriptors on
successive lines)@comma{} the Zset/Z@'ebulon @code{geof} and the
FEpX @code{fepx}.
,
above-mentioned values, plain}

@subsection Post-Processing Options

The first options apply to the cells and seeds of a tessellation or a
raster tessellation, independently of its dimension,

@post{-statcell, char_string,
Provide statistics on the tessellation cells.  Give as argument
the keys as described in @ref{Tessellation Keys} for a tessellation and
@ref{Raster Tessellation Keys} for a raster tessellation (combine with
@samp{@SEPNODEP}).
,
any, none,
.stcell}

@post{-statseed, char_string,
Provide statistics on the tessellation seeds.  Give as argument
the keys as described in @ref{Tessellation Keys} for a tessellation and
@ref{Raster Tessellation Keys} for a raster tessellation (combine with
@samp{@SEPNODEP}).
,
any, none,
.stseed}

For tessellations, it is also possible to get statistics on an
entity-basis,

@post{-statver, char_string,
Provide statistics on the tessellation vertices.  Give as argument
the keys as described in @ref{Tessellation Keys} (combine with
@samp{@SEPNODEP}).
,
any, none,
.stver}

@post{-statedge, char_string,
Provide statistics on the tessellation edges.  Give as argument
the keys as described in @ref{Tessellation Keys} (combine with
@samp{@SEPNODEP}).
,
any, none,
.stedge}

@post{-statface, char_string,
Provide statistics on the tessellation faces.  Give as argument
the keys as described in @ref{Tessellation Keys} (combine with
@samp{@SEPNODEP}).
,
any, none,
.stface}

@post{-statpoly, char_string,
Provide statistics on the tessellation polyhedra.  Give as argument
the keys as described in @ref{Tessellation Keys} (combine with
@samp{@SEPNODEP}).
,
any, none,
.stpoly}

Finally, it is possible to get statistics for a particular set of
points. The option applies to a tessellation.

@post{-statpoint, char_string,
Provide statistics on points.  The points must be loaded with option
@option{-loadpoint}. Give as argument
the keys as described in @ref{Point Keys} (combine @w{with
@samp{@SEPNODEP}}).
,
any, none,
.stpoint}

@subsection Debugging Options

@kindex -checktess
@inp{-checktess, file_name,
Check a tessellation file.  Provide as argument the file name.
Use this option if the tessellation file fails to load using
option @option{-loadtess} or in other modules.
,
any, none}

@section Output Files

@subsection Tessellation

@itemize
@item Neper tessellation file: @file{.tess}

It contains a scalar description of the tessellation.
See @ref{File Formats} for the file syntax.

@item Neper raster tessellation: @file{.tesr}

It contains a raster description of the tessellation.
See @ref{File Formats} for the file syntax.

@item Gmsh geometry file: @file{.geo}

It contains a minimal description of the tessellation written under the
Gmsh geometry file format @file{.geo}.  This file can be opened with
Gmsh for visualization.

@item Ply file: @file{.ply}

It contains a description of the tessellation written under the
standard ``Polygon File Format'' @file{.ply}.

@item Wavefront geometry file: @file{.obj}

It contains a description of the tessellation written under the
Wavefront geometry format @file{.obj}.

@item 3DEC file: @file{.3dec}

It contains a description of the tessellation written under the
3DEC format @file{.3dec}.

@c @item tessellation debugging file: @file{.debug}
@c It contains a human-friendly description of the tessellation, for
@c debugging.

@item Orientation file: @file{.ori}

It contains crystal orientations for the tessellation cells.  The
orientations are written on successive lines, using the descriptor
specified by option @option{-oridescriptor} (see also
@ref{Rotations and Orientations}) and the writing convention specified
by option @option{-oriformat}.

@end itemize

@subsection Statistics

Statistics files are provided for cells, seeds, vertices, edges, faces, polyhedra and
points.  They are formatted with one entity per line.  Each line
contains the
data specified to the corresponding @option{-stat} option and described in
@ref{Tessellation Keys} and
@ref{Raster Tessellation Keys} (files @file{.stcell} and @file{.stseed}
only).

@itemize
  @item Tessellation cell statistics file, @file{.stcell}.
  @item Tessellation seed statistics file, @file{.stseed}.
  @item Tessellation vertex statistics file, @file{.stver}.
  @item Tessellation edge statistics file, @file{.stedge}.
  @item Tessellation face statistics file, @file{.stface}.
  @item Tessellation polyhedron statistics file, @file{.stpoly}.
  @item Point statistics file, @file{.stpoint}.
@end itemize

@section Examples

Below are some examples of use of neper -T.

@enumerate
@c Example_beg
@item    Generate a Voronoi tessellation containing 100 cells (with identifier = 1).
@com{neper -T -n 100 -id 1}
@item    Use an elongated domain and generate a Voronoi tessellation
containing 100 cells.
@com{neper -T -n 100 -id 1 -domain "cube(3,1,0.33)"}
@item    Generate a Voronoi tessellation containing 100 cells and
scale it to get elongated cells.
@com{neper -T -n 100 -id 1 -scale 3:1:0.33}
@item    Generate a Voronoi tessellation containing 100 cells and apply regularization.
@com{neper -T -n 100 -id 1 -reg 1}
@item    Generate a 2D Voronoi tessellation containing 100 cells.
@com{neper -T -n 100 -id 1 -dim 2}
@item    Generate a 2D Voronoi tessellation containing 100 cells at raster
format with 50 points along each coordinate axis;
apply filtering to prepare it for meshing.
@com{neper -T -n 100 -id 1 -dim 2 -format tesr -tesrsize 50 -filter size}
@item    Generate a Voronoi tessellation containing 100 cells and get, for
each cell, its volume and its number of faces.
@com{neper -T -n 100 -id 1 -statcell vol,facenb}
@item    Generate a 2-scale Voronoi tessellation containing
@iftex
@math{100@times10}
@end iftex
@ifinfo
100 x 10
@end ifinfo
cells.
@com{neper -T -n 100@SEPFRAC{}10 -id 1@SEPFRAC{}1}
@item    Generate a 2-scale Voronoi tessellation containing 3 primary
cells divided into 1, 10 and 100 secondary cells, respectively.
@com{neper -T -n 3@SEPFRAC{}@@myfile -id 1@SEPFRAC{}1}

@verbatim
      myfile:
      1 1
      2 10
      3 100
@end verbatim
@item    Generate a 2-scale Voronoi tessellation containing
@iftex
@math{2@times3}
@end iftex
@ifinfo
2 x 3
@end ifinfo
cells with specific seed coordinates at both scales (files @file{coo1} and @file{coo2}).
@com{neper -T -n 2@SEPFRAC{}3 -id 1@SEPFRAC{}1 -morpho @@coo1::@@coo2}

@verbatim
      coo1:			coo2:
      0.25 0.5 0.5		1 0.25 0.25 0.5
      0.75 0.5 0.5		1 0.25 0.75 0.5
				2 0.75 0.25 0.5
				2 0.75 0.75 0.5
@end verbatim
@c Example_end
@end enumerate
@c Example_end

