.. _half-edge-io:

The halfedge.io module
======================
Reading an obj file
-------------------
Assume we have a obj file which we would like to convert into a surface.

The file should contain vertices and their coordinates such that for every vertex there exists a line of the form::

    v x y z

Optional are lines for texture and normal coordinates of the form::

    vt x y z
    vn x y z

Depending on the previous input faces need to be specified by::

    f 1 2 3               #(no vt and vn given)
    f 1/1 2/1 3/1         #(vt but no vn given)
    f 1//1 2//1 3//1      #(vn but no vt given)
    f 1/6/7 2/6/7 3/6/7   #(both, vn and vt given where the middle number stands for the vt index)

Note that the numbers refer to vertex indices of the given order starting at 1 !!

For our executing program we want to:

.. doctest::

    >>> import ddg.datastructures.halfedge.io as io

A surface can be created simply by running:

.. doctest::

    >>> file = "pathtofile/surface.obj" #doctest: +SKIP
    >>> hds = io.obj_to_surface(file) #doctest: +SKIP

The texture and normal attributes vt and vn (if given) belong to vertices but also depend on the face that is specified. 
They are stored as attributes "vt" and "vn" of the (half)edge pointing to the corresponding vertex. 

Take the face  *f 1/4/5 2/6/7 3/8/9*  with edges e1 from 3 to 1 , e2 from 1 to 2 and e3 from 2 to 3 as an example.
Vertex indices can be reconstructed by using ``vertex.ifs_index`` where these indices will start at zero, i.e the vertex
with ``ifs_index == 0`` will be the first vertex specified in the obj file.
Note that edges in the surface can also run in the different direction, such that the order of the vertices of the edge loop is reversed to the order of the vertices in the input by the face f.
The example will result::

    e1.head.ifs_index == 0
    e1.vt == [x, y, z]   #coordinates of the fourth vertex of the obj file which has ifs_index == 3
    e1.vn == [x, y, z]   #coordinates of the fifth vertex of the obj file which has ifs_index == 4

    e2.head.ifs_index == 1
    e2.vt == [x, y, z]  #coordinates of the six'th vertex of the obj file which has ifs_index == 5