========
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.

   .. py:method:: object_has_metadata_key(id, key)

      Check if the metadata has a key registered on a specific object.

      :param id: Id of an object from the database.
      :type id: str
      :param key: Any string.
      :type key: str

      :returns: :py:obj:`True` if the ``key`` is registered on this object, :py:obj:`False` otherwise.
      :rtype: bool


   .. py:method:: object_metadata_value(id, key)

      Get the metadata value associated to the ``key`` from the given object.

      :param id: Id of an object from the database.
      :type id: str
      :param key: Any string.
      :type key: str

      :returns: The value associated to the ``key`` if it is registered or an empty string otherwise.
      :rtype: str


   .. py:method:: set_object_metadata_value(id, key, new_value)

      Store a metadata value to the given object and key.

      :param id: Id of an object from the database.
      :type id: str
      :param key: Any string.
      :type key: str
      :param new_value: The value to store.
      :type new_value: str


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

   .. py:method:: object_metadata_store(id)

      Get all the metadata keys and values from an object.

      :param id: Id of an object from the database.
      :type id: str

      :returns: A dictionnary of all keys and values associated to the object.
      :rtype: dict(str, str)


   .. py:method:: set_object_metadata_store(id, store)

      Set the metadata store of an object.

      :param id: Id of an object from the database.
      :type id: str
      :param store: A dictionnary containing the metadata key and values.
      :type store: dict(str, str)


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

   .. py:method:: delete_object_metadata_key(id, key)

      Remove a key from the metadata associated to an object.

      :param id: Id of an object from the database.
      :type id: str
      :param key: Any string.
      :type key: str


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

   .. py:method:: delete_object_metadata(id)

      Clean the metadata associated to an object.

      :param id: Id of an object from the database.
      :type id: str


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

   .. py:method:: list_product_key_animations()

      List all the :py:obj:`ProductKeyAnimation`.


      :returns: The list of :py:obj:`ProductKeyAnimation` in the database.
      :rtype: list(ProductKeyAnimation)


   .. py:method:: find_product_key_animation(id)

      Find an :py:obj:`ProductKeyAnimation` by id.

      :param id: :py:obj:`ProductKeyAnimation` id to find.
      :type id: str

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


   .. py:method:: create_camera_bookmark_animation(name)

      Create a new :py:obj:`CameraBookmarkAnimation` in the database.

      :param name: Name of the :py:obj:`CameraBookmarkAnimation`.
      :type name: str

      :returns: The newly created :py:obj:`CameraBookmarkAnimation`.
      :rtype: CameraBookmarkAnimation

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

   .. py:method:: list_camera_bookmark_animations()

      List all the :py:obj:`CameraBookmarkAnimation`.


      :returns: The list of :py:obj:`CameraBookmarkAnimation` in the database.
      :rtype: list(CameraBookmarkAnimation)


   .. py:method:: find_camera_bookmark_animation(id)

      Find an :py:obj:`CameraBookmarkAnimation` by id.

      :param id: :py:obj:`CameraBookmarkAnimation` id to find.
      :type id: str

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


   .. py:method:: create_camera_bezier_path_animation(name)

      Create a new :py:obj:`CameraBezierPathAnimation` in the database.

      :param name: Name of the :py:obj:`CameraBezierPathAnimation`.
      :type name: str

      :returns: The newly created :py:obj:`CameraBezierPathAnimation`.
      :rtype: CameraBezierPathAnimation

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

   .. py:method:: list_camera_bezier_path_animations()

      List all the :py:obj:`CameraBezierPathAnimation`.


      :returns: The list of :py:obj:`CameraBezierPathAnimation` in the database.
      :rtype: list(CameraBezierPathAnimation)


   .. py:method:: find_camera_bezier_path_animation(id)

      Find an :py:obj:`CameraBezierPathAnimation` by id.

      :param id: :py:obj:`CameraBezierPathAnimation` id to find.
      :type id: str

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


   .. py:method:: create_configuration_key_animation(name)

      Create a new :py:obj:`ConfigurationKeyAnimation` in the database.

      :param name: Name of the :py:obj:`ConfigurationKeyAnimation`.
      :type name: str

      :returns: The newly created :py:obj:`ConfigurationKeyAnimation`.
      :rtype: ConfigurationKeyAnimation

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

   .. py:method:: list_configuration_key_animations()

      List all the :py:obj:`ConfigurationKeyAnimation`.


      :returns: The list of :py:obj:`ConfigurationKeyAnimation` in the database.
      :rtype: list(ConfigurationKeyAnimation)


   .. py:method:: find_configuration_key_animation(id)

      Find an :py:obj:`ConfigurationKeyAnimation` by id.

      :param id: :py:obj:`ConfigurationKeyAnimation` id to find.
      :type id: str

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


   .. py:method:: create_channels_simple_animation(name)

      Create a new :py:obj:`ChannelsSimpleAnimation` in the database.

      :param name: Name of the :py:obj:`ChannelsSimpleAnimation`.
      :type name: str

      :returns: The newly created :py:obj:`ChannelsSimpleAnimation`.
      :rtype: ChannelsSimpleAnimation

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

   .. py:method:: create_channels_curve_animation(name)

      Create a new :py:obj:`ChannelsCurveAnimation` in the database.

      :param name: Name of the :py:obj:`ChannelsCurveAnimation`.
      :type name: str

      :returns: The newly created :py:obj:`ChannelsCurveAnimation`.
      :rtype: ChannelsCurveAnimation

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

   .. py:method:: list_channels_simple_animations()

      List all the :py:obj:`ChannelsSimpleAnimation`.


      :returns: The list of :py:obj:`ChannelsSimpleAnimation` in the database.
      :rtype: list(ChannelsSimpleAnimation)


   .. py:method:: list_channels_curve_animations()

      List all the :py:obj:`ChannelsCurveAnimation`.


      :returns: The list of :py:obj:`ChannelsCurveAnimation` in the database.
      :rtype: list(ChannelsCurveAnimation)


   .. py:method:: list_surface_baked_animations()

      List all the :py:obj:`SurfaceBakedAnimation`.


      :returns: The list of :py:obj:`SurfaceBakedAnimation` in the database.
      :rtype: list(SurfaceBakedAnimation)


   .. py:method:: find_channels_simple_animation(id)

      Find an :py:obj:`ChannelsSimpleAnimation` by id.

      :param id: :py:obj:`ChannelsSimpleAnimation` id to find.
      :type id: str

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


   .. py:method:: find_channels_curve_animation(id)

      Find an :py:obj:`ChannelsCurveAnimation` by id.

      :param id: :py:obj:`ChannelsCurveAnimation` id to find.
      :type id: str

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


   .. py:method:: find_surface_baked_animation(id)

      Find an :py:obj:`SurfaceBakedAnimation` by id.

      :param id: :py:obj:`SurfaceBakedAnimation` id to find.
      :type id: str

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


   .. py:method:: list_texture_animations()

      List all the :py:obj:`TextureAnimation`.


      :returns: The list of :py:obj:`TextureAnimation` in the database.
      :rtype: list(TextureAnimation)


   .. py:method:: find_texture_animation(id)

      Find an :py:obj:`TextureAnimation` by id.

      :param id: :py:obj:`TextureAnimation` id to find.
      :type id: str

      :returns: The :py:obj:`ProductKeyAnimaTextureAnimationtion` found or :py:obj:`None` if not found.
      :rtype: TextureAnimation or None


   .. py:method:: create_timeline(name)

      Create a new :py:obj:`Timeline` in the database.

      :param name: Name of the :py:obj:`Timeline`.
      :type name: str

      :returns: The newly created :py:obj:`Timeline`.
      :rtype: Timeline

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

   .. py:method:: list_timelines()

      List all the :py:obj:`Timeline`.


      :returns: The list of :py:obj:`Timeline` in the database.
      :rtype: list(Timeline)


   .. py:method:: find_timeline(id)

      Find an :py:obj:`Timeline` by id.

      :param id: :py:obj:`Timeline` id to find.
      :type id: str

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