initial code.

.gitignore

@@ -0,0 +1,28 @@
+*.swp
+*.pyc
+*.pkl
+*.py~
+*.bak
+.pytest_cache
+.DS_Store
+.idea
+.coverage
+.coverage.*
+__pycache__/
+_build/
+*.egg-info
+.cache
+
+# for the unity ml-agents
+unity/envs/*
+*unity-environment.log
+
+# for jupyter notebook and development
+*.ipynb_checkpoints
+# logging
+log/*
+
+# directories
+output/
+results/
+data/

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2020, Princeton University
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,115 @@
+<img src="images/packit.gif" align="right" width="30%"/>
+
+**PackIt: A Virtual Environment for Geometric Planning**
+[Ankit Goyal](http://imankgoyal.github.io), [Jia Deng](https://www.cs.princeton.edu/~jiadeng/)  
+*International Conference on Machine Learning (ICML), 2020*
+```
+@inproceedings{goyal2020packit,
+  title={PackIt: A Virtual Environment for Geometric Planning},
+  author={Goyal, Ankit and Deng, Jia},
+  booktitle={International Conference on Machine Learning},
+  year={2020},
+}
+```
+
+## Getting Started
+
+First clone the repository. We would refer to the directory containing the code as `<packit_dir>`.
+
+```
+git clone [email protected]:princeton-vl/PackIt.git
+```
+
+#### Requirements
+The PackIt environment is build using [Unity ML-agents](https://github.com/Unity-Technologies/ml-agents/tree/0.4.0) version **0.4.0**. 
+To train the neural network model, we recommend using a machine with GPU. 
+The code is tested on Linux OS with Python version **3.5**, CUDA version **8.0**, and cuDNN version **5.1**.
+We provide standlone [Unity builds for Linux x86_64 platform](https://docs.unity3d.com/2017.4/Documentation/Manual/BuildSettingsStandalone.html).
+For visualization, we also provide a Unity build for Mac OS.
+
+#### Install Libraries
+We recommend to first install [Anaconda](https://anaconda.org/) and create a virtual environment.
+```
+conda create --name packit python=3.5
+```
+
+Activate the virtual environment and install the libraries. Make sure you are in `<packit_dir>`.
+```
+conda activate packit
+pip install -r requirements.txt
+```
+
+#### Download Datasets and Pre-trained Models
+Make sure you are in `<packit_dir>`. `download.sh` script downloads all the data, unzips them, and places them at correct locations. Note that symbolic links are created between the `data` folder and appropriate locations inside the unity data directory. This is necessary so that the data is accessible from the build unity game.
+```
+chmod +x download.sh
+./download.sh
+```
+
+## Code Organization
+- `<packit_dir>/main.py`: Python script for training and evaluating learning based-models on PackIt and PackIt-Easy. 
+
+- `<packit_dir>/main_heuristic.py`: Python script for training and evaluating heuritic-based models on PackIt and PackIt-Easy. 
+
+- `<packit_dir>/stable-baselines`: Adapted from [stable-baselines](https://github.com/hill-a/stable-baselines) with some modification. We use it for our PPO baselines. 
+
+- `<packit_dir>/unity`: Adapted from [Unity ML-agents](https://github.com/Unity-Technologies/ml-agents/tree/0.4.0) with minor modification. It is required to run the PackIt environment. It communicates with the game built using Unity using sockets and provides a python interface for interacting with the environment.
+
+- `<packit_dir>/packing`: Contains code for creating and evaluating OpenAI gym compatible PackIt environment as well as various baselines.
+
+- `<packit_dir>/log`: Created after `download.sh` is run. Stores the pretrained learning-based models according to the naming convention [here](https://github.com/princeton-vl/PackIt/blob/master/main.py#L81).  
+
+- `<packit_dir>/unity/envs`: Created after `download.sh` is run. Stores the unity game build. `<packit_dir>/unity/envs/packit.x86_64` is game build for the main unity environment while `<packit_dir>/unity/envs/packit.x86_64` is the game build for the visualization environment.
+
+- `<packit_dir>/data`: Created after `download.sh` is executed. Contains information about the shapes and packs. This folder is symbolically linked to `<packit_dir>/unity/envs/packit_Data/StreamingAssets` and `<packit_dir>/unity/envs/packit_viz_Data/StreamingAssets` so that it can be accessed by the unity game build. More information about StreamingAssets in Unity can be found [here](https://docs.unity3d.com/2017.4/Documentation/Manual/StreamingAssets.html).
+
+- `<packit_dir>/data/data_<tr/va/te>`: Contains the shapenet shapes as [asset bundles](https://docs.unity3d.com/Manual/AssetBundlesIntro.html). This helps in faster loading for data.
+
+- `<packit_dir>/data/pack_<ab/te/tr/va>`: Contains information about packs in json format. Each file (like `<packit_dir>/data/pack_tr/0_tr`) can have information about multiple packs. We refer to the order of the pack inside this file as its `id`. On average, each file has information about 5 packs.
+
+- `<packit_dir>/data/pack_<ab/te/tr/va>_precompute_<python/unity>`: Contains information about packs so that they can be loaded faster. We precompute things like voxel representation of shapes and store here.
+
+- `<packit_dir>/data/visualize`: Contains some saved actions for different baselines. These can be used during visualization. For more information refer to the visualization section.
+
+- `<packit_dir>/results`: Created after `download.sh` is executed. It contains the reward of various agents. Once an agent is evaluated, a pickle file with rewards is saved here based on the naming [here](https://github.com/princeton-vl/PackIt/blob/master/main.py#L185) and [here](https://github.com/princeton-vl/PackIt/blob/master/main_heuristic.py#L105). We also provide precomputed rewards for our agents. Change [this](https://github.com/princeton-vl/PackIt/blob/master/results.py#L30) line to the result you want to see and run `python results.py`.
+
+## Testing
+To debug whether everything is set up correctly, use the `test_packing_env.ipynb` jupyter notebook. It runs a packing environment with ground-truth actions.  Make sure you have downloaded everything properly before this step. Note that the plotting of voxels in matplotlib is slow. 
+
+
+## Running Experiments
+To run any experiment, refer to the `command` dictionary inside `commands.py`. For example to run heuristic-based baseline same as row 1 in table 1 of the paper use the command `python main_heuristic.py --eval_va_or_te 0 --pol_1 sha_rand`. For some experiments, like `tab_3_row_2_3`, the dictionary contains a list of commands. Essentially, we break the evaluation into multiple commands so that they can be run in parallel. Depending on the computing infrastructure, these commands can be run in parallel or serial.
+
+
+## Visualization
+Make sure you have downloded everything before this step. Follow the steps below:
+
+1. Save the actions. Follow the python script `<packit_dir>/visualize.py`. It saves the agents actions in a json file. We also provide some prerecorded actions in `<packit_dir>/data/visualize`
+1. Run the unity visulization build like this `./<packit_dir>/unity/evns/packit_viz.x86_64 -getSavedAct true -fileName pack_va/0_va -packID 1 -actFileName visualize/pack_va_0_va_1_gt`. This would run visualization for the pack inside `pack_va/0_va` with ID `1` using the groundtruth actions. When the unity build opens up, press `a` to execute the actions. Only for visualization, we also provide a Mac OS unity build which could be used for visualization on Mac OS. The Mac OS visualizer could be run as `./<packit_dir>/unity/evns/packit_viz_mac.app/Contents/MacOS/EgpGame3 -getSavedAct true -fileName pack_va/0_va -packID 1 -actFileName visualize/pack_va_0_va_1_gt`.
+
+
+## Notes
+- We train our learning-based model with 8 parallel environments. We recommend using a system with at least 8 CUPs to do the same with 4 GB of RAM each.
+
+- Unity environment communicated with the python process using ports. The `--id-start` flag inside `main.py` and `main_heuristic.py` could be used to start a process with different port id. The code will crash in case multiple unity environments are using the same port. This is the reason why we give different `--id-start` for different commands while running multiple environments in parallel. `--id-start 0` corresponds to port `5005` on OS (as defined [here](https://github.com/princeton-vl/PackIt/blob/master/unity/unityagents/environment.py#L33)). Any increment in `--id-start` updates the port incrementally. For example, `--id-start 10` corresponds to port `5015`.
+
+- `--eval_start_id` and `--eval_end_id` flags inside `main.py` and `main_heuristic.py` are used to specify the id of the packing files which we want to evaluate. While running multiple parallel environments of evaluation, we can use these flags to specify the id of packing files on which we want to evaluate. 
+
+- When the unity environnment is running, you might get a terminal log similar to the following. It is expected and the environment would still run fine. 
+```
+ALSA lib confmisc.c:767:(parse_card) cannot find card '0'
+ALSA lib conf.c:4568:(_snd_config_evaluate) function snd_func_card_driver returned error: Permission denied
+ALSA lib confmisc.c:392:(snd_func_concat) error evaluating strings
+ALSA lib conf.c:4568:(_snd_config_evaluate) function snd_func_concat returned error: Permission denied
+ALSA lib confmisc.c:1246:(snd_func_refer) error evaluating name
+ALSA lib conf.c:4568:(_snd_config_evaluate) function snd_func_refer returned error: Permission denied
+ALSA lib conf.c:5047:(snd_config_expand) Evaluate error: Permission denied
+ALSA lib pcm.c:2565:(snd_pcm_open_noupdate) Unknown PCM default
+```
+
+- Apart from the stdout, unity log is written in `<packit_dir>/log/unity/<port>`, which might be useful for debugging.
+
+- For generating more data or making your own unity build refer to [this repository](https://github.com/princeton-vl/PackIt_Extra).
+
+## Acknowledgment
+This repository uses code from [ML-Agents](https://github.com/Unity-Technologies/ml-agents/tree/0.4.0) and [stable-baselines](https://github.com/hill-a/stable-baselines).

ablation.py

@@ -0,0 +1,45 @@
+import sys
+import cProfile
+import pickle as pkl
+sys.path.insert(0, './')
+sys.path.insert(0, './unity/')
+sys.path.insert(0, './stable-baselines/')
+
+from packing.packing_evalute import evaluate
+from packing.packing_heuristic import *
+
+list_pack_file_name = [["pack_ab/{}_tr_{}_ab".format(i, j) for i in range(0, 17)] for j in range(0, 800, 50)]
+
+configs = [
+    {
+        'pol1': sha_lar,
+        'pol2': mov_best,
+        'pol3': rot_best_pos,
+        'rot_before_mov': False
+    },
+    {
+        'pol1': sha_lar,
+        'pol2': rot_best,
+        'pol3': mov_best,
+        'rot_before_mov': True
+    }
+]
+
+for config in configs:
+    for pack_file_names in list_pack_file_name:
+        model = HeuristicModel(config['pol1'], config['pol2'], config['pol3'])
+        rewards = evaluate(
+            pack_file_name=pack_file_names,
+            model=model,
+            n_envs=4,
+            env_name='unity/envs/packit',
+            rot_before_mov=config['rot_before_mov'],
+            batch_size=20,
+            save_sup_data=False,
+            worker_id_start=400)
+        iter_number = pack_file_names[0].split("_")[-2]
+        filehandler = open(
+            "results/ablations/ab_{}_{}_{}_{}".format(iter_number, config['pol1'].__name__,
+                                    config['pol2'].__name__, config['pol3'].__name__), "wb")
+        pkl.dump(rewards, filehandler)
+        filehandler.close()

commands.py

@@ -0,0 +1,87 @@
+import itertools
+
+# he: heuristic, le: learning, tab: table, tr: train, ev: eval
+command = {
+    # Figure 4
+    'fig_4': 'python ablation.py',
+
+    # evaluate the heuristic models
+    'he_tab_1_row_1': 'python main_heuristic.py --eval_va_or_te 0'\
+                      ' --pol_1 sha_rand',
+    'he_tab_1_row_2': 'python main_heuristic.py --eval_va_or_te 0'\
+                      ' --pol_2 rot_rand',
+    'he_tab_1_row_3': 'python main_heuristic.py --eval_va_or_te 0'\
+                      ' --pol_3 mov_rand',
+    'he_tab_1_row_4': 'python main_heuristic.py --eval_va_or_te 0',
+    'he_tab_4_row_2': 'python main_heuristic.py --eval_va_or_te 0'\
+                      ' --rot_before_mov 0 --pol_2 mov_best'\
+                      ' --pol_3 rot_best_pos',
+
+    # train the learning based model
+    'tr_le_tab_1_row_5': 'python main.py --id_start 10 --learn_or_evaluate 1',
+
+    # evaluate the learning based model
+    'ev_le_tab_1_row_5': 'python main.py --id_start 0 --learn_or_evaluate 0'\
+                         ' --eval_va_or_te 0',
+
+    # train the learning based model on PackIt Easy
+    'tr_le_tab_4_row_5': 'python main.py --id_start 20 --learn_or_evaluate 1'\
+                         ' --rot_before_mov 0',
+
+    # evaluate the learning based model trained on PackIt
+    # and tested on PackIt-Easy
+    'ev_le_tab_4_row_4': 'python main.py --id_start 0 --learn_or_evaluate 0'\
+                         ' --eval_va_or_te 0 --rot_before_mov_env 0',
+
+    # evaluate the learning based model trained on PackIt-Easy and
+    # tested on PackIt-Easy
+    'ev_le_tab_4_row_5': 'python main.py --id_start 0 --learn_or_evaluate 0'\
+                         ' --eval_va_or_te 0 --rot_before_mov 0',
+
+    # heuristic with backtracks
+    'he_tab_2_row_2_4': [
+        'python main_heuristic.py --eval_va_or_te 0 --id_start {}'\
+        ' --result_folder results/he_bts'\
+        ' --pol_1 sha_all_sorted --pol_2 None --pol_3 None'\
+        ' --back_track_search 1 --budget {}'\
+        ' --eval_start_id {} --eval_end_id {}'.format(
+            (10 * j) + (1000 * _i), i, j, j+10)\
+        for (_i, i), j in itertools.product(enumerate([2, 4, 8]),
+                                            list(range(0, 100, 10)))
+    ],
+
+    # heuristic with beam
+    'he_tab_3_row_2_3': [
+        'python main_heuristic.py --eval_va_or_te 0 --id_start {}'\
+        ' --result_folder results/he_bes'\
+        ' --pol_1 sha_lar_n --pol_2 None --pol_3 None'\
+        ' --beam_search 1 --beam_size {}'\
+        ' --eval_start_id {} --eval_end_id {}'.format(
+            3000 + (10 * j) + (1000 * _i), i, j, j+10)\
+        for (_i, i), j in itertools.product(enumerate([2, 4]),
+                                            list(range(0, 100, 10)))
+    ],
+
+    # evaluate the learning based model with beam
+    'le_tab_2_row_6_8': [
+        'python main.py --eval_va_or_te 0 --id_start {}'\
+        ' --result_folder results/le_bts --learn_or_evaluate 0'\
+        ' --back_track_search 1 --budget {}'\
+        ' --eval_start_id {} --eval_end_id {}'.format(
+            (10 * j) + (1000 * _i), i, j, j+10)\
+        for (_i, i), j in itertools.product(enumerate([2, 4, 8]),
+                                            list(range(0, 100, 10)))
+    ],
+
+    # evaluate the learning based model with beam
+    'le_tab_3_row_5_6': [
+        'python main.py --eval_va_or_te 0 --id_start {}'\
+        ' --result_folder results/le_bes --learn_or_evaluate 0'\
+        ' --beam_search 1 --beam_size {}'\
+        ' --eval_start_id {} --eval_end_id {}'.format(
+            3000 + (10 * j) + (1000 * _i), i, j, j+10)\
+        for (_i, i), j in itertools.product(enumerate([2, 4]),
+                                            list(range(0, 100, 10)))
+    ],
+}
+

download.sh

@@ -0,0 +1,35 @@
+wgetgdrive(){
+  # $1 = file ID
+  # $2 = file name
+
+  URL="https://docs.google.com/uc?export=download&id=$1"
+
+  wget --load-cookies /tmp/cookies.txt "https://docs.google.com/uc?export=download&confirm=$(wget --quiet --save-cookies /tmp/cookies.txt --keep-session-cookies --no-check-certificate $URL -O- | sed -rn 's/.*confirm=([0-9A-Za-z_]+).*/\1\n/p')&id=$1" -O $2 && rm -rf /tmp/cookies.txt
+}
+
+mkdir tmp
+wgetgdrive 1x6GbwLDSBcwmxSvhL1SY7oIW5x118sDF tmp/env.zip
+wgetgdrive 1kTOcgB0Mz082v0eEkUNDMjVT2Bj1_E9s tmp/env_viz.zip
+wgetgdrive 11aT7Lw1asQXYhBZUPSEt3Q7NxWhHUXZ1 tmp/env_viz_mac.zip
+wgetgdrive 132G9nqMpOkTYfMaUihLpyocOp1ezx2On tmp/model.zip
+wgetgdrive 1DD7bdRJSPbEIXe8qXzrD3lEz0nzfbGbU tmp/data.zip
+wgetgdrive 1MLZ8g0w-TcFtwSMxwv8CwPpvTjV5zeJ9 tmp/results.zip
+
+mkdir unity/envs
+unzip tmp/env.zip -d unity/envs
+unzip tmp/env_viz.zip -d unity/envs
+unzip tmp/env_viz_mac.zip -d unity/envs
+
+unzip tmp/data.zip
+mv StreamingAssets data
+ln -s ../../../data unity/envs/packit_Data/StreamingAssets
+ln -s ../../../data unity/envs/packit_viz_Data/StreamingAssets
+ln -s ../../../../../../data unity/envs/packit_viz_mac.app/Contents/Resources/Data/StreamingAssets
+
+mkdir log
+unzip tmp/model.zip -d log
+mkdir log/unity
+
+unzip tmp/results.zip
+
+rm -r tmp