========
Timeline
========

.. py:currentmodule:: p3dsdk

.. py:class:: Timeline


   .. py:method:: id
      :property:

      The id of the timeline.

      :type: str, read-only

   .. py:method:: name
      :property:

      The name of the timeline.

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

   .. py:method:: range_start
      :property:

      The beginning of the animation (in seconds).

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

   .. py:method:: range_end
      :property:

      The end of the animation (in seconds).

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


   .. py:method:: product_animation_track()

      Get the product animation track.


      :returns: The product animation track.
      :rtype: TimelineTrack


   .. py:method:: camera_animation_track()

      Get the camera animation track.


      :returns: The camera animation track.
      :rtype: TimelineTrack


   .. py:method:: configuration_animation_track()

      Get the configuration animation track.


      :returns: The configuration animation track.
      :rtype: TimelineTrack


   .. py:method:: channels_animation_tracks()

      Get the list of channels animation tracks.


      :returns: The list of channels animation tracks.
      :rtype: list(TimelineTrack)


   .. py:method:: texture_animation_tracks()

      Get the list of texture animation tracks.


      :returns: The list of texture animation tracks.
      :rtype: list(TimelineTrack)


   .. py:method:: empty_channels_track()

      Get the empty Channels track.


      :returns: The empty Channels track.
      :rtype: TimelineTrack


   .. py:method:: empty_texture_track()

      Get the empty Texture track.


      :returns: The empty Texture track.
      :rtype: TimelineTrack


   .. py:method:: duplicate()

      Duplicate this timeline.


      :returns: The duplicated timeline.
      :rtype: Timeline

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

   .. py:method:: remove()

      Delete a timeline

      .. note::
         If there is only one timeline left, it cannot be deleted.



      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: Cannot be removed if the timeline is the only one remaining.


TimelineLoopType
----------------

.. py:class:: TimelineLoopType

   .. py:attribute:: NONE
      :annotation: = 0

      No loop.

   .. py:attribute:: REPEAT
      :annotation: = 1

      Repeat loop.

   .. py:attribute:: INCREMENT
      :annotation: = 2

      Configuration keys.

TimelineTrack
-------------

.. py:class:: TimelineTrack


   .. py:method:: id
      :property:

      The id of the timeline track.

      :type: str, read-only

   .. py:method:: name
      :property:

      The name of the timeline track.

      :type: str, read-only

   .. py:method:: type
      :property:

      The type of the timeline track.

      :type: TimelineTrackType, read-only

   .. py:method:: empty
      :property:

      Whether the timeline track is empty or not.

      :type: bool, read-only


   .. py:method:: insert_animation(start_time_ms, animation)

      Insert the ``animation`` at :py:obj:`startTime` in the timeline track.

      :param start_time_ms: Start time for the animation in the timeline track (in milliseconds).
      :type start_time_ms: int
      :param animation: Animation to be inserted.
      :type animation: Animation

      :returns: The id of the clip inserted in the given timeline track.
      :rtype: int

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

   .. py:method:: move_animation(clip_id, track, new_start_time_ms)

      Move the animation at :py:obj:`startTimeMs` in the track to track at :py:obj:`newTrackIndex` at :py:obj:`newStartTimeMs`

      .. note::
         The moved animation has a new clip id and the old id becomes invalid.

      :param clip_id: Id of the clip to be moved.
      :type clip_id: int
      :param track: Timeline track in which the animation will be inserted.
      :type track: TimelineTrack
      :param new_start_time_ms: New start time for the moved animation (in milliseconds).
      :type new_start_time_ms: int

      :returns: The new id of the clip moved to the given timeline track.
      :rtype: int

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

   .. py:method:: remove_animation(clip_id)

      Remove the animation at :py:obj:`startTimeMs` from the timeline track

      .. note::
         By default, if the timeline track becomes empty after the removal and is either a Channel Track or Texture Track, a new track of the same type will be added to the timeline.

      :param clip_id: Id of the clip to be removed.
      :type clip_id: int


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

   .. py:method:: list_animations()

      Get the animation list used in the timeline track.


      :returns: The list of animation used in the timeline track.
      :rtype: list(Animation)


   .. py:method:: has_animation(animation)

      Check if the timeline track has this ``animation``.

      :param animation: Animation to be found.
      :type animation: Animation

      :returns: Whether the timeline track has the animation or not.
      :rtype: bool


   .. py:method:: clear()

      Remove all the animations inserted in the timeline track.



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

   .. py:method:: has_clip(clip_id)

      Check if the timeline track has the clip with the id :py:obj:`idClip`.

      :param clip_id: Id of the clip to be checked.
      :type clip_id: int

      :returns: Whether the timeline track has the clip or not.
      :rtype: bool


   .. py:method:: clip_start_time(clip_id)

      Get the start time for the clip with the id :py:obj:`idClip`.

      :param clip_id: Id of the clip to be checked.
      :type clip_id: int

      :returns: Start time in ms.
      :rtype: int


   .. py:method:: clip_animation(clip_id)

      Returns the animation for the clip animation with the id :py:obj:`idClip`.

      :param clip_id: Id of the clip to be checked.
      :type clip_id: int

      :returns: The animation corresponding to the clip.
      :rtype: Animation

      :raises ValueError: If the timeline does not have a clip with the given id :py:obj:`idClip`.

   .. py:method:: list_clip_id()

      Get the clip id list in the timeline track.


      :returns: The list of clip id in the timeline track.
      :rtype: list(int)


   .. py:method:: list_clip_id_for_animation(animation)

      Get the clip id list in the timeline track corresponding to the given ``animation``.

      :param animation: Animation for which the clip id list is to be found.
      :type animation: Animation

      :returns: The list of clip id corresponding to the animation in the timeline track, empty if no clip exists for this animation.
      :rtype: list(int)


   .. py:method:: is_clip_playback_reversed(clip_id)

      Whether the clip's playback is reversed.

      :param clip_id: Id of the clip.
      :type clip_id: int

      :returns: Whether the clip's playback is reversed.
      :rtype: bool


   .. py:method:: set_clip_playback_reversed(clip_id, reversed)

      Set the clip's playback reversed or not.

      :param clip_id: Id of the clip.
      :type clip_id: int
      :param reversed: New value for clip playback reversed.
      :type reversed: bool


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

   .. py:method:: clip_loop_type(clip_id)

      Whether the clip's playback is reversed.

      :param clip_id: Id of the clip.
      :type clip_id: int

      :returns: Whether the clip's playback is reversed.
      :rtype: TimelineLoopType


   .. py:method:: set_clip_loop_type(clip_id, loop_type)

      Set the clip's loop type.

      :param clip_id: Id of the clip.
      :type clip_id: int
      :param loop_type: New value for clip loop type.
      :type loop_type: TimelineLoopType


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


TimelineTrackType
-----------------

.. py:class:: TimelineTrackType

   .. py:attribute:: PRODUCT_KEYS
      :annotation: = 0

      Product keys.

   .. py:attribute:: CAMERA_ANIMATIONS
      :annotation: = 1

      Camera animations.

   .. py:attribute:: CONFIGURATION_KEYS
      :annotation: = 2

      Configuration keys.

   .. py:attribute:: CHANNELS_ANIMATIONS
      :annotation: = 3

      Channel animations.

   .. py:attribute:: DYNAMIC_TEXTURES
      :annotation: = 4

      Video textures.