10.1. Player basics#


The Player is an interactive class that needs an interactive Matplotlib backend. See section Installing Python, Spyder and Kinetics Toolkit for more information.

In this section, we will use kinematic data of tennis serves as a TimeSeries or marker positions.

import kineticstoolkit.lab as ktk

# Set an interactive backend, not required if already enabled in Spyder
%matplotlib qt5

# Download and read markers from a sample C3D file
filename = ktk.doc.download("kinematics_tennis_serve_2players.c3d")
markers = ktk.read_c3d(filename)["Points"]

To visualize these markers, we instantiate a Player using one of these methods:

p = ktk.Player(markers)

# or

p = ktk.Player()

Then we can start playback by pressing space bar, or using:


Press h to print a help overlay on how to control the Player using the keyboard:

    ktk.Player help
    show/hide this help : h
    previous index      : left
    next index          : right
    previous second     : shift+left
    next second         : shift+right
    play/pause          : space
    2x playback speed   : +
    0.5x playback speed : -
    toggle track        : t
    toggle perspective  : d (depth)
    set back/front view : 1/2
    set left/right view : 3/4
    set top/bottom view : 5/6
    set initial view    : 0
    select a point      : left-click
    3d rotate           : left-drag
    pan                 : middle-drag or shift+left-drag
    zoom                : right-drag or wheel

Note the coloured global reference frame on the bottom. This reference frame and every other follow the same standard colour scheme:

  • x = Red

  • y = Green

  • z = Blue

Once a player has been instantiated, lots of properties can be modified to control or customize it:

ktk.Player with properties:
            'current_index': 0
             'current_time': 6.02
           'playback_speed': 1.0
                       'up': 'y'
                 'anterior': 'x'
                     'zoom': 1.0
                  'azimuth': 0.0
                'elevation': 0.2
              'perspective': True
                      'pan': (0.0, 0.0)
                   'target': (0.0, 0.0, 0.0)
                    'track': False
      'default_point_color': (0.8, 0.8, 0.8)
               'point_size': 4.0
    'interconnection_width': 1.5
               'frame_size': 0.1
              'frame_width': 3.0
                'grid_size': 10.0
               'grid_width': 1.0
    'grid_subdivision_size': 1.0
              'grid_origin': (0.0, 0.0, 0.0)
               'grid_color': (0.3, 0.3, 0.3)
         'background_color': (0.0, 0.0, 0.0)
               'title_text': ''

We will learn how to use these properties in the following sections.


Every property can be set directly at creation time, for example:

p = ktk.Player(markers, up="z", anterior="-y")

10.1.1. Orienting the data#

We clearly see that these data do not match the orientation of the Player’s ground plane. In these data, the vertical axis is z, and the antero-posterior axis is y, pointing backward. To align the Player correctly to the data:

p.up = "z"
p.anterior = "-y"

10.1.2. Setting the viewpoint#

Use the mouse to change the viewpoint interactively.

In addition, once the Player is correctly aligned to the data, we can set the viewpoint using the keyboard (numbers 1-6) or ktk.Player.set_view:


To revert to the initial view (at the instantiation of the Player):


It is also possible to set a custom viewpoint, using these properties (some of them are illustrated in Fig. 10.1):

  • target: where the camera looks

  • azimuth: from what angle in the transverse plane

  • elevation: from what angle relative to the transverse plane

  • pan: panning in (x, y), in the camera’s point of view

  • zoom: zoom, in the camera’s point of view

Player custom viewpoint

Fig. 10.1 Visual representation of target, azimuth and elevation.#

For example:

p.target = (0.0, 0.0, 1.0)
p.azimuth = 3.1416 / 4  # pi/4 = 45 deg
p.elevation = 3.1416 / 6  # pi/6 = 30 deg
p.zoom = 0.75