Merge pull request #671 from threedworld-mit/wireframe_shader

Wireframe shader

Author: alters-mit

Documentation/Changelog.md

@@ -4,6 +4,24 @@
 
 To upgrade from TDW v1.11 to v1.12, read [this guide](upgrade_guides/v1.11_to_v1.12.md).
 
+## v1.12.21
+
+### Command API
+
+#### New Commands
+
+| Command           | Description                                   |
+| ----------------- | --------------------------------------------- |
+| `set_wireframe_material` | Set the visual material of an object or one of its sub-objects to wireframe. |
+
+### `tdw` module
+
+- Added: `TDWUtils.set_wireframe_material(substructure, object_id, color, thickness)`.
+
+### Example Controllers
+
+- Added: `scene_setup_low_level/set_wireframe_material.py`
+
 ## v1.12.20
 
 ### Command API

Documentation/api/command_api.md

@@ -548,6 +548,7 @@
 | [`set_texture_scale`](#set_texture_scale) | Set the scale of the tiling of the material's main texture. |
 | [`set_visual_material`](#set_visual_material) | Set a visual material of an object or one of its sub-objects.  |
 | [`set_visual_material_smoothness`](#set_visual_material_smoothness) | Set the smoothness (glossiness) of an object's visual material. |
+| [`set_wireframe_material`](#set_wireframe_material) | Set the visual material of an object or one of its sub-objects to wireframe.  |
 
 **Wheelchair Replicant Command**
 
@@ -7227,6 +7228,30 @@ Set the smoothness (glossiness) of an object's visual material.
 | `"object_name"` | string | The name of the sub-object. | |
 | `"id"` | int | The unique object ID. | |
 
+***
+
+## **`set_wireframe_material`**
+
+Set the visual material of an object or one of its sub-objects to wireframe. 
+
+- <font style="color:darkslategray">**Requires a material asset bundle**: To use this command, you must first download an load a material. Send the [add_material](#add_material) command first.</font>
+
+```python
+{"$type": "set_wireframe_material", "material_index": 1, "color": {"r": 0.219607845, "g": 0.0156862754, "b": 0.6901961, "a": 1.0}, "object_name": "string", "id": 1}
+```
+
+```python
+{"$type": "set_wireframe_material", "material_index": 1, "color": {"r": 0.219607845, "g": 0.0156862754, "b": 0.6901961, "a": 1.0}, "object_name": "string", "id": 1, "thickness": 0.02}
+```
+
+| Parameter | Type | Description | Default |
+| --- | --- | --- | --- |
+| `"material_index"` | int | The index of the material in the sub-object's list of materials. | |
+| `"thickness"` | float | The thickness of the wireframe lines. | 0.02 |
+| `"color"` | Color | The new RGBA color of the wireframe. | |
+| `"object_name"` | string | The name of the sub-object. | |
+| `"id"` | int | The unique object ID. | |
+
 # WheelchairReplicantCommand
 
 These commands affect a WheelchairReplicant currently in the scene.

Documentation/python/tdw_utils.md

@@ -405,6 +405,24 @@ _(Static)_
 
 _Returns:_  A list of commands to set ALL visual materials on an object to a single material.
 
+#### set_wireframe_material
+
+**`TDWUtils.set_wireframe_material(substructure, object_id, color)`**
+
+**`TDWUtils.set_wireframe_material(substructure, object_id, color, thickness=0.02)`**
+
+_(Static)_
+
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| substructure |  List[dict] |  | The metadata substructure of the object. |
+| object_id |  int |  | The ID of the object in the scene. |
+| color |  Dict[str, float] |  | The color to make the wireframe. |
+| thickness |  float  | 0.02 | The thickness of the wireframe lines. |
+
+_Returns:_  A list of commands to set ALL visual materials on an object to a single wireframe material.
+
 #### get_depth_values
 
 **`TDWUtils.get_depth_values(image)`**

Python/example_controllers/scene_setup_low_level/set_wireframe_material.py

@@ -0,0 +1,35 @@
+from tdw.controller import Controller
+from tdw.tdw_utils import TDWUtils
+from tdw.add_ons.third_person_camera import ThirdPersonCamera
+from tdw.add_ons.image_capture import ImageCapture
+from tdw.librarian import ModelLibrarian
+from tdw.backend.paths import EXAMPLE_CONTROLLER_OUTPUT_PATH
+
+"""
+Set an object's material to wireframe.
+"""
+
+c = Controller()
+object_id_1 = c.get_unique_id()
+object_id_2 = c.get_unique_id()
+
+lib = ModelLibrarian()
+model_record_1 = lib.get_record("white_lounger_chair")
+model_record_2 = lib.get_record("chair_billiani_doll")
+cam = ThirdPersonCamera(position={"x": 3.6, "y": 1.6, "z": -0.6},
+                        look_at=object_id_1)
+path = EXAMPLE_CONTROLLER_OUTPUT_PATH.joinpath("set_wireframe_material")
+print(f"Images will be saved to: {path}")
+cap = ImageCapture(avatar_ids=[cam.avatar_id], pass_masks=["_img"], path=path)
+c.add_ons.extend([cam, cap])
+
+commands = [TDWUtils.create_empty_room(12, 12),
+            c.get_add_object(model_name=model_record_1.name,
+                             object_id=object_id_1),
+            c.get_add_object(model_name=model_record_2.name,
+                             object_id=object_id_2,
+                             position={"x": 2, "y": 0, "z": 0})]
+commands.extend(TDWUtils.set_wireframe_material(substructure=model_record_1.substructure, object_id=object_id_1, color={"r": 1.0, "g": 0, "b": 0, "a": 1.0}, thickness=0.05))
+commands.extend(TDWUtils.set_wireframe_material(substructure=model_record_2.substructure, object_id=object_id_2, color={"r": 0, "g": 0, "b": 1.0, "a": 1.0}, thickness=0.035))
+c.communicate(commands)
+c.communicate({"$type": "terminate"})

Python/tdw/tdw_utils.py

@@ -443,6 +443,28 @@ def set_visual_material(c: Controller, substructure: List[dict], object_id: int,
                                   "material_index": i}])
         return commands
 
+    @staticmethod
+    def set_wireframe_material(substructure: List[dict], object_id: int, color: Dict[str, float], thickness: float = 0.02) -> List[dict]:
+        """
+        :param substructure: The metadata substructure of the object.
+        :param object_id: The ID of the object in the scene.
+        :param color: The color to make the wireframe.
+        :param thickness: The thickness of the wireframe lines.
+ 
+        :return A list of commands to set ALL visual materials on an object to a single wireframe material.
+        """
+
+        commands = []
+        for sub_object in substructure:
+            for i in range(len(sub_object["materials"])):
+                commands.extend([{"$type": "set_wireframe_material",
+                                  "id": object_id,
+                                  "color": color,
+                                  "thickness": thickness,
+                                  "object_name": sub_object["name"],
+                                  "material_index": i}])
+        return commands
+
     @staticmethod
     def get_depth_values(image: np.ndarray, depth_pass: str = "_depth", width: int = 256, height: int = 256, near_plane: float = 0.1, far_plane: float = 100) -> np.ndarray:
         """

Python/tdw/version.py

@@ -1 +1 @@
-__version__ = "1.12.20.0"
+__version__ = "1.12.21.0"