Merge pull request #9 from threedworld-mit/getting_started_example

Getting started example

Documentation/Changelog.md

@@ -2,6 +2,29 @@
 
 # v1.6.x
 
+## v1.6.2
+
+### `tdw` module
+
+- Fixed: `tdw` module doesn't work in virtualenv.
+
+#### `DebugController`
+
+- Added parameters `launch_build` and `display`.
+
+### Build
+
+- Fixed: Downloaded builds don't have execute permissions in OS X or Linux (the downloader now runs `chmod` after extracting the .zip file)
+- Fixed: `NullReferenceException` when Sticky Mitten Avatar tries to put down an object that was never held.
+
+### Documentation
+
+#### Modified Documentation
+
+| Document             | Description                                                  |
+| -------------------- | ------------------------------------------------------------ |
+| `getting_started.md` | 1. The example uses `models_core.json` so it works for everybody.<br>2. Better explanation for how to get object IDs.<br>3. Added image saving to the example. |
+
 ## v1.6.1
 
 ### New Features

Documentation/getting_started.md

@@ -232,7 +232,7 @@ c.communicate({"$type": "add_object",
                "id": box_id})
 ```
 
-Then an **avatar** can be added to the scene. In this case, the avatar is just a camera. The avatar can then send an image:
+Then an **avatar** can be added to the scene. In this case, the avatar is just a camera. The avatar can then send an image. This image is a numpy array that can be either saved to disk or fed directly into a ML system:
 
 ```python
 avatar_id = "a"
@@ -257,9 +257,24 @@ for r in resp[:-1]:
     # Find the image data.
     if r_id == "imag":
         img = Images(r)
+
+        # Usually, you'll want to use one of these functions, but not both of them:
+
+        # Use this to save a .jpg
+        TDWUtils.save_images(img, filename="test_img") 
+
+        # Use this to convert the image to a PIL image, which can be processed by a ML system at runtime.
+        # The index is 0 because we know that there is only one pass ("_img").
+        pil_img = TDWUtils.get_pil_image(img, index=0)
 ```
 
-This image is a numpy array that can be either saved to disk or fed directly into a ML system. Put together, the example code will create this image:
+To terminate the build once your simulation is done:
+
+```python
+c.communicate({"$type": "terminate"})
+```
+
+Put together, the example code will create this image:
 
 ![](images/box_on_desk.png)
 

Python/setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup, find_packages
 from pathlib import Path
 
-__version__ = "1.6.1.6"
+__version__ = "1.6.2.0"
 readme_path = Path('../README.md')
 if readme_path.exists():
     long_description = readme_path.read_text(encoding='utf-8')

Python/tdw/debug_controller.py

@@ -18,17 +18,19 @@ class DebugController(Controller):
     ```
     """
 
-    def __init__(self, port=1071):
+    def __init__(self, port: int = 1071, launch_build: bool = True, display: int = None):
         """
         Create the network socket and bind the socket to the port.
 
         :param port: The port number.
+        :param launch_build: If True, automatically launch the build. If one doesn't exist, download and extract the correct version. Set this to False to use your own build, or (if you are a backend developer) to use Unity Editor.
+        :param display: If launch_build == True, launch the build using this display number (Linux-only).
         """
 
         # This will be used to record each list of commands sent to the build.
         self.record = []
 
-        super().__init__(port=port)
+        super().__init__(port=port, launch_build=launch_build, display=display)
 
     def communicate(self, commands: Union[dict, List[dict]]) -> list:
         """

Python/tdw/release/build.py

@@ -4,6 +4,7 @@
 from pathlib import Path
 from zipfile import ZipFile
 from distutils import dir_util
+from subprocess import call
 from tdw.version import __version__
 from tdw.backend.platforms import SYSTEM_TO_RELEASE, SYSTEM_TO_EXECUTABLE
 
@@ -34,6 +35,18 @@ def get_url(version: str = __version__) -> Tuple[str, bool]:
             release_exists = True
         return url, release_exists
 
+    @staticmethod
+    def chmod() -> None:
+        """
+        Add execute permissions to the build.
+        :return:
+        """
+
+        if system() == "Darwin":
+            call(["chmod", "+x", str(Build.BUILD_PATH.joinpath("Contents/MacOS/TDW").resolve())])
+        elif system() == "Linux":
+            call(["chmod", "+x", str(Build.BUILD_PATH.resolve())])
+
     @staticmethod
     def download(version: str = __version__) -> bool:
         """
@@ -66,4 +79,7 @@ def download(version: str = __version__) -> bool:
         # Delete the zip file.
         zip_path.unlink()
         print("Deleted the .zip file.")
+
+        # Add execute permissions.
+        Build.chmod()
         return True

Python/tdw/version.py

@@ -1 +1 @@
-__version__ = "1.6.1"
+__version__ = "1.6.2"