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 an API Key to interact with the API endpoints mentioned in this tutorial. API Keys are available to all active Reboot Motion customers. If you do not already have an API Key from Reboot Motion, you can generate one from your Reboot Motion Dashboard.

Step 0: 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 file properly, so let's make sure you have the following import statements and constants at the top of your file — we are going to use the os.getenv() function to get our API Key from wherever it is currently stored:

import os
import requests 
API_KEY = "API_KEY_FROM_REBOOT"

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.

Note that "API_KEY_FROM_REBOOT" would be replaced with your actual API Key, given to you by Reboot Motion, as detailed in the Getting Set Up tutorial. In our example, we are hard-coding the API key for ease of understanding, but in practice it's wise to read the API key from an environment variable leveraging a library like python-dotenv. As mentioned in the tutorial, please be incredibly careful not to commit your API Key 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.

Step 1: 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. 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"
}

Step 1: 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 
API_KEY = "API_KEY_FROM_REBOOT"
API_HEADER = {'x-api-key': API_KEY}

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=API_HEADER,
        json=mocap_sesssion_file_input,
    )
    print(create_mocap_sesssion_file.json())

if __name__ == "__main__":
    main()

Running this file 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.

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 file:
    files = {"file": file}
    upload_response = requests.put(sample_file_url, files=files)

print(upload_response.status_code)

Note: when uploading text-based files (such as Hawk-Eye action files) instead of video, using the requests library's files parameter can result in header information being wrapped around the JSON data being uploaded, which will cause the file to fail processing in our pipeline. For example:

--ca2e89550075226ed956eaf35c99ff77
Content-Disposition: form-data; name="file"; filename="example_file.baseball.action"
Content-Type: application/octet-stream

<json data>

--ca2e89550075226ed956eaf35c99ff77--

To prevent this issue, use the data parameter instead:

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

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 401: Unauthorized

You need to include a proper 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!