==========
Kinematics
==========

.. py:currentmodule:: p3dsdk

.. py:class:: KinematicNode

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


   .. 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:: add_surface(surface)

      Add the given :py:obj:`Surface` to the current kinematic node.

      :param surface: The :py:obj:`Surface` to add into the kinematic node.
      :type surface: Surface


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

   .. py:method:: create_axis(name)

      Create an :py:obj:`Axis` in the current KinematicNode.

      :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 the current KinematicNode.

      :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 the current KinematicNode.

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

      List the surfaces of this kinematic node.


      :returns: The list of surfaces of this kinematic node.
      :rtype: list(Surface)



Axis
----

.. py:class:: Axis

   Base class: :py:class:`KinematicNode`


   .. py:method:: origin_point
      :property:

      The initial extremity of the axis.

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

   .. py:method:: end_point
      :property:

      The final extremity of the axis.

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

   .. py:method:: min_angle
      :property:

      The minimal angle value (in degrees).

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

   .. py:method:: max_angle
      :property:

      The maximal angle value (in degrees).

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


   .. py:method:: add_surface(surface)

      Add the given :py:obj:`Surface` to the current kinematic node.

      :param surface: The :py:obj:`Surface` to add into the kinematic node.
      :type surface: Surface


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

   .. py:method:: create_axis(name)

      Create an :py:obj:`Axis` in the current KinematicNode.

      :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 the current KinematicNode.

      :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 the current KinematicNode.

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

      List the surfaces of this kinematic node.


      :returns: The list of surfaces of this kinematic node.
      :rtype: list(Surface)


   .. py:method:: duplicate()

      Duplicate this axis node with its children.


      :returns: The duplicated axis.
      :rtype: Axis

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


Null
----

.. py:class:: Null

   Base class: :py:class:`KinematicNode`


   .. py:method:: position
      :property:

      The position of the null.

      .. note::
         This coincides with the property translation from the inherited class SceneObject.

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


   .. py:method:: add_surface(surface)

      Add the given :py:obj:`Surface` to the current kinematic node.

      :param surface: The :py:obj:`Surface` to add into the kinematic node.
      :type surface: Surface


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

   .. py:method:: create_axis(name)

      Create an :py:obj:`Axis` in the current KinematicNode.

      :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 the current KinematicNode.

      :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 the current KinematicNode.

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

      List the surfaces of this kinematic node.


      :returns: The list of surfaces of this kinematic node.
      :rtype: list(Surface)


   .. py:method:: duplicate()

      Duplicate this null node with its children.


      :returns: The duplicated null.
      :rtype: Null

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


Vector
------

.. py:class:: Vector

   Base class: :py:class:`KinematicNode`


   .. py:method:: origin_point
      :property:

      The initial extremity of the vector.

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

   .. py:method:: end_point
      :property:

      The final extremity of the vector.

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

   .. py:method:: min_distance
      :property:

      The minimal distance value.

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

   .. py:method:: max_distance
      :property:

      The maximal distance value.

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


   .. py:method:: add_surface(surface)

      Add the given :py:obj:`Surface` to the current kinematic node.

      :param surface: The :py:obj:`Surface` to add into the kinematic node.
      :type surface: Surface


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

   .. py:method:: create_axis(name)

      Create an :py:obj:`Axis` in the current KinematicNode.

      :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 the current KinematicNode.

      :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 the current KinematicNode.

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

      List the surfaces of this kinematic node.


      :returns: The list of surfaces of this kinematic node.
      :rtype: list(Surface)


   .. py:method:: duplicate()

      Duplicate this vector node with its children.


      :returns: The duplicated vector.
      :rtype: Vector

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