From a23c9dc4aa1e0679a5089af376e7cbd32434c2f5 Mon Sep 17 00:00:00 2001 From: Elizabeth Argall Date: Wed, 26 Jun 2024 13:33:23 -0700 Subject: [PATCH] {Documentation} Update Readme Summary: Update to include platform requirements, formatting and wording tweaks Reviewed By: SeaOtocinclus Differential Revision: D59071967 fbshipit-source-id: d38a3747430299afcf6cad18f535c6472f2d4491 --- README.md | 60 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 41 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 5c76099..c4c8ab6 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,22 @@ # HOT3D: A dataset for egocentric 3D hand and object tracking -This repository hosts the API for downloading and utilizing HOT3D, a benchmark dataset designed for the vision-based understanding of 3D hand-object interactions. +This repository hosts the API for downloading and utilizing [HOT3D](https://www.projectaria.com/datasets/hot3D/), a benchmark dataset for vision-based understanding of 3D hand-object interactions. -# Installation and usage +# Step 1: Install the downloader + +This Python repository can be used with Pixi and Conda environments and can run on: + +* x64 Linux distributions of: + * Fedora 36, 37, 38 + * Ubuntu jammy (22.04 LTS) and focal (20.04 LTS) +* Mac Intel or Mac ARM-based (M1) with MacOS 11 (Big Sur) or newer + +Python 3.9+ (3.10+ if you are on [Apple Silicon](https://support.apple.com/en-us/116943)). -This python repository can be used with pixi and conda environments. ## Using Pixi -[Pixi](https://prefix.dev/) is a package management tool for developers. It allows the developer to install libraries and applications in a reproducible way and ease the installation and usage of a python environment for the HOT3D API. +[Pixi](https://prefix.dev/) is a package management tool for developers. Developers can install libraries and applications in a reproducible way, which makes it easier to install and use a Python environment for the HOT3D API. ``` # 1. Install pixi @@ -21,18 +29,19 @@ cd hot3d # 3. Call `pixi install` to setup the environment pixi install -# 4. (Optional) Install the third-party dependencies required for hands by reviewing and accepting the licenses provided on the corresponding third-party repositories +# 4. (Optional) Install the third-party dependencies required for hands, by reviewing and accepting the licenses provided on the corresponding third-party repositories pixi run setup_hands ``` -### A quick introduction to [PIXI environment](https://prefix.dev/) +### A quick introduction to the [PIXI environment](https://prefix.dev/) - Execute Pixi environment commands from within the `hot3d` folder. - The Pixi environment is located in the `.pixi` folder. - Activate the Pixi HOT3D environment by using the command `pixi shell`. - Exit the Pixi HOT3D environment by typing `exit`. - Remove the environment by executing the command `rm -rf .pixi`. + ## Using Conda [Conda](https://conda.io/projects/conda/en/latest/index.html) is a package manager used for managing software environments and dependencies in data science and scientific computing. @@ -54,24 +63,36 @@ python3 -m pip install 'git+https://github.com/vchoutas/smplx.git' python3 -m pip install 'git+https://github.com/mattloper/chumpy' ``` -### A quick introduction to [CONDA environment](https://docs.conda.io/projects/conda/en/4.6.1/user-guide/tasks/manage-environments.html#managing-environments) +### A quick introduction to the [CONDA environment](https://docs.conda.io/projects/conda/en/4.6.1/user-guide/tasks/manage-environments.html#managing-environments) - Activate the Conda HOT3D environment by executing `conda activate hot3d`. - Exit the Conda HOT3D environment using `source deactivate`. - Remove the Conda HOT3D environment by executing `conda remove --name hot3d --all`. -# Dataset downloading -Please review the [HOT3D license agreement](https://www.projectaria.com/datasets/hot3d/license/) first, and then examine the specific licenses applicable to the data types you wish to use, such as Sequence, Hand annotations, and 3D object models. +# Step 2: Sign up and get the download links file + +1. Review the [HOT3D license agreement](https://www.projectaria.com/datasets/hot3d/license/). + * Examine the specific licenses applicable to the data types you wish to use, such as Sequence, Hand annotations, and 3D object models. +2. Go to the [HOT3D website](https://www.projectaria.com/datasets/hot3D/) and sign up. + * Scroll down to the bottom of the page. + * Enter your email and select **Access the Datasets**. +3. The HOT3D page will be refreshed to contain instructions and download links + * The download view is ephemeral, keep the tab open to access instructions and links + * Download links that last for 14 days + * Enter your email again on the HOT3D main page to get fresh links +4. Select the Download button for any of the data types: + * “Download the HOT3D Aria Dataset" + * "Download the HOT3D Quest Dataset" + * "Download the HOT3D Assets Dataset" +5. These will swiftly download JSON files with urls that the downloader will use + -Required: -- After agreeing to the license, download the cdn url files from the "Access HOT3D Dataset and Accompanying Tools" section on [HOT3D projectaria.com website](https://www.projectaria.com/datasets/hot3d). You should see buttons corresponding to each download data type as follows - - "Download the HOT3D Aria Dataset" - - "Download the HOT3D Quest Dataset" - - "Download the HOT3D Assets Dataset" +# Step 3: Download the data +Use the HOT3D downloader to download some, or all of the data. ``` -# 1. Activate your environment (assuming your are in the hot3d folder): +# 1. Activate your environment (assuming from the hot3d folder): # conda: conda activate hot3d # pixi: pixi shell @@ -83,17 +104,18 @@ mkdir -p ../dataset # Download HOT3D Object Library data python3 dataset_downloader_base_main.py -c Hot3DAssets_download_urls.json -o ../dataset --sequence_name all -# Download HOT3D Aria data (here one sequence) +# Download one HOT3D Aria data sequence python3 dataset_downloader_base_main.py -c Hot3DAria_download_urls.json -o ../dataset --sequence_name P0003_c701bd11 --data_types all # Type answer `y` -# Download HOT3D Quest data (here one sequence) +# Download one HOT3D Quest data sequence python3 dataset_downloader_base_main.py -c Hot3DQuest_download_urls.json -o ../dataset --sequence_name P0002_1464cbdc --data_types all # Type answer `y` ``` +**Tip:** To download all sequences in a download links JSON file (such as the HOT3D Object Library data in step 3), do not include the sequence_name argument. -# Running the dataset viewer +# Step 4: Run the dataset viewer ## Viewing objects and headset pose trajectory ``` @@ -133,4 +155,4 @@ python3 viewer --sequence_folder --sequence_folder /hot3d_dataset/P0001_04 # Contributing -See [contributing](CONTRIBUTING.md) and the [code of conduct](CODE_OF_CONDUCT.md). +Go to [Contributing](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).