=======
Surface
=======

.. py:currentmodule:: p3dsdk

.. py:class:: Surface

   Base class: :py:class:`SceneObject`


   .. py:method:: id
      :property:

      The id of the scene object.

      :type: str, read-only

   .. py:method:: name
      :property:

      The name of the scene object.

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

   .. py:method:: type
      :property:

      The type of the scene object.

      :type: SceneObjectType, read-only

   .. py:method:: parent_object
      :property:

      The parent object of this object or :py:obj:`None` if no parent.

      :type: KinematicNode or None
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If trying to move the object into one of its children, trying to move the object to another model, trying to move the object to itself
       or trying to move the object to an object which is not a :py:obj:`KinematicNode` (that is an :py:obj:`Axis`, a :py:obj:`Null` or a :py:obj:`Vector` ).

   .. py:method:: visible
      :property:

      The scene object visibility.

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

   .. py:method:: locked
      :property:

      The scene object lock state.

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

   .. py:method:: selected
      :property:

      Whether the scene object is selected.

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

   .. py:method:: color
      :property:

      The shaper color of the scene object.

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

   .. py:method:: translation
      :property:

      The global translation of the scene object, in meters.

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

   .. py:method:: rotation
      :property:

      The global rotation of the scene object, in degrees.

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

   .. py:method:: scale
      :property:

      The global scale of the scene object.

      :type: Vector3
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If trying to set a negative scale or trying to scale a Kinematics object.

   .. py:method:: pivot_to_world_translation
      :property:

      The translation from pivot point to global position, in meters.

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

   .. py:method:: pivot_to_world_rotation
      :property:

      The rotation from pivot point to global orientation, in degrees.

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

   .. py:method:: local_to_pivot_translation
      :property:

      The translation from local point to pivot position, in meters.

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

   .. py:method:: local_to_pivot_rotation
      :property:

      The rotation from local point to pivot  orientation, in degrees.

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

   .. py:method:: pivot_to_parent_translation
      :property:

      The translation from pivot point to parent position, in meters

      .. note::
         If the object does not have a parent, it returns the global translation.

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

   .. py:method:: pivot_to_parent_rotation
      :property:

      The rotation from pivot point to parent orientation, in degrees

      .. note::
         If the object does not have a parent, it returns the global rotation.

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

   .. py:method:: local_to_parent_translation
      :property:

      The translation from local point to parent position, in meters.

      :type: Vector3, read-only

   .. py:method:: local_to_parent_rotation
      :property:

      The rotation from local point to parent orientation, in degrees.

      :type: Vector3, read-only

   .. py:method:: layer
      :property:

      The geometry layer containing this surface.

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

   .. py:method:: symmetry
      :property:

      Whether symmetry is enabled for this layer.

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

   .. py:method:: symmetry_plane_normal
      :property:

      The normal vector of the symmetry plane.

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

   .. py:method:: symmetry_plane_distance
      :property:

      The distance in meters of the symmetry plane from the origin.

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

   .. py:method:: is_merged
      :property:

      Whether the surface is a merged or not.

      :type: bool, read-only

   .. py:method:: triangle_mesh_indices
      :property:

      Indices of vertices to make triangles in counter-clockwise order.

      :type: list(int), read-only

   .. py:method:: triangle_mesh_positions
      :property:

      Indexed triangle mesh vertices position (x, y, z) as floats. Units are meters.

      :type: list(float), read-only

   .. py:method:: triangle_mesh_normals
      :property:

      Indexed triangle mesh vertices normals (x, y, z) as floats or :py:obj:`None` if the mesh has no normals.

      :type: list(float) or None, read-only

   .. py:method:: triangle_mesh_uvs
      :property:

      The 32 UV layers of the indexed triangle mesh mesh. Each layer contains UVs (u, v) as floats or :py:obj:`None` if the mesh has no UV at this layer.

      :type: list(list(float) or None), read-only


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

      List the child kinematic object of this objects.

      :param recursive: If :py:obj:`True`, lists all child objects in this object, otherwise only the direct child objects are returned.
      :type recursive: bool

      :returns: The list of kinematic object of this node.
      :rtype: list(KinematicNode)


   .. py:method:: has_tag(tag)

      Whether the tag is assigned to the scene object.

      :param tag: Name of the tag.
      :type tag: str

      :returns: Whether the tag is assigned to the scene object.
      :rtype: bool


   .. py:method:: list_tags()

      List all the tags assigned to the scene object.


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


   .. py:method:: add_tag(tag)

      Create a new tag and assign to the scene object.

      :param tag: Name of the tag.
      :type tag: str

      :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(tag)

      Remove tag from the scene object.

      :param tag: Name of the tag.
      :type tag: str


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

   .. py:method:: remove()

      Delete this scene object.



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

   .. py:method:: shadow_cast(layer)

      Get surface property shadow cast for the lighting layer.

      :param layer: The lighting layer.
      :type layer: LightingLayer

      :returns: The shadow cast property of the surface.
      :rtype: bool


   .. py:method:: dressing_mapping_mode(uv_set)

      Get the mapping mode for the given dressing.

      .. note::
         Available for dressings of any mapping mode.

      :param uv_set: The queryied dressing uv_set.
      :type uv_set: int

      :returns: The mapping mode for the given dressing.
      :rtype: MappingMode

      :raises ValueError: If trying to set an invalid uvset, must be between 0 and 31.

   .. py:method:: set_dressing_mapping_mode(uv_set, value)

      Set for the given uv_set the given mapping mode.

      .. note::
         Available for dressings of any mapping mode.

      :param uv_set: The queryied dressing uv_set.
      :type uv_set: int
      :param value: The queryied dressing mapping mode.
      :type value: MappingMode


      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If trying to set an invalid uvset, must be between 0 and 31.

   .. py:method:: dressing_scale_uv(uv_set)

      Get if the given uv_set dressing UV is scaled using surface scale.

      .. note::
         Only available for :py:obj:`EXTRACT`, :py:obj:`PLANAR`, :py:obj:`CYLINDRICAL`, :py:obj:`CYLINDRICAL_WITH_CAP`, :py:obj:`SPHERICAL`, :py:obj:`BOX`, :py:obj:`BOX_WITHOUT_CAP` and :py:obj:`TORUS_MAPPER` mapping modes.

      :param uv_set: The queryied dressing uv_set.
      :type uv_set: int

      :returns: If the given uv_set dressing UV is scaled using surface scale.
      :rtype: bool

      :raises ValueError: If trying to set an invalid uvset, must be between 0 and 31.

   .. py:method:: set_dressing_scale_uv(uv_set, value)

      Set if the given uv_set dressing UV is scaled using surface scale.

      .. note::
         Only available for :py:obj:`EXTRACT`, :py:obj:`PLANAR`, :py:obj:`CYLINDRICAL`, :py:obj:`CYLINDRICAL_WITH_CAP`, :py:obj:`SPHERICAL`, :py:obj:`BOX`, :py:obj:`BOX_WITHOUT_CAP` and :py:obj:`TORUS_MAPPER` mapping modes.

      :param uv_set: The queryied dressing uv_set.
      :type uv_set: int
      :param value: Set true if you want to apply surface scale to uv mapping, false otherwise.
      :type value: bool


      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If trying to set an invalid uvset, must be between 0 and 31.

   .. py:method:: dressing_local_translation(uv_set)

      Get the dressing local translation.

      .. note::
         Only available for :py:obj:`PLANAR`, :py:obj:`CYLINDRICAL`, :py:obj:`CYLINDRICAL_WITH_CAP`, :py:obj:`SPHERICAL`, :py:obj:`BOX`, :py:obj:`BOX_WITHOUT_CAP` and :py:obj:`TORUS_MAPPER` mapping modes.

      :param uv_set: The queryied dressing uv_set.
      :type uv_set: int

      :returns: The dressing local translation.
      :rtype: Vector3

      :raises ValueError: If trying to set an invalid uvset, must be between 0 and 31.

   .. py:method:: set_dressing_local_translation(uv_set, value)

      Set the dressing local translation.

      .. note::
         Only available for :py:obj:`PLANAR`, :py:obj:`CYLINDRICAL`, :py:obj:`CYLINDRICAL_WITH_CAP`, :py:obj:`SPHERICAL`, :py:obj:`BOX`, :py:obj:`BOX_WITHOUT_CAP` and :py:obj:`TORUS_MAPPER` mapping modes.

      :param uv_set: The queryied dressing uv_set.
      :type uv_set: int
      :param value: The new dressing local translation.
      :type value: Vector3


      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If trying to set an invalid uvset, must be between 0 and 31.

   .. py:method:: dressing_local_orientation(uv_set)

      Get the dressing local orientation.

      .. note::
         Only available for :py:obj:`PLANAR`, :py:obj:`CYLINDRICAL`, :py:obj:`CYLINDRICAL_WITH_CAP`, :py:obj:`SPHERICAL`, :py:obj:`BOX`, :py:obj:`BOX_WITHOUT_CAP` and :py:obj:`TORUS_MAPPER` mapping modes.

      :param uv_set: The queryied dressing uv_set.
      :type uv_set: int

      :returns: The dressing local orientation.
      :rtype: Vector3

      :raises ValueError: If trying to set an invalid uvset, must be between 0 and 31.

   .. py:method:: set_dressing_local_orientation(uv_set, value)

      Set the dressing local orientation.

      .. note::
         Only available for :py:obj:`PLANAR`, :py:obj:`CYLINDRICAL`, :py:obj:`CYLINDRICAL_WITH_CAP`, :py:obj:`SPHERICAL`, :py:obj:`BOX`, :py:obj:`BOX_WITHOUT_CAP` and :py:obj:`TORUS_MAPPER` mapping modes.

      :param uv_set: The queryied dressing uv_set.
      :type uv_set: int
      :param value: The new dressing local orientation.
      :type value: Vector3


      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If trying to set an invalid uvset, must be between 0 and 31.

   .. py:method:: dressing_size(uv_set)

      Get the dressing size.

      .. note::
         Only available for :py:obj:`PLANAR`, :py:obj:`CYLINDRICAL`, :py:obj:`CYLINDRICAL_WITH_CAP`, :py:obj:`SPHERICAL`, :py:obj:`BOX`, :py:obj:`BOX_WITHOUT_CAP` and :py:obj:`TORUS_MAPPER` mapping modes.

      :param uv_set: The queryied dressing uv_set.
      :type uv_set: int

      :returns: The dressing size.
      :rtype: Vector3

      :raises ValueError: If trying to set an invalid uvset, must be between 0 and 31.

   .. py:method:: set_dressing_size(uv_set, value)

      Set the dressing size.

      .. note::
         Only available for :py:obj:`PLANAR`, :py:obj:`CYLINDRICAL`, :py:obj:`CYLINDRICAL_WITH_CAP`, :py:obj:`SPHERICAL`, :py:obj:`BOX`, :py:obj:`BOX_WITHOUT_CAP` and :py:obj:`TORUS_MAPPER` mapping modes.

      :param uv_set: The queryied dressing uv_set.
      :type uv_set: int
      :param value: The new dressing size.
      :type value: Vector3


      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If trying to set an invalid uvset, must be between 0 and 31.

   .. py:method:: dressing_tile(uv_set)

      Get the dressing tile.

      .. note::
         Only available for :py:obj:`PLANAR`, :py:obj:`CYLINDRICAL`, :py:obj:`CYLINDRICAL_WITH_CAP`, :py:obj:`SPHERICAL`, :py:obj:`BOX`, :py:obj:`BOX_WITHOUT_CAP` and :py:obj:`TORUS_MAPPER` mapping modes.

      :param uv_set: The queryied dressing uv_set.
      :type uv_set: int

      :returns: The dressing tile.
      :rtype: Vector3

      :raises ValueError: If trying to set an invalid uvset, must be between 0 and 31.

   .. py:method:: set_dressing_tile(uv_set, value)

      Set the dressing tile.

      .. note::
         Only available for :py:obj:`PLANAR`, :py:obj:`CYLINDRICAL`, :py:obj:`CYLINDRICAL_WITH_CAP`, :py:obj:`SPHERICAL`, :py:obj:`BOX`, :py:obj:`BOX_WITHOUT_CAP` and :py:obj:`TORUS_MAPPER` mapping modes.

      :param uv_set: The queryied dressing uv_set.
      :type uv_set: int
      :param value: The new dressing tile.
      :type value: Vector3


      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If trying to set an invalid uvset, must be between 0 and 31.

   .. py:method:: aabb_min()

      Get minimum point of the surface aabb.


      :returns: The minimum point of the surface aabb.
      :rtype: Vector3


   .. py:method:: aabb_max()

      Get maximum point of the surface aab.


      :returns: The maximum point of the surface aabb.
      :rtype: Vector3


   .. py:method:: set_shadow_cast(layer, value)

      Set surface property shadow cast for the lighting layer.

      :param layer: The lighting layer.
      :type layer: LightingLayer
      :param value: The value to be set for shadow cast property.
      :type value: bool


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

   .. py:method:: shadow_receive(layer)

      Get surface property shadow receive for the lighting layer.

      :param layer: The lighting layer.
      :type layer: LightingLayer

      :returns: The shadow receive property of the surface.
      :rtype: bool


   .. py:method:: set_shadow_receive(layer, value)

      Set surface property shadow receive for the lighting layer.

      :param layer: The lighting layer.
      :type layer: LightingLayer
      :param value: The value to be set for shadow receive property.
      :type value: bool


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

   .. py:method:: duplicate()

      Duplicate this surface.


      :returns: The duplicated surface.
      :rtype: Surface

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