ktk.Player

class Player(*ts, interconnections={'ForcePlatforms': {'Color': (0.5, 0.0, 1.0), 'Links': [['*_Corner1', '*_Corner2'], ['*_Corner2', '*_Corner3'], ['*_Corner3', '*_Corner4'], ['*_Corner1', '*_Corner4']]}}, vectors={'*Force': {'Color': (1.0, 1.0, 0.0), 'Origin': '*COP', 'Scale': 0.001}}, current_index=0, current_time=None, playback_speed=1.0, up='y', anterior='x', zoom=1.0, azimuth=0.0, elevation=0.2, pan=(0.0, 0.0), target=(0.0, 0.0, 0.0), perspective=True, track=False, default_point_color=(0.8, 0.8, 0.8), default_interconnection_color=(0.8, 0.8, 0.8), default_vector_color=(1.0, 1.0, 0.0), point_size=4.0, interconnection_width=1.5, vector_width=2.0, frame_size=0.1, frame_width=3.0, grid_size=10.0, grid_subdivision_size=1.0, grid_width=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), **kwargs)

Bases: object

A class that allows visualizing points and frames in 3D.

player = ktk.Player(parameters) creates and launches an interactive Player instance. Once the window is open, press h to show a help overlay.

All of the following parameters are also accessible as read/write properties, except the contents and the interconnections that are accessible using get_contents, set_contents, get_interconnections and set_interconnections.

Parameters:

• *ts (TimeSeries) – Contains the points and frames to visualize, where each data key is either a point position expressed as Nx4 array, or a frame expressed as a Nx4x4 array. Multiple TimeSeries can be provided.

• interconnections (dict[str, dict[str, Any]]) –

  Optional. Each key corresponds to a group of interconnections, which is a dictionary with the following keys:

  • ”Links”: list of connections where each string is a point name. For example, to create a link that connects Point1 to Point2, and another link that spans Point3, Point4 and Point5:

    interconnections["Example"]["Links"] = [
        ["Point1", "Point2"],
        ["Point3", "Point4", "Point5"]
    ]
    

    which internally is converted to:

    interconnections["Example"]["Links"] = [
        ["Point1", "Point2"],
        ["Point3", "Point4"],
        ["Point4", "Point5"]
    ]
    

    Point names can include wildcards (*) either as a prefix or as a suffix. This is useful to apply a single set of interconnections to multiple bodies. For instance, if the Player’s contents include these points: [Body1_HipR, Body1_HipL, Body1_L5S1, Body2_HipR, Body2_HipL, Body2_L5S1], we could link L5S1 and both hips at once using:

    interconnections["Pelvis"]["Links"] = [
        ["*_HipR", "*_HipL", "*_L5S1"]
    ]
    

  • ”Color”: character or tuple (RGB) that represents the color of the link. These two examples are equivalent:

    interconnections["Pelvis"]["Color"] = 'r'
    interconnections["Pelvis"]["Color"] = (1.0, 0.0, 0.0)
    

  Its default value connects the four corners of force platforms in purple:

  interconnections = {
      "ForcePlatforms": {
          "Links": [['*_Corner1', '*_Corner2'],
                    ['*_Corner2', '*_Corner3'],
                    ['*_Corner3', '*_Corner4'],
                    ['*_Corner1', '*_Corner4']]
          "Color": (0.5, 0.0, 1.0)
      }
  }
  

• vectors (dict[str, dict[str, Any]]) –

  Optional. A dictionary where each key is the name of a vector and each value contains its origin, scale, and color. For example:

  vectors = {
      "WristForce": {
          "Origin": "WristCenter",
          "Scale": 0.001,
          "Color": (1.0, 1.0, 0.0)
      },
      "ElbowForce": {
          "Origin": "ElbowCenter",
          "Scale": 0.001,
          "Color": (1.0, 1.0, 0.0)
      },
  }
  

  will draw lines for the forces WristForce and ElbowForce, with their origin being at WristCenter and ElbowCenter, and with a scale of 0.001 metre per newton. Force and point names can include wildcards (*) either as a prefix or as a suffix. For instance, to draw forces recorded by multiple force plates, we could use:

  vectors = {
      "*Force": {
          "Origin": "*COP",
          "Scale": 0.001,
          "Color": (1.0, 1.0, 0.0)
      }
  }
  

  which would assign any point ending by “COP” to its counterpart force. This is the default, so that force plate data read by read_c3d_file are shown by default in the Player.

• current_index (int) – Optional. The current index being shown.

• current_time (float | None) – Optional. The current time being shown.

• playback_speed (float) – Optional. Speed multiplier. Set to 1.0 for normal speed, 1.5 to increase playback speed by 50%, etc.

• up (str) – Optional. Defines the ground plane by setting which axis is up. May be {“x”, “y”, “z”, “-x”, “-y”, “-z”}. Default is “y”.

• anterior (str) – Optional. Defines the anterior direction. May be {“x”, “y”, “z”, “-x”, “-y”, “-z”}. Default is “x”.

• zoom (float) – Optional. Camera zoom multiplier.

• azimuth (float) – Optional. Camera azimuth in radians. If anterior is set, then an azimuth of 0 corresponds to the right sagittal plane, pi/2 to the front frontal plane, -pi/2 to the back frontal plane, etc.

• elevation (float) – Optional. Camera elevation in radians. Default is 0.2. If up is set, then a value of 0 corresponds to a purely horizontal view, pi/2 to the top transverse plane, -pi/2 to the bottom transverse plane, etc.

• perspective (bool) – Optional. True to draw the scene using perspective, False to draw the scene orthogonally.

• pan (tuple[float, float]) – Optional. Camera translation (panning). Default is (0.0, 0.0).

• target (tuple[float, float, float]) – Optional. Camera target in metres. Default is (0.0, 0.0, 0.0).

• track (bool) – Optional. False to keep the camera static, True to follow the last selected point when changing index. Default is False.

• default_point_color (str | tuple[float, float, float]) – Optional. Default color for points that do not have a “Color” info. Can be a character or tuple (RGB) where each RGB color is between 0.0 and 1.0. Default is (0.8, 0.8, 0.8).

• default_interconnection_color (str | tuple[float, float, float]) – Optional. Default color for interconnections. Can be a character or tuple (RGB) where each RGB color is between 0.0 and 1.0. Default is (0.8, 0.8, 0.8).

• default_vector_color (str | tuple[float, float, float]) – Optional. Default color for vectors. Can be a character or tuple (RGB) where each RGB color is between 0.0 and 1.0. Default is (1.0, 1.0, 0.0).

• point_size (float) – Optional. Point size as defined by Matplotlib marker size. Default is 4.0.

• interconnection_width (float) – Optional. Width of the interconnections as defined by Matplotlib line width. Default is 1.5.

• vector_width (float) – Optional. Width of the vectors as defined by Matplotlib line width. Default is 2.0.

• frame_size (float) – Optional. Length of the frame axes in metres. Default is 0.1.

• frame_width (float) – Optional. Width of the frame axes as defined by Matplotlib line width. Default is 3.0.

• grid_size (float) – Optional. Length of one side of the grid in metres. Default is 10.0.

• grid_subdivision_size (float) – Optional. Length of one subdivision of the grid in metres. Default is 1.0.

• grid_width (float) – Optional. Width of the grid lines as defined by Matplotlib line width. Default is 1.0.

• grid_origin (tuple[float, float, float]) – Optional. Origin of the grid in metres. Default is (0.0, 0.0, 0.0).

• grid_color (str | tuple[float, float, float]) – Optional. Color of the grid. Can be a character or tuple (RGB) where each RGB color is between 0.0 and 1.0. Default is (0.3, 0.3, 0.3).

• background_color (str | tuple[float, float, float]) – Optional. Background color. Can be a character or tuple (RGB) where each RGB color is between 0.0 and 1.0. Default is (0.0, 0.0, 0.0).

Note

Matplotlib must be in interactive mode.

Methods

close	Close the Player and its associated window.
get_contents	Get contents value.
get_interconnections	Get interconnections value (deprecated).
pause	Pause the animation.
play	Start the animation.
set_contents	Set contents value.
set_interconnections	Set interconnections value (deprecated).
set_view	Set the current view to an orthogonal view in a given plane.
to_image	Save the current view to an image file.
to_video	Save the current view to an MP4 video file.

Attributes

anterior	Read/write anterior.
azimuth	Read/write azimuth.
background_color	Read/write background_color.
contents	Use get_contents or set_contents instead.
current_index	Read/write current_index.
current_time	Read/write current_time.
default_interconnection_color	Read/write default_interconnection_color.
default_point_color	Read/write default_point_color.
default_vector_color	Read/write default_vector_color.
elevation	Read/write elevation.
frame_size	Read/write frame_size.
frame_width	Read/write frame_width.
grid_color	Read/write grid_color.
grid_origin	Read/write grid_origin.
grid_size	Read/write grid_size.
grid_subdivision_size	Read/write grid_subdivision_size.
grid_width	Read/write grid_width.
interconnection_width	Read/write interconnection_width.
interconnections	Read/write interconnections.
pan	Read/write pan as (x, y).
perspective	Read/write perspective.
playback_speed	Read/write playback_speed.
point_size	Read/write point_size.
target	Read/write target as (x, y, z).
title_text	Read/write the text info on top of the figure.
track	Read/write track.
up	Read/write up.
vector_width	Read/write vector_width.
vectors	Read/write vectors.
zoom	Read/write zoom.