Tool functions

Description

Functions to perform simple tasks that can be used throughout the toolbox and beyond.

Functions

Path functions

tool_functions.find_common_parent_path(paths)

Finds the common root to a series of paths. If the root of the paths is different, the function returns an empty string.

New in version 2.0.

Parameters:

paths (list(str)) – The list of paths. If the list contains only one element, this element will be returned by the function.

Returns:

The common parent path between the paths passed as parameters.

Return type:

str

Example

>>> path1 = "C:/Users/Olivia/Documents/Word/Novels/Celsius 233.docx"
>>> path2 = "C:/Users/Olivia/Documents/Word/Novels/Arrogance and Preconception.docx"
>>> path3 = "C:/Users/Olivia/Documents/Word/Documentation/Krajjat documentation.docx"
>>> path4 = "C:/Users/Olivia/Documents/Excel/Results/Results_1.xlsx"
>>> path5 = "C:/Users/Olivia/Documents/Excel/Results/Results_2.xlsx"
>>> path6 = "C:/Users/Olivia/Documents/Contract.pdf"
>>> print(find_common_parent_path([path1, path2, path3, path4, path5, path6]))
C:/Users/Olivia/Documents/
tool_functions.compute_subpath(path1, path2)

Considering two absolute paths path1 and path2, where one is a parent path of the other, this function returns the subdirectories absent from the other.

New in version 2.0.

Parameters:
  • path1 (str) – An absolute path.

  • path2 (str) – An absolute path.

Returns:

The subdirectories of one of the two paths that is absent from the other.

Return type:

str

Example

>>> path1 = "C:/Users/Shawn/"
>>> path2 = "C:/Users/Shawn/Music/Coldplay/A Rush of Blood to the Head/"
>>> print(compute_subpath(path1, path2))
Music/Coldplay/A Rush of Blood to the Head/
tool_functions.get_difference_paths(paths)

Returns, for each path, a list of the subfolders that are not common with all the other paths.

New in version 2.0.

Parameters:

paths (list(str)) – The list of paths.

Returns:

A list containing a list for each path, which itself contains the subfolders that are not common with the other paths.

Return type:

list(list(str))

Example

>>> path1 = "C:/Sequences/Raw/Subject1/Feb1/Sequence1"
>>> path2 = "C:/Sequences/Resampled/Subject1/Mar1/Sequence1"
>>> get_difference_paths([path1, path2])
[['Raw', 'Feb1'], ['Original', 'Mar1']]
tool_functions.create_subfolders(path, verbosity=1)

Creates all the subfolders that do not exist in a path. For example, if the folder "C:/Recordings/" is empty, and the parameter "path" is set on "C:/Recordings/Subject_01/Session_01/Video_01/", the function will successively create the folders "C:/Recordings/Subject_01/", "C:/Recordings/Subject_01/Session_01/", and "C:/Recordings/Subject_01/Session_01/Video_01/".

New in version 2.0.

Parameters:
  • path (str) – The absolute path to a folder.

  • 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.

tool_functions.get_objects_paths(list_of_objects)

Returns a list of the attributes path of the objects passed as parameter (Sequence or Audio instances).

New in version 2.0.

Parameters:

list_of_objects (list(Sequence) or list(Audio)) – A list of Sequence or Audio instances.

Returns:

A list of paths.

Return type:

list(str)

Name functions

tool_functions.get_objects_names(list_of_objects)

Returns a list of the attributes name of the objects passed as parameter (Sequence or Audio instances).

New in version 2.0.

Parameters:

list_of_objects (list(Sequence) or list(Audio)) – A list of Sequence or Audio instances.

Returns:

A list of names.

Return type:

list(str)

Sequence comparison functions

tool_functions.compute_different_joints(sequence1, sequence2, verbosity=False)

Returns the number of joints having different coordinates between two sequences having the same amount of poses. This function can be used to check how many joints have been modified by a processing function.

New in version 2.0.

Note

To discard the rounding errors due to other functions, this function rounds the coordinates to the fifth decimal.

Parameters:
  • sequence1 (Sequence) – A Sequence instance.

  • sequence2 (Sequence) – A Sequence instance.

  • 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.

Returns:

  • int – The number of different joints between the two sequences.

  • int – The total number of joints in each of the sequences.

tool_functions.align_two_sequences(sequence1, sequence2)

Checks if one sequence is a subset of another; if true, the function returns the indices at which the two sequences start synchronizing. Otherwise, it returns False.

New in version 2.0.

Parameters:
  • sequence1 (Sequence) – A Sequence instance.

  • sequence2 (Sequence) – A Sequence instance.

Returns:

If one of the sequences is a subsequence of the other, the function returns a list of two integers, corresponding to the indices of the first and the second sequences where the two sequences synchronize, respectively. Otherwise, this function returns False.

Return type:

list or False

File reading functions

tool_functions.get_system_csv_separator()

Returns the separator (comma or semicolon) of the regional settings of the system; if it can’t access it, returns a comma by default.

New in version 2.0.

Note

This function detects the local decimal separator, and sets the csv delimiter on a semicolon (“;”) if the local decimal separator is a comma (“,”). In any other case, the csv delimiter is set on a comma (“,”). Note that in specific regions of the world, the result may not be ideal. In that case, you can force the csv delimiter to be the symbol of your choice by writing “csv,” or “csv;” when asked for a file extension.

Returns:

The character used as separator in csv files on the current system.

Return type:

str

tool_functions.get_filetype_separator(extension)

Returns the separator used in specific text format files (comma, semicolon or tab). For csv, returns the separator used on the current system. For txt or tsv files, returns a tabulation symbol.

New in version 2.0.

Parameters:

extension (str) – A file extension (csv, tsv or txt).

Returns:

The character used as separator between values in the target file extension.

Return type:

str

tool_functions.read_json(path)

Loads and returns the content of a .json file.

New in version 2.0.

Parameters:

path (str) – The path to a json file.

Returns:

The content of the json file.

Return type:

list or dict

tool_functions.read_text_table(path)

Detects the encoding, loads and returns the content of a .csv, .tsv or .txt file containing a table.

New in version 2.0.

Parameters:

path (str) – The path to a text file.

Returns:

The content of the text file, with each sub-list containing the elements of a row of the file.

Return type:

list(list)

tool_functions.read_xlsx(path)

Loads and returns the content of a .xlsx (Excel) file.

New in version 2.0.

Parameters:

path (str) – The path to an Excel file.

Returns:

The content of the Excel file, with each element of the list being a row of the Excel file.

Return type:

list(list)

tool_functions.convert_data_from_qtm(data, verbosity=1)

Processes and converts the data from a .tsv file produced by QTM, by stripping the header data, standardizing the name of the joint labels, and converting the distance unit from mm to m. This function then returns the loaded table.

New in version 2.0.

Parameters:
  • data (list(str)) – The data from a .tsv QTM file with each line separated as the elements of a list.

  • 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.

Returns:

A table containing the QTM data, with each sub-list containing the elements of a row of the file.

Return type:

list(list(str))

File saving functions

tool_functions.write_text_table(table, separator, path, verbosity=1)

Converts a table to a string, where elements on the same row are separated by a defined separator, and each row is separated by a line break.

New in version 2.0.

Parameters:
  • table (list(list)) – A two-dimensional list where each element is a table row.

  • separator (str) – The character used to separate elements on the same row.

  • path (str) – The complete path of the text file to save.

  • 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.

Returns:

The table in string version.

Return type:

str

tool_functions.write_xlsx(table, path, verbosity=1)

Saves a table in a .xlsx file.

New in version 2.0.

Parameters:
  • table (list(list)) – A list where each sublist is a row of the table.

  • path (str) – The complete path of where to store the Excel file.

  • 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.

Calculation functions

tool_functions.resample_data(data, time_points, frequency, mode='linear', time_unit='s')

Resamples non-uniform data to a uniform time series according to a specific frequency, by interpolating the data.

New in version 2.0.

Note

This function is a wrapper for interpolate_data(), solely creating a new array of time points from the indicated frequency.

Important

This function is dependent of the module numpy.

Parameters:
  • data (list(float) or numpy.ndarray(float)) – A list or an array of values.

  • time_points (list(float) or numpy.ndarray(float)) – A list or an array of the time points corresponding to the values of the data.

  • frequency (int or float) – The frequency at which you wish to resample the time series.

  • mode (str, optional) – The way to interpolate the data. This parameter also allows for all the values accepted for the kind parameter in the function scipy.interpolate.interp1d(): "linear", "nearest", "nearest-up", "zero", "slinear", "quadratic", "cubic"”, "previous", and "next". See the documentation for this Python module for more.

  • time_unit (str, optional) – The time unit of the time points. By default, it is set on “s” (seconds).

Returns:

  • numpy.ndarray(float) – The resampled values.

  • numpy.ndarray(float) – The resampled time points, at a fixed frequency.

tool_functions.interpolate_data(data, time_points_data, time_points_interpolation, mode='linear')

Interpolates incomplete data to a linear array of values.

New in version 2.0.

Important

This function is dependent of the modules numpy and scipy.

Parameters:
  • data (list(float) or numpy.ndarray(float)) – A list or an array of values.

  • time_points_data (list(float) or numpy.ndarray(float)) – A list or an array of the time points corresponding to the values of the data.

  • time_points_interpolation (list(float) or numpy.ndarray(float)) – A list or an array of the time points to which interpolate the data.

  • mode (str, optional) –

    The way to interpolate the data. This parameter also allows for all the values accepted for the kind parameter in the function scipy.interpolate.interp1d(): "linear", "nearest", "nearest-up", "zero", "slinear", "quadratic", "cubic"”, "previous", and "next". See the documentation for this Python module for more.

Returns:

  • numpy.ndarray(float) – The interpolated values.

  • numpy.ndarray(float) – The interpolated time points (same as the parameter time_points_interpolation).

tool_functions.pad(data, time_points_data, time_points_padding, padding_value=0, verbosity=1)

Given an array of values (data) and its corresponding time_points_data, and a larger array time_points_padding, pads the data array with the value specified in padding_value for the time points present in time_points_padding that are absent from time_points_data.

New in version 2.0.

Parameters:
  • data (list(float) or numpy.ndarray(float)) – A list or an array of values.

  • time_points_data (list(float) or numpy.ndarray(float)) – A list or an array of the time points corresponding to the values of the data.

  • time_points_padding (list(float) or numpy.ndarray(float)) – A list or an array of time points containing the values from time_points_data (or values equal up to the fifth decimal), with additional values at the beginning and/or at the end.

  • padding_value (int, numpy.nan or float) – The value with which to pad the data (default: 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.

Returns:

  • np.ndarray – The original data array, padded with zeros.

  • list – The array time_points_padding, passed as parameter.

tool_functions.add_delay(timestamps, delay)

Given an array of timestamps, adds or removes a delay to each timestamp.

New in version 2.0.

Parameters:
  • timestamps (list(float)) – An array of timestamps.

  • delay (float) – The delay, positive or negative to add to each timestamp.

Returns:

An array of timestamps with the delay specified as parameter.

Return type:

list(float)

tool_functions.calculate_distance(joint1, joint2, axis=None)

Uses the Euclidian formula to calculate the distance between two joints. This can be used to calculate the distance travelled by one joint between two poses, or the distance between two joints on the same pose. If an axis is specified, the distance is calculated on this axis only.

New in version 2.0.

Parameters:
  • joint1 (Joint) – The first Joint object.

  • joint2 (Joint) – The second Joint object.

  • axis (str or None, optional) – If specified, the returned distances travelled will be calculated on a single axis. If None (default), the distance travelled will be calculated based on the 3D coordinates.

Returns:

The absolute distance, in meters, between the two joints.

Return type:

float

tool_functions.calculate_velocity(pose1, pose2, joint_label)

Given two poses and a joint label, returns the velocity of the joint, i.e. the distance travelled between the two poses, divided by the time elapsed between the two poses.

New in version 2.0.

Parameters:
  • pose1 (Pose) – The first Pose object, at the beginning of the movement.

  • pose2 (Pose) – The second Pose object, at the end of the movement.

  • joint_label (str) – The label of the joint.

Returns:

The velocity of the joint between the two poses, in m/s.

Return type:

float

tool_functions.calculate_acceleration(pose1, pose2, pose3, joint_label)

Given three poses and a joint label, returns the acceleration of the joint, i.e. the difference of velocity between pose 1 and pose 2, and pose 2 and pose 3, over the time elapsed between pose 2 and pose 3.

New in version 2.0.

Parameters:
  • pose1 (Pose) – The first Pose object.

  • pose2 (Pose) – The second Pose object.

  • pose3 (Pose) – The third Pose object.

  • joint_label (str) – The label of the joint.

Returns:

The velocity of the joint between the two poses, in m/s.

Return type:

float

tool_functions.calculate_delay(pose1, pose2)

Returns the delay between two poses, in seconds.

New in version 2.0.

Parameters:
  • pose1 (Pose) – The first Pose object.

  • pose2 (Pose) – The second Pose object.

Returns:

The time, in seconds, between the two poses.

Return type:

float

Note

The time returned by the function is not an absolute value. In other words, if pose1 has a higher timestamp than pose2, the returned value will be negative.

tool_functions.generate_random_joints(number_of_joints, x_scale=0.2, y_scale=0.3, z_scale=0.5)

Creates and returns a list of Joint objects with random coordinates. The coordinates are generated following a uniform distribution centered around 0 and with limits defined by x_scale, y_scale and z_scale.

New in version 2.0.

Parameters:
  • number_of_joints (int) – The number of random joints to generate.

  • x_scale (float) – The absolute maximum value of the random uniform distribution on the x axis.

  • y_scale (float) – The absolute maximum value of the random uniform distribution on the y axis.

  • z_scale (float) – The absolute maximum value of the random uniform distribution on the z axis.

Returns:

A list of joints with randomized coordinates.

Return type:

list(Joint)

tool_functions.divide_in_windows(array, window_size, overlap=0, add_incomplete_window=True)

Given an array of values, divides the array in windows of a size window_size, with or without an overlap.

New in version 2.0.

Parameters:
  • array (list(int or float) or np.array(int or float)) – An array of numerical values.

  • window_size (int) – The number of array elements in each window.

  • overlap (int) – The number of array elements overlapping in each window.

  • add_incomplete_window (bool) – If set on True, the last window will be added even if its size is smaller than window_size. Otherwise, it will be ignored.

Returns:

A list where each element is a window of size window_size.

Return type:

list(list(int or float))

Color functions

tool_functions.load_color_names()

Returns a dictionary containing the 140 lower-case, whitespaces-stripped X11 and HTML/CSS colors as keys (plus 7 variations of grey/gray), and a tuple of their 256-level RGBA codes as values. The colors are contained in res/color_codes.txt. The color names follow the 140 HTML/CSS color names).

New in version 2.0.

Returns:

dict(str – A dictionary of the color names and their RGBA values.

Return type:

tuple(int))

tool_functions.load_color_schemes()

Returns a dictionary containing the color gradients saved in res/color_gradients.txt.

New in version 2.0.

Returns:

dict(int – A dictionary with the name of color gradients as keys, and a list of their corresponding RGBA colors as values.

Return type:

list(tuple(int, int, int, int)))

tool_functions.hex_color_to_rgb(color, include_alpha=None)

Converts a color from its hexadecimal value to its RGB or RGBA value.

Parameters:
  • color (str) – The hexadecimal value of a color, with or without a leading number sign ("#").

  • include_alpha (bool, optional) – If True, returns the RGB color with an alpha value. If an alpha value is not present in the hexadecimal value, the alpha channel will be set to 255. If set on None (default), the returned value will contain and alpha value only if the input color contains one.

Returns:

A RGB or RGBA value.

Return type:

tuple(int, int, int) or tuple(int, int, int, int)

tool_functions.rgb_color_to_hex(color, include_alpha=False)

Converts a color from its RGB or RGBA value to its hexadecimal value.

Parameters:
  • color (tuple(int, int, int) or tuple(int, int, int, int)) – The RGB or RGBA value of a color.

  • include_alpha (bool, optional) – If True, returns the hexadecimal color with an alpha value. If an alpha value is not present in the RGB value, the alpha channel will be set to ff.

Returns:

A hexadecimal value, with a leading number sign ("#").

Return type:

str

tool_functions.convert_color(color, color_format='rgb', include_alpha=True)

Converts a color to the desired format.

New in version 2.0.

Parameters:
  • color (str or tuple(int, int, int) or tuple(int, int, int, int)) –

    This parameter can take a number of forms:

    • The HTML/CSS name of a color (e.g. "red" or "blanched almond"),

    • The hexadecimal code of a color, starting with a number sign (#, e.g. "#ffcc00" or "#c0ffee").

    • The RGB or RGBA tuple of a color (e.g. (153, 204, 0) or (77, 77, 77, 255)).

  • color_format (str, optional) – The format in which you want to convert the color. This parameter can be "rgb" (default), "rgba" or "hex".

  • include_alpha (bool, optional) – If True, returns the color with an alpha value. If an alpha value is not present in the original value, the alpha channel will be set to 255 (or ff).

Returns:

A list of RGB or RGBA values, or hexadecimal strings with a leading number sign.

Return type:

list(tuple(int, int, int)) or list(tuple(int, int, int, int)) or list(string)

tool_functions.convert_colors(color_scheme_or_colors, color_format='RGB', include_alpha=True)

Converts a list of colors to the desired format.

New in version 2.0.

Parameters:
  • color_scheme_or_colors (str or list(str)) –

    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.

    • 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_format (str, optional) – The format in which you want to convert the colors. This parameter can be "RGB" (default), "RGBA" or "HEX".

  • include_alpha (bool, optional) – If True, returns the colors with an alpha value. If an alpha value is not present in the original value, the alpha channel will be set to 255 (or ff).

Returns:

A RGB or RGBA value, or a hexadecimal string with a leading number sign.

Return type:

tuple(int, int, int) or tuple(int, int, int, int) or string

tool_functions.calculate_color_points_on_gradient(color_scheme, no_points)

Given a color scheme and a number of points, creates a list of equidistant colors to create a gradient.

Parameters:
  • color_scheme (str or list(tuple(int, int, int, int))) – The name of a color scheme (see Color schemes for the available schemes), or a list of RGBA color tuples.

  • no_points (int) – The number of colors to get on the gradient.

Returns:

A list of colors in a progressive gradient following the colors of the color scheme.

Return type:

list(tuple(int, int, int, int))

tool_functions.calculate_color_ratio(colors, ratio, type_return='rgb', include_alpha=True)

Given a gradient of colors, returns a color located at a specific ratio on the gradient.

New in version 2.0.

Parameters:
  • colors (list(tuple(int, int, int)) or list(tuple(int, int, int, int))) – A list of RGB or RGBA color tuples.

  • ratio (float) – The ratio of the color, between 0 and 1, on the gradient. If this parameter is equal to or inferior to 0, the function will return the first color of the colors parameter. If the ratio is equal or superior to 1, the function will return the last color of the colors parameter.

  • type_return (str, optional) – The way the color should be returned. If set on "rgb" (default) or "rgba", the color will be returned as a tuple of integers. If set on "hex", the color will be returned as a string containing hexadecimal values, with a number sign (#) as a leading character.

  • include_alpha (bool, optional) – If True, returns the hexadecimal color with an alpha value. If an alpha value is not present in the RGB value, the alpha channel will be set to 255.

Returns:

A color in RGB, RGBA or hex form.

Return type:

list(tuple(int, int, int)) or list(tuple(int, int, int, int)) or str

tool_functions.calculate_colors_by_values(dict_values, color_scheme='default', type_return='rgb', include_alpha=True)

Returns a dictionary of colors on a gradient depending on the values of a dictionary. The extreme colors of the color scheme will be attributed to the extreme values of the dictionary; all the intermediate values are attributed their corresponding intermediate color on the gradient.

New in version 2.0.

Parameters:
  • dict_values (dict(str: float or int)) – A dictionary where keys (e.g., joint labels) are attributed to values (floats or integers).

  • color_scheme (str or list) – A color scheme or a list of colors that can be parsed by the function tool_functions.convert_colors_rgba().

  • type_return (str, optional) – The way the color should be returned. If set on "rgb" (default) or "rgba", the color will be returned as a tuple of integers. If set on "hex", the color will be returned as a string containing hexadecimal values, with a number sign (#) as a leading character.

  • include_alpha (bool, optional) – If True, returns the hexadecimal color with an alpha value. If an alpha value is not present in the RGB value, the alpha channel will be set to 255.

Returns:

dict(str – A dictionary where each key is matched to an RGBA color.

Return type:

tuple(int, int, int, int))

tool_functions.generate_random_color()

Generates a random color, and returns its RGBA value (with an alpha value of 255).

New in version 2.0.

Returns:

A tuple containing the RGBA values of a random color, with an alpha value of 255.

Return type:

tuple(int, int, int, int)

Audio functions

tool_functions.scale_audio(audio_array, max_value, use_abs_values=False, set_lowest_at_zero=False, verbosity=1)

Scale an array of audio samples according to a maximum value.

Parameters:
  • audio_array (list(int or float) or numpy.array(int or float)) – An array of audio samples.

  • max_value (int or float) – The value that will become the maximum value of the scaled array.

  • use_abs_values (bool, optional) – If set on True, the values of the samples will be converted to absolute values. If set on False (default), the sign of the samples will be preserved.

  • set_lowest_at_zero (bool, optional) – If set on True, if the minimum sample value of the audio is over zero, the minimal value will be subtracted from all the samples. This parameter is set on False by default.

  • 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.

Returns:

An array of scaled audio samples.

Return type:

list(float)

tool_functions.stereo_to_mono(audio_arrays, verbosity=1)

Turns the sample data into mono by averaging the samples from the audio channels.

New in version 2.0.

Parameters:
  • audio_arrays (numpy.ndarray) – An array containing sub-lists with the sample values from all the channels as elements. Typically, the output of scipy.io.wavfile.read.

  • 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.

Returns:

An array containing the samples averaged across all channels.

Return type:

np.ndarray(np.intp)

Joint labels loading functions

tool_functions.load_kinect_joint_labels()

Loads the list of the 21 kinect joint labels from res/kinect_joint_labels.txt.

New in version 2.0.

Returns:

The list of the Kinect joint labels.

Return type:

list(str)

tool_functions.load_qualisys_joint_labels(label_style='original')

Loads the list of the 44 Qualisys joint labels from res/kualisys_joint_labels.txt.

New in version 2.0.

Parameters:

label_style (str, optional) – If set on "original", the returned joint labels are the original ones from the Qualisys system. If set on "krajjat" or "kualisys", the returned joint labels are the renamed Kualisys joint labels from the Krajjat toolbox. For more information, see Joint labels.

Returns:

The list of the Qualisys joint labels.

Return type:

list(str)

tool_functions.load_qualisys_joint_label_conversion()

Returns a dictionary containing the original Qualisys joint labels as keys, and the renamed Kualisys joints labels as values. The dictionary is loaded from res/kualisys_joint_labels.txt. For more information, see Joint labels.

New in version 2.0.

Returns:

dict(str – A dictionary with the original Qualisys joint labels as keys, and the Kualisys renamed joint labels as values.

Return type:

str)

tool_functions.load_joint_labels(path)

Returns a list of joint labels from a path.

New in version 2.0.

Parameters:

path (str) – The path to a file containing a joint label on each line.

Returns:

A list containing joint labels.

Return type:

list(str)

tool_functions.load_joints_connections(path)

Returns a list of joint pairs between which a line can be traced to form a skeleton.

New in version 2.0.

Parameters:

path (str) – The path to a file containing joint label pairs separated by a tabulation on each line.

Returns:

A list of sub-lists, each containing two elements (two joint labels).

Return type:

list(list(str))

tool_functions.load_qualisys_to_kinect()

Loads a dictionary containing Kinect joint labels as keys, and a series of Kualisys joint labels as values. The Kinect joints can be averaged from the joints in values. The dictionary is loaded from res/kualisys_to_kinect.txt. For more information, see Joint labels.

New in version 2.0.

Returns:

dict(str – A dictionary of Kinect joint labels as keys, and a series of Kualisys joint labels as values.

Return type:

list(str))

tool_functions.load_joints_subplot_layout(joint_layout)

Returns a dictionary of the subplot positions of the joints on a skeleton graph. Loads the data from "res/kinect_joints_subplot_layout.txt" or "res/kualisys_joints_subplot_layout.txt".

New in version 2.0.

Parameters:

joint_layout (str) – The layout to load, either "kinect" or "qualisys".

Returns:

dict(str – A dictionary containing joint labels as keys, and subplot positions as values.

Return type:

int)

tool_functions.load_steps_gui()

Loads the steps for the modification of the parameters in the GUI of the graphic functions, from the file res/steps_gui.txt.

New in version 2.0.

Miscellaneous functions

tool_functions.show_progression(verbosity, current_iteration, goal, next_percentage, step=10)

Shows a percentage of progression if verbosity is equal to 1.

New in version 2.0.

Parameters:
  • verbosity (int) – This parameter must be equal to 1 for the function to print information. If the value is set on 2 (chatty mode), the percentage will not be displayed, in favour of more detailed information related to the ongoing operations.

  • current_iteration (int or float) – The current iteration in a loop.

  • goal (int or float) – The stopping value of the loop.

  • next_percentage (int or float) – The next percentage at which to print the progression.

  • step (int or float, optional) – The step between each print of the progression.

Returns:

The next percentage at which to print the progression.

Return type:

int or float

Example

>>> next_percentage = 10
>>> goal = 100
>>> for i in range(goal):
...       next_percentage = show_progression(1, i, goal, next_percentage)
10% 20̀% 30% 40% 50% 60% 70% 80M 90%
tool_functions.resample_images_to_frequency(images_paths, timestamps, frequency)

Given a series of images with specific timestamps, returns a new series of images and timestamps, resampled at a given frequency. For example, for images with timestamps at a rate of 20 Hz, and with a frequency set on 100 Hz, each image path will be copied 5 times with 5 different timestamps in the output. This can be used to obtain a video set at a defined framerate, regardless of the original frequency.

New in version 2.0.

Parameters:
  • images_paths (list(str)) – A list of images paths.

  • timestamps (list(float)) – A list of timestamps for each image path.

  • frequency (int or float) – The frequency at which to resample the images (images per second).

Returns:

  • list(str) – A list of images paths.

  • list(float) – A list of timestamps.

tool_functions.get_min_max_values_from_plot_dictionary(plot_dictionary, keys_to_exclude=None)

Returns the minimum and maximum values of all the graphs contained in a plot dictionary.

New in version 2.0.

Parameters:
  • plot_dictionary (dict) – A dictionary with labels as keys and Graph elements as values.

  • keys_to_exclude (list(string)) – A list of keys of the dictionary to exclude from the search of the minimum and maximum values.

Returns:

  • float – The minimum value detected in all the series.

  • float – The maximum value detected in all the series.

tool_functions.kwargs_parser(dictionary, suffix)

Given a dictionary of keyword arguments and a suffix, returns a dictionary that removes the suffix from the given keywords. If a key without the suffix already exists in the dictionary, it is left untouched and the key with the suffix is removed.

New in version 2.0.

Parameters:
  • dictionary (dict) – A dictionary of keyword arguments.

  • suffix (str) – The suffix to look for in the keys of the dictionary.

tool_functions.format_time(time, time_unit='s', time_format='hh:mm:ss')

Formats a given time in a given unit according to a time format.

New in version 2.0.

Parameters:
  • time (int or float) – A value of time.

  • time_unit (str, optional) – The unit of the time parameter. This parameter can take the following values: “ns”, “1ns”, “10ns”, “100ns”, “µs”, “1µs”, “10µs”, “100µs”, “ms”, “1ms”, “10ms”, “100ms”, “s”, “sec”, “1s”, “min”, “mn”, “h”, “hr”, “d”, “day”.

  • time_format (str, optional) – The format in which to return the time. Can be either “hh:mm:ss”, “hh:mm:ss.ms”, “hh:mm”, “mm:ss” or “mm:ss.ms”.