Merge branch 'development'

.gitignore

@@ -27,7 +27,7 @@ wheels/
 
 docs/_build
 **/*.mp4
-**/mcs_config.yaml
+**/mcs_config.ini
 
 # Debug output
 **/SCENE_HISTORY

README.md

@@ -19,7 +19,7 @@ python -m pip install --upgrade pip setuptools wheel
 With the activated virtual environment, install the MCS package from the git url. MCS has a dependency on an ai2thor fork and will take a while to install. Please be patient.
 
 ```
-python -m pip install git+https://github.com/NextCenturyCorporation/MCS@latest#egg=machine_common_sense
+python -m pip install git+https://github.com/NextCenturyCorporation/MCS@master#egg=machine_common_sense
 ```
 
 ## MCS Package Developer Installation
@@ -93,14 +93,13 @@ Example usage of the MCS library:
 import machine_common_sense as mcs
 
 # We will give you the Unity app file.
-controller = mcs.create_controller(unity_app_file_path, depth_maps=True,
-                                   object_masks=True)
+controller = mcs.create_controller(unity_app_file_path, config_file_path='./some-path/config.ini')
 
-# Either load the config data dict from an MCS config JSON file or create your own.
-# We will give you the training config JSON files and the format to make your own.
-config_data, status = mcs.load_config_json_file(config_json_file_path)
+# Either load the scene data dict from an MCS scene config JSON file or create your own.
+# We will give you the training scene config JSON files and the format to make your own.
+scene_data, status = mcs.load_scene_json_file(scene_json_file_path)
 
-output = controller.start_scene(config_data)
+output = controller.start_scene(scene_data)
 
 # Use your machine learning algorithm to select your next action based on the scene
 # output (goal, actions, images, metadata, etc.) from your previous action.
@@ -123,12 +122,11 @@ Example running multiple scenes sequentially:
 import machine_common_sense as mcs
 
 # Only create the MCS controller ONCE!
-controller = mcs.create_controller(unity_app_file_path, depth_maps=True,
-                                   object_masks=True)
+controller = mcs.create_controller(unity_app_file_path)
 
-for config_json_file_path in config_json_file_list:
-    config_data, status = mcs.load_config_json_file(config_json_file_path)
-    output = controller.start_scene(config_data)
+for scene_json_file_path in scene_json_file_list:
+    scene_data, status = mcs.load_scene_json_file(scene_json_file_path)
+    output = controller.start_scene(scene_data)
     action, params = select_action(output)
     while action != '':
         controller.step(action, params)
@@ -141,49 +139,78 @@ for config_json_file_path in config_json_file_list:
 To start the Unity application and enter your actions and parameters from the terminal, you can run the `run_in_human_input_mode` script that was installed in the package with the MCS Python Library (the `mcs_unity_build_file` is the Unity executable downloaded previously):
 
 ```
-run_in_human_input_mode <mcs_unity_build_file> <mcs_config_json_file>
+run_in_human_input_mode <mcs_unity_build_file> <mcs_scene_json_file>
 ```
 
 Run options:
-- `--debug`
-- `--depth_maps`
-- `--noise`
-- `--object_masks`
-- `--seed <python_random_seed>`
-- `--size <screen_width_450_or_more>`
+- `--config_file_path <file_path>`
 
 ## Run with Scene Timer
 
 To run the Unity application and measure your runtime speed, you can run the `run_scene_timer` script that was installed in the package with the MCS Python Library:
 
 ```
-run_scene_timer <mcs_unity_build_file> <mcs_config_file_folder>
+run_scene_timer <mcs_unity_build_file> <mcs_scene_file_folder>
 ```
 
-Run options:
-- `--debug`
-
-This will run all of the MCS scene configuration JSON files in the given folder, use the PASS action for 20 steps (or for a number of steps equal to the last_step of the config file's goal, if any) in each scene, and print out the total, average, minimum, and maximum run time for all the scenes and the steps.
+This will run all of the MCS scene configuration JSON files in the given folder, use the PASS action for 20 steps (or for a number of steps equal to the last_step of the scene file's goal, if any) in each scene, and print out the total, average, minimum, and maximum run time for all the scenes and the steps.
 
 ## Config File
 
-To use an MCS configuration file, set the `MCS_CONFIG_FILE_PATH` environment variable to the path of your MCS configuration file.
+To use an MCS configuration file, you can either pass in a file path via the `config_file_path` property in the create_controller() method, or set the `MCS_CONFIG_FILE_PATH` environment variable to the path of your MCS configuration file (note that the configuration must be an INI file -- see [sample_config.ini](./sample_config.ini) for an example).
 
 ### Config File Properties
 
+#### debug
+
+(boolean, optional)
+
+Whether to save MCS output debug files in this folder and print debug output to terminal. Will default to `False`.
+
+#### debug_output
+
+(string, optional)
+
+Alternatively to the `debug` property, `debug_output` can be used to either print debug info to the terminal or to debug files only. This should either be set to `file` or `terminal`, and will default to None. Will be ignored if `debug` is set.
+
 #### metadata
 
+(string, optional)
+
 The `metadata` property describes what metadata will be returned by the MCS Python library. The `metadata` property is available so that users can run baseline or ablation studies during training. It can be set to one of the following strings:
 
 - `oracle`: Returns the metadata for all the objects in the scene, including visible, held, and hidden objects. Object masks will have consistent colors throughout all steps for a scene.
 - `level2`: Only returns the images (with depth maps AND object masks), camera info, and properties corresponding to the player themself (like head tilt or pose). No information about specific objects will be included. Note that here, object masks will have randomized colors per step.
 - `level1`: Only returns the images (with depth maps but NOT object masks), camera info, and properties corresponding to the player themself (like head tilt or pose). No information about specific objects will be included.
+- `none`: Only returns the images (but no depth maps or object masks), camera info, and properties corresponding to the player themself (like head tilt or pose). No information about specific objects will be included.
 
 Otherwise, return the metadata for the visible and held objects.
 
+#### noise_enabled
+
+(boolean, optional)
+
+Whether to add random noise to the numerical amounts in movement and object interaction action parameters. Will default to `False`.
+
+# seed
+
+(int, optional)
+
+A seed for the Python random number generator (defaults to None).
+
+#### size
+
+(int, optional)
+
+Desired screen width. If value given, it must be more than `450`. If none given, screen width will default to `600`.
+
 ### Using the Config File to Generate Scene Graphs or Maps
 
-1. Save your MCS configuration file with `metadata: oracle`
+1. Save your .ini MCS configuration file with:
+```
+[MCS]
+metadata: oracle`
+```
 
 2. Create a simple Python script to loop over one or more JSON scene configuration files, load each scene in the MCS controller, and save the output data in your own scene graph or scene map format.
 
@@ -200,12 +227,12 @@ unity_app = # Path to your MCS Unity application
 controller = mcs.create_controller(unity_app)
 
 for scene_file in scene_files:
-    config_data, status = mcs.load_config_json(scene_file)
+    scene_data, status = mcs.load_scene_json_file(scene_file)
 
     if status is not None:
         print(status)
     else:
-        output = controller.start_scene(config_data)
+        output = controller.start_scene(scene_data)
         # Use the output to save your scene graph or map
 ```
 
@@ -253,12 +280,12 @@ import machine_common_sense as mcs
 # use your path to the MCS Unity executable
 controller = mcs.create_controller('MCS.x86_64')
 # find a test scene
-config_file_path = 'playroom.json'
-config_data, status = mcs.load_config_json(config_file_path)
-config_file_name = config_file_path[config_file_path.rfind('/')+1]
-if 'name' not in config_data.keys():
-    config_data['name'] = config_file_name[0:config_file_name.find('.')]
-output = controller.start_scene(config_data)
+scene_file_path = 'playroom.json'
+scene_data, status = mcs.load_scene_json_file(scene_file_path)
+scene_file_name = scene_file_path[scene_file_path.rfind('/')+1]
+if 'name' not in scene_data.keys():
+    scene_data['name'] = scene_file_name[0:scene_file_name.find('.')]
+output = controller.start_scene(scene_data)
 for i in range(1, 12):
     output = controller.step('RotateLook')
     for j in range(len(output.image_list)):

machine_common_sense/API.md

@@ -24,7 +24,7 @@
 ## Controller
 
 
-### class machine_common_sense.controller.Controller(unity_app_file_path, debug=False, enable_noise=False, seed=None, size=None, depth_maps=None, object_masks=None, history_enabled=True)
+### class machine_common_sense.controller.Controller(unity_app_file_path, config_file_path=None)
 MCS Controller class implementation for the MCS wrapper of the AI2-THOR
 library.
 
@@ -33,25 +33,11 @@ library.
 
 * **Parameters**
 
-
-    * **debug** (*boolean**, **optional*) – Whether to save MCS output debug files in this folder.
-    (default False)
-
-
-    * **enable_noise** (*boolean**, **optional*) – Whether to add random noise to the numerical amounts in movement
-    and object interaction action parameters.
-    (default False)
-
-
-    * **seed** (*int**, **optional*) – A seed for the Python random number generator.
+    **config_file_path** (*str**, **optional*) – Path to configuration file to read in and set various properties,
+    such as metadata level and whether or not to save history files
     (default None)
 
 
-    * **history_enabled** (*boolean**, **optional*) – Whether to save all the history files and generated image
-    history to local disk or not.
-    (default False)
-
-
 
 #### end_scene(choice, confidence=1.0)
 Ends the current scene.
@@ -73,7 +59,7 @@ Ends the current scene.
 
 #### generate_noise()
 Returns a random value between -0.05 and 0.05 used to add noise to all
-numerical action parameters enable_noise is True.
+numerical action parameters noise_enabled is True.
 :returns: A value between -0.05 and 0.05 (using random.uniform).
 :rtype: float
 

machine_common_sense/DEV.md

@@ -76,7 +76,7 @@ We have made multiple run scripts:
 To run a script (like `run_human_input.py`) from the terminal with visual output:
 
 ```
-run_human_input <mcs_unity_build_file> <mcs_config_json_file>
+run_in_human_input_mode <mcs_unity_build_file> <mcs_config_json_file>
 ```
 
 To run it headlessly, first install xvfb (on Ubuntu, run `sudo apt-get install xvfb`), then:
@@ -95,6 +95,83 @@ First, install ffmpeg. Then (change the frame rate with the `-r` option):
 ffmpeg -r 3 -i frame_image_%d.png output.gif
 ```
 
+## Full List of Config Options
+
+Outlined here is a comprehensive list of config file options that can be used.
+
+To use an MCS configuration file, you can either pass in a file path via the `config_file_path` property in the create_controller() method, or set the `MCS_CONFIG_FILE_PATH` environment variable to the path of your MCS configuration file (note that the configuration must be an INI file -- see [sample_config.ini](../sample_config.ini) for an example).
+
+### Config File Properties
+
+#### AWS specific properties
+
+The following string properties can be specified in order to upload and organize files in S3:
+- aws_access_key_id
+- aws_secret_access_key
+- s3_bucket
+- s3_folder
+
+#### debug
+
+(boolean)
+
+Whether to save MCS output debug files in this folder and print debug output to terminal. Will default to `False`. In lieu of a config file, this can be set using the `MCS_DEBUG_MODE` environment variable.
+
+#### debug_output
+
+(string)
+
+Alternatively to the `debug` property, `debug_output` can be used to either print debug info to the terminal or to debug files only. This should either be set to `file` or `terminal`, and will default to None. Will be ignored if `debug` or `MCS_DEBUG_MODE` is set.
+
+#### evaluation
+
+(boolean)
+
+Whether or not we're running in evaluation mode (default: False). If `True`, evaluation files for each scene will be created and uploaded to S3.
+
+#### evaluation_name
+
+(string)
+
+Identifier to add to filenames uploaded to S3 (default: '').
+
+#### metadata
+
+(string)
+
+The `metadata` property describes what metadata will be returned by the MCS Python library. This can also be specified via the `MCS_METADATA_LEVEL` environment variable. It can be set to one of the following strings:
+
+- `oracle`: Returns the metadata for all the objects in the scene, including visible, held, and hidden objects. Object masks will have consistent colors throughout all steps for a scene.
+- `level2`: Only returns the images (with depth masks AND object masks), camera info, and properties corresponding to the player themself (like head tilt or pose). No information about specific objects will be included. Note that here, object masks will have randomized colors per step.
+- `level1`: Only returns the images (with depth masks but NOT object masks), camera info, and properties corresponding to the player themself (like head tilt or pose). No information about specific objects will be included.
+- `none`: Only returns the images (but not the masks), camera info, and properties corresponding to the player themself (like head tilt or pose). No information about specific objects will be included.
+
+Otherwise, return the metadata for the visible and held objects.
+
+#### noise_enabled
+
+(boolean)
+
+Whether to add random noise to the numerical amounts in movement and object interaction action parameters. Will default to `False`.
+
+# seed
+
+(int)
+
+A seed for the Python random number generator (defaults to None).
+
+#### size
+
+(int)
+
+Desired screen width. If value given, it must be more than `450`. If none given, screen width will default to `600`.
+
+#### team
+
+(string)
+
+Team name identifier to prefix to filenames uploaded to S3 (default: '').
+
 ## References
 
 - AI2-THOR Documentation: http://ai2thor.allenai.org/documentation

machine_common_sense/__init__.py

@@ -1,4 +1,4 @@
-from .mcs import create_controller, load_config_json_file
+from .mcs import create_controller, load_scene_json_file
 from .action import Action
 from .controller import Controller
 from .goal_metadata import GoalMetadata, GoalCategory