Merge branch 'master' into audio_clip_memory_leak

Documentation/Changelog.md

@@ -4,6 +4,74 @@
 
 To upgrade from TDW v1.8 to v1.9, read [this guide](upgrade_guides/v1.8_to_v1.9.md).
 
+## v1.9.7
+
+### Command API
+
+#### Modified Commands
+
+| Command                | Modification                              |
+| ---------------------- | ----------------------------------------- |
+| `add_trigger_collider` | Added trigger collider shape `"cylinder"` |
+
+### Build
+
+- Fixed: DllNotFoundException in TDW.app (OS X) due to missing AudioPluginOculusSpatializer.bundle
+
+### `tdw` module
+
+- Fixed: `struct.error` in `CompositeObjectManager` when deserializing static spring data.
+- Added `TriggerCollisionManager` add-on. Manager per-frame trigger collision data.
+- Added the following trigger collider/collision data classes:
+  - `TriggerColliderShape` Enum describing the shape of the collider.
+  - `TriggerCollisionEvent` Wrapper for trigger collision data.
+- Added `ContainerManager` add-on. Manager per-frame containment data. This is a subclass of `TriggerCollisionManager`.
+- Added the following container trigger collider/collision data classes:
+  - `ContainerBoxTriggerCollider` Data for a box-shaped container trigger collider.
+  - `ContainerColliderTag` Enum of semantic tags for container trigger colliders.
+  - `ContainerCylinderTriggerCollider` Data for a cylinder-shaped container trigger collider.
+  - `ContainerNonUniformScaleTriggerCollider` Abstract class for container trigger colliders with non-uniform scales.
+  - `ContainerSphereTriggerCollider` Data for a sphere-shaped container trigger collider.
+  - `ContainerTriggerCollider` Abstract base class for container trigger collider data.
+  - `ContainmentEvent` Wrapper for containment trigger collision data.
+
+### Model Library
+
+- Added cached trigger collision data to model records. Not all records have container trigger colliders; see `model_record.trigger_colliders`.
+  - (Backend) Added: `tdw.librarian._Encoder` JSONEncoder extension that is used within `_Librarian` classes. For now, this just handles container collider data.
+- Added models `models_core.json` and `models_full.json`: cabinet_36_two_door_wood_oak_white_composite, cabinet_36_two_door_wood_beech_honey_composite, cabinet_24_wall_wood_beech_honey_composite, cabinet_24_wall_wood_oak_white_composite, cabinet_36_wall_wood_beech_honey_composite, cabinet_36_wall_wood_oak_white_composite, appliance-ge-profile-microwave3_composite, appliance-ge-profile-microwave_composite, microwave_composite
+
+### Example Controllers
+
+- Moved composite object controllers from `physx/` to `semantic_states/`
+- Moved overlap and raycast controllers from `objects_and_scenes/` to `semantic_states/`
+- Added: `semantic_states/containment.py`
+- Added: `semantic_states/trigger_collisions.py`
+
+### Documentation
+
+#### New Documentation
+
+| Document                                                     | Description                                                 |
+| ------------------------------------------------------------ | ----------------------------------------------------------- |
+| `lessons/semantic_states/containment.md`                     | Documentation for how to use the `ContainerManager`.        |
+| `lessons/semantic_state/grasped.md`                          | Overview of "grasped" semantic states with various agents.  |
+| `lessons/semantic_states/overview.md`                        | Overview of semantic states.                                |
+| `lessons/semantic_states/trigger_collisions.md`              | Documentation for how to use the `TriggerCollisionManager`. |
+| `python/add_ons/container_manager.md`                        | API documentation for `ContainerManager`.                   |
+| `python/add_ons/trigger_collision_manager.md`                | API documentation for `TriggerCollisionManager`.            |
+| `python/collision_data/trigger_collider_shape.md`<br>`python/collision_data/trigger_collision_event.md` | API documentation for trigger collision data classes.       |
+| `python/container_data/container_box_trigger_collider.md`<br>`python/container_data/container_collider_tag.md`<br>`python/container_data/container_cylinder_trigger_collider.md`<br>`python/container_data/container_non_uniform_scale_trigger_collider.md`<br>`python/container_data/container_sphere_trigger_collider.md`<br>`python/container_data/container_trigger_collider.md`<br>`python/container_data/containment_event.md` | API documentation for containment data classes.             |
+
+
+#### Modified Documentation
+
+| Document                                | Modification                                             |
+| --------------------------------------- | -------------------------------------------------------- |
+| `lessons/objects_and_scenes/raycast.md` | Moved to: `lessons/semantic_states/raycast.md`           |
+| `lessons/objects_and_scenes/overlap.md` | Moved to: `lessons/semantic_states/overlap.md`           |
+| `lessons/physx/composite_objects.md`    | Moved to: `lessons/semantic_states/composite_objects.md` |
+
 ## v1.9.6
 
 ### Command API

Documentation/api/command_api.md

@@ -3961,6 +3961,7 @@ The shape of the trigger collider.
 | --- | --- |
 | `"cube"` |  |
 | `"sphere"` |  |
+| `"cylinder"` |  |
 
 ***
 

Documentation/lessons/navigation/occupancy_maps.md

@@ -53,7 +53,7 @@ Output:
  [-1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1]]
 ```
 
-Note that it takes two `communicate()` calls to create the occupancy map; the first gets the bounds of the scene and the second divides the bounds into cells and requests [`Raycast`](../objects_and_scenes/raycast.md) and [`Overlap`](../objects_and_scenes/overlap.md) data per cell.
+Note that it takes two `communicate()` calls to create the occupancy map; the first gets the bounds of the scene and the second divides the bounds into cells and requests [`Raycast`](../semantic_states/raycast.md) and [`Overlap`](../semantic_states/overlap.md) data per cell.
 
 `occupancy_map.generate()` prepares to send commands to the build but doesn't actually send commands to the build (only a controller can do that). You always need to send `occupancy_map.generate()` *then* `c.communicate(commands)`.
 

Documentation/lessons/objects_and_scenes/proc_gen_objects.md

@@ -621,7 +621,7 @@ As mentioned earlier, procedural generation is an unbounded problem and there's
 
 ***
 
-**Next: [`Raycast` output data](raycast.md)**
+**Next: [Reset a scene](reset_scene.md)**
 
 [Return to the README](../../../README.md)
 

Documentation/lessons/physx/disable_physics.md

@@ -34,7 +34,7 @@ Typically, users want to disable physics if they are setting up a scene that inv
 Besides the obvious (objects won't move due to physics), there are some other effects of disabling physics:
 
 1. [Collision detection](collisions.md) is disabled.
-2. [Raycasts](../objects_and_scenes/raycast.md) and [overlaps](../objects_and_scenes/overlap.md) won't work.
+2. [Raycasts](../semantic_states/raycast.md) and [overlaps](../semantic_states/overlap.md) won't work.
 
 ***
 

Documentation/lessons/physx/forces.md

@@ -212,7 +212,7 @@ Result:
 
 ***
 
-**Next: [Composite objects (objects with affordances)](composite_objects.md)**
+**Next: [Skip physics frames](step_physics.md)**
 
 [Return to the README](../../../README.md)
 

Documentation/lessons/physx/composite_objects.md → Documentation/lessons/semantic_states/composite_objects.md

@@ -1,7 +1,9 @@
-##### Physics (PhysX)
+##### Semantic States
 
 # Composite objects (objects with affordances)
 
+*Composite objects utilize the PhysX physics engine. If you haven't done so already, please read [the documentation for PhysX in TDW](../physx/physx.md)*.
+
 **Composite objects** are objects in TDW that have multiple "sub-objects". Sub-objects appear in [output data](../core_concepts/output_data.md) as separate objects with separate IDs and [segmentation colors](../visual_perception/id.md).
 
 Composite objects can be:
@@ -227,7 +229,7 @@ In general, you shouldn't adjust the spring force. You *can* safely adjust the d
 
 ## Kinematic states
 
-If you send [`set_kinematic_state`](../../api/command_api.md#set_kinematic_state) for a composite object, the command will only affect the [kinematic state](physics_objects.md) of the top-level object. To set the state for the top-level object *and* all sub-objects, send  [`set_composite_object_kinematic_state`](../../api/command_api.md#set_composite_object_kinematic_state):
+If you send [`set_kinematic_state`](../../api/command_api.md#set_kinematic_state) for a composite object, the command will only affect the [kinematic state](../physx/physics_objects.md) of the top-level object. To set the state for the top-level object *and* all sub-objects, send  [`set_composite_object_kinematic_state`](../../api/command_api.md#set_composite_object_kinematic_state):
 
 ```python
 from tdw.controller import Controller
@@ -265,7 +267,7 @@ c.communicate(commands)
 
 ## General object commands
 
-Sub-objects will respond to TDW commands just like any other object; you can, for example, [apply forces](forces.md) to individual sub-objects. Sub-objects likewise appear as separate objects in the output data.
+Sub-objects will respond to TDW commands just like any other object; you can, for example, [apply forces](../physx/forces.md) to individual sub-objects. Sub-objects likewise appear as separate objects in the output data.
 
 In this example, we'll add the microwave to the scene and make it kinematic (as explained above, the door will remain non-kinematic). Then, we'll apply a torque to the door:
 
@@ -378,17 +380,17 @@ Microwave door is open on frame 16 at angle 30.119487762451172.
 
 ***
 
-**Next: [Skip physics frames](step_physics.md)**
+**Next: [Grasped objects](grasped.md)**
 
 [Return to the README](../../../README.md)
 
 ***
 
 Example controllers:
 
-- [composite_object.py](https://github.com/threedworld-mit/tdw/blob/master/Python/example_controllers/physx/composite_object.py) Demonstration of how to use composite sub-objects with a test model.
-- [composite_object_torque.py](https://github.com/threedworld-mit/tdw/blob/master/Python/example_controllers/physx/composite_object_torque.py) Apply a torque to the door of a microwave.
-- [composite_object_open.py](https://github.com/threedworld-mit/tdw/blob/master/Python/example_controllers/physx/composite_object_open.py) Determine when a composite object is "open".
+- [composite_object.py](https://github.com/threedworld-mit/tdw/blob/master/Python/example_controllers/semantic_states/composite_object.py) Demonstration of how to use composite sub-objects with a test model.
+- [composite_object_torque.py](https://github.com/threedworld-mit/tdw/blob/master/Python/example_controllers/semantic_states/composite_object_torque.py) Apply a torque to the door of a microwave.
+- [composite_object_open.py](https://github.com/threedworld-mit/tdw/blob/master/Python/example_controllers/semantic_states/composite_object_open.py) Determine when a composite object is "open".
 
 Python API: