=============
LightingLayer
=============

.. py:currentmodule:: p3dsdk

.. py:class:: LightingLayer


   .. py:method:: id
      :property:

      The id of the layer.

      :type: str, read-only

   .. py:method:: name
      :property:

      The name of the layer.

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

   .. py:method:: model
      :property:

      The parent model of this layer.

      :type: Model, read-only

   .. py:method:: visible
      :property:

      The layer visibility.

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

   .. py:method:: exposure
      :property:

      The layer exposure.

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

   .. py:method:: gamma
      :property:

      The layer gamma.

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

   .. py:method:: format
      :property:

      The layer format.

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


   .. py:method:: duplicate()

      Duplicate this lighting layer.


      :returns: The duplicated layer.
      :rtype: LightingLayer

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

   .. py:method:: remove()

      Delete this lighting layer.



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

   .. py:method:: find_color(id)

      Find a color by id.

      :param id: Color id to find.
      :type id: str

      :returns: The color found or :py:obj:`None` if not found.
      :rtype: LightingColor or None

      :raises InvalidIdFormat: If ``id`` is not in GUID format.

   .. py:method:: list_colors()

      List the colors of the layer.


      :returns: The list of colors of the layer.
      :rtype: list(LightingColor)


   .. py:method:: create_color(name)

      Create a new color in this layer.

      :param name: Name of the color.
      :type name: str

      :returns: The newly created color.
      :rtype: LightingColor

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

   .. py:method:: find_light_group(id)

      Find a light group by id.

      :param id: Light group id to find.
      :type id: str

      :returns: The light group found or :py:obj:`None` if not found.
      :rtype: LightGroup or None

      :raises InvalidIdFormat: If ``id`` is not in GUID format.

   .. py:method:: list_light_groups(recursive = True)

      List the light groups of this layer.

      :param recursive: If :py:obj:`True`, list all light groups in the layer, otherwise only the root groups are returned.
      :type recursive: bool

      :returns: The list of light groups in the layer.
      :rtype: list(LightGroup)


   .. py:method:: create_light_group(name, group = None)

      Create a new light group.

      :param name: The name of the group.
      :type name: str
      :param group: Parent group of the new group, or :py:obj:`None` to put the group at the root of the hierarchy.
      :type group: LightGroup or None

      :returns: The newly created group.
      :rtype: LightGroup

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

   .. py:method:: find_light(id)

      Find a light by id.

      :param id: Light id to find.
      :type id: str

      :returns: The light found or :py:obj:`None` if not found.
      :rtype: Light or None

      :raises InvalidIdFormat: If ``id`` is not in GUID format.

   .. py:method:: list_lights(recursive = True)

      List the lights of this layer.

      :param recursive: If :py:obj:`True`, list all lights in the layer, otherwise only the root lights are returned.
      :type recursive: bool

      :returns: The list of lights in the layer.
      :rtype: list(Light)


   .. py:method:: create_spot_light(name, group = None)

      Create a new spot light.

      :param name: The name of the light.
      :type name: str
      :param group: Group of the new light, or :py:obj:`None` to put the light at the root of the hierarchy.
      :type group: LightGroup or None

      :returns: The newly created light.
      :rtype: SpotLight

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

   .. py:method:: create_omni_light(name, group = None)

      Create a new omni light.

      :param name: The name of the light.
      :type name: str
      :param group: Group of the new light, or :py:obj:`None` to put the light at the root of the hierarchy.
      :type group: LightGroup or None

      :returns: The newly created light.
      :rtype: OmniLight

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

   .. py:method:: create_sun_light(name, group = None)

      Create a new sun light.

      :param name: The name of the light.
      :type name: str
      :param group: Group of the new light, or :py:obj:`None` to put the light at the root of the hierarchy.
      :type group: LightGroup or None

      :returns: The newly created light.
      :rtype: SunLight

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

   .. py:method:: create_sky_light(name, group = None)

      Create a new sky light.

      :param name: The name of the light.
      :type name: str
      :param group: Group of the new light, or :py:obj:`None` to put the light at the root of the hierarchy.
      :type group: LightGroup or None

      :returns: The newly created light.
      :rtype: SkyLight

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

   .. py:method:: create_mesh_area_light(name, group = None)

      Create a new mesh area light.

      :param name: The name of the light.
      :type name: str
      :param group: Group of the new light, or :py:obj:`None` to put the light at the root of the hierarchy.
      :type group: LightGroup or None

      :returns: The newly created light.
      :rtype: MeshAreaLight

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

   .. py:method:: create_plane_area_light(name, group = None)

      Create a new plane area light.

      :param name: The name of the light.
      :type name: str
      :param group: Group of the new light, or :py:obj:`None` to put the light at the root of the hierarchy.
      :type group: LightGroup or None

      :returns: The newly created light.
      :rtype: PlaneAreaLight

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

   .. py:method:: create_cylinder_area_light(name, group = None)

      Create a new cylinder area light.

      :param name: The name of the light.
      :type name: str
      :param group: Group of the new light, or :py:obj:`None` to put the light at the root of the hierarchy.
      :type group: LightGroup or None

      :returns: The newly created light.
      :rtype: CylinderAreaLight

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