In this example, we will show you how to create a video from an animated scenario created in Speos. First, this article will introduce all the requirements needed to set up an animated scenario and, in a second time, explain how to perform easily and quickly thanks to a dedicated workflow relying on python automation. No skills in python/programming are required here, as the workflow has been designed to not interact with scripts directly. This article is relying on Timeline feature introduced in the following article : Speos Timeline Best Practices – Ansys Optics.
NOTES: Software Prerequisites
To be able to use this example, the following tools and assets need to be installed on your computer:
- Ansys Speos 2024 R2 or later.
- Python OpenCV (automatically installed during the workflow).
- Python 3.10 : no dedicated installation needed, as Speos 2024R2 embed a version of Python 3.10.
- For non admin Windows session users, please execute one time Virtual Photometric Lab 2024R2 as administrator (to allow Speos API to be called without problem).
Overview
Understand the simulation workflow and key results
The following YouTube shows two examples of videos based on timeline simulation with Speos :
- Usecase 1 : Trafic light LED Flickering
- Usecase 2 (at 0:28) : LED Pulse Width Modulation
Final Result Video
The article proposes an automotive use case, illustrating the effect of traffic light’s flickering on a front camera. If you're interested by the Pulse Width Modulation use case, please refer to this article. And how to create a video from simulation results.
Run and Results
Instructions for running the model and discussion for key results
Step 1 : Scene description
This is a minimalist scene where all 3D objects are imported through Lightbox formats. Two reasons justify this choice :
- Scene and scenario are considering a moving car geometry. This moving geometry capability is only possible with Lightbox feature. CAD geometries cannot be moved thanks to timeline's moving trajectory files.
- Scene is “meshing ready” for Speos simulation, so no time spent to mesh during simulation initialization. This is a good way to optimize the iteration loop for a video creation. In this case, we reduce as much as possible time wasted outside of computation time.
- Reduce the file size to ease its sharing.
This use case has a specific file/folder structure like illustrated in the picture below :
Special folder structure in END folder is linked to video creation workflow described in the last section of this article.
After opening START.scdocx or END.scdocx, 3D view should display these elements :
If it’s not the case, please follow these steps :
- go in Simulation > START > Components.
- Ctrl + click and select “Tunnel”, “Cross_Road” and “Ego_Car”.
- Right click and press compute.
The three Lightboxes are computed sequentially, and the following representation of 3D objects is displayed :
START model is composed of the following Speos elements :
END model is composed of the following Speos elements :
Step 2 : Set Up Moving objects
START project proposes you two types of objects to move : a car body (as Lightbox) and a camera model. We also provide predefined trajectories in the SPEOS input files folder. To better understand how a trajectory file is created, we recommend you to refer to Speos Timeline Best Practices – Ansys Optics.
To set up moving capacity of your Speos element, please follow the steps below :
For moving geometry :
- [Optional] Double-click on “Ego_Car”.
- In Trajectory file line browse and import “Trajectory_40kmh.json”.
- Once the trajectory file is imported, a line is visible in the 3D view :
For moving camera :
- Double-click on Camera.Car.
- In Trajectory file line browse and import “Cam_Trajectory_30kmh.json”.
- Once the trajectory file is imported, a line is visible in the 3D view :
Step 3 : Set up Light signal
There are three surface sources to edit in START project : RED_LED, ORANGE_LED and GREEN_LED. Each of these light sources will have a specific Flux variation file. In this example, the goal is to show LED flickering of a traffic light moving from green light to red one with a short transition with orange light. To better understand how timeline is working with surface source, we recommend you to follow the last section of Speos Timeline Best Practices – Ansys Optics.
How to apply flux variation file into Surface Source :
- Double-click on “Red_LED”.
- In Definition Tab, click in small gear icon on the top corner right to access “RED_LED” parameters.
- In Timeline > Flux variation file, import “LED_Red.json” available in Speos input files.
- These steps must be repeated for “Orange_LED” and “Green_LED” with, respectively, “LED_Orange.json” and “LED_Green.json”.
To get the effect for Light transition on traffic light, Flux variation file of red, orange and green lights must contain the same time base with an end synchronized with end of driving scenario.
When light source signal is not active, time stamps and signal values can be skipped by simply removing values between scenario start time (0s here) and time when light signal starts its activity :
{
"Time": [
0.0,
7.417,
7.5,
7.583,
…
],
"Relative_flux": [
0,
0,
0,
1,
…
]
}
Step 4 : Set up simulation
To perform a timeline simulation with a camera sensor, Inverse simulation is required with Timeline parameter set to “True” like displayed in the picture below :
Once activated, a new parameter pop up at the bottom of the simulation’s definition tab like in the picture below :
Start parameter determines when the timeline-related parameters are taken into account in the simulation.
For more information, you can refer to this Knowledge Based article link.
Step 5 : Set up video automation workflow
Now your model is correctly set up, it can be saved and closed. Speos can also be closed. Video workflow proposed in this article is relying on the following principle :
This workflow can be found on Ansys Optical-automation Github or in the dataset of this article, in the folder named "Video_Workflow_Template".
The process is split in two main blocks :
- The “back end” contains the processing files. This block relies on two python scripts : one for Speos execution and frame generation, and the other one for video creation thanks to images generated by the first script.
- The “front end” contains the input and execution files. Users execute the Batch file and provide workflow inputs in a configuration YAML file (.yml).
Users are not supposed to open .py files and edit them. This process is adapted for every kind of user, as there is no need to be familiar with Python to execute this process.
As introduced in the schema above, the process is relaying on several files but also has a folder structure. This structure is displayed in the picture below :
To work well, the process follows some rules :
- Project (Speos scdocx + associated inputs files and output files folders) data, used for the video creation, must be placed in “PROJECT” folder. If you use the “Timeline_Template” for the first time, the PROJECT folder is empty and needs to be fulfilled thanks to a copy/past operation, for example.
- Process inputs must be specified in “Animation_Inputs.yml” located in “SCRIPTS” folder.
- User should follow the template layout. This workflow is handling error management. If suitable data are not given by user, the process will not work as expected and can give incorrect result.
Use cases 1 & 2 END folders already contain the correct file template to perform video automation workflow.
Important Models Settings
Description of important objects and settings used in this model
Most important is making sure Timeline mode is activated in Inverse simulation before running your simulation. Otherwise trajectory and/or flux variation files will not be considered.
If your company doesn't grant you, by default, admin rights on your computer, make sure you can have them while you will run this workflow for the first time. Two reasons justify it :
- Process is doing operations on XMP maps. Which means Virtual Photometric Lab is called and opened through Python API command line. A prerequisite is required to allow this API call : run one time Virtual Photometric Lab as administrator on your computer. This action is needed just one time and then, user can perform the workflow on his classical session with limited admin rights.
- OpenCV installation. The installation is done automatically after first batch file execution. As this installation may require admin rights, we advise you to have these rights available during the first execution.
Updating the Model With Your Parameter
Instructions for updating the model based on your device parameters
For both examples, if you want to create your own trajectory or flux variation files, best is to duplicate files available in the example and modify values while keeping the file structure. If you want to create file from scratch, best is to follow this article : Speos Timeline Best Practices.
Taking the Model Further
Information and tips for users that want to further customize the model
Connect Speos Timeline video frames to SSS Exporter
If you want to go further you can even connect video frames generated outside this process to Speos Sensor System Exporter (SSS Exporter).
Before going further in this section, we recommend you to have a prior experience with SSS Exporter usage.
SSS Exporter has a specific mode which allows to create video as output. We propose an additional python script, named "Timeline_To_SSS.py" and placed, with other python scripts, in Video_Workflow_Template > SCRIPTS.
This process requires two inputs :
- Working directory folder : where all frames as stored as XMP format.
- XMP format can be set as true by setting as "Yes" the "Keep XMP" input parameter in Animation_Inputs.yml.
- SSS Exporter's Inputs.yaml file : Script will use the structure of this file to create another one including all video frames.
Inputs.yaml file should be set in 'Given Files' mode. Otherwise SSS Exporter video mode cannot be used.
As output, script provides a new yaml file with all frames listed in Given files.
Once this step is done. You can simply run the SSS Exporter with the new Inputs.yaml file generated and a video is generated in Output file folder.
- Line 10 : hard code the absolute path of your working directory containing all your xmp frames.
- Line 11: hard code the absolute path of your Input.yaml file.
- Line 46: hard code the absolute path of your new Input.yaml file (you can create one with a new name, to not erase one used as reference).
- Execute the script.
- Run the SSS Exporter.
- Video is generated in the Output folder.
Additional Resources
Additional documentation, examples and training material