========
Algo API
========

.. py:module:: p3dsdk.algo

.. toctree::
   :glob:
   :maxdepth: 3

   algo/*

.. py:function:: flatten_aspect_layers(flatten_result, layers)

   Flatten aspect layers into the given aspect layer.

   :param flatten_result: The layer which will contain the result of the given list of layers flatten.
   :type flatten_result: AspectLayer
   :param layers: The list of aspect layers to flatten.
   :type layers: list(AspectLayer)


   :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
   :raises ValueError: If the list of aspect layers is empty.
   :raises ValueError: If all the given layers are not in the same product.

.. py:function:: merge_surfaces(leader, surfaces, exclude_seams = True)

   Merge surfaces

   .. note::
      After the merge, the input surfaces are deleted. This function has no effects if :py:obj:`surfaces` is empty or only contains the :py:obj:`leader`.

   :param leader: The leader surface to use for the merge.
   :type leader: Surface
   :param surfaces: The list of surfaces to merge. The :py:obj:`leader` surface can be in the list or can be omitted.
   :type surfaces: list(Surface)
   :param exclude_seams: Whether to exclude seam surfaces or surfaces containing seams. If :py:obj:`False`, these surfaces will be merged but the seam information will be lost.
   :type exclude_seams: bool

   :returns: The merged surface.
   :rtype: Surface

   :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
   :raises ValueError: If not enough surfaces to merge.
   :raises ValueError: If a surface is not in the same model as the :py:obj:`leader`.
   :raises ValueError: If the :py:obj:`leader` contains seams but :py:obj:`exclude_seams` is :py:obj:`True`.

.. py:function:: render_lighting(database, remote = False)

   Render lighting

   .. note::
      Render lighting for the current active model.


   .. note::
      Remote rendering is not available when using .p3d direct access.

   :param database: Database.
   :type database: Database
   :param remote: Whether to use remote rendering or not.
   :type remote: bool


   :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

.. py:function:: render_lighting_for_surfaces(layer, surfaces, remote = False)

   Render lighting for the specified surfaces

   .. note::
      Render lighting for the current active model.


   .. note::
      Remote rendering is not available when using .p3d direct access.

   :param layer: Lighting layer to render.
   :type layer: LightingLayer
   :param surfaces: Surfaces to render lighting.
   :type surfaces: list(Surface)
   :param remote: Whether to use remote rendering or not.
   :type remote: bool


   :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

.. py:function:: split_surface(surface)

   Split surface

   .. note::
      If the surface cannot be splited, an exception will be raised, otherwhise the input surface is deleted.

   :param surface: The surface to split.
   :type surface: Surface

   :returns: The splited surfaces.
   :rtype: list(Surface)

   :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
   :raises ValueError: If there is no surface to split.

.. py:function:: stitch_surfaces(leader, surfaces)

   Stitch surfaces

   .. note::
      After the stitch, the input surfaces are deleted. This function has no effects if :py:obj:`surfaces` is empty or only contains the :py:obj:`leader`.

   :param leader: The leader surface to use for the stitch.
   :type leader: Surface
   :param surfaces: The list of surfaces to stitch. The :py:obj:`leader` surface can be in the list or can be omitted.
   :type surfaces: list(Surface)

   :returns: The stitched surfaces.
   :rtype: list(Surface)

   :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
   :raises ValueError: If not enough surfaces to stitch.
   :raises ValueError: If a surface is not in the same model as the :py:obj:`leader`.

.. py:function:: unmerge_surface(surface)

   Unmerge surface

   .. note::
      If the surface cannot be unmerged, an exception will be raised, otherwhise the input surface is deleted.

   :param surface: The surface to unmerge.
   :type surface: Surface

   :returns: The list of surfaces resulting of the surfaces unmerge.
   :rtype: list(Surface)

   :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
   :raises ValueError: If there is no surface to unmerge.