Welcome to the discussion board!

[felixchenier]

Feel free to ask any question here. By asking questions, you may help others to solve their own questions.

For questions on how to use Kinetics Toolkit for this or that case, or to better understand some features of Kinetics Toolkit, please use the 1. Users Q&A category.

For propositions of improvement, ideas, wishes for upcoming versions of Kinetics Toolkit, please use the 2. Development: Ideas, new features, doc, etc. category.

Don't be shy to propose your own answers in discussions of any category. Exchanges are always good 😃

[ezmcmahon]

Hi all,

Just started my own journey into the use of Python within Biomechanics.

I am comfortable with the use of VICON and Visual 3D, but have little experience so far with Python.

Thankfully came across this group on github after doing a few google searches for recommendations learning Python in biomechanics.

My question is, any advice on learning Python for use within a Biomechanics Lab?

Any feedback will be appreciated.

Thank you.

[felixchenier]

Hi @ezmcmahon

Warm welcome! I think you found the right place. Everything here is directed toward learning Python for biomechanics, including of course biomechanics labs.

It is my aim to guide newcomers to Python from having no bases in programming up to being able to code or at least understand data processing code for biomechanics. It will be a challenge for sure, but I think you will find this rewarding. If you have no to little experience with Python, then start with the Learning Python for biomechanics section which takes you from installing Python, using a developement environment (Spyder), writing you first python code, up to generating curves with Matplotlib and process series of vectors and matrices using NumPy.

Then, you can go to the Kinetics Toolkit Manual where you need to read at least the sections on TimeSeries. Then you can go where you want, but since you're working with VICON and Visual 3D, I think your more relevant sections will be "3D rigid body geometry" and "Kinematic analysis".

Good luck and never hesitate to ask for help in the Q&A section of the discussion board.

[ezmcmahon]

Thank you.

I appreciate the advice!

[Alek050]

Hi @felixchenier,

First of all, you created a great package, really enjoying it. I am not sure whether you have already covered it but browsing through the code and some of the documentation I was not able to find it. Some tracking systems do not save point data in the c3d files, but only rotation matrices of segments (example file). I tried if ezc3d has covered this already, and similar to obtaining points (ezc3d_c3d["data"]["points"]) you can obtain these rotation matrices (ezc3d_c3d["data"]["rotations"]) which will by a np.ndarray of shape (4, 4, n_segments, n_frames). Is there already a way of loading this in the kineticstoolkit and calculating angles between different segments over time?

Thanks for you reaction!

[felixchenier]

Hi @Alek050

Thanks for your feedback! I wasn't aware that C3D files can hold full transform series; I only dealt with points and analogs up to now. So the answer (for now) is no, those transforms are not loaded at the moment. But from what you tell me, it would be very easy to add this feature in a future release. I'll add a feature request for it. It won't be in the next release (0.14) though, since I already plan to release 0.14 very soon. But it will be for sure in 0.15.

Only in the case you are confident and have time, and you want to add this feature yourself, at least for a local copy of yours:

The read_c3d function is defined in kineticstoolkit/files.py. Look at the section that reads the points, from line 475 to 581:

    # ---------------------------------
    # Create the points TimeSeries
    points = TimeSeries()

    # Get the marker label names and create a timeseries data entry for each
    # Get the labels
    point_rate = reader["parameters"]["POINT"]["RATE"]["value"][0]
    point_unit = reader["parameters"]["POINT"]["UNITS"]["value"][0]
    point_start = reader["header"]["points"]["first_frame"]
    start_time = point_start / point_rate
    n_points = reader["parameters"]["POINT"]["USED"]["value"][0]

    labels = reader["parameters"]["POINT"]["LABELS"]["value"]
    # Check if labels2, labels3, labels4,.... exist.
    # https://www.c3d.org/HTML/default.htm?turl=Documents%2Fpointlabels2.htm
    i_additional_labels = 2
    while True:
        str_labels = f"LABELS{i_additional_labels}"
        try:
            additional_labels = reader["parameters"]["POINT"][str_labels][
                "value"
            ]
        except KeyError:
            break
        labels.extend(additional_labels)
        i_additional_labels += 1

    # Solve the point unit conversion mess (issue #147)
    scales = {"mm": 0.001, "cm": 0.01, "dm": 0.1, "m": 1.0}

    if convert_point_unit is None:
        if point_unit == "m":
            point_factor = 1.0
            point_unit = "m"
        elif point_unit in scales:
            warnings.warn(
                "In the specified file, points are expressed in "
                f"{point_unit}. They were automatically converted to meters "
                f"by scaling them by {scales[point_unit]}. Please note that "
                "if this file also contains calculated values such as "
                "angles, powers, etc., they were also (wrongly) scaled by "
                f"{scales[point_unit]}. Consult "
                "https://kineticstoolkit.uqam.ca/doc/api/ktk.read_c3d.html "
                "for more information. You can mute this warning "
                "by explicitely setting `convert_point_unit` to either True "
                "or False."
            )
            point_factor = scales[point_unit]
            point_unit = "m"
        else:
            warnings.warn(
                "In the specified file, points are expressed in "
                f"`{point_unit}`, which is not recognized by ktk.read_c3d. They "
                "were left as is, without attempting to convert to meters. "
                "You can mute this warning by setting `convert_point_unit` to "
                "False."
            )
            point_factor = 1.0
            # point_unit = Do not update

    elif convert_point_unit is True:
        try:
            point_factor = scales[point_unit]
            point_unit = "m"
        except KeyError:
            raise ValueError(
                "In the specified file, points are expressed in "
                f"`{point_unit}`, which is not recognized by ktk.read_c3d. "
                "Please set `convert_point_unit` to None of False."
            )

    else:
        point_factor = 1
        # point_unit = Do not update

    for i_label in range(n_points):
        # Make sure it's UTF8, and strip leading and ending spaces
        label = labels[i_label]
        key = label.encode("utf-8", "ignore").decode("utf-8").strip()
        if label != "":
            points.data[key] = np.array(
                [point_factor, point_factor, point_factor, 1]
                * reader["data"]["points"][:, i_label, :].T
            )
            points = points.add_data_info(key, "Unit", point_unit)

    if n_points > 0:
        points.time = (
            np.arange(points.data[key].shape[0]) / point_rate + start_time
        )

    # Add events
    for i_event in range(len(event_names)):
        event_time = event_times[i_event]
        if include_event_context:
            event_name = event_contexts[i_event] + ":" + event_names[i_event]
        else:
            event_name = event_names[i_event]
        points.add_event(
            event_time,
            event_name,
            in_place=True,
        )
    points.sort_events(in_place=True)

    # Add to output
    output["Points"] = points

I think this code is relatively straightforward if you understand both the ezc3d structure and the TimeSeries class. If it's the case, then you could probably take a large chunk of that code to read the rotations in addition to points and analogs, and return those rotations in the output dictionary.

But do not waste your time if you don't have this time. I'll do it with pleasure, only not in the really short term.

---

Is there already a way of loading this in the kineticstoolkit and calculating angles between different segments over time?

Not loading it, as we discussed it, but once you have those transforms as TimeSeries, then yes, you can calculate angles between the segments. You can read on it here: https://kineticstoolkit.uqam.ca/doc/geometry_angles.html

I hope this answer satisfies you at least for the moment :-)

[Alek050]

Thanks for your elaborate reply, very clear. I did not find a contributing.md or something so I am not fully aware what the expected workflow is, but I assume just forking main and creating a pull request? I've also not dived into the source code, but looking in it quickly it seems like only the read_c3d and write_c3d need changes at this point (and corresponding tests)?

[felixchenier]

@Alek050 Great, so you're thinking about making the change to the code base yourself! Excellent, I highly encourage it :-)

The development instructions are on the website: https://kineticstoolkit.uqam.ca/doc/dev_rules.html But I agree I should put a contributing.md that links there.

You're right, it's the usual fork/PR method. As you tell, only read_c3d and write_c3d need to be modified. Their tests are in /tests/test_files.py. You should add two tests, one for read_c3d using the provided sample on the c-motion site, and the other for write_c3d which could be in two parts: one that writes and reads back the sample data from c-motion; another one that creates a c3d from scratch, from bare TimeSeries.

You can add the sample file from c-motion to data/c3d_test_suite/others and commit it, and use ktk.doc.download to access the file (take example on the other tests). ktk.doc.download always looks for a local file before downloading, it's just a very convenient way to play with sample files.

You will need additional packages to run the tests, I think of black, mypy, coverage and pytest. I may forget one but I think this is it.

If you change your mind, there is absolutely no problem. I can do this change, it will be my pleasure. But I know it's fun for some people to participate in open source projects (I personally enjoy it much) so if you're in, please go ahead! :-) In this case, we may continue this conversation on the feature request issue: #229