How to modify scene elements#

This tutorial demonstrates how to modify a scene. For example how to modify an existing sensor, how to add a new sensor. The logic is the same to modify sources, simulations, materials.

Template vs Instance#

When applicable, the speos objects are separated in two different notions: template and instance. The template represents the feature with its inherent characteristics. The instance represents the completion of a template by adding properties such as spatial position, link to geometry, etc.

Template#

The template objects are handled by a manager. It was explained how to interact with them in the kernel-object-link example (“How to use an ObjectLink”). The interesting thing about the template notion is that the same template can be used several times with different properties.

Instance#

The template objects are instantiated in the Scene object, with properties needed to place them at the wanted position, or attached to the wanted geometry. The Scene object will gather all features that you need to run a job (compute a simulation).

[1]:

from pathlib import Path

from ansys.api.speos.sensor.v1 import camera_sensor_pb2
from ansys.speos.core import Speos
from ansys.speos.core.kernel.scene import ProtoScene
from ansys.speos.core.kernel.sensor_template import ProtoSensorTemplate

# 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")

Create connection with speos rpc server

[2]:

speos = Speos(host="localhost", port=50098)

Create an empty scene and load speos file to fill it.

[3]:

my_scene = speos.client.scenes().create()

speos_file = str(assets_data_path / "Inverse_SeveralSensors.speos" / "Inverse_SeveralSensors.speos")
my_scene.load_file(file_uri=speos_file)

Modify existing data#

Modify a camera instance#

[7]:

my_scene_data = my_scene.get()  # get() = retrieve datamodel corresponding to my_scene
camera_i_0 = my_scene_data.sensors[
    0
]  # retrieve the specific part of the message corresponding to the first sensor
assert camera_i_0.HasField("camera_properties")  # verify that it is a camera

# Modification on protobuf message : axis system + layer type
camera_i_0.camera_properties.ClearField("axis_system")
camera_i_0.camera_properties.axis_system.extend(
    [17.0, 10.0, 15.0] + [0.0, 0.0, -1.0] + [0.0, 1.0, 0.0] + [1.0, 0.0, 0.0]
)  # Origin + Xvector + Yvector + Zvector
camera_i_0.camera_properties.layer_type_none.SetInParent()

# Until now, we only modified the data locally. We need to push the changes to the server:
my_scene.set(my_scene_data)  # set = Update using modified datamodel

print(my_scene.get().sensors[0])  # Do another get() to check new value on database

ansys.api.speos.scene.v2.Scene.SensorInstance
{
    "name": "Camera.1:21",
    "sensor_guid": "13a2505c-2818-4331-be50-6f929eb00902",
    "result_file_name": "Inverse.1.Camera.1",
    "camera_properties": {
        "axis_system": [
            17.0,
            10.0,
            15.0,
            0.0,
            0.0,
            -1.0,
            0.0,
            1.0,
            0.0,
            1.0,
            0.0,
            0.0
        ],
        "layer_type_none": {},
        "trajectory_file_uri": ""
    },
    "description": "",
    "metadata": {}
}

Modify a camera template#

[8]:

new_distortion_file = str(
    assets_data_path / "CameraInputFiles" / "CameraDistortion_150deg.OPTDistortion"
)

# Retrieve SensorTemplateLink corresponding to camera_i_0.sensor_guid
camera_t_0 = speos.client[camera_i_0.sensor_guid]

# get() = retrieve datamodel corresponding to camera_t_0 from database
camera_t_0_data = camera_t_0.get()

# Modification on protobuf message : distortion_file_uri + focal_length
assert camera_t_0_data.HasField("camera_sensor_template")
camera_t_0_data.camera_sensor_template.distortion_file_uri = new_distortion_file
camera_t_0_data.camera_sensor_template.focal_length = 4.5

# set = Update using modified datamodel (push modified data to the server)
camera_t_0.set(camera_t_0_data)

print(camera_t_0)  # Print ObjectLink to see its datamodel in database

ansys.api.speos.sensor.v1.SensorTemplate
{
    "camera_sensor_template": {
        "sensor_mode_photometric": {
            "transmittance_file_uri": "/app/assets/Inverse_SeveralSensors.speos/CameraTransmittance_7906-9f99-c97d-838a..spectrum",
            "gamma_correction": 2.2,
            "color_mode_color": {
                "red_spectrum_file_uri": "/app/assets/Inverse_SeveralSensors.speos/CameraSensitivityRed_adf4-0b27-cefc-fa35..spectrum",
                "green_spectrum_file_uri": "/app/assets/Inverse_SeveralSensors.speos/CameraSensitivityGreen_7c86-e7df-6de8-cb15..spectrum",
                "blue_spectrum_file_uri": "/app/assets/Inverse_SeveralSensors.speos/CameraSensitivityBlue_8072-c4fe-d903-ca3f..spectrum",
                "balance_mode_none": {}
            },
            "wavelengths_range": {
                "w_start": 400.0,
                "w_end": 700.0,
                "w_sampling": 13
            },
            "acquisition_integration": 0.0,
            "acquisition_lag_time": 0.0,
            "png_bits": "PNG_08"
        },
        "focal_length": 4.5,
        "imager_distance": 10.0,
        "f_number": 30.0,
        "distorsion_file_uri": "/app/assets/Inverse_SeveralSensors.speos/CameraDistortion.OPTDistortion",
        "horz_pixel": 640,
        "vert_pixel": 480,
        "width": 5.0,
        "height": 5.0,
        "distortion_file_uri": "/app/assets/CameraInputFiles/CameraDistortion_150deg.OPTDistortion"
    },
    "name": "Camera.1:21",
    "description": "",
    "metadata": {}
}

Add new data (like a new sensor)#

Create a camera template#

[9]:

sensor_t_db = speos.client.sensor_templates()  # Retrieve access to sensor templates db

# Create protobuf message SensorTemplate
sensor_t_data = ProtoSensorTemplate(name="CameraFromScratch")
photometric = sensor_t_data.camera_sensor_template.sensor_mode_photometric
photometric.acquisition_integration = 0.01
photometric.acquisition_lag_time = 0
photometric.transmittance_file_uri = str(
    assets_data_path / "CameraInputFiles" / "CameraTransmittance.spectrum"
)
photometric.gamma_correction = 2.2
photometric.png_bits = camera_sensor_pb2.EnumSensorCameraPNGBits.PNG_16
photometric.color_mode_color.red_spectrum_file_uri = str(
    assets_data_path / "CameraInputFiles" / "CameraSensitivityRed.spectrum"
)
photometric.color_mode_color.green_spectrum_file_uri = str(
    assets_data_path / "CameraInputFiles" / "CameraSensitivityGreen.spectrum"
)
photometric.color_mode_color.blue_spectrum_file_uri = str(
    assets_data_path / "CameraInputFiles" / "CameraSensitivityBlue.spectrum"
)
photometric.color_mode_color.balance_mode_none.SetInParent()
photometric.wavelengths_range.w_start = 400
photometric.wavelengths_range.w_end = 700
photometric.wavelengths_range.w_sampling = 13
sensor_t_data.camera_sensor_template.focal_length = 5
sensor_t_data.camera_sensor_template.imager_distance = 10
sensor_t_data.camera_sensor_template.f_number = 20
sensor_t_data.camera_sensor_template.distortion_file_uri = str(
    assets_data_path / "CameraInputFiles" / "CameraDistortion_130deg.OPTDistortion"
)
sensor_t_data.camera_sensor_template.horz_pixel = 640
sensor_t_data.camera_sensor_template.vert_pixel = 480
sensor_t_data.camera_sensor_template.width = 5
sensor_t_data.camera_sensor_template.height = 5

# Store it in db and retrieve SensorTemplateLink
sensor_t_new = sensor_t_db.create(message=sensor_t_data)
print(sensor_t_new)

ansys.api.speos.sensor.v1.SensorTemplate
{
    "camera_sensor_template": {
        "sensor_mode_photometric": {
            "acquisition_integration": 0.01,
            "transmittance_file_uri": "/app/assets/CameraInputFiles/CameraTransmittance.spectrum",
            "gamma_correction": 2.2,
            "png_bits": "PNG_16",
            "color_mode_color": {
                "red_spectrum_file_uri": "/app/assets/CameraInputFiles/CameraSensitivityRed.spectrum",
                "green_spectrum_file_uri": "/app/assets/CameraInputFiles/CameraSensitivityGreen.spectrum",
                "blue_spectrum_file_uri": "/app/assets/CameraInputFiles/CameraSensitivityBlue.spectrum",
                "balance_mode_none": {}
            },
            "wavelengths_range": {
                "w_start": 400.0,
                "w_end": 700.0,
                "w_sampling": 13
            },
            "acquisition_lag_time": 0.0
        },
        "focal_length": 5.0,
        "imager_distance": 10.0,
        "f_number": 20.0,
        "horz_pixel": 640,
        "vert_pixel": 480,
        "width": 5.0,
        "height": 5.0,
        "distortion_file_uri": "/app/assets/CameraInputFiles/CameraDistortion_130deg.OPTDistortion",
        "distorsion_file_uri": ""
    },
    "name": "CameraFromScratch",
    "description": "",
    "metadata": {}
}

Create a camera instance#

[10]:

camera_i_2 = ProtoScene.SensorInstance(name=sensor_t_new.get().name + ".1")
# An instance has to reference a template - here we use the SensorTemplateLink's key that we got
camera_i_2.sensor_guid = sensor_t_new.key
# just above.
camera_i_2.camera_properties.axis_system.extend(
    [50, 50, 50, 1, 0, 0, 0, 1, 0, 0, 0, 1]
)  # Choose axis system
camera_i_2.camera_properties.layer_type_source.SetInParent()  # choose separation by source

Add this instance in our scene#

[11]:

my_scene_data = my_scene.get()  # Retrieve scene datamodel

# Modify scene datamodel to add our camera instance
my_scene_data.sensors.append(camera_i_2)

# We can also reference it in the first simulation, so that it will be taken into account by this
# simulation
my_scene_data.simulations[0].sensor_paths.append(camera_i_2.name)  # We reference by name

# Update value in db
my_scene.set(my_scene_data)

# Check scene data after update
print(my_scene)

ansys.api.speos.scene.v2.Scene
{
    "name": "Inverse_SeveralSensors",
    "description": "From /app/assets/Inverse_SeveralSensors.speos/Inverse_SeveralSensors.speos",
    "part_guid": "85dda74e-8a11-4807-b851-8bc939161655",
    "sources": [
        {
            "name": "Surface.1:1",
            "source_guid": "4ec12319-979e-459e-9249-e669ccbfb475",
            "surface_properties": {
                "exitance_constant_properties": {
                    "geo_paths": [
                        {
                            "geo_path": "Corps:2408912477/face.1:3892963602",
                            "reverse_normal": false
                        }
                    ]
                }
            },
            "description": "",
            "metadata": {}
        },
        {
            "name": "Surface.2:1",
            "source_guid": "a92f6bea-5c9e-4e3e-93cd-d65a3f180b39",
            "surface_properties": {
                "exitance_constant_properties": {
                    "geo_paths": [
                        {
                            "geo_path": "Corps:1976534910/face.1:889032133",
                            "reverse_normal": false
                        }
                    ]
                }
            },
            "description": "",
            "metadata": {}
        }
    ],
    "sensors": [
        {
            "name": "Camera.1:21",
            "sensor_guid": "13a2505c-2818-4331-be50-6f929eb00902",
            "result_file_name": "Inverse.1.Camera.1",
            "camera_properties": {
                "axis_system": [
                    17.0,
                    10.0,
                    15.0,
                    0.0,
                    0.0,
                    -1.0,
                    0.0,
                    1.0,
                    0.0,
                    1.0,
                    0.0,
                    0.0
                ],
                "layer_type_none": {},
                "trajectory_file_uri": ""
            },
            "description": "",
            "metadata": {}
        },
        {
            "name": "Irradiance.1:28",
            "sensor_guid": "a9dce6a8-cfb3-4c5c-aedf-53dc1baba08e",
            "result_file_name": "Inverse.1.Irradiance.1",
            "irradiance_properties": {
                "axis_system": [
                    0.0,
                    0.0,
                    0.0,
                    0.0,
                    0.0,
                    1.0,
                    0.0,
                    1.0,
                    -0.0,
                    -1.0,
                    0.0,
                    0.0
                ],
                "layer_type_sequence": {
                    "maximum_nb_of_sequence": 10,
                    "define_sequence_per": "Faces"
                },
                "ray_file_type": "RayFileNone",
                "integration_direction": []
            },
            "description": "",
            "metadata": {}
        },
        {
            "name": "CameraFromScratch.1",
            "sensor_guid": "e50bdc95-0ae0-43d8-aa2f-b5b4761ebff5",
            "camera_properties": {
                "axis_system": [
                    50.0,
                    50.0,
                    50.0,
                    1.0,
                    0.0,
                    0.0,
                    0.0,
                    1.0,
                    0.0,
                    0.0,
                    0.0,
                    1.0
                ],
                "layer_type_source": {},
                "trajectory_file_uri": ""
            },
            "description": "",
            "metadata": {},
            "result_file_name": ""
        }
    ],
    "simulations": [
        {
            "name": "Inverse.1",
            "simulation_guid": "0a6dd2f5-f81a-433f-94e1-97e8f9545809",
            "sensor_paths": [
                "Camera.1:21",
                "Irradiance.1:28",
                "CameraFromScratch.1"
            ],
            "source_paths": [
                "Surface.1:1",
                "Surface.2:1"
            ],
            "description": "",
            "metadata": {}
        }
    ],
    "materials": [
        {
            "name": "Material.1",
            "vop_guid": "6e0d2822-24d5-4c46-adc5-a791078f69dd",
            "sop_guids": [
                "0f8e2ef4-6d8d-4610-bf6d-f7aa9bc80807"
            ],
            "geometries": {
                "geo_paths": [
                    "Corps:2408912477",
                    "Corps:1976534910"
                ]
            },
            "description": "",
            "metadata": {}
        },
        {
            "name": "Material.2",
            "vop_guid": "b0343b92-6365-4453-b880-73e071a09504",
            "description": "",
            "metadata": {},
            "sop_guids": []
        }
    ],
    "metadata": {},
    "scenes": []
}

When loading a speos file into a scene, this creates many objects (source templates, sensor templates, vop template, sop templates). Then at the end of the example, we just clean all databases

[12]:

for item in (
    speos.client.scenes().list()
    + speos.client.simulation_templates().list()
    + speos.client.sensor_templates().list()
    + speos.client.source_templates().list()
    + speos.client.intensity_templates().list()
    + speos.client.spectrums().list()
    + speos.client.vop_templates().list()
    + speos.client.sop_templates().list()
    + speos.client.parts().list()
    + speos.client.bodies().list()
    + speos.client.faces().list()
):
    item.delete()