.. _obj_to_halfedge:

-----------------------------------------
OBJ to halfedge
-----------------------------------------

OBJ files store data representing 3d objects.
The `pyddg` library can read such files and convert them to :py:class:`~ddg.datastructures.indexedfaceset.ifs.IndexedFaceSet`
or :py:class:`~ddg.datastructures.halfedge.surface.Surface`. The conversion to :py:class:`~ddg.datastructures.halfedge.surface.Surface`
internally converts it to :py:class:`~ddg.datastructures.indexedfaceset.ifs.IndexedFaceSet` and then uses
:py:func:`~ddg.datastructures.indexedfaceset.utils.indexed_face_set_to_surface`.
Additionally, if ``vt`` and ``vn`` attributes were given in the obj file,
these are written as (half)edge attributes on the resulting surface. For general information on OBJ files and their conversion to
:py:class:`~ddg.datastructures.indexedfaceset.ifs.IndexedFaceSet` see :ref:`obj_to_ifs`.

For the direct conversion to a :py:class:`~ddg.datastructures.halfedge.surface.Surface` object use
:py:func:`~ddg.conversion.halfedge.obj.obj_to_hds`.
If the OBJ data is located in the file "surface.obj", the object can be simply created by:

.. doctest::

    >>> import ddg.datastructures.halfedge.io as io
    >>> file = "path_to_file/surface.obj"  # doctest: +SKIP
    >>> hds = io.obj_to_surface(file)  # doctest: +SKIP

.. note::
    In an OBJ file vertex indices start at 1. In the :py:class:`~ddg.datastructures.halfedge.surface.Surface`
    datastructure vertex indices start at 0.
    Thus the vertex indices of the resulting object are given with an offset of -1.

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.

For example 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.
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 line starting with vt in the obj file
    e1.vn == [x, y, z]   #coordinates of the fifth line starting with vn in the obj file

    e2.head.ifs_index == 1
    e2.vt == [x, y, z]  #coordinates of the fifth line starting with vt in the obj file

.. warning::
    The conversion from OBJ to :py:class:`~ddg.datastructures.halfedge.surface.Surface` only works if there is only a single
    object specified in the OBJ file (see also :ref:`obj_to_ifs`).