How to use the the delaunay module
==================================


The Delaunay Command Line Application
-------------------------------------


This example shows how to use the Delaunay command line application to
create an intrinsic Delaunay Triangulation for a given triangulated mesh.

Open the corresponding description in the command line by entering::

    ~/path_to_ddg:$ python3 -m ddg delaunay -h

.. highlight:: none

to show its help for usage and all options: ::

    usage: ddg delaunay [-h] [--name output_name] [--path output_path]
                    [--format out_format] [--extr] [--refine] [--lengthsGiven]
                    original_mesh

    Compute the intrinsic (or extrinsic) Delaunay Triangulation for a given
    triangulated mesh.

    positional arguments:
      original_mesh        File containing the original mesh, format: obj or json.

    optional arguments:
      -h, --help           show this help message and exit
      --name output_name   The name of the output file.
      --path output_path   Output path (default: export).
      --format out_format  Output file format (obj or json) (default: obj).
      --extr               Executes the extrinsic edge flip algo.
      --refine             Create and return the refined surface.
      --lengthsGiven       Edgelength are provided and shall not be calculated
                           from Coordinates.

With the Delaunay command line application one can perform the edge flip
algorithm on a given input triangulation and thus generate a corresponding
Delaunay triangulation. To do so you should provide an input file of
format obj or json containing the mesh you want to transform.

Let's assume the input mesh is given in the file called *bunny.obj*, then ::

    ~/path_to_ddg:$  python3 -m ddg delaunay bunny.obj

performs the intrinsic edge flip algorithm on the given mesh. The resulting
intrinsic Delaunay triangulation will be written into a file named
*iDT_bunny.obj* which can be found in the *export* folder.

The name, location and format of the output file can be defined with the
options ``--name``, ``--path`` and ``--format`` respectively. Possible output
formats
are obj (default) and json.

If you want to perform the extrinsic Flip Algo, use the option ``--extr``.
But notice that extrinsic flips might cause errors with their visualization
(for example in blender). Edges and faces might collapse onto already existing
ones (e.g. flipping an edge of a tetrahedron collapses into a kite of two
double-triangles.).

By default the edge-flipped structure is returned as the intrinsic Delaunay
Triangulation. As only edges were flipped, it has the same vertices as the
original one. But it is not necessarily a regular triangulation anymore as
for example edges may form loops.
For visualization or other purpose, it might be useful to use a refined
version of the flipped structure, that is regular and also shows the overlay
with the original surface. It has extra vertices where the flipped edges
kink and added pairs of edges where the original egdes have been.
Use the option ``--refined`` to get this refined surface as output.

If you want to use defined edgelengths (stored in 'len' attribute of
the edges), state this with the option ``--lengthsGiven``. Otherwise the
edgelength attribute will be newly set by calculating them from coordinates