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 generic example, illustrating the effect of Pulse Width Modulation of light sources on a camera. If you're interested by the automotive use case focusing on trafic light flickering, 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 use case is focusing on light source's flux variation. So there is no moving sensor or moving object here. Speos scene is basic : a camera sensor is pointing a panel composed of several surface sources defined with different Pulse Wave Modulation (PWM).
These modulations are varying between 5, 10, 25 and 50 Hertz with a duty cycle varying between 25%, 50% and 75% like illustrated on the following image :
All flux variation files used in this example have been generated in Excel. This excel can be found in the "START" folder of the shared dataset. Excel file is composed of several spreadsheets : each of them correspond to a specific signal creation. Each spreadsheet is structured like following :
This way to do, in Excel, is just an example and can be adapted for your own needs. Also, there is no limitation in the way to define a signal. As long as your signal can be sampled with a given time stamp and the appropriate data format, any signal can be rectangle, triangle, sine, cosine or anything else more custom.
Another method based on script is described in the following article Speos Timeline Best Practices > Timeline with Light source section.
This example follows a specific file/folder structure as described in the picture below :
A special folder structure in END folder is linked to video creation workflow described in the last section of this article.
Step 2 : Set up Light signal
How to apply flux variation file into Surface Source :
- Double-click on “50Hz_Duty_75_Rectangle”.
- In Definition Tab, click in small gear icon on the top corner right to access “RED_LED” parameters.
- In Timeline > Flux variation file, import “50Hz_Duty_75_Rectangle.json” available in Speos input files.
- Repeat the operation of each surface source defined in the Speos tree.
- Note that light sources are divided in two main folders : 1 for rectangle PWM and 1 for Cosine PWM. There is, as optional, an extra third folder for triangle PWM.
To get the effect of 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.
Step 3 : 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 4 : 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.
UC1 & 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