Skip to content

Commit 404593c

Browse files
violinyanevviolinyanev
authored
Merge pull request #37 from bmwcarit/feature/add-traceplayer-guide-with-rctrace-file-format
add traceplayer user-guide and .rctrace file format
2 parents 283b779 + 69f208b commit 404593c

File tree

5 files changed

+366
-0
lines changed

5 files changed

+366
-0
lines changed

‎advanced/traceplayer/README.md

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
<!--
2+
SPDX-License-Identifier: MPL-2.0
3+
4+
This file is part of Ramses Composer
5+
(see https://github.com/COVESA/ramses-composer-docs).
6+
7+
This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
8+
If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
9+
-->
10+
11+
# TracePlayer
12+
13+
The Ramses Composer contains a built-in trace player, which allows to play back RaCo trace (.rctrace) files.
14+
Good applications of the TracePlayer include:
15+
* re-playing captured real-world traces to debug exotic issues
16+
* looping predefined sequence of scene states, for demos and scene validation purposes
17+
18+
## Basics
19+
20+
The TracePlayer has the usual playback features (Load, Play, Pause, Stop, toggle Loop mode, Step-forward/backward, and Jump-to).
21+
![](docs/traceplayer_notrace.png "TracePlayer - No Trace Loaded")
22+
23+
First, browse to a valid `.rctrace` file and load it using the 3-dots icon (*this article includes an [example](#example-g05oss) based on the BMW X5 example model*).
24+
![](docs/traceplayer_init.png "TracePlayer - Initial State").
25+
26+
The TracePlayer parses the `.rctrace` file, then updates properties of relevant Lua nodes sequentially in the scene based on their names. Therefore, you need to make sure to add the equivalent interface Lua scripts to the scene and match their names.
27+
Furthermore, **IN** interfaces of the Lua script have to match the same structure on the properties in the `.rctrace` file.
28+
29+
## The .rctrace File Format
30+
31+
The trace file is a JSON file and must contain an array of frames, where each frame is a JSON object containing two nested objects: "SceneData" and "TracePlayerData".
32+
**SceneData** can contain a list of features; those features are parsed and mapped by name by TracePlayer to the corresponding Lua nodes in the scene. The supported property types are boolean, integer, double, and strings.
33+
**TracePlayerData** must contain the timestamp of a frame in milliseconds.
34+
35+
This is how a valid trace can look like:
36+
37+
```json
38+
[
39+
{ // frame#1
40+
"SceneData" :
41+
{
42+
"Feature_1" : // TracePlayer will look the scene up for a Lua node with the name "Feature_1". It shall have IN interface structs named "Function_1" and "Function_2"
43+
{
44+
"Function_1" : // "Function_1" struct shall contain "active", "ranking", "speed", and "color" IN properties with equivalent types
45+
{
46+
"active" : true, // BOOL
47+
"ranking" : 7, // INT
48+
"speed" : 123.50, // FLOAT
49+
"color" : "blue" // STRING
50+
},
51+
"Function_2" :
52+
{
53+
"length" : 12.0,
54+
"width" : 5.50,
55+
}
56+
},
57+
"Feature_2" :
58+
{
59+
"Function_1" :
60+
{
61+
"class" : 3
62+
},
63+
"Function_2" :
64+
{
65+
"positionX" : 1.789,
66+
"positionY" : 45.887,
67+
}
68+
}
69+
},
70+
"TracePlayerData" :
71+
{
72+
"timestamp(ms)" : 1
73+
}
74+
},
75+
{ // frame#2
76+
"SceneData" :
77+
{
78+
/* list of features */
79+
},
80+
"TracePlayerData" :
81+
{
82+
"timestamp(ms)" : 2
83+
}
84+
},
85+
{ // frame#3
86+
"SceneData" :
87+
{
88+
/* list of features */
89+
},
90+
"TracePlayerData" :
91+
{
92+
"timestamp(ms)" : 3
93+
}
94+
}
95+
]
96+
```
97+
98+
## TracePlayerData
99+
100+
The TracePlayer offers the following property in the **TracePlayerData** object:
101+
- **timestamp_milli**: an integer of the playback actual time in milliseconds, which can be used as the reference timer for animation.
102+
103+
## Example (BMW X5)
104+
105+
This article includes a sample trace file based on the BMW X5 demo model. You can find it in the [traces folder](./traces).
106+
107+
Download the X5 project from its [repository](https://github.com/bmwcarit/digital-car-3d) and load the **G05_main.rca** file as documented in project README.
108+
Load and play the RaCo trace [g05_demo](traces/g05_demo.rctrace). Try changing the frame timestamps and properties to see how the playback changes in the Ramses Composer viewport.

‎advanced/traceplayer/docs/traceplayer_init.png

Lines changed: 3 additions & 0 deletions
Loading

‎advanced/traceplayer/docs/traceplayer_notrace.png

Lines changed: 3 additions & 0 deletions
Loading

‎advanced/traceplayer/traces/g05_demo.rctrace

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
[
2+
{
3+
"SceneData": {
4+
"SceneControls": {
5+
"CameraPerspective_ID": 1,
6+
"CarPaint_ID": 1,
7+
"Door_F_L_OpeningValue": 0.0,
8+
"Door_F_R_OpeningValue": 0.0,
9+
"Door_B_L_OpeningValue": 0.0,
10+
"Door_B_R_OpeningValue": 0.0,
11+
"Tailgate_OpeningValue": 0.0
12+
}
13+
},
14+
"TracePlayerData": {
15+
"timestamp(ms)": 1
16+
}
17+
},
18+
{
19+
"SceneData": {
20+
"SceneControls": {
21+
"CameraPerspective_ID": 1,
22+
"CarPaint_ID": 1
23+
}
24+
},
25+
"TracePlayerData": {
26+
"timestamp(ms)": 2
27+
}
28+
},
29+
{
30+
"SceneData": {
31+
"SceneControls": {
32+
"CarPaint_ID": 2
33+
}
34+
},
35+
"TracePlayerData": {
36+
"timestamp(ms)": 5001
37+
}
38+
},
39+
{
40+
"SceneData": {
41+
"SceneControls": {
42+
"CameraPerspective_ID": 2
43+
}
44+
},
45+
"TracePlayerData": {
46+
"timestamp(ms)": 10001
47+
}
48+
},
49+
{
50+
"SceneData": {
51+
"SceneControls": {
52+
"CarPaint_ID": 5
53+
}
54+
},
55+
"TracePlayerData": {
56+
"timestamp(ms)": 15001
57+
}
58+
},
59+
{
60+
"SceneData": {
61+
"SceneControls": {
62+
"CameraPerspective_ID": 3
63+
}
64+
},
65+
"TracePlayerData": {
66+
"timestamp(ms)": 20001
67+
}
68+
},
69+
{
70+
"SceneData": {
71+
"SceneControls": {
72+
"Door_F_L_OpeningValue": 1.0
73+
}
74+
},
75+
"TracePlayerData": {
76+
"timestamp(ms)": 23501
77+
}
78+
},
79+
{
80+
"SceneData": {
81+
"SceneControls": {
82+
"Door_F_R_OpeningValue": 1.0
83+
}
84+
},
85+
"TracePlayerData": {
86+
"timestamp(ms)": 24001
87+
}
88+
},
89+
{
90+
"SceneData": {
91+
"SceneControls": {
92+
"Door_B_L_OpeningValue": 1.0
93+
}
94+
},
95+
"TracePlayerData": {
96+
"timestamp(ms)": 24501
97+
}
98+
},
99+
{
100+
"SceneData": {
101+
"SceneControls": {
102+
"Door_B_R_OpeningValue": 1.0,
103+
"CarPaint_ID": 4
104+
}
105+
},
106+
"TracePlayerData": {
107+
"timestamp(ms)": 25001
108+
}
109+
},
110+
{
111+
"SceneData": {
112+
"SceneControls": {
113+
"CameraPerspective_ID": 4,
114+
"Door_F_L_OpeningValue": 0.0,
115+
"Door_F_R_OpeningValue": 0.0,
116+
"Door_B_L_OpeningValue": 0.0,
117+
"Door_B_R_OpeningValue": 0.0
118+
}
119+
},
120+
"TracePlayerData": {
121+
"timestamp(ms)": 30001
122+
}
123+
},
124+
{
125+
"SceneData": {
126+
"SceneControls": {
127+
"CarPaint_ID": 6
128+
}
129+
},
130+
"TracePlayerData": {
131+
"timestamp(ms)": 35001
132+
}
133+
},
134+
{
135+
"SceneData": {
136+
"SceneControls": {
137+
"CameraPerspective_ID": 5
138+
}
139+
},
140+
"TracePlayerData": {
141+
"timestamp(ms)": 40001
142+
}
143+
},
144+
{
145+
"SceneData": {
146+
"SceneControls": {
147+
"CarPaint_ID": 3
148+
}
149+
},
150+
"TracePlayerData": {
151+
"timestamp(ms)": 45001
152+
}
153+
},
154+
{
155+
"SceneData": {
156+
"SceneControls": {
157+
"CameraPerspective_ID": 6
158+
}
159+
},
160+
"TracePlayerData": {
161+
"timestamp(ms)": 50001
162+
}
163+
},
164+
{
165+
"SceneData": {
166+
"SceneControls": {
167+
"Tailgate_OpeningValue": 1.0
168+
}
169+
},
170+
"TracePlayerData": {
171+
"timestamp(ms)": 52501
172+
}
173+
},
174+
{
175+
"SceneData": {
176+
"SceneControls": {
177+
"Door_B_R_OpeningValue": 1.0
178+
}
179+
},
180+
"TracePlayerData": {
181+
"timestamp(ms)": 53501
182+
}
183+
},
184+
{
185+
"SceneData": {
186+
"SceneControls": {
187+
"Door_B_L_OpeningValue": 1.0
188+
}
189+
},
190+
"TracePlayerData": {
191+
"timestamp(ms)": 54001
192+
}
193+
},
194+
{
195+
"SceneData": {
196+
"SceneControls": {
197+
"Door_F_R_OpeningValue": 1.0
198+
}
199+
},
200+
"TracePlayerData": {
201+
"timestamp(ms)": 54501
202+
}
203+
},
204+
{
205+
"SceneData": {
206+
"SceneControls": {
207+
"Door_F_L_OpeningValue": 1.0,
208+
"CarPaint_ID": 7
209+
}
210+
},
211+
"TracePlayerData": {
212+
"timestamp(ms)": 55001
213+
}
214+
},
215+
{
216+
"SceneData": {
217+
"SceneControls": {
218+
"CameraPerspective_ID": 7,
219+
"Door_F_L_OpeningValue": 0.0,
220+
"Door_F_R_OpeningValue": 0.0,
221+
"Door_B_R_OpeningValue": 0.0,
222+
"Tailgate_OpeningValue": 0.0
223+
}
224+
},
225+
"TracePlayerData": {
226+
"timestamp(ms)": 60001
227+
}
228+
},
229+
{
230+
"SceneData": {
231+
"SceneControls": {
232+
"CarPaint_ID": 1,
233+
"Door_B_L_OpeningValue": 0.0
234+
}
235+
},
236+
"TracePlayerData": {
237+
"timestamp(ms)": 65001
238+
}
239+
},
240+
{
241+
"SceneData": {
242+
"SceneControls": {
243+
"CameraPerspective_ID": 1
244+
}
245+
},
246+
"TracePlayerData": {
247+
"timestamp(ms)": 70001
248+
}
249+
}
250+
]

‎readme.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,8 @@ your data.
5858

5959
[Best practices](./advanced/best_practices/README.md) - Suggests best practices for project structure.
6060

61+
[TracePlayer](./advanced/traceplayer/README.md) - Explains how to use TracePlayer, and the .rctrace file.
62+
6163
## Troubleshooting
6264

6365
[Versions](./debugging/versions/README.md) - Supported versions, API and ABI compatibility.

0 commit comments

Comments
 (0)