.. _to_obj:

Conversion to OBJ File
======================

This section will show you how you can convert
:py:class:`~ddg.datastructures.indexedfaceset.ifs.IndexedFaceSet` and
:py:class:`~ddg.datastructures.halfedge.surface.Surface` datastructures into
`OBJ files <https://en.wikipedia.org/wiki/Wavefront_.obj_file#:~:text=OBJ%20(or%20.,OBJ%20geometry%20format>`_.

Indexed Face Set to OBJ file
----------------------------

In order to store an indexed face set in an OBJ file
it is mandatory to have a coordinate attribute
representing the 3D coordinates of the vertices.

.. doctest::
    
    >>> from ddg.datastructures.indexedfaceset.ifs import IndexedFaceSet as IFS
    >>> import numpy as np
    >>> surf = IFS([[0, 1, 2], [3, 4, 5], [6, 7, 8]])
    >>> co = np.arange(27).reshape((9, 3))
    >>> surf.set_attribute("co", "verts", co)

To convert an indexed face set to an OBJ file
use the function :py:func:`~ddg.conversion.obj.ifs.ifs_to_obj`:

.. autofunction:: ddg.conversion.obj.ifs.ifs_to_obj
    :noindex:

It can be used as easy as

.. doctest::

    >>> from ddg.conversion.obj.ifs import ifs_to_obj
    >>> from ddg.datastructures.indexedfaceset.ifs_generator import cube
    >>> example_ifs = cube()
    >>> object_name = "sample_obj"
    >>> file_location = "path-to-file/sample_obj_file.obj"
    >>> ifs_to_obj(example_ifs, object_name, file_location, "co")  # doctest: +SKIP

This will generate a file with the following content.

.. code-block:: none

    # generated with pyddg library.
    o sample_obj
    v 1.0000 1.0000 1.0000
    v 1.0000 -1.0000 -1.0000
    v -1.0000 1.0000 -1.0000
    v -1.0000 -1.0000 1.0000
    f 1 2 3
    f 3 4 1
    f 2 4 3
    f 1 4 2

.. note::
    In an OBJ file vertex indices start at 1.
    In the IFS datastructure vertex indices start at 0.
    Thus, the vertex indices of the resulting OBJ file
    will contain an offset of 1.

With ``o`` the object name, ``v`` representing
the vertices and ``f`` representing the faces with vertex indices.

.. note::
    OBJ files can also contain texture and normal coordinates,
    ``vt`` and ``vn``, for vertices.
    These belong to pairs of the form ``(vertex, face)``.
    Such pairs can't be handled by :ref:`IFS`.
    Thus, a resulting OBJ file will only contain vertex
    coordinates and therefore only faces of the form ``f 1 2 3``.


Halfedge to OBJ File
--------------------

Similarly, to convert a
:py:class:`~ddg.datastructures.halfedge.surface.Surface` to an
`OBJ file <https://en.wikipedia.org/wiki/Wavefront_.obj_file#:~:text=OBJ%20(or%20.,OBJ%20geometry%20format>`_
use :py:func:`~ddg.conversion.obj.halfedge.hds_to_obj`:

.. autofunction:: ddg.conversion.obj.halfedge.hds_to_obj
    :noindex:

.. doctest::

    >>> from ddg.conversion.obj.halfedge import hds_to_obj
    >>> from ddg.datastructures.halfedge.surface_generator import tetrahedron
    >>> example_surface = tetrahedron()
    >>> file_location = "path-to-file/sample_obj_file.obj"
    >>> hds_to_obj(example_surface, file_location, "co")  # doctest: +SKIP

Which will generate a file with the following content.

.. code-block:: none

    Obj file created by halfedge data structure 

    v 0 0 0
    v 1 1 0
    v 0 1 1
    v 1 0 1

    f 3 1 2
    f 1 3 4
    f 3 2 4
    f 2 1 4

.. warning::
    This conversion does not support an `object_name`.

If ``vt`` and/or ``vn`` were given as (half)edge attributes,
the corresponding values are written to the OBJ file
and the face values are changed accordingly.