Plot functions
Description
These various functions allow to plot the data from the Sequence and Audio instances on graphs, or to plot statistics calculated using the Stats functions.
Functions
- plot_functions.single_joint_movement_plotter(sequence_or_sequences, joint_label='HandRight', align=True, timestamp_start=None, timestamp_end=None, line_color='blue', line_width=1.0, verbosity=1)
Plots the x, y, z positions across time of the joint of one or more sequences, along with the distance travelled, velocity and absolute variations of acceleration.
Note
The values for distance travelled and velocity are, by definition, calculated between two timestamps. The acceleration is calculated between three timestamps. For simplification purposes, in these graphs, the values are plotted at the ending timestamp. In other words, the plotting of the distance and velocity values starts at the second timestamp, while the plotting for the acceleration starts at the third timestamp.
New in version 2.0.
- Parameters:
sequence_or_sequences (Sequence or list(Sequence)) – One or multiple sequence instances.
joint_label (str, optional) – The label of the joint from which to use the values to plot (default:
"HandRight"
).align (bool, optional) – If this parameter is set on
"True"
(default), and if the parametersequence_or_sequences
is a list containing more than one sequence instance, the function will try to check if one or more of the sequences provided is or are sub-sequences of others. If it is the case, the function will align the timestamps of the sequences for the plot. If only one sequence is provided, this parameter is ignored.timestamp_start (float or None, optional) – If defined, indicates at what timestamp the plot starts.
timestamp_end (float or None, optional) – If defined, indicates at what timestamp the plot ends.
line_color (tuple or string or list) –
The color of the line(s) in the graph. Each color can be:
A HTML/CSS name (e.g.
"red"
or"blanched almond"
),An hexadecimal code, starting with a number sign (
#
, e.g."#ffcc00"
or"#c0ffee"
).A RGB or RGBA tuple (e.g.
(153, 204, 0)
or(77, 77, 77, 255)
).
If more than one sequence is provided, this parameter should be a list with the color for each line.
line_width (float, optional) – The width of the plotted lines, in pixels (default: 1.0).
verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- plot_functions.joints_movement_plotter(sequence, time_series='velocity', audio_or_derivative=None, overlay_audio=False, line_width=1.0, color_scheme='default', show_scale=False, verbosity=1)
Plots the distance or velocity across time of the joints, in separate sub-graphs whose localisation roughly follows the original body position of the joints.
New in version 2.0.
- Parameters:
sequence (Sequence) – A Sequence instance.
time_series (str, optional) – Defines which time series to display in the graphs, either
"x"
,"y"
or"z"
for the distance travelled between poses on one single axis,"distance"
for the euclidian 3D distance travelled between poses,"velocity"
(default) for the velocity between poses, or"acceleration"
for the changes of velocity between pairs of poses.audio_or_derivative (Audio, AudioDerivative or None, optional) – An Audio instance, or any of the AudioDerivative child classes (
Envelope
,Pitch
,Intensity
orFormant
). If provided, the samples of the object will be plotted in the top-left corner.overlay_audio (bool, optional) – If set on
True
, and if audio_or_derivative is not None, the samples of theaudio_or_derivative
object will be shown on overlay of the different joint velocities.line_width (float, optional) – The width of the plotted lines, in pixels (default: 1.0).
color_scheme (string or list, optional) – The name of a color scheme or a list of colors to create a gradient. The resulting color gradient will be used to color the joints plots depending on their quantity of movement. If set on
"default"
, the default color scheme will be used, with the joints having the highest quantity of movement colored red. If a list of colors is set as parameter, the colors can be specified in RGB, RGBA, hexadecimal or standard HTML/CSS color names.show_scale (bool, optional) – If set on
True
, shows a colored scale on the left side of the graph.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- plot_functions.framerate_plotter(sequence_or_sequences, line_width=1.0, line_color='#000000')
Plots the framerates across time for one or multiple sequences. The framerate is calculated by getting the inverse of the time between consecutive poses.
New in version 2.0.
- Parameters:
sequence_or_sequences (Sequence or list(Sequence)) – One or multiple sequence instances.
line_width (float, optional) – The width of the plotted lines, in pixels (default: 1.0).
line_color (tuple(int, int, int) or tuple(int, int, int, int) or string) –
The color of the line in the graph. This parameter can be:
A HTML/CSS name (e.g.
"red"
or"blanched almond"
),An hexadecimal code, starting with a number sign (
#
, e.g."#ffcc00"
or"#c0ffee"
).A RGB or RGBA tuple (e.g.
(153, 204, 0)
or(77, 77, 77, 255)
).
- plot_functions.audio_plotter(audio, threshold_low_pass_envelope=10, number_of_formants=3)
Given an audio instance, plots the samples, filtered envelope, pitch, intensity, formants and spectrogram.
New in version 2.0.
- Parameters:
audio (Audio) – An Audio instance.
threshold_low_pass_envelope (int or None, optional) – Defines the threshold frequency over which the envelope will be filtered (default: 10). If set on
None
, the envelope will not be filtered.number_of_formants (int, optional) – The number of formants to plot (default: 3).
Warning
With non-resampled audio files, this function can take several minutes to compute before being able to plot the graphs. It is recommended to perform a downsampling of the audio object before running this function.
- plot_functions.plot_body_graphs(plot_dictionary, joint_layout='auto', title=None, min_scale=None, max_scale=None, show_scale=False, title_scale=None, color_scheme='default', title_audio='Audio')
Creates multiple sub-plots placed so that each joint is roughly placed where it is located on the body. The values of each subplot are taken from the parameter
plot_dictionary
, and the positions from the layout differ between Kinect and Kualisys systems.New in version 2.0.
- Parameters:
plot_dictionary (dict(str: Graph)) – A dictionary containing the title of the sub-graphs as keys, and Graph objects as elements.
joint_layout (str, optional) –
Defines the layout to use for the sub-plots of the joints:
"kinect"
or"qualisys"
/"kualisys"
. If set on"auto"
(default), the function will automatically assign the layout depending on if the joint label"Chest"
is among the keys of theplot_dictionary
.The joint layouts are a grid of 7 × 5 sub-plots for Kinect, and 13 × 7 subplots for Qualisys. The corresponding spot for each joint are loaded from
"res/kinect_joints_subplot_layout.txt"
and"res/kualisys_joints_subplot_layout.txt"
.title (str or None, optional) – The title to display on top of the plot.
min_scale (float or None, optional) – The minimum value to set on the y axis, for all the elements in the
plot_dictionary
that match joint keys (i.e., except from the sub-plot under the"Audio"
key). If set on None (default), the minimum value will be the overall minimum value from theplot_dictionary
, with the sub-graph"Audio"
excluded.max_scale (float or None, optional) – The maximum value to set on the y axis, for all the elements in the
plot_dictionary
that match joint keys (i.e., except from the sub-plot under the"Audio"
key). If set on None (default), the maximum value will be the overall minimum value from theplot_dictionary
, with the sub-graph"Audio"
excluded.show_scale (bool, optional) – If set on
True
, shows a colored scale on the right side of the graph.title_scale (str or None, optional) – Defines a title to give to the scale, if
show_scale
is set onTrue
.color_scheme (str or list, optional) – The color scheme to use for the color scale. This color scheme should be coherent with the colors defined in the
plot_dictionary
.title_audio (str or None, optional) – The title to give to the sub-plot that matches the key
"Audio"
from theplot_dictionary
. This sub-plot is located in the top-left corner of the plot, and is not scaled the same way as the other plots. By default, the title of this sub-plot is"Audio"
, but this parameter allows to change the title to put the name of an AudioDerivative type, such as"Envelope"
or"Pitch"
, for example.
- plot_functions.plot_silhouette(plot_dictionary, joint_layout='auto', title=None, min_scale='auto', max_scale='auto', show_scale=True, title_scale=None, color_scheme='default', color_background='white', color_silhouette='black', resolution=0.5, full_screen=False, path_save=None, verbosity=1)
Plots a silhouette with circles representing the different joints, colored according to their values in the
plot_dictionary
. Passing the mouse on the different joints shows, in the bottom right corner, the value associated to the joint the mouse is on.New in version 2.0.
- Parameters:
plot_dictionary (dict(str: float)) – A dictionary containing the title of the sub-graphs as keys, and values as elements.
joint_layout (str, optional) –
Defines the layout to use for the sub-plots of the joints:
"kinect"
or"qualisys"
/"kualisys"
. If set on"auto"
(default), the function will automatically assign the layout depending on if the joint label"Chest"
is among the keys of theplot_dictionary
. In order to create a personalized layout, it is possible to click on the figure to print in the console a specific position. Pressing the CTRL key at the same time allows to display a test circle where the mouse is located, to give an idea of the render.The joint layouts are a grid of 7 × 5 sub-plots for Kinect, and 13 × 7 subplots for Qualisys. The corresponding spot for each joint are loaded from
"res/kinect_joints_subplot_layout.txt"
and"res/kualisys_joints_subplot_layout.txt"
.title (str or None, optional) – The title to display on top of the plot.
min_scale (str or float, optional) – If set on
"auto"
(default), the lowest value of the scale will be set on the lowest value in theplot_dictionary
. If set on a number, all the values below that number will be colored will the color matching this parameter on the scale.max_scale (str or float, optional) – If set on
"auto"
(default), the highest value of the scale will be set on the highest value in theplot_dictionary
. If set on a number, all the values above that number will be colored will the color matching this parameter on the scale.show_scale (bool, optional) – If set on
True
, shows a colored scale on the left side of the graph.title_scale (str or None, optional) – Defines a title to give to the scale, if
show_scale
is set onTrue
.color_scheme (str or list, optional) –
The color scheme of the scale. This parameter can take a number of forms:
The name of a color scheme: a string matching one of the color gradients available in Color schemes (default:
"default"
).A list of colors: a list containing colors, either using:
Their HTML/CSS names (e.g.
"red"
or"blanched almond"
),Their hexadecimal code, starting with a number sign (
#
, e.g."#ffcc00"
or"#c0ffee"
).Their RGB or RGBA tuples (e.g.
(153, 204, 0)
or(77, 77, 77, 255)
).
These different codes can be used concurrently, e.g.
["red", (14, 18, 32), "#a1b2c3"]
.
color_background (str, tuple(int, int, int) or tuple(int, int, int, int), optional) –
The color of the background (default:
"white"
). This parameter can be a tuple with RGB or RGBA values, a string with a hexadecimal value (starting with a leading#
) or one of the standard HTML/CSS color names.color_silhouette (str, tuple(int, int, int) or tuple(int, int, int, int), optional) –
The color of the silhouette (default:
"black"
). This parameter can be a tuple with RGB or RGBA values, a string with a hexadecimal value (starting with a leading#
) or one of the standard HTML/CSS color names.resolution (tuple(int, int) or float or None, optional) –
The resolution of the Pygame window that will display the silhouette. This parameter can be:
A tuple with two integers, representing the width and height of the window in pixels.
A float, representing the ratio of the total screen width and height; for example, setting this parameter on 0.5 on a screen that is 1920 × 1080 pixels will create a window of 960 × 540 pixels. Note: if a video is provided and set on the side of the sequence, or if two sequences are provided, side by side, the horizontal resolution will be set to be twice the size. A parameter of 0.5 on a screen that is 1920 × 1080 pixels will, in that case, create a window of 1920 × 540 pixels.
None: in that case, the window will be the size of the screen.
full_screen (bool, optional) – Defines if the window will be set full screen (
True
) or not (False
, default).path_save (str or None optional) – If provided, the function will save the silhouette as a picture. The path should contain the folder, the name file, and one of the following extensions:
".png"
,".jpeg"
or".bmp"
.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.