========
Database
========

.. py:currentmodule:: p3dsdk

.. py:class:: Database


   .. py:method:: read_only
      :property:

      The database read only status.

      :type: bool, read-only

   .. py:method:: active_model
      :property:

      The active model.

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

   .. py:method:: active_material_group
      :property:

      The active material group.

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

   .. py:method:: active_texture_group
      :property:

      The active texture group.

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

   .. py:method:: active_background_group
      :property:

      The active background group.

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

   .. py:method:: active_environment_group
      :property:

      The active environment group.

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

   .. py:method:: active_overlay_group
      :property:

      The active overlay group.

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

   .. py:method:: active_postprocess_group
      :property:

      The active postprocess group.

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

   .. py:method:: active_sensor_group
      :property:

      The active sensor group.

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

   .. py:method:: active_material
      :property:

      The active material.

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

   .. py:method:: active_background
      :property:

      The active background.

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

   .. py:method:: active_environment
      :property:

      The active environment.

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

   .. py:method:: active_overlay
      :property:

      The active overlay.

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

   .. py:method:: active_postprocess
      :property:

      The active postprocess.

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

   .. py:method:: active_sensor
      :property:

      The active sensor.

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


   .. py:method:: save()

      Save the database.


      :returns: :py:obj:`True` if successful.
      :rtype: bool

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

   .. py:method:: save_and_clean(save_cache)

      Save and clean the database.

      :param save_cache: Whether to save the cache or not.
      :type save_cache: bool

      :returns: :py:obj:`True` if successful.
      :rtype: bool

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

   .. py:method:: save_as(filename, save_cache)

      Save the database to another file.

      :param filename: The new database filename.
      :type filename: str
      :param save_cache: Whether to save the cache or not.
      :type save_cache: bool

      :returns: :py:obj:`True` if successful.
      :rtype: bool

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

   .. py:method:: close()

      Close the database

      .. note::
         The database is not automatically saved. Call :py:obj:`save()` or :py:obj:`save_as()` before :py:obj:`close()` if you want to do so.




   .. py:method:: find_camera(id)

      Find a camera by id.

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

      :returns: The camera found or :py:obj:`None` if not found.
      :rtype: Camera or None


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

      List the cameras of the database.

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

      :returns: The list of cameras in the database.
      :rtype: list(Camera)


   .. py:method:: create_camera(group = None)

      Create a camera.

      :param group: Group of the new camera, or :py:obj:`None` to put the camera at the root of the hierarchy.
      :type group: CameraGroup or None

      :returns: The new camera.
      :rtype: Camera

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

   .. py:method:: find_camera_group(id)

      Find a camera group by id.

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

      :returns: The camera group found or :py:obj:`None` if not found.
      :rtype: CameraGroup or None


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

      List the camera groups of the database.

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

      :returns: The list of camera groups in the database.
      :rtype: list(CameraGroup)


   .. py:method:: create_camera_group(name, parent_group = None)

      Create a camera group.

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

      :returns: The new group.
      :rtype: CameraGroup

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

   .. py:method:: find_model(id)

      Find a model by id.

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

      :returns: The model found or :py:obj:`None` if not found.
      :rtype: Model or None


   .. py:method:: list_models()

      List the models of the database.


      :returns: The list of models in the database.
      :rtype: list(Model)


   .. py:method:: create_material_group(name)

      Create a new material group.

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

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

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

   .. py:method:: find_material_group(id)

      Find a material group by id.

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

      :returns: The material group found or :py:obj:`None` if not found.
      :rtype: MaterialGroup or None


   .. py:method:: list_material_groups()

      List the material groups of the database.


      :returns: The list of material groups in the database.
      :rtype: list(MaterialGroup)


   .. py:method:: create_texture_group(name)

      Create a new texture group.

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

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

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

   .. py:method:: find_texture_group(id)

      Find a texture group by id.

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

      :returns: The texture group found or :py:obj:`None` if not found.
      :rtype: TextureGroup or None


   .. py:method:: list_texture_groups()

      List the texture groups of the database.


      :returns: The list of texture groups in the database.
      :rtype: list(TextureGroup)


   .. py:method:: create_background_group(name)

      Create a new background group.

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

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

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

   .. py:method:: find_background_group(id)

      Find a background group by id.

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

      :returns: The background group found or :py:obj:`None` if not found.
      :rtype: BackgroundGroup or None


   .. py:method:: list_background_groups()

      List the background groups of the database.


      :returns: The list of background groups in the database.
      :rtype: list(BackgroundGroup)


   .. py:method:: create_environment_group(name)

      Create a new environment group.

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

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

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

   .. py:method:: find_environment_group(id)

      Find a environment group by id.

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

      :returns: The environment group found or :py:obj:`None` if not found.
      :rtype: EnvironmentGroup or None


   .. py:method:: list_environment_groups()

      List the environment groups of the database.


      :returns: The list of environment groups in the database.
      :rtype: list(EnvironmentGroup)


   .. py:method:: create_overlay_group(name)

      Create a new overlay group.

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

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

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

   .. py:method:: find_overlay_group(id)

      Find a overlay group by id.

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

      :returns: The overlay group found or :py:obj:`None` if not found.
      :rtype: OverlayGroup or None


   .. py:method:: list_overlay_groups()

      List the overlay groups of the database.


      :returns: The list of overlay groups in the database.
      :rtype: list(OverlayGroup)


   .. py:method:: create_postprocess_group(name)

      Create a new postprocess group.

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

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

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

   .. py:method:: find_postprocess_group(id)

      Find a postprocess group by id.

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

      :returns: The postprocess group found or :py:obj:`None` if not found.
      :rtype: PostprocessGroup or None


   .. py:method:: list_postprocess_groups()

      List the postprocess groups of the database.


      :returns: The list of postprocess groups in the database.
      :rtype: list(PostprocessGroup)


   .. py:method:: create_sensor_group(name)

      Create a new sensor group.

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

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

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

   .. py:method:: find_sensor_group(id)

      Find a sensor group by id.

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

      :returns: The sensor group found or :py:obj:`None` if not found.
      :rtype: SensorGroup or None


   .. py:method:: list_sensor_groups()

      List the sensor groups of the database.


      :returns: The list of sensor groups in the database.
      :rtype: list(SensorGroup)


   .. py:method:: create_configuration_rule(name)

      Create a new configuration rule in the database.

      :param name: Name of the configuration rule.
      :type name: str

      :returns: The newly created configuration rule.
      :rtype: ConfigurationRule

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

   .. py:method:: find_configuration_rule(id)

      Find a configuration rule by id.

      :param id: Configuration rule id to find.
      :type id: str

      :returns: The configuration rule found or :py:obj:`None` if not found.
      :rtype: ConfigurationRule or None


   .. py:method:: list_configuration_rules()

      List the configuration rules of the database.


      :returns: The list of configuration rules in the database.
      :rtype: list(ConfigurationRule)


   .. py:method:: export_kdr(filename, products, version = 0)

      Export the specified products to a KDR file.

      :param filename: KDR filename.
      :type filename: str
      :param products: Products to export.
      :type products: list(Product)
      :param version: KDR version: 0 is for latest version, n is for Xn version.
      :type version: int


      :raises FileNotFoundError: If the destination directory does not exist.
      :raises ValueError: If KDR version is not valid.
      :raises ValueError: If some products uses features that are not compatible with specified KDR version.

   .. py:method:: export_kdc(filename, products, version = 0)

      Export the specified products to a KDC file.

      :param filename: KDC filename.
      :type filename: str
      :param products: Products to export.
      :type products: list(Product)
      :param version: KDR version: 0 is for latest version, n is for Xn version.
      :type version: int


      :raises FileNotFoundError: If the destination directory does not exist.
      :raises ValueError: If KDR version is not valid.
      :raises ValueError: If some products uses features that are not compatible with specified KDR version.