Wiki source code of V2 Simulation Visualization

Version 7.1 by aas2 on 2017/08/17 14:26
Show last authors
1 = Visualize the Simulation State with an SVG Image =
2
3
4
5 {{toc/}}
6
7 == Overview ==
8
9 The Data Pool View shows all variables present in the simulation. However it can be difficult for humans to interpret the state of a model when having only a load of numbers and variables. The former KIELER Environment Visualization (KEV) had been developed to display the simulation state in a more pleasant way. Therefore KEV loaded an SVG image and could manipulate it to reflect the state of the simulation.
10
11 This approach has been developed further in KIELER Visualization (KiVis) to integrate with the new simulation. Furthermore a DSL for kivis files has been created to configure how the SVG image will be manipulated.
12
13 Besides displaying the state of the simulation, KiVis is also able to interact with the simulation, e.g., when an element in the simulation is clicked. Thus buttons in the SVG image can be created to set variables in the simulation, or to step, stop, play and pause the simulation.
14
15 == Creating an SVG Image ==
16
17 In this section the open-source vector graphics program **Inkscape** is used to illustrate how to create an SVG image that can be used with KiVis.
18
19 It is advisable to first set the document size. In Inkscape this is done under **File > Document Settings**. In the image below the size is set to 512x512 px. This setting defines the coordinate system of the file, which is useful when animating, e.g., movement later. Anyhow, SVG images can be scaled to any size.
20
21 (% class="confluence-embedded-file-wrapper confluence-embedded-manual-size" %)[[image:attach:Screenshot_20170411_223815.png]]
22
23 Afterwards three circles and a rectangle have to be created. The circles will simulate the red, green and yellow lights of a traffic light, and thus are colored accordingly. The rectangle will show the same information, but using different animations.
24
25 (% class="confluence-embedded-file-wrapper confluence-embedded-manual-size" %)[[image:attach:Screenshot_20170411_224717.png]]
26
27 After the elements of the image have been created, it is necessary to give elements that should be animated a unique name. This can be done in Inkscape by selecting the object and using **Right click > Object properties**. In the window that opens, an **id** can be set in the **first field** (the value without leading hash, labelled "Kennung" in german). Name the circles according to their color, **theRedOne**, **theYellowOne** and **theGreenOne**. The rectangle gets the id **theRect.**
28
29 Note that a new id has to be applied using the button in the object properties window!
30
31 (% class="confluence-embedded-file-wrapper confluence-embedded-manual-size" %)[[image:attach:Screenshot_20170411_225238.png]]
32
33 Finally, save the result as **Inkscape-SVG** (recommended) or **Normal-SVG** and name it **Lights.svg**.
34
35 === Groups and Layers ===
36
37 SVG is an XML format. Elements can be grouped and layers can be created which forms a hierarchy. When working with groups and layers in Inkscape, it can be useful to work with the XML-Editor (Ctlr+Shift+X).
38
39 === Flowed Text ===
40
41 In Inkscape it is possible to create a flowed text element, which is text that wraps its content inside a user defined area. However this is not a fully specified feature in SVG and thus not supported by many SVG viewers. For instance Gimp displays these elements as black box and Firefox does not display them at all.
42 KEV and the newer KiVis uses Apache Batik for SVG rendering, which also does not support flowed text. If you encounter issues with text object, try to convert them to simple text in Inkscape, via// Text > Convert to normal text//.
43
44 For more information see also the Inkscape FAQ for this topic: [[http:~~/~~/wiki.inkscape.org/wiki/index.php/Frequently_asked_questions#What_about_flowed_text.3F>>url:http://wiki.inkscape.org/wiki/index.php/Frequently_asked_questions#What_about_flowed_text.3F||shape="rect"]]
45
46 === Text Colors ===
47
48 Sadly the Batik SVG Renderer that is used in KIELER does not handle text colors as well as Inkscape does. When setting the fill color directly on a text element in Inkscape, it will not be displayed in the Simulation Visualization View. The text will be black.
49
50 However there is a simple workaround: Select the text objects that should be colored, group them (Ctrl + G), then set the fill color on this group. The child elements will inherit the color and (for whatever reason) this does also work in Batik.
51
52 == Creating a Configuration File ==
53
54 The configuration depends on the model to be simulated. In the following a simple kivis file is shown for the example model below.
55
56 {{code title="Example KiVis File"}}
57 image: "Lights.svg"
58
59 animate theRect {
60 apply color using showLight {
61 fillColor: 0 is "red", 1 is "yellow", 2 is "green"
62 }
63 }
64
65 animate theRedOne {
66 apply color using showLight {
67 opacity: 0 is 1, 1-2 is 0
68 }
69 }
70
71 animate theYellowOne {
72 apply color using showLight {
73 opacity: 0 is 0, 1 is 1, 2 is 0
74 }
75 }
76
77 animate theGreenOne {
78 apply color using showLight {
79 opacity: 0-1 is 0, 2 is 1
80 }
81 }
82
83
84 {{/code}}
85
86 This configuration will animate the **svg** **element** with the id **theRect**. The value of the** variable showLight** is used to determine the attributes of the **color animation**, in this case the **fillColor attribute** is set. The value 0 of showLight is mapped to the value "red" for the attribute, 1 is mapped to "yellow" and 2 is mapped to "green".
87
88 The animations of theRedOne / theYellowOne / theGreenOne is used to show this element (opacity is 1) when the showLight variable is 0 / 1 / 2 and to hide them otherwise (opacity is 0). This represents a very simple traffic light.
89
90 When writing a visualiation configuration, code completion can be used to show the available attributes of an animation. In the following the available animations are explained.
91
92 === Animation Handler Base Class ===
93
94 The attributes of this class are also available for all other animation handlers and provide generic features.
95
96 |=(((
97 Attribute
98 )))|=(((
99 Domain
100 )))|=(((
101 Description
102 )))
103 |(((
104 recursive
105 )))|(((
106 Boolean
107 )))|(((
108 Applies the animation to this element as well as all child elements recursively.
109
110 This might be useful, e.g., to set the opacity of an element and also in its children and their children.
111 However, in most cases this option is not required.
112 )))
113
114 \\
115
116 === Color Animation ===
117
118 It is used to change the appearance of elements. The fill color, stroke color and with as well as opacity can be changed.
119
120 (% class="relative-table wrapped" style="width: 70.6623%;" %)
121 |=(((
122 Attribute
123 )))|=(((
124 Domain
125 )))|=(((
126 Description
127 )))
128 |(((
129 fillColor
130 )))|(((
131 String, either a color name of predefined colors,
132 or a hexadecimal rgb color
133 )))|(((
134 Sets the fill color
135 )))
136 |(% colspan="1" %)(% colspan="1" %)
137 (((
138 fillOpacity
139 )))|(% colspan="1" %)(% colspan="1" %)
140 (((
141 Float, ranges from 0 (fully transparent) to 1 (fully visible)
142 )))|(% colspan="1" %)(% colspan="1" %)
143 (((
144 Sets the opacity of the filling
145 )))
146 |(% colspan="1" %)(% colspan="1" %)
147 (((
148 strokeColor
149 )))|(% colspan="1" %)(% colspan="1" %)
150 (((
151 Same as fillColor
152 )))|(% colspan="1" %)(% colspan="1" %)
153 (((
154 Sets the color of the outline / stroke
155 )))
156 |(% colspan="1" %)(% colspan="1" %)
157 (((
158 strokeOpacity
159 )))|(% colspan="1" %)(% colspan="1" %)
160 (((
161 Same as fillOpacity
162 )))|(% colspan="1" %)(% colspan="1" %)
163 (((
164 Sets the opacity of the outline / stroke
165 )))
166 |(% colspan="1" %)(% colspan="1" %)
167 (((
168 opacity
169 )))|(% colspan="1" %)(% colspan="1" %)
170 (((
171 Same as fillOpacity
172 )))|(% colspan="1" %)(% colspan="1" %)
173 (((
174 Sets the overall transparency
175 )))
176
177 === Text Animation ===
178
179 This animation can be used for text objects in the SVG to set the font and text.
180
181 (% class="relative-table wrapped" %)
182 |=(((
183 Attribute
184 )))|=(((
185 Domain
186 )))|=(((
187 Description
188 )))
189 |(((
190 text
191 )))|(((
192 String
193 )))|(((
194 Sets the text of the element
195 )))
196 |(% colspan="1" %)(% colspan="1" %)
197 (((
198 fontSize
199 )))|(% colspan="1" %)(% colspan="1" %)
200 (((
201 Integer
202 )))|(% colspan="1" %)(% colspan="1" %)
203 (((
204 Sets the size of the text element
205 )))
206 |(% colspan="1" %)(% colspan="1" %)
207 (((
208 fontFamily
209 )))|(% colspan="1" %)(% colspan="1" %)
210 (((
211 String, name of an installed font (e.g. "Arial Black" or "serif")
212 )))|(% colspan="1" %)(% colspan="1" %)
213 (((
214 Sets the font family
215 )))
216
217 === Move Animation ===
218
219 This animation changes the position of an SVG element relative to its original position.
220
221 (% class="relative-table wrapped" %)
222 |=(((
223 Attribute
224 )))|=(((
225 Domain
226 )))|=(((
227 Description
228 )))
229 |(((
230 x
231 )))|(((
232 Float
233 )))|(((
234 The x coordinate relative to the original position
235 )))
236 |(% colspan="1" %)(% colspan="1" %)
237 (((
238 y
239 )))|(% colspan="1" %)(% colspan="1" %)
240 (((
241 Float
242 )))|(% colspan="1" %)(% colspan="1" %)
243 (((
244 The y coordinate relative to the original position
245 )))
246
247 === Rotate Animation ===
248
249 This animation changes the rotation of elements.
250
251 (% class="relative-table wrapped" %)
252 |=(((
253 Attribute
254 )))|=(((
255 Domain
256 )))|=(((
257 Description
258 )))
259 |(((
260 angle
261 )))|(((
262 Integer
263 )))|(((
264 The angle in degrees that the object should be rotated
265 )))
266 |(% colspan="1" %)(% colspan="1" %)
267 (((
268 anchorX
269 )))|(% colspan="1" %)(% colspan="1" %)
270 (((
271 Float, 0 to 1
272 )))|(% colspan="1" %)(% colspan="1" %)
273 (((
274 Relative position inside the SVG element where the anchor point of the rotation will be.
275
276 0 is at the left side, 1 is at the right side. Default is 0.5, which is the middle.
277 )))
278 |(% colspan="1" %)(% colspan="1" %)
279 (((
280 anchorY
281 )))|(% colspan="1" %)(% colspan="1" %)
282 (((
283 Float, 0 to 1
284 )))|(% colspan="1" %)(% colspan="1" %)
285 (((
286 Relative position inside the SVG element where the anchor point of the rotation will be.
287
288 0 is at the top side, 1 is at the bottom side. Default is 0.5, which is the middle.
289 )))
290
291 === Walk Path Animation ===
292
293 This animation is used to position SVG elements on SVG paths. Therefore the start value of the path and the end value of the path have to be defined. The position is then interpolated linearly between start and end.
294
295 This is a powerful animation to position SVG elements, because the position can be drawn as path in the svg itself.
296
297 (% class="relative-table wrapped" %)
298 |=(((
299 Attribute
300 )))|=(((
301 Domain
302 )))|=(((
303 Description
304 )))
305 |(% colspan="1" %)(% colspan="1" %)
306 (((
307 name
308 )))|(% colspan="1" %)(% colspan="1" %)
309 (((
310 String
311 )))|(% colspan="1" %)(% colspan="1" %)
312 (((
313 The id of the path in the SVG image
314 )))
315 |(% colspan="1" %)(% colspan="1" %)
316 (((
317 start
318 )))|(% colspan="1" %)(% colspan="1" %)
319 (((
320 Float
321 )))|(% colspan="1" %)(% colspan="1" %)
322 (((
323 The start position of the path.
324
325 When the position value is the same as the value of this attribute, the object will be position at the beginning of the path.
326 )))
327 |(% colspan="1" %)(% colspan="1" %)
328 (((
329 end
330 )))|(% colspan="1" %)(% colspan="1" %)
331 (((
332 Float
333 )))|(% colspan="1" %)(% colspan="1" %)
334 (((
335 The end position of the path.
336
337 When the position value is the same as the value of this, the object will be position at the end of the path.
338 )))
339 |(% colspan="1" %)(% colspan="1" %)
340 (((
341 length
342 )))|(% colspan="1" %)(% colspan="1" %)
343 (((
344 Float
345 )))|(% colspan="1" %)(% colspan="1" %)
346 (((
347 The length of the path.
348
349 Can be used instead the absolute end position. In this case the end position is calculated as
350 end = start+length
351 )))
352 |(% colspan="1" %)(% colspan="1" %)
353 (((
354 position
355 )))|(% colspan="1" %)(% colspan="1" %)
356 (((
357 Float
358 )))|(% colspan="1" %)(% colspan="1" %)
359 (((
360 Used to set a fixed position on the path. Normally the position is taken from a variable in the simulation data pool, but it can also be set to a fixed value with this attribute.
361
362 The value should be between start and end of the path
363 )))
364 |(% colspan="1" %)(% colspan="1" %)
365 (((
366 autoOrientation
367 )))|(% colspan="1" %)(% colspan="1" %)
368 (((
369 Boolean, true / false
370 )))|(% colspan="1" %)(% colspan="1" %)
371 (((
372 Determines if the object should also align its rotation to the path
373 )))
374 |(% colspan="1" %)(% colspan="1" %)
375 (((
376 angleOffset
377 )))|(% colspan="1" %)(% colspan="1" %)
378 (((
379 Integer
380 )))|(% colspan="1" %)(% colspan="1" %)
381 (((
382 When autoOrientation is true, this offset in degrees is added to the calculated rotation on the path.
383
384 For example if the element is facing with in the wrong direction when it is walking the path, an offset of 180 can be used to turn it.
385 )))
386 |(((
387 angle
388 )))|(((
389 see rotate animation
390 )))|(((
391 see rotate animation
392 )))
393 |(% colspan="1" %)(% colspan="1" %)
394 (((
395 anchorX
396 )))|(% colspan="1" %)(% colspan="1" %)
397 (((
398 see rotate animation
399 )))|(% colspan="1" %)(% colspan="1" %)
400 (((
401 see rotate animation
402 )))
403 |(% colspan="1" %)(% colspan="1" %)
404 (((
405 anchorY
406 )))|(% colspan="1" %)(% colspan="1" %)
407 (((
408 see rotate animation
409 )))|(% colspan="1" %)(% colspan="1" %)
410 (((
411 see rotate animation
412 )))
413
414 === Interaction with the Simulation ===
415
416 It is also possible to interact with the visualization. For the image that has been created above, a simple interaction could be configured as follows:
417
418 {{code title="Interaction example"}}
419 image: "Lights.svg"
420
421 animate theRect {
422 apply color using showLight {
423 fillColor: 0 is "red", 1 is "yellow", 2 is "green"
424 } when showLight >= 1
425 }
426
427 perform on click from theRect {
428 showLight = 1
429 step simulation
430 } when showLight != 1
431 {{/code}}
432
433 This illustrates that animations and interactions can be used with the same SVG element, which is //theRect// in this case.
434
435 The interaction that is setup in this example is a click listener for theRect. If the element with this id is clicked, the variable showLight will be set to 1 and the simulation will perform a macro tick. However this is only done when the condition holds. Thus the simulation will not be stepped, if the showLight variable already has a value of 1.
436
437 === Example Model ===
438
439 Create an empty SCChart and fill it with the following content:
440
441 {{code language="sct"}}
442 scchart TrafficLight {
443 output int showLight
444
445 initial state init
446 go to init do showLight += 1; showLight = showLight % 3
447 }
448 {{/code}}
449
450 This model will set the variable **showLight** successively to 0, 1 and 2.
451
452 \\
453
454 see rotate animation

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage