=====
Model
=====

.. py:currentmodule:: p3dsdk

.. py:class:: Model


   .. py:method:: id
      :property:

      The id of the model.

      :type: str, read-only

   .. py:method:: name
      :property:

      The name of the model.

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

   .. py:method:: lighting_mode
      :property:

      The current lighting mode.

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

   .. py:method:: active_geometry_layer
      :property:

      The current active geometry layer.

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

   .. py:method:: active_position_layer
      :property:

      The current active position layer.

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

   .. py:method:: selected_surfaces
      :property:

      The surfaces currently selected.

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

   .. py:method:: leader_surface
      :property:

      The selection leader surface.

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

   .. py:method:: selected_scene_objects
      :property:

      The scene objects currently selected.

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

   .. py:method:: leader_scene_object
      :property:

      The selection leader scene object.

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


   .. py:method:: list_surfaces()

      List the surfaces of the model.


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


   .. py:method:: list_visible_surfaces()

      List the visible surfaces of the model.


      :returns: The list of visible surfaces of the model.
      :rtype: list(Surface)


   .. py:method:: find_lighting_layer(id)

      Find a lighting layer by id.

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

      :returns: The lighting layer found or :py:obj:`None` if not found.
      :rtype: LightingLayer or None

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

   .. py:method:: list_lighting_layers()

      List the lighting layers of the model.


      :returns: The list of lighting layers of the model.
      :rtype: list(LightingLayer)


   .. py:method:: create_lighting_layer(name)

      Create a new lighting layer in this model.

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

      :returns: The newly created layer.
      :rtype: LightingLayer

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

   .. py:method:: find_geometry_layer(id)

      Find a geometry layer by id.

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

      :returns: The geometry layer found or :py:obj:`None` if not found.
      :rtype: GeometryLayer or None

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

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

      List the geometry layers of the model.

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

      :returns: The list of geometry layers of the model.
      :rtype: list(GeometryLayer)


   .. py:method:: create_geometry_layer(name)

      Create a new geometry layer in this model.

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

      :returns: The newly created layer.
      :rtype: GeometryLayer

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

   .. py:method:: find_bezier_path(id)

      Find a bezier path by id.

      :param id: Bezier path id to find.
      :type id: str

      :returns: The bezier path found or :py:obj:`None` if not found.
      :rtype: BezierPath or None

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

   .. py:method:: list_bezier_paths()

      List the bezier paths of the model.


      :returns: The list of bezier paths of the model.
      :rtype: list(BezierPath)


   .. py:method:: create_bezier_path(name, positions, tangents, closed = True)

      Create a new bezier path in this model.

      :param name: Name of the bezier path.
      :type name: str
      :param positions: Positions of the bezier path points. Must at least contain two element.
      :type positions: list(Vector3)
      :param tangents: Tangents (left and right) of the bezier path points, in absoute positions. Must have twice the count of :py:obj:`positions`.
      :type tangents: list(Vector3)
      :param closed: If the bezier path must be closed or not.
      :type closed: bool

      :returns: The newly created bezier path.
      :rtype: BezierPath

      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If positions and tangents do not have the same length or have less than 2 elements.

   .. py:method:: find_position_layer(id)

      Find a position layer by id.

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

      :returns: The position layer found or :py:obj:`None` if not found.
      :rtype: PositionLayer or None

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

   .. py:method:: list_position_layers()

      List the position layers of the model.


      :returns: The list of position layers of the model in the right order.
      :rtype: list(PositionLayer)


   .. py:method:: create_position_layer(name)

      Create a new position layer in this model

      .. note::
         The created layer will be activated.

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

      :returns: The newly created layer.
      :rtype: PositionLayer

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

   .. py:method:: merge_position_layers(layer_list)

      Merge the list of position layers.

      :param layer_list: The list of layers to merge.
      :type layer_list: list(PositionLayer)

      :returns: The merged layer.
      :rtype: PositionLayer

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

   .. py:method:: find_scene_object(id)

      Find a scene object by id.

      :param id: Scene object id to find.
      :type id: str

      :returns: The scene object found or :py:obj:`None` if not found.
      :rtype: SceneObject or None

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

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

      List the kinematics objects of the model.

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

      :returns: The list of kinematics objects of the model.
      :rtype: list(KinematicNode)


   .. py:method:: create_axis(name)

      Create an :py:obj:`Axis` in this model.

      .. note::
         The created object will be selected, and the previous selection will be lost.

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

      :returns: The created axis.
      :rtype: Axis

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

   .. py:method:: create_vector(name)

      Create a :py:obj:`Vector` in this model.

      .. note::
         The created object will be selected, and the previous selection will be lost.

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

      :returns: The created vector.
      :rtype: Vector

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

   .. py:method:: create_null(name)

      Create a :py:obj:`Null` in this model.

      .. note::
         The created object will be selected, and the previous selection will be lost.

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

      :returns: The created null.
      :rtype: Null

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

   .. py:method:: find_product(id)

      Find a product by id.

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

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

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

   .. py:method:: list_products()

      List the products of the model.


      :returns: The list of products of the model.
      :rtype: list(Product)


   .. py:method:: create_product(name)

      Create a new product in this model.

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

      :returns: The newly created product.
      :rtype: Product

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

   .. py:method:: list_configuration_parameters()

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


      :returns: The list of :py:obj:`ConfigurationParameter` in this model.
      :rtype: list(ConfigurationParameter)


   .. py:method:: list_configuration_presets()

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


      :returns: The list of :py:obj:`Configuration` in this model.
      :rtype: list(ConfigurationPreset)


   .. py:method:: create_configuration_preset(name)

      Create a new :py:obj:`ConfigurationPreset` in this model.

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

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

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

   .. py:method:: list_tags()

      List all the tags as string.


      :returns: The list of tags in this model.
      :rtype: list(str)


   .. py:method:: list_tags_for_scene_objects(objects)

      List all the tags assigned to scene objects.

      :param objects: List of scene objects to get tags from.
      :type objects: list(SceneObject)

      :returns: The list of tags assigned to the scene objects.
      :rtype: list(str)


   .. py:method:: add_tag_to_scene_objects(tag, objects)

      Create a new tag and assign to scene objects.

      :param tag: Name of the tag.
      :type tag: str
      :param objects: List of scene objects.
      :type objects: list(SceneObject)

      :returns: Whether the tag was added or not.
      :rtype: bool

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

   .. py:method:: remove_tag_from_scene_objects(tag, objects)

      Remove tag from scene objects.

      :param tag: Name of the tag.
      :type tag: str
      :param objects: List of scene objects.
      :type objects: list(SceneObject)


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

   .. py:method:: find_saved_selection(id)

      Find a saved selection by id.

      :param id: Saved selection id to find.
      :type id: str

      :returns: The saved selection found or :py:obj:`None` if not found.
      :rtype: SavedSelection or None

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

   .. py:method:: list_saved_selections()

      List the saved selections of the model.


      :returns: The list of saved selections of the model.
      :rtype: list(SavedSelection)


   .. py:method:: create_saved_selection(name)

      Create a new empty saved selection in this model.

      :param name: Name of the saved selection.
      :type name: str

      :returns: The newly created saved selection.
      :rtype: SavedSelection

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