Kineticstoolkit

New features

Scripting API for the Player

The Player can now be entirely scripted:

- Get/set the TimeSeries to be visualized using `Player.get_contents()` and `Player.set_contents()`
- Get/set the point interconnections using `Player.get_interconnections()` and `Player.set_interconnections()`
- Play/pause using `Player.play()` and `Player.pause()`
- Access and modify all settings using properties such as `current_index`, `current_time`, `target`, `zoom`, `elevation`, `azimuth`, etc.

Styling the Player

Every element can now be stylized using properties such as `background_color`, `default_point_color`, `point_size`, `frame_size`, `frame_width`, `grid_size`, `grid_subdivision_size`, etc.

Exporting the Player's content to images and videos

You can now export the Player's content to image files such as PNG, JPEG, PDF, SVG or TIFF using `Player.to_image()`, or to MP4 videos using `Player.to_video()`. This, combined to styling, should help you giving nice presentations!

Standard views in the Player

By defining which axes (x, y, z, -x, -y, -z) correspond to the up and anterior direction using the `up` and `anterior` properties, you can now switch to standard orthogonal views using `Player.set_view()`. For example: `p.set_view("front")`, `p.set_view("top")`, `p.set_view("right")`, etc. These views are also available interactively using number keys 1 to 6.

Convert anything to a TimeSeries

It is now easier than never to create a TimeSeries. For instance, a list of data:

A new release on the road toward version 1.0. Remember that starting from 0.12, the API is mostly stable and we won't remove any feature or make any incompatible change before either 1.0 is released or before 2 years of deprecation warnings. **It is safe to use Kinetics Toolkit in your work, we won't let you down!**

In this release:

Improvements

- `ktk.read_c3d()` can now read the event contexts, not just the names, using the new `include_event_context` argument. If False, the events in the output TimeSeries are named after the events names in the C3D files, e.g.: "Start", "Heel Strike", "Toe Off". If True, the events in the output TimeSeries are named using this scheme "context:name", e.g.,: "General:Start", "Right:Heel strike", "Left:Toe Off". The default is False. **Thanks jorgomezga for suggesting and testing!**
- TimeSeries' methods `get_ts_between_indexes()`, `get_ts_between_times()` and `get_ts_between_events()` now accept a new form for their argument `inclusive`. In addition to provide a simple boolean (False: strictly between, True: inclusive between), we can now provide a tuple/list of two booleans. For instance, [True, False] means "greater or equal to first index/time, and strictly less than second index/time".
- TimeSeries' methods `get_ts_between_indexes()`, `get_ts_between_times()` are now much faster on very long TimeSeries.
- Introducing progress bars for long operations, starting with `ktk.cycles.detect_events()`. If the optional package `tqdm` is installed, a progress bar is shown if the function takes lots of time. If it is not installed, the function works as usual, without a progress bar.

Bugfixes

- `ktk.read_c3d()` now works correctly with files with more than 255 markers or 255 analog signals, or with no labels. **Kudos jorgomezga for noticing and for proposing a fix!**
- `TimeSeries.get_ts_after_index` and `TimeSeries.get_ts_before_index` now return a `TimeSeriesRangeError` when index is invalid, instead of wrongly returning an empty TimeSeries.
- Function that expect integers as arguments do not complain anymore when they receive a numpy.int64 instead.
- Saving a Pandas DataFrame that contains different data types using `ktk.save` now loads back correctly.

As always, do not hesitate to ask for help on the [discussion board](https://github.com/felixchenier/kineticstoolkit/discussions). We are seeing more and more activity there and it is very motivating.

New features
- [ktk.write_c3d](https://kineticstoolkit.uqam.ca/doc/api/ktk.write_c3d.html) can now write analogs in addition to points.
- [ktk.geometry.rotate](https://kineticstoolkit.uqam.ca/doc/api/ktk.geometry.rotate.html), [ktk.geometry.translate](https://kineticstoolkit.uqam.ca/doc/api/ktk.geometry.translate.html), [ktk.geometry.scale](https://kineticstoolkit.uqam.ca/doc/api/ktk.geometry.scale.html): Instead of having to create a series of transformation matrices and then apply this series to a series of coordinates, we can now use these three shortcut functions that directly transform series of coordinates.

Enhancements
- Addition of a `scales` parameter to [ktk.geometry.create_transforms](https://kineticstoolkit.uqam.ca/doc/api/ktk.geometry.create_transforms.html). We already had `angles` and `translations`, we now also have a scales parameter to create all kinds of rigid transforms matrices.
- Now every [ktk.geometry](https://kineticstoolkit.uqam.ca/doc/api/ktk.geometry.html) operation with rigid transforms checks that the transform matrices are rigid (determinant = 1) before doing the calculation. This is mainly to ensure that (1) there is no user error with the shape and contents of the provided matrix series, and (2) we propagate error from long lists of calculations on badly conditioned matrices.
- Parameter `convert_point_unit` is now optional and defaults to None in [ktk.read_c3d](https://kineticstoolkit.uqam.ca/doc/api/ktk.read_c3d.html). The docstring and behaviour of ktk.read_c3d were clarified for cases when c3d points are not expressed in meters, to clear confusion when the file contains application-specific "points" such as calculated angles, powers and forces.
- These functions are not experimental anymore:
- [ktk.kinematics.create_cluster](https://kineticstoolkit.uqam.ca/doc/api/ktk.kinematics.create_cluster.html),
- [ktk.kinematics.extend_cluster](https://kineticstoolkit.uqam.ca/doc/api/ktk.kinematics.extend_cluster.html),
- [ktk.kinematics.track_cluster](https://kineticstoolkit.uqam.ca/doc/api/ktk.kinematics.track_cluster.html),
- [ktk.geometry.register_points](https://kineticstoolkit.uqam.ca/doc/api/ktk.geometry.register_points.html),
- [ktk.TimeSeries.resample](https://kineticstoolkit.uqam.ca/doc/api/ktk.TimeSeries.resample.html),
- [ktk.TimeSeries.fill_missing_samples](https://kineticstoolkit.uqam.ca/doc/api/ktk.TimeSeries.fill_missing_samples.html).

Bugfixes
- Now we get a clear error message in [ktk.cycles.time_normalize](https://kineticstoolkit.uqam.ca/doc/api/ktk.cycles.time_normalize.html) when an unknown event name is given as parameter.

Requirement changes
- Now requires Python 3.10 or later.

- New feature: `ktk.TimeSeries.count_events`. Counts the number of occurrences of a given event. This function is useful for example to loop over cycles.
- New feature: `ktk.TimeSeries.remove_duplicate_events`. Removes duplicate events (that share a same name and same time).
- Improvement: Better error messages. All functions now perform basic real-time type checking and return clear messages in case of unexpected input. Many error messages are also more helpful, particularly in TimeSeries’ get_ts_ methods.
- Improvement: `ktk.Player` now allows interconnections to be any length, not only bouts of two-marker connections.
- Improvement: `ktk.TimeSeries.add_event` now has an optional unique argument to prevent adding duplicate events.
- Improvement: `ktk.TimeSeries.merge` does not duplicate events anymore if a same event was present in both TimeSeries.
- Improvement: Now uses Python 3.9 annotations (using from __future__ import annotations). Python 3.9 is not required yet, only Python 3.8.
- Improvement: Now uses Numpy’s ArrayLike in static typing annotations.
- Bugfix: `ktk.Player`’s target parameter now respects the ground plane orientation given by the up parameter introduced in 0.9.1.
- Bugfix: `ktk.TimeSeries.sort_events` does not miss duplicate events anymore.
- Deprecation: The following TimeSeries methods were deprecated because they don’t provide enough functionality compared to the complexity they generate when learning Kinetics Toolkit by new users. Using those functions now generates a deprecation warning with a suggestion to get the same result with other functions:
- `TimeSeries.get_event_index()`
- `TimeSeries.get_event_time()`
- `TimeSeries.get_ts_at_event()`
- `TimeSeries.get_ts_at_time()`
- `TimeSeries.sync_event()`
- `TimeSeries.ui_get_ts_between_clicks()`
- Breaking change: These parameter names were changed in `ktk.kinematics`:
- Changed `marker_names` parameter for `names` in `ktk.kinematics.create_cluster`.
- Changed `new_point` parameter for `name` in `ktk.kinematics.extend_cluster`.
- Breaking change: Changed default value of unique from `True` to `False` in `ktk.TimeSeries.sort_events`.

- New feature: ktk.Player now has a `up` parameter. Before, the ground plane was xz with y being up. Now, any ground plane can be used, by choosing `up` among {'x', 'y', 'z', '-x', '-y', '-z'}.
- Bugfix: Resolved an error in ktk.read_c3d where reading would fail on c3d files with empty events.