Speos Timeline Best Practices

Since the release 2021R2, Speos can manage simulation including time dimension. Up to now, this aspect was only applied to Systems sensors: LiDAR and Camera. With 2024R2, this concept has also been extended to light sources by defining a timeline input into Surface Source. The following article will give you useful information on how to use timeline features for system sensors and light sources.

Overview

Understand the simulation workflow and key results

Trajectory for moving geometries

Understand how to set up a moving geometry in Speos.

To simulate motion blur and rolling shutter effects realistically, objects movements must be considered. This includes to understand the motion of objects within the scene, their velocities, trajectories, and how they interact with light and the sensor.

Moving objects are modeled in the scene through the Speos LightBox feature. This type of Speos object can have a Trajectory assigned.

Speos Lightbox is a container: it stores meshed geometries and light sources in relative XYZ coordinates. It is a specific binary format only readable by Speos. This container can also be protected by a password and/or black boxed.

How to manage Lightbox

There are two options for the Lightbox feature:

Export Speos Lightbox allows converting CAD geometries into Lightbox meshed bodies. In case those geometries must be shared with confidentiality, a password protection can be added. File generated as output has the .SPEOSLightBox extension.

Import Speos Lightbox allows importing LightBox files into Speos model. In case the file is protected by a password, there is a special password field in the Definition tab to fulfill, in order to access meshed geometries.

Steps to complete to have moving geometries:

Go in Light Simulation ribbon > Component tab > LightBox > Export Speos Lightbox .
An Lightbox export item is created in the Speos tree under Component node.
Select origin point and orientation axis systems.
Select geometries.
[Optional] Select light sources.
Press right click on Export Lightbox item > Options to access to Speos meshing parameters.
Press “Compute” icon in the 3D view (or right click and compute).
A .SPEOSLightBox is generated in the project’s output file.

Note: Export Lightbox feature can manage more than one CAD geometry to convert. We recommend you to only adding geometries linked to one object. For example, if the object to move is a car, composed of wheel, body and doors geometries, all these geometries can be grouped into a single Lightbox. In the case of multiple cars, we recommend having separate LightBoxes at the end: one per car.

The following image illustrates the process shared just above.

Create an “Import Speos Lightbox”.
Import .SPEOSLightBox generated in the previous "Export Lightbox" operation.
Define origin axis system.
[Mandatory for moving object] Import a JSON trajectory file.
- JSON trajectory file generation is described in the next section How to generate and manage trajectory file.
Press "Compute".
In Simulation tree > Components node > Import Light Box, all meshed corps are listed and can be selected as geometry for a Speos simulation.

Note: It is recommended to select the Axis which corresponds to the position where the object will start its movement. A new axis system can be generated if necessary.

The following image illustrates the process shared just above.

How to generate and manage trajectory file

To generate a trajectory curve, there are two main steps:

Create a trajectory CAD spline.
Create a JSON file containing trajectory coordinates and object speed.

JSON files are generated thanks to a Python script found here.

Create a Trajectory spline.

Go into Sketch mode.
Select «Spline» tool.
In “Option Selection” make sure “Auto-merge” is not activated.
Make sure to draw a lot of points: it will be easier to adjust the spline after.
- Points have no link to object speed/acceleration.
Once the Spline is created, we recommend moving it to a “Trajectory” component, especially created to store all trajectory curves.
And rename it with a distinctive name.

Note: A Spline can be modified afterward with “Move” tool found in “Design” Tab.

Create a JSON trajectory file.

Open “Script” in “Design” Tab
Copy and paste Python script available in Ansys Documentation into Script Editor.
Be sure to well comment all lines from the header – to comment multiple lines at the same time, please use “Crtl + k” keyboard shortcut.
Also be sure script can find your correct installation bin folder path - in case of standard installation, it’s only v2XX to change, v241 = 2024R1.
Save as “Trajectory.py”
Run the script.
1. Script asks several inputs described in the table bellow:
  - Type of input
    Illustration
    
    In 3D :
    
    Spline
    
    Reference coordinate
    
    In Input Tab :
    
    Trajectory name
    
    Timeline frame rate
    
    Object Speed
    
    Reverse direction
2. Script will run for each position, and you can follow the progression by looking at 3D view. Coordinate system should be moving.
3. The output of the script is a .json file.
4. It is saved in the project folder.
5. JSON file is composed of timestamp with coordinate system position and orientation along the trajectory. More details can be found here.

The text block just bellow, describe the trajectory JSON file structure generated by the script :

{
    "Trajectory": [
        {
            "Time": T1,                 #in s
            "Origin": {
                "X": X1,                #in mm
                "Y": Y1,
                "Z": Z1
            },
            "Direction_X": {
                "X": X2,
                "Y": Y2,
                "Z": Z2
            },
            "Direction_Y": {
                "X": X3,
                "Y": Y3,
                "Z": Z3
            }
        },
        {
            "Time": T2,
            "Origin": {
                "X": X4,
                "Y": Y4,
                "Z": Z4
            },
            "Direction_X": {
                "X": X5,
                "Y": Y5,
                "Z": Z5
            },
            "Direction_Y": {
                "X": X6,
                "Y": Y6,
                "Z": Z6
            }
        },
        …
        }
    ],
    "VersionsDictionary": [
        {
            "Name": "DAxisSystemTrajectory\u0000",
            "Id": ID1,
            "Version": 1
        },
        {
            "Name": "DAxisSystemData\u0000",
            "Id": ID2,
            "Version": 1
        }
    ]
}

Link trajectory JSON file to moving object:

Edit the Imported Lightbox you want to move, as described in How to manage Lightbox section .
In “Trajectory file” import the .json file.
- Make sure axis system directions applied on the moving object are the same as the one used for spline generation. Otherwise, the Lightbox's trajectory will move the meshed body in a wrong direction.

Trajectory JSON file has a beginning and an end, contrary to JSON for light source (as described in the section Surface Source Model). Moved Lightbox will stop its movement at the last time stamp position registered in the JSON file. If the animated scenario is running longer, Lightbox will be "blocked" at the last known position of its trajectory.

Timeline with System Sensors

Understand how to set up a sensor model considering temporal aspect

LiDAR model and simulation

LiDAR considers the temporal aspect with its Rotating and Scanning types. Both types require, as input, scanning and rotating sequence files which manage Transceiver (Tx) beam orientation over the time.

LiDAR Scanning and Rotating models can also be moved over time in Speos simulation, like Lightbox geometries, by linking, as input parameter, a JSON trajectory file. The picture below shows you where the input parameter is located in LiDAR model definition.

LiDAR simulation, found in Light Simulation > Simulations > System, contains a Timeline feature. Once activated, it gives access to a Start and an End time.

These two time tables are linked to firing sequences (scanning and rotating ones) and a Trajectory file applied to LiDAR sensor model. More details can be found here.

Note : LiDAR (Timeline or not) simulation is compatible with CPU and HPC.

Camera model and simulation

As for LiDAR model, Camera also considers time at two levels: in the model and in the simulation definition.

Camera Model, found in Light Simulation > Sensors > System, considers as input the Integration and Lag Time defined in seconds.

Camera sensor models can also be moved over time in Speos simulation, like Lightbox geometries, by linking, as input parameter, a trajectory .json file.

Note : To perform a timeline simulation, you must have, at least, non null Camera's Integration parameter.

Inverse simulation, used for Camera sensor and found in Light Simulation > Simulations, contains a Timeline feature. Once activated, it gives access to a Start time. More information can be found in this documentation section.

Note : Inverse Timeline simulation is compatible with CPU, GPU and HPC.

Timeline with Light source

Understand how to set up a light source model considering temporal aspect

Surface Source Model

Surface Source benefits of a Timeline feature, starting from 2024R2 release. Surface Source’s flux can vary over time following a custom pattern. This pattern is composed of discrete values embedded into a JSON file format. Be careful, JSON file format used as input for Surface Source is not the same as JSON file used for moving geometries. The structure of the JSON file used for Surface Source is detailed at the bottom of the 7.3.3.2. Understanding the Surface Source Parameters documentation section page.

JSON file can be generated in several ways:

Manually: By editing directly JSON file or using excel to format the data first, and do a copy past after. JSON file can be fed by hand as the structure is quite easy to handle. The following image illustrates how the file is structured.
Scripting: By creating a JSON file from various inputs. Speos user guide provides an example of a script to help to understand how to set up a script for signal generation. This example has to be launched into Speos interface as it is relying on Speos Graphical User Interface APIs. Bellow a table detailing the inputs needed :

Time duration in second
Frequency in hertz
Relative modulation factor (no unit)
Path of the JSON file output
JSON file name

To ease the understanding of Surface Source's Timeline feature, let's take an example : we would like to implement a rectangular pattern like following :

Surface source timeline is cyclic, which means the period contained into the JSON file will be looped and repeated over and over. So, no need to generate the complete time frame, the picture billow illustrates this concept.

How to set up Timeline parameters in Surface Source:

Generate a Surface Source.
In Definition > Options > Timeline.
Import .json file created following previous recommendations/guidance.

Surface source timeline is compatible with Inverse Simulation Timeline only.

Additional resources

Additional documentation, examples and training material

Ansys Speos Documentation 2024R2 and beyond

Related publications

Reference and related publication format:

Type of input	Illustration
In 3D :
Spline Reference coordinate
In Input Tab :
Trajectory name Timeline frame rate Object Speed Reverse direction