docs: Update example combine-speos.py

doc/changelog.d/499.documentation.md

@@ -0,0 +1 @@
+Update example combine-speos.py

examples/workflow/combine-speos.py

@@ -1,6 +1,9 @@
-# # Moving car example by using speos files combination
-
+# # Moving car example by combining Speos files
+#
 # This tutorial demonstrates how to run moving car workflow use case.
+# ## Prerequisites
+#
+# ### Perform imports
 
 # +
 import os
@@ -10,96 +13,105 @@
 from ansys.speos.core.sensor import SensorCamera
 from ansys.speos.core.simulation import SimulationInverse
 from ansys.speos.core.source import SourceLuminaire
-from ansys.speos.core.workflow.combine_speos import (
-    SpeosFileInstance,
-    combine_speos,
-)
+from ansys.speos.core.workflow.combine_speos import SpeosFileInstance, combine_speos
 
-# If using docker container
-assets_data_path = Path("/app") / "assets"
-# If using local server
-# assets_data_path = Path().resolve().parent.parent / "tests" / "assets"
-# If using a different path
-# assets_data_path = Path("path/to/downloaded/example/assets")
 # -
 
+# ### Define constants
+# Constants help ensure consistency and avoid repetition throughout the example.
+
+HOSTNAME = "localhost"
+GRPC_PORT = 50098  # Be sure the Speos GRPC Server has been started on this port.
+CAR_NAMES = ["BlueCar", "RedCar"]
+ENVIRONMENT_NAME = "Env_Simplified"
+USE_DOCKER = True  # Set to False if you're running this example locally as a Notebook.
+USE_GPU = False
+
+# ## Coordinate systems
+#
+# Define the global coordinate systems for each of the assets.
+
+GLOBAL_CS = [
+    0,  # Origin x
+    0,  # Origin y
+    0,  # Origin z
+    1,  # x-direction x
+    0,  # x-direction y
+    0,  # x-direction z
+    0,  # y-direction x
+    1,  # y-direction y
+    0,  # y-direction z
+    0,  # z-direction x
+    0,  # z-direction y
+    0,  # z-direction z
+]
+CAR_CS = {
+    "red": [-4000, 0, 48000, 1.0, 0.0, 0.0, 0.0, 0.0, -1.0, 0.0, 1.0, 0.0],
+    "blue": [2000, 0, 35000, 0.0, 0.0, -1.0, -1.0, 0.0, 0.0, 0.0, 1.0, 0.0],
+}
+
+
+# ## Load assets
+# Assets used to run this example are available in the
+# [PySpeos repository](https://github.com/ansys/pyspeos/) on GitHub.
+#
+# > **Note:** Make sure you
+# > have downloaded simulation assets and set ``assets_data_path``
+# > to point to the assets folder.
+
+if USE_DOCKER:  # Running on the remote server.
+    assets_data_path = Path("/app") / "assets"
+else:
+    assets_data_path = Path("/path/to/your/download/assets/directory")
+
 # ## Create connection with speos rpc server
 
-# +
-speos = Speos(host="localhost", port=50098)
-# -
+speos = Speos(host=HOSTNAME, port=GRPC_PORT)
 
 # ## Combine several speos files into one project
-
+#
 # Here we are building a project with:
 # - An environment which is a road
 # - A blue car
 # - A red car
 
-# +
+full_env_path = assets_data_path / f"{ENVIRONMENT_NAME}.speos" / f"{ENVIRONMENT_NAME}.speos"
+car_paths = [assets_data_path / f"{car}.speos" / f"{car}.speos" for car in CAR_NAMES]
+assets = [
+    SpeosFileInstance(
+        speos_file=str(full_env_path),
+        axis_system=GLOBAL_CS,
+    ),
+    SpeosFileInstance(
+        speos_file=str(car_paths[0]),
+        axis_system=CAR_CS["red"],
+    ),
+    SpeosFileInstance(
+        speos_file=str(car_paths[1]),
+        axis_system=CAR_CS["blue"],
+    ),
+]
 p = combine_speos(
     speos=speos,
-    speos_to_combine=[
-        SpeosFileInstance(
-            speos_file=str(assets_data_path / "Env_Simplified.speos" / "Env_Simplified.speos"),
-            axis_system=[0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1],
-        ),
-        SpeosFileInstance(
-            speos_file=str(assets_data_path / "BlueCar.speos" / "BlueCar.speos"),
-            axis_system=[
-                2000,
-                0,
-                35000,
-                0.0,
-                0.0,
-                -1.0,
-                -1.0,
-                0.0,
-                0.0,
-                0.0,
-                1.0,
-                0.0,
-            ],
-        ),
-        SpeosFileInstance(
-            speos_file=str(assets_data_path / "RedCar.speos" / "RedCar.speos"),
-            axis_system=[
-                -4000,
-                0,
-                48000,
-                1.0,
-                0.0,
-                0.0,
-                0.0,
-                0.0,
-                -1.0,
-                0.0,
-                1.0,
-                0.0,
-            ],
-        ),
-    ],
+    speos_to_combine=assets,
 )
+
 print(p)
-# -
 
 # ## Preview the project
-
+#
 # User can review the created/loaded project using preview method.
 
-# +
 p.preview()
-# -
 
 # ## Complete the project with sensor/source/simulation
-
+#
 # We are adding a camera sensor to have output results, a luminaire to have a light source.
-
+#
 # And, we gather the source and the sensor into a simulation (we will compute it just after).
-
+#
 # ### Create a sensor
 
-# +
 ssr = p.create_sensor(name="Camera.1", feature_type=SensorCamera)
 ssr.set_distortion_file_uri(
     uri=str(assets_data_path / "CameraInputFiles" / "CameraDistortion_190deg.OPTDistortion")
@@ -114,12 +126,11 @@
 )
 ssr.set_axis_system([-2000, 1500, 11000, -1, 0, 0, 0, 1, 0, 0, 0, -1])
 ssr.commit()
-# -
 
 # ### Create a source
-
+#
 # In this example, a luminaire source is created with an IES file.
-
+#
 # More details on creating/editing source examples can be found in core examples.
 
 # +
@@ -128,83 +139,67 @@
     uri=str(assets_data_path / "IES_C_DETECTOR.ies")
 ).set_spectrum().set_daylightfluorescent()
 src.set_axis_system([0, 10000, 50000, 1, 0, 0, 0, 1, 0, 0, 0, 1])
+
 src.commit()
 # -
 
 # ### Create a simulation
-
+#
 # More details on creating/editing simulation examples can be found in core examples.
 
-# +
 sim = p.create_simulation(name="Inverse.1", feature_type=SimulationInverse)
 sim.set_sensor_paths(["Camera.1"]).set_source_paths(["Luminaire.1"])
 sim.commit()
-# -
 
 # ## Run the simulation
-
+#
 # Simulation can be run using CPU via compute_CPU method or using GPU via compute_GPU method.
 
-# +
-sim.compute_CPU()  # run simulation in CPU
-# sim.compute_GPU()  # run simulation in GPU
-# -
+run_sim = sim.compute_GPU if USE_GPU else sim.compute_CPU
+run_sim()  # Run the simulation
 
 # ## Check and review result
-
+#
 # Open result (only windows)
 
-# +
 if os.name == "nt":
     from ansys.speos.core.workflow.open_result import open_result_image
 
     open_result_image(simulation_feature=sim, result_name="Camera.1.png")
-# -
-
 
 # ## Modify part
-
+#
 # Move the part via changing the axis_system of a part.
-
+#
 # axis_system is a list of 12 float values:
 # x, y, z,
 # x_vect_x, x_vect_y, x_vect_z,
 # y_vect_x, y_vect_y, y_vect_z,
 # z_vect_x, z_vect_y, z_vect_z.
 
-# +
 blue_car_sub_part = p.find(name="BlueCar", feature_type=Part.SubPart)[0]
 blue_car_sub_part.set_axis_system([2000, 0.0, 20000, 0.0, 0.0, -1.0, -1.0, 0.0, 0.0, 0.0, 1.0, 0.0])
 blue_car_sub_part.commit()
-# -
 
-# Re-run simulation with the modified part position
+# ## Re-run simulation with the modified part position
 
-# +
-sim.compute_CPU()
-# -
+run_sim()
 
 # Review result:
 
-# +
 if os.name == "nt":
     open_result_image(simulation_feature=sim, result_name="Camera.1.png")
-# -
 
 # ## Modify camera property
-
+#
 # Modify the camera, e.g. focal length to 10
 
-# +
 cam1 = p.find(name="Camera.1", feature_type=SensorCamera)[0]
 cam1.set_focal_length(value=10)
 cam1.commit()
-# -
 
 # Re-run the simulation and review result
 
-# +
-sim.compute_CPU()
+run_sim()
 if os.name == "nt":
     open_result_image(simulation_feature=sim, result_name="Camera.1.png")
-# -