Partner S3 Bucket Documentation (Deprecated)

Overview

Reboot Motion maintains a separate Amazon Simple Storage Service (S3) bucket for each partner organization. This bucket is the home for all data uploaded to and processed by our platform. To facilitate easy data management, we provide you with two ways to access this bucket: in your web browser, using the AWS Management Console, and programmatically (i.e., using the AWS Command Line Interface tool or through your own custom code.)

AWS Management Console

You can log into the AWS Management Console using the username and password provided by Reboot Motion at the following URL: https://rebootmotion.signin.aws.amazon.com/console.

The above link should pre-fill the Reboot Motion account ID into the login form. However, if you find yourself at a login screen and the Account ID (12 digits) or account alias field is blank, you can enter our account alias, which is simply rebootmotion.

In the interest of security, you will need to change the password when you log in for the first time. Additionally, you should change your password every 90 days, and we recommend you enable Multi-Factor Authentication as well.

You can change your password or modify your MFA settings from the My Security Credentials page. You can access this page by clicking your username in the top right corner of the browser window and selecting Security credentials from the menu.

If you forget your password, need help configuring your MFA settings, or have any other questions regarding accessing the AWS Management Console, please email our team at [email protected] for assistance.

Programmatic Access

To access your S3 bucket programmatically, you will need to generate an access key. On the My Security Credentials page, you can manage your access keys under the heading Access keys for CLI, SDK, & API access.

In the interest of security, you should never share your access key or secret with anyone, and you should rotate these keys frequently (we recommend every 90 days.)

If you need help creating or rotating your access key and secret, please email our team at [email protected] for assistance.

Bucket Structure

In your S3 bucket, the structure can vary depending on your organization’s choice of motion capture providers. However, at the top level, all buckets will have the same two file path prefixes (similar to directories):

1. data_delivery/
2. upload_sessions/

Our partners can upload data from any motion capture source under the upload_sessions/ file path prefix. We will then deliver all processing results back under the data_delivery/ file path prefix.

Accessing Your Bucket

Reboot Motion names S3 buckets according to the convention reboot-motion-<Organization ID>, where Organization ID is the unique identifier generated and provided to you when you begin working with Reboot Motion. For example, if your Organization ID is org-example, then your S3 bucket would be named reboot-motion-org-example.

If you are not sure of your Organization ID or bucket name, or need help accessing your bucket, please email our team at [email protected] for assistance.

Via the AWS Management Console

For the privacy of all of our partner organizations, we do not allow buckets to be listed on the main Amazon S3 page. You can access your S3 bucket by entering its URL directly into your web browser:

https://s3.console.aws.amazon.com/s3/buckets/<BUCKET_NAME>?region=us-west-1&tab=objects.

Following the above example, if your Organization ID is org-example and your bucket name is reboot-motion-org-example, then the URL to access your S3 bucket would be:

https://s3.console.aws.amazon.com/s3/buckets/reboot-motion-org-example?region=us-west-1&tab=objects.

On this page, you should see a listing of the two top-level file path prefixes that looks something like this:

Via the Amazon Command Line Interface (CLI)

As noted above, you will need to access your bucket by name, and that restriction applies to access via the command line (and other programmatic access) as well. For example, to list the contents of org-example’s bucket using the Amazon CLI, the command would be:

$ aws s3 ls s3://reboot-motion-org-example/

And the output of that command would look like this, showing the same two directories as the AWS Management Console.

$ aws s3 ls s3://reboot-motion-org-example/
                    PRE data_delivery/
                    PRE upload_sessions/

Amazon provides instructions on getting started with the Amazon CLI, as well as detailed documentation of all the commands available to interact with your S3 bucket.

Uploading Data

As described above, the upload_sessions/ file path prefix is where you upload all motion capture data to our system. For each individual file, the S3 object key (essentially, the path where the file is uploaded) will provide us with most of the metadata we need to kick off processing.

However, we also require a few other complementary metadata files, described below. Samples for each file type can be provided upon request.

Additionally, it is important to note that we do not support the deletion of any motion capture or metadata files. This is done to avoid situations where a file is deleted while it is being processed. If you upload something in error and need it to be removed, please reach out to our team for assistance. However, we encourage exercising caution to avoid situations where large quantities of files would need to be found and deleted.

Player Weights File

For all motion capture data sources, for every session of motion capture data uploaded, we encourage our partners to submit information about each player that participated in the motion capture session. To accomplish this we use a text file named player_weights.txt, which is a player-by-player summary of all players who participated in the session. The player’s weight is the most important piece of information in this file, as this enables us to calculate momentum.

Note: a player weights file is only required when there are new players to register in our database. However, we recommend using regularly as an update mechanism for existing players (for example, to inform us that a player’s weight has changed over time).

The player_weights.txt file typically contains 9 pipe-separated columns, which can be provided in any order. However, if an MLBAM ID is provided, we are able to pull some information from the MLB API, rendering the corresponding columns optional. The columns for this file are:

† As previously mentioned, the columns denoted above as optional are only optional if you send the MLBAM ID, as we can pull that information programmatically from the MLB API.

†† Your organization’s internal ID for the player is optional, but we highly recommend including it to facilitate capturing both MLB and non-MLB events.

††† We are able to pull a player’s weight from the MLB API when provided with an MLBAM ID; however, those values can sometimes be inaccurate, so it’s always better to provide internal weight values for a player if available.

An example player_weights.txt file for a hypothetical Example Player, with some optional columns omitted, would look like this:

org_player_id|last_name|first_name|weight_lbs|height_ft|mlbam_id
123456|Player|Example|185.00|6.00|999999

Player weights files should be uploaded into the Action folder, at the same level as Hawk-Eye motion capture files. So, for example, if Reboot Motion’s example organization (org-example) captured a practice session at Reboot Motion Field on December 1, 2021, the player weights file would be uploaded to:

s3://reboot-motion-org-example/upload_sessions/hawkeye/Reboot Motion Field/2021-12-01/0/Action/player_weights.txt

More details on how this directory structure is constructed can be found in the Hawk-Eye Motion Capture Files section, below.

Event Metadata

In our biomechanics pipeline, we allow for the distinction between different groups of motion capture files by event type. There are five different event types that we recognize, sorted in order from highest intensity to lowest intensity:

1. session
2. scrimmage
3. live-practice
4. practice
5. drill

Our default event type is session, which is the type we use for games.

If you'd like to manually set one of these types when providing us with a motion capture session, you can upload an event.txt file alongside the player_weights.txt file, but it's not required. If it's not submitted, we will default to session as the type. The file is simple, with the column heading event_type followed by a new line and then one of the values from the list above.

An example event.txt file that indicates a practice intensity level would look like this:

event_type
practice

Event metadata files, like player weights files, should be uploaded into the Action folder, at the same level as Hawk-Eye motion capture files. So, for example, if Reboot Motion’s example organization (org-example) captured a practice session at Reboot Motion Field on December 1, 2021, the example event.txt from above would be uploaded to:

s3://reboot-motion-org-example/upload_sessions/hawkeye/Reboot Motion Field/2021-12-01/0/Action/event.txt

More details on how this directory structure is constructed can be found in the Hawk-Eye Motion Capture Files section, below.

Hawk-Eye Motion Capture Files

Hawk-Eye motion capture files are JSON files (whose suffix is .action) that contain batter and pitcher motion capture information. For these files, here is the format of the S3 object key that should be used upon upload:

s3://<BUCKET_NAME>/upload_sessions/hawkeye/<VENUE>/<SESSION_DATE>/<NUMERIC_GAME_ID>/Action/<HAWK-EYE FILENAME>

The elements used in the S3 Object Key naming convention are:

So, for example, if Hawk-Eye provided Reboot Motion’s example organization (org-example) with a file called 1234_1_123456_1_2_3_4_5.baseball.action that was captured at the first practice session (rather than a live game) on December 1, 2021 at Reboot Motion Field, the filename would look like this:

s3://reboot-motion-org-example/upload_sessions/hawkeye/Reboot Motion Field/2021-12-01/0/Action/1234_1_123456_1_2_3_4_5.baseball.action

† The numeric game ID can be the MLB game id or any other integer you choose. When not using the MLB game ID, we prefer using incrementing integers that reset each day. So for example, on a day with a double header the first game would be 0 and the second game would be 1. Note that for us, these only have to be unique within a given day. Also note that if you have your own internal game id that isn’t an integer, let us know and we can handle this here as well, it will just require some setting changes on our end.

Pitch-by-Pitch Metadata

In addition to the uploaded Hawk-Eye action files, we allow users to submit metadata about each pitch. We require this metadata file for partners who use internal player IDs as their Org Player IDs. For those that use all MLB standard IDs, this metadata file is optional. For the metadata, we use a file named hawkeye_pitches.txt, which is a pitch-by-pitch summary of all the action files in the Hawk-Eye motion capture session. It should be uploaded in the S3 bucket at the same file level as the action files referenced in the previous section. For example, the companion hawkeye_pitches.txt for our December 1st practice at Reboot Motion Field would be uploaded to the following path:

s3://reboot-motion-org-example/upload_sessions/hawkeye/Reboot Motion Field/2021-12-01/0/Action/hawkeye_pitches.txt

The hawkeye_pitches.txt file contains at a minimum 3 pipe-separated columns, with support for optional additional columns for other pitch-by-pitch level metadata (such as pitch type, which is included in this table). If you want to include other columns here, please let us know so we can work with you to add support for them.

Lastly, if possible, the hawkeye_pitches.txt rows should be sorted chronologically, such that the order of the rows is the order in which the pitches occurred in the game. For analyses of fatigue, chronological ordering is imperative. Hawk-Eye typically delivers the files with chronological ordering in the file names, so this should be straightforward.

An example hawkeye_pitches.txt file that includes 3 pitches with pitch_type would look like this:

uuid|batterid|pitcherid|pitch_type
xxxxxxxxxxxxx|xxxxxxxxxxxxxxxx|xxxxxxxxxxxxxxxxx|xx
xxxxxxxxxxxxx|xxxxxxxxxxxxxxxx|xxxxxxxxxxxxxxxxx|xx
xxxxxxxxxxxxx|xxxxxxxxxxxxxxxx|xxxxxxxxxxxxxxxxx|xx

Example Upload Directory Structure

When uploading to your S3 bucket, it should look something like this.

Amazon S3 > reboot-motion-org-example/ > upload_sessions/ > hawkeye/ > 1_Major League Baseball/ > Reboot Motion Field/ > 2021-12-01/ > 0/ > Action/

Accessing Analyzed Data

After we’ve completed processing uploaded data, we deliver a number of files back to your organization’s S3 bucket. This includes 1) processed data, 2) generated reports, and 3) additional educational resources.

Educational Resources

In your S3 bucket, you will find educational resources, providing definitions and context for the data we deliver back to your organization.

Reboot Motion Definitions

The Reboot Motions Definitions document is where we explain all of the biomechanical metrics and concepts we focus on. It is titled RebootMotionDefinitions.docx, and can be found in the data_delivery folder of your S3 bucket.

OpenSim Information

This provides a few details regarding how we use OpenSim, the biomechanics engine we use to convert raw Hawk-Eye data to skeletal data. It is titled OpenSimInfo.docx, and can be found in the data_delivery folder of your S3 bucket.

OpenSim Skeletal Models

For each player we analyze, we generate a personalized OpenSim skeleton .osim file. Here is where we deliver the skeleton model for each of these players.

Hawk-Eye

Here is where we deliver the processed data and reports for each uploaded Hawk-Eye motion capture session. In general we deliver 5 types of information for each uploaded motion capture session:

1. Reports
2. Report Data
3. Skeletons
4. OpenSim Motions
5. Processed Data

The information is uploaded to an S3 object key with a prefix constructed from the following elements:

s3://<BUCKET_NAME>/data_delivery/hawkeye/<SESSION_DATE>/<NUMERIC_GAME_ID>/<MOVEMENT_TYPE>/<ORG_INTERNAL_PLAYER_ID>

We currently support the following movement types (MOVEMENT_TYPE):

1. baseball-hitting
2. baseball-pitching

So, to access data for our example organization’s practice on December 1st, hitting-related files would be prefixed as:

s3://reboot-motion-example-org/data_delivery/hawkeye/20211201/0/baseball-hitting/

And pitching related files would be prefixed as:

s3://reboot-motion-example-org/data_delivery/hawkeye/20211201/0/baseball-pitching/

Under each prefix will be the Organization’s internal ID for the player. So pitching data about our hypothetical Example Player (ID: 123456) would be found by navigating to the prefix:

s3://reboot-motion-example-org/data_delivery/hawkeye/20211201/0/baseball-pitching/123456/

Reports

In general, we will deliver a player’s report for a given motion capture session with an S3 object key that looks like this:

​​s3://<BUCKET_NAME>/data_delivery/hawkeye/<SESSION_DATE>/<NUMERIC_GAME_ID>/<MOVEMENT_TYPE>/<ORG_INTERNAL_PLAYER_ID>/<ORG_INTERNAL_PLAYER_ID>_<DOM_HAND>_Event_<[Hitting | Pitching]>Report.html

We currently support the following values for dominant hand (DOM_HAND):

1. RHA (right-handed)
2. LHA (left-handed)

For switch hitters and pitchers (i.e. Pat Venditte), there will be a separate report for each hand.

You’ll notice that the report filename also includes an indicator of either “Hitting” or “Pitching”, depending on the movement type, so anywhere MOVEMENT_TYPE is baseball-hitting, the report name would end in _Event_HittingReport.html.

So the pitching report for Example Player, who throws right-handed (RHA), from the practice session at Reboot Motion Field on December 1st would be found at:

s3://reboot-motion-example-org/data_delivery/hawkeye/20211201/0/baseball-pitching/123456/123456_RHA_Event_PitchingReport.html

And the hitting report for the same player would be found at:

s3://reboot-motion-example-org/data_delivery/hawkeye/20211201/0/baseball-hitting/123456/123456_RHA_Event_HittingReport.html

Report Data

In the report-data folder, you will find many supplementary pieces of information, such as generated images and individual report sections, by navigating to the report-data/ folder at the same level where the report is stored. So, to access the supplementary information for Example Player’s hitting report, you would find those items here:

s3://reboot-motion-example-org/data_delivery/hawkeye/20211201/0/baseball-hitting/123456/report-data/

HTML and PNG files

Inside the report-data/ folder are all the individual animations and images that make up the report, in case you want to use a piece of a report but not the whole thing. For example, to view just the balance section of the report, you will find that at:

s3://reboot-motion-example-org/data_delivery/hawkeye/20211201/0/baseball-hitting/123456/report-data/RHA_Event_balance_html.html

Action-by-Action Summary

If you prefer to view summary data at the pitch-by-pitch or swing-by-swing level (rather than time step-by-time step, as in the processed data files), an action-by-action summary file (named <DOM_HAND>_Event_action_by_action_summary.csv) is included in the report-data/ folder, and includes the dominant hand indicator in its filename. For our Example Player, this action-by-action summary file would be found at:

s3://reboot-motion-example-org/data_delivery/hawkeye/20211201/0/baseball-hitting/123456/report-data/RHA_Event_action_by_action_summary.csv

This file contains the pitch by pitch or swing by swing summary of this entire motion capture session. Here, for each pitch or swing in the session, you will find all of the metrics we generated for that pitch or swing, and these are the metrics we use to generate the report.

The details of each metric can be found in Reboot Motion Definitions. The primary key here is the Reboot Motion Movement ID, but we also include the Hawk-Eye pitch or swing UUID as well as the MLB Play ID when available.

Note: We encourage our partner organizations to ingest this document into a larger database to enable more in depth data science within and across players.

Report Metadata

This file (named <DOM_HAND>_Event_report_metadata.csv) provides metadata about the report, including the Hawk-Eye Role ID, the player’s dominant hand, the Organization’s Internal Player ID, etc. For our Example Player, this report metadata file would be found at:

s3://reboot-motion-example-org/data_delivery/hawkeye/20211201/0/baseball-hitting/123456/report-data/RHA_Event_report_metadata.csv

Event Summary

This file (named <DOM_HAND>_Event_summary.csv) presents the median value for each metric in the report. For our Example Player, this event summary file would be found at:

s3://reboot-motion-example-org/data_delivery/hawkeye/20211201/0/baseball-hitting/123456/report-data/RHA_Event_summary.csv

Skeletons

We provide skeleton files, which are the Hawk-Eye joint centers converted into an easy-to-use CSV format, in the skeletons/ folder at the same level as the report-data/ folder. The filenames for skeleton files are constructed as <MOVEMENT_NUMBER>_<HAWKEYE_UUID>_skel.csv. For our Example Player, the skeletons for their first movement would be found here:

s3://reboot-motion-example-org/data_delivery/hawkeye/20211201/0/baseball-hitting/123456/skeletons/1_123e4567-e89b-12d3-a456-426614174000.csv

OpenSim Motions

For each movement in a session, we provide OpenSim motion files in the opensim-motion/ folder at the same level as the report-data/ folder. These are the standard OpenSim-format files that can be used with the OpenSim biomechanics engine to animate the OpenSim skeletal models denoted above. There is one motion file for each pitch or swing. These files, plus the OpenSim skeletal models, enable biomechanics research. The filenames for the OpenSim motion files are constructed as <MOVEMENT_NUMBER>_<HAWKEYE_UUID>.mot. For our Example Player, the skeletons for their first movement would be found here:

s3://reboot-motion-example-org/data_delivery/hawkeye/20211201/0/baseball-hitting/123456/opensim-motion/1_123e4567-e89b-12d3-a456-426614174000.mot

Processed Data

For each pitch or swing that we process, we also provide a CSV file of processed data in the processed-data/ folder, at the same level as the report-data/ folder, named as <MOVEMENT_NUMBER>_<HAWKEYE_UUID>_<PITCH_TYPE_OR_SWING_SIDE>.csv. The primary key of a processed data CSV is the norm_time column, which is explained in Reboot Motion Definitions. In each processed data file, we include all the joint angles, as well as other time series data of interest including segment specific energy and momentum.

In constructing the filename, <PITCH_TYPE_OR_SWING_SIDE> reflects either the handedness of the individual swing (RHA, LHA) or the standard two-letter code for pitch type.

For our Example Player’s practice at-bat, you’d find a processed data file for one swing here:

s3://reboot-motion-example-org/data_delivery/hawkeye/20211201/0/baseball-hitting/123456/processed-data/1_123e4567-e89b-12d3-a456-426614174000_RHA.csv

Example Delivery Directory Structure

When uploading to your S3 bucket, it should look something like this.

Amazon S3 > reboot-motion-org-example/ > data_delivery/ > hawkeye/ > 20211201/ > 0 > baseball-hitting/ > 123456/