How To: Upload Motion Capture Data via the Reboot Motion API

Welcome!

This tutorial walks you through uploading one or more motion capture files via the Reboot Motion API. For more information about the endpoints included in this tutorial, or any other endpoint, you can check out our API documentation.

Note: You will need a valid Access Token (or legacy API Key) to interact with the API endpoints mentioned in this tutorial. Access to the Reboot Motion API is available to all active Reboot Motion customers, and you can find authentication-related documentation in the Reboot Motion API Documentation.

Understanding the Endpoint

First, let’s take a look at the Reboot Motion API documentation for Motion Capture. You'll notice two endpoints, both of which will be used in this tutorial:

In order to upload motion capture files, we will first create a Motion Capture Session (essentially, a collection of motion capture files) using the POST /mocap_session endpoint. This endpoint returns a Session object.

Next, we will upload one or more files from our motion capture session using the POST /mocap_session_file endpoint, which creates Motion Capture Session File objects. The POST /mocap_session_file endpoint accepts a collection of filenames and returns pre-signed URLs to which those files can be uploaded. Each Motion Capture Session File is associated to a Session object.

Before we start, we want to set up our main.py we want to set up our main.py file properly, so let's make sure you have the any required import statements and constants at the top of your file —, like the os library for interacting with environment variables, and the requests library for making HTTP requests.

import os
import requests 

ACCESS_TOKEN = "<YOUR ACCESS TOKEN>"

If you're not sure what any of these import statements or constants are doing, hop over to our Getting Set Up tutorial, which walks you through each of those.

Also note that the ACCESS_TOKEN constant above would reflect an actual access token provided by our authentication process, which is detailed in the Getting Set Up tutorial. In our example, we are hard-coding a token value for ease of understanding, but in practice, you'll need to ensure your credentials are stored securely and an access token is retrieved before making your API requests. It is wise to read your credentials from a secure value store or from an environment variable, rather than hard-coding them into your code. As mentioned in the tutorial, please be incredibly careful not to commit your credentials to a public repository.

As a reminder: all the values used in this tutorial are example values. You cannot plug and play with the example values as they currently are; you will need to put in the correct values for your organization. The example values used in this tutorial are for a fictional values.

Motion Capture Session

As mentioned above, our first step is to create the Motion Capture Session, using the POST /mocap_session endpoint (API Documentation: Create Motion Capture Session.)

This step creates and returns a Session, to which motion capture files can subsequently be uploaded using the Create Mocap Session File endpoint.

Before we begin, you will notice that the POST /mocap_session endpoint requires the following parameters below when making a request.

{
    "org_id": "org-1501e096",
    "mocap_type_id": 2,
    "session_date": "2022-03-30",
    "session_type_id: 1,
}

There are some Reboot Motion-specific terms in here, so let’s define those:

There are other optional fields that can be included in the request and these are listed and explained in our API Documentation for the Create Motion Capture Session endpoint.

Now let's create a Motion Capture Session:

import os
import requests 
API_KEY = "API_KEY_FROM_REBOOT"
API_HEADER = {'x-api-key': API_KEY}

def main():
    
    mocap_sesssion_input = {
        "mocap_type_id": 2,
        "session_date": "2022-03-30",
        "session_type_id: 1
    }

    create_mocap_sesssion = requests.post(
        "https://api.rebootmotion.com/mocap_sesssion",
        headers=API_HEADER,
        json=mocap_sesssion_input,
    )
    print(create_mocap_sesssion.json())

if __name__ == "__main__":
    main()

Running the above example code will create a motion capture session, and will print out the JSON values of the response to your terminal. As a reminder, you should NOT just copy/paste/run the above code; instead, you should modify it to fit your individual use case. In your production code, you'll want customize this to handle errors and utilize the response values.

If no errors occur, the output should look something like this:

{
    "session_date": "2022-03-30",
    "session_type_id": 1,
    "mocap_type_id": 2,
    "num_movements": 1,
    "id": "4d559f35-43c0-4126-a7d5-15abbe2f72ff",
    "status": "pending",
    "num_players": 1,
    "created_at": "2022-03-30 12:15:000",
    "updated_at": "2022-03-30 12:15:000",
    "session_id": "4d559f35-43c0-4126-a7d5-15abbe2f72ff"
}

Motion Capture Session File

Now that we've created a Motion Capture Session, we can create a Motion Capture Session File using the POST /mocap_session_fle endpoint. (API Documentation: Create Motion Capture Session File.)

This step uses a collection of filenames (along with associated metadata) to create and return pre-signed URLs to which those files can be uploaded. Once uploaded, files will be associated with the appropriate Session (that you created with the Create Mocap Session endpoint.)

Before we begin, you will notice that the POST /mocap_session_file endpoint requires a number of parameters when making a request.

For example, if you're uploading video files (the rebootmotion mocap type), that might look like:

{
    "session_id": "6d559c45-45c0-4137-a2d8-15acbe2f72fe",
    "filenames": ["play1.mp4", "play2.mp4"]
}

Or if you're uploading Hawk-Eye action files, it might look like:

{
    "session_id": "6d559c45-45c0-4137-a2d8-15acbe2f72fe",
    "filenames": ["play1.baseball.action", "play2.baseball.pitcher"]
}

Some additional, optional parameters to make note of :

• video_framerate: represents how quickly frames appears within a second. Typically optional; however, this parameter is required when the session's motion capture type is rebootmotion (video).
• reprocess: If set to True/true, this parameter allows for files that already exist for the provided session to be uploaded again for reprocessing. Defaults to false, in which case attempting to upload a duplicate file will result in an error.

Details on all required and optional parameters can be found in the API Documentation for the Create Mocap Session File endpoint.

Now let's create a motion capture session file for a rebootmotion (video) Motion Capture type:

import os
import requests 

ACCESS_TOKEN = '<YOUR ACCESS TOKEN>'


def main():
    
    mocap_sesssion_file_input = {
        "session_id": "4d559f35-43c0-4126-a7d5-15abbe2f72ff",
        "filenames": ["play1.mp4", "play2.mp4"]
    }

    create_mocap_sesssion_file = requests.post(
        "https://api.rebootmotion.com/mocap_sesssion",
        headers={
            "Authentication": f"Bearer {ACCESS_TOKEN}"
        },
        json=mocap_sesssion_file_input,
    )
    print(create_mocap_sesssion_file.json())

if __name__ == "__main__":
    main()

Running the above example code will create a Motion Capture Session File, and will print out the JSON values of the response to your terminal. As with the previous example, our example below will simply print the JSON response from the API. Your implementation will likely vary. As a reminder, you should NOT just copy/paste/run the above code; instead, you should modify it to fit your individual use case.

If no error occurs, the sample output will look something like this:

{
    "play1.mp4": "https://reboot-motion-api-uploads.s3.amazonaws.com/org_id%3Dorg-1501e096/mocap_type%3Drebootmotion/sequence%3D0/org_player_id%3D579C3ED5-2A18-444A-9CD0-73D065ACEA8F/movement_type%3Dbaseball-hitting/session_date%3D2022-03-30/session_type%3Dsession/session_num%3D0/org_session_id%3DB113B27E-C5B5-470C-BCC0-C55A71119C8B/video_clip_fps%3D240/play1.mp4.mp4?<aws key value params hidden for security>",
    "play2.mp4": "https://reboot-motion-api-uploads.s3.amazonaws.com/org_id%3Dorg-1501e096/mocap_type%3Drebootmotion/sequence%3D1/org_player_id%3D579C3ED5-2A18-444A-9CD0-73D065ACEA8F/movement_type%3Dbaseball-hitting/session_date%3D2022-03-30/session_type%3Dsession/session_num%3D0/org_session_id%3DB113B27E-C5B5-470C-BCC0-C55A71119C8B/video_clip_fps%3D240/play2.mp4.mp4?<aws key value params hidden for security>",
}

The output contains a key-value pair of mappings for each provided filename and a pre-signed URL where you can upload that file. A subsequent PUT HTTP request is required to actually upload each file.

An example of initiating an upload with a provided pre-signed URL is shown below:

import requests 

sample_file_url = ("https://reboot-motion-api-uploads.s3.amazonaws.com/org_id%3Dorg-1501e096/mocap_type%3Drebootmotion/sequence%3D0/org_player_id%3D579C3ED5-2A18-444A-9CD0-73D065ACEA8F/movement_type%3Dbaseball-hitting/session_date%3D2022-03-30/session_type%3Dsession/session_num%3D0/org_session_id%3DB113B27E-C5B5-470C-BCC0-C55A71119C8B/video_clip_fps%3D240/play1.mp4.mp4?<aws key value params hidden for security>")

with open(object_name, 'rb') as upload_file:
    upload_response = requests.put(sample_file_url, data=upload_file)

print(upload_response.status_code)

Optionally, you can read the file contents in and pass them to the data parameter, like this:

with open(object_name, 'rb') as upload_file:
    upload_response = requests.put(sample_file_url, data=upload_file.read())

But note that this is optional; excluding the .read() will stream the file contents to the destination URL instead.

The output should be a status of 2XX if no error is encountered.

Common Errors

Ideally, you wouldn't run into any errors while going through this tutorial, but there's a lot of information here and sometimes errors happen. That being said, let's go through some of the more common errors and the first steps to take to troubleshoot those errors to save you some time.

You can always access a full list of errors in the Reboot Motion documentation, but we will walk you through some more specific error messages you may encounter while trying to create a Motion Capture Session File.

ModuleNotFoundError: No module named '<module_name>'

This error comes from the module in question not being installed — you will need to install the module in order to use it. You can do this by running pip install requests in your terminal. If you are using a different package manager, you will need to use the appropriate command for that package manager.

HTTP Exception 403: Forbidden

You need to include a valid access token (or legacy API Key). If you don't know how to get this, take a look at the Getting Set Up tutorial.

HTTP Exception 500: Internal Server Error

This means something is wrong on the Reboot Motion server's end - please reach out to the team at [email protected].

If you need to retry the API call after a failure, check that you have everything above correct, restart your server, and make the call again. If you continue to get an error message and can't figure out why, feel free to reach out to the Reboot Motion team.

Please feel free to reach out to the team with any additional questions you may have, or if you run into any issues that weren't addressed above!