===========
Environment
===========

.. py:currentmodule:: p3dsdk

.. py:class:: Environment


   .. py:method:: id
      :property:

      The id of the environment.

      :type: str, read-only

   .. py:method:: name
      :property:

      The name of the environment.

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

   .. py:method:: group
      :property:

      The group of the environment.

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

   .. py:method:: gamma
      :property:

      The gamma value of the environment image.

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

   .. py:method:: saturation
      :property:

      The color saturation of the environment image.

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

   .. py:method:: mapping_type
      :property:

      The projection method for the type of HDRI image.

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

   .. py:method:: inverted
      :property:

      Whether the projection of the environment image is inverted.

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

   .. py:method:: diffuse_exposure
      :property:

      The influence of the exposure of the environment on the diffuse layer of a material.

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

   .. py:method:: lightmap_coloration
      :property:

      The influence of the environment color on the diffusion of the materials using lighting textures.

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

   .. py:method:: specular_exposure
      :property:

      The influence of the exposure of the environment on the specular or reflection layer of a material.

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

   .. py:method:: specular_resolution
      :property:

      The resolution of the image used for adjusting the mirroring in pixels.

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

   .. py:method:: improve_mipmaps_quality
      :property:

      Whether to eliminate whitening and aliasing effects environment reflections on sharp geometries in scenes with very intense areas.

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

   .. py:method:: background_exposure
      :property:

      The influence of the exposure of the environment on the background.

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

   .. py:method:: altitude
      :property:

      The altitude of the background.

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

   .. py:method:: background_resolution
      :property:

      The resolution of the image used for the background.

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

   .. py:method:: alternative_background_map
      :property:

      The high resolution texture in a low dynamic range format (JPG, PNG...) to be used instead of the HDR environment for environment materials  or :py:obj:`None` if there is no map assigned.

      :type: Texture or None
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: parallax_correction_type
      :property:

      The proxy surface type used in parallax correction.

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

   .. py:method:: parallax_correction_aabb_min
      :property:

      The min of the bounding box used in parallax correction.

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

   .. py:method:: parallax_correction_aabb_max
      :property:

      The max of the bounding box used in parallax correction.

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

   .. py:method:: parallax_correction_hemisphere_center
      :property:

      The center of the hemisphere used in parallax correction.

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

   .. py:method:: parallax_correction_hemisphere_radius
      :property:

      The radius of the hemisphere used in parallax correction.

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

   .. py:method:: parallax_correction_surface
      :property:

      The surface used in parallax correction.

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

   .. py:method:: is_local_env
      :property:

      Whether the environment is local.

      :type: bool, read-only

   .. py:method:: local_env_product
      :property:

      The corresponding product id for the local environment.

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

   .. py:method:: local_env_position
      :property:

      The origin point at which the local environment will be captured by providing the origin's XYZ coordinates.

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

   .. py:method:: local_env_radius
      :property:

      The size of the capture box.

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

   .. py:method:: local_env_resolution
      :property:

      The resolution of the environment texture at a chosen resolution.

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

   .. py:method:: local_env_surfaces_tags
      :property:

      The tag of the surfaces to be ignored by the local environment.

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


   .. py:method:: duplicate()

      Duplicate this environment.


      :returns: The duplicated environment.
      :rtype: Environment

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

   .. py:method:: orientation_in_product(product)

      Get orientation, in degrees, for the current :py:obj:`Environment` in the :py:obj:`Product`.

      :param product: Product in which the environment orientation will be returned.
      :type product: Product

      :returns: The orientation of the environment in degrees.
      :rtype: Vector3


   .. py:method:: set_orientation_in_product(product, orientation)

      Set orientation, in degrees, for the current :py:obj:`Environment` in the :py:obj:`Product`.

      :param product: Product in which the environment orientation will be modified.
      :type product: Product
      :param orientation: The orientation of the environment, in degrees, overriding the default orientation.
      :type orientation: Vector3


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

   .. py:method:: encoded_data(format, compression = -1)

      Get the encoded data of the environment.

      :param format: The file format to encode the image to (exr, hdr).
      :type format: str
      :param compression: The compression value to use while encoding.
          The value to use depend on the format (e.g. 0 to 100 for JPEG, 0 to 9 for PNG).
          -1 means default compression value.
      :type compression: int

      :returns: The encoded data.
      :rtype: bytes


   .. py:method:: export_kev(filename)

      Export the environment to a KEV file.

      :param filename: KEV filename.
      :type filename: str


      :raises FileNotFoundError: If the destination directory does not exist.

   .. py:method:: remove(force = False)

      Delete this environment

      .. note::
         By default, only not used environments can be deleted (:py:obj:`InUseError` is raised otherwise), use ``force`` to force deletion of used environments.

      :param force: Force the deletion of the environment even if it is in use.
      :type force: bool


      :raises InUseError: If ``force`` is :py:obj:`False` and the environment is used.
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.


GeometryType
------------

.. py:class:: GeometryType

   .. py:attribute:: NONE
      :annotation: = 0

      None.

   .. py:attribute:: BOX
      :annotation: = 1

      Box.

   .. py:attribute:: HEMISPHERE
      :annotation: = 2

      Hemisphere.

MappingType
-----------

.. py:class:: MappingType

   .. py:attribute:: ANGULAR_MAP
      :annotation: = 0

      Angular Map (Light Probe).

   .. py:attribute:: LONGITUDE_LATITUDE
      :annotation: = 1

      Longitude Latitude.

   .. py:attribute:: VERTICAL_CROSS
      :annotation: = 2

      Vertical Cross.

Resolution
----------

.. py:class:: Resolution

   .. py:attribute:: RES_128
      :annotation: = 128

      128 x 128 x 6 faces.

   .. py:attribute:: RES_256
      :annotation: = 256

      256 x 256 x 6 faces.

   .. py:attribute:: RES_512
      :annotation: = 512

      512 x 512 x 6 faces.

   .. py:attribute:: RES_1024
      :annotation: = 1024

      1024 x 1024 x 6 faces.

   .. py:attribute:: RES_2048
      :annotation: = 2048

      2048 x 2048 x 6 faces.

   .. py:attribute:: RES_4096
      :annotation: = 4096

      4096 x 4096 x 6 faces.

   .. py:attribute:: RES_8192
      :annotation: = 8192

      8192 x 8192 x 6 faces.