Last modified by Richard Kreissig on 2023/09/14 11:08
Show last authors
1 == Deprecated since 0.14 ==
2 This article is deprecated. The described features are no longer available in current releases.
3
4
5 {{info title="Version 0.13 RC1"}}
6 This page is part of the SCCharts Editor 0.13 RC1 documentation. This page is still under construction. We are still in the process of creating the release candidate. Please excuse any missing or incomplete entry. We apologize for any inconvenience.
7 {{/info}}
8
9 = Visualize the Simulation State with an SVG Image =
10
11
12
13 {{toc/}}
14
15 == Overview ==
16
17 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.
18
19 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.
20
21 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.
22
23 == Creating an SVG Image ==
24
25 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.
26
27 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.
28
29 (% class="confluence-embedded-file-wrapper confluence-embedded-manual-size" %)[[image:attach:Screenshot_20170411_223815.png]]
30
31 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.
32
33 (% class="confluence-embedded-file-wrapper confluence-embedded-manual-size" %)[[image:attach:Screenshot_20170411_224717.png]]
34
35 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.**
36
37 Note that a new id has to be applied using the button in the object properties window!
38
39 (% class="confluence-embedded-file-wrapper confluence-embedded-manual-size" %)[[image:attach:Screenshot_20170411_225238.png]]
40
41 Finally, save the result as **Inkscape-SVG** (recommended) or **Normal-SVG** and name it **Lights.svg**.
42
43 === Groups and Layers ===
44
45 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).
46
47 === Flowed Text ===
48
49 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.
50 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//.
51
52 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"]]
53
54 === Text Colors ===
55
56 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.
57
58 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.
59
60 == Creating a Configuration File ==
61
62 The configuration depends on the model to be simulated. In the following a simple kivis file is shown for the example model below.
63
64 {{code title="Example KiVis File"}}
65 image: "Lights.svg"
66
67 animate theRect {
68 apply color using showLight {
69 fillColor: 0 is "red", 1 is "yellow", 2 is "green"
70 }
71 }
72
73 animate theRedOne {
74 apply color using showLight {
75 opacity: 0 is 1, 1-2 is 0
76 }
77 }
78
79 animate theYellowOne {
80 apply color using showLight {
81 opacity: 0 is 0, 1 is 1, 2 is 0
82 }
83 }
84
85 animate theGreenOne {
86 apply color using showLight {
87 opacity: 0-1 is 0, 2 is 1
88 }
89 }
90
91
92 {{/code}}
93
94 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".
95
96 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.
97
98 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.
99
100 === Animation Handler Base Class ===
101
102 The attributes of this class are also available for all other animation handlers and provide generic features.
103
104 (% class="wrapped" %)
105 |=(((
106 Attribute
107 )))|=(((
108 Domain
109 )))|=(((
110 Description
111 )))
112 |(((
113 recursive
114 )))|(((
115 Boolean
116 )))|(((
117 Applies the animation to this element as well as all child elements recursively.
118
119 This might be useful, e.g., to set the opacity of an element and also in its children and their children.
120 However, in most cases this option is not required.
121 )))
122
123
124 === Color Animation ===
125
126 It is used to change the appearance of elements. The fill color, stroke color and with as well as opacity can be changed.
127
128 (% class="relative-table wrapped" style="width:70.6623%" %)
129 |=(((
130 Attribute
131 )))|=(((
132 Domain
133 )))|=(((
134 Description
135 )))
136 |(((
137 fillColor
138 )))|(((
139 String, either a color name of predefined colors,
140 or a hexadecimal rgb color
141 )))|(((
142 Sets the fill color
143 )))
144 |(% colspan="1" %)(% colspan="1" %)
145 (((
146 fillOpacity
147 )))|(% colspan="1" %)(% colspan="1" %)
148 (((
149 Float, ranges from 0 (fully transparent) to 1 (fully visible)
150 )))|(% colspan="1" %)(% colspan="1" %)
151 (((
152 Sets the opacity of the filling
153 )))
154 |(% colspan="1" %)(% colspan="1" %)
155 (((
156 strokeColor
157 )))|(% colspan="1" %)(% colspan="1" %)
158 (((
159 Same as fillColor
160 )))|(% colspan="1" %)(% colspan="1" %)
161 (((
162 Sets the color of the outline / stroke
163 )))
164 |(% colspan="1" %)(% colspan="1" %)
165 (((
166 strokeOpacity
167 )))|(% colspan="1" %)(% colspan="1" %)
168 (((
169 Same as fillOpacity
170 )))|(% colspan="1" %)(% colspan="1" %)
171 (((
172 Sets the opacity of the outline / stroke
173 )))
174 |(% colspan="1" %)(% colspan="1" %)
175 (((
176 opacity
177 )))|(% colspan="1" %)(% colspan="1" %)
178 (((
179 Same as fillOpacity
180 )))|(% colspan="1" %)(% colspan="1" %)
181 (((
182 Sets the overall transparency
183 )))
184
185 === Text Animation ===
186
187 This animation can be used for text objects in the SVG to set the font and text.
188
189 (% class="relative-table wrapped" %)
190 |=(((
191 Attribute
192 )))|=(((
193 Domain
194 )))|=(((
195 Description
196 )))
197 |(((
198 text
199 )))|(((
200 String
201 )))|(((
202 Sets the text of the element
203 )))
204 |(% colspan="1" %)(% colspan="1" %)
205 (((
206 fontSize
207 )))|(% colspan="1" %)(% colspan="1" %)
208 (((
209 Integer
210 )))|(% colspan="1" %)(% colspan="1" %)
211 (((
212 Sets the size of the text element
213 )))
214 |(% colspan="1" %)(% colspan="1" %)
215 (((
216 fontFamily
217 )))|(% colspan="1" %)(% colspan="1" %)
218 (((
219 String, name of an installed font (e.g. "Arial Black" or "serif")
220 )))|(% colspan="1" %)(% colspan="1" %)
221 (((
222 Sets the font family
223 )))
224
225 === Move Animation ===
226
227 This animation changes the position of an SVG element.
228
229 (% class="relative-table wrapped" %)
230 |=(((
231 Attribute
232 )))|=(((
233 Domain
234 )))|=(((
235 Description
236 )))
237 |(((
238 x
239 )))|(((
240 Float
241 )))|(((
242 The x coordinate relative to the original position
243 )))
244 |(% colspan="1" %)(% colspan="1" %)
245 (((
246 y
247 )))|(% colspan="1" %)(% colspan="1" %)
248 (((
249 Float
250 )))|(% colspan="1" %)(% colspan="1" %)
251 (((
252 The y coordinate relative to the original position
253 )))
254 |(% colspan="1" %)(% colspan="1" %)
255 (((
256 absolute
257 )))|(% colspan="1" %)(% colspan="1" %)
258 (((
259 Boolean
260 )))|(% colspan="1" %)(% colspan="1" %)
261 (((
262 Determines if the given position is absolute or relative to the element's original position
263 )))
264
265 === Rotate Animation ===
266
267 This animation changes the rotation of elements.
268
269 (% class="relative-table wrapped" %)
270 |=(((
271 Attribute
272 )))|=(((
273 Domain
274 )))|=(((
275 Description
276 )))
277 |(((
278 angle
279 )))|(((
280 Integer
281 )))|(((
282 The angle in degrees that the object should be rotated
283 )))
284 |(% colspan="1" %)(% colspan="1" %)
285 (((
286 anchorX
287 )))|(% colspan="1" %)(% colspan="1" %)
288 (((
289 Float, 0 to 1
290 )))|(% colspan="1" %)(% colspan="1" %)
291 (((
292 Relative position inside the SVG element where the anchor point of the rotation will be.
293
294 0 is at the left side, 1 is at the right side. Default is 0.5, which is the middle.
295 )))
296 |(% colspan="1" %)(% colspan="1" %)
297 (((
298 anchorY
299 )))|(% colspan="1" %)(% colspan="1" %)
300 (((
301 Float, 0 to 1
302 )))|(% colspan="1" %)(% colspan="1" %)
303 (((
304 Relative position inside the SVG element where the anchor point of the rotation will be.
305
306 0 is at the top side, 1 is at the bottom side. Default is 0.5, which is the middle.
307 )))
308
309 === Walk Path Animation ===
310
311 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.
312
313 This is a powerful animation to position SVG elements, because the position can be drawn as path in the svg itself.
314
315 (% class="relative-table wrapped" %)
316 |=(((
317 Attribute
318 )))|=(((
319 Domain
320 )))|=(((
321 Description
322 )))
323 |(% colspan="1" %)(% colspan="1" %)
324 (((
325 name
326 )))|(% colspan="1" %)(% colspan="1" %)
327 (((
328 String
329 )))|(% colspan="1" %)(% colspan="1" %)
330 (((
331 The id of the path in the SVG image
332 )))
333 |(% colspan="1" %)(% colspan="1" %)
334 (((
335 start
336 )))|(% colspan="1" %)(% colspan="1" %)
337 (((
338 Float
339 )))|(% colspan="1" %)(% colspan="1" %)
340 (((
341 The start position of the path.
342
343 When the position value is the same as the value of this attribute, the object will be position at the beginning of the path.
344 )))
345 |(% colspan="1" %)(% colspan="1" %)
346 (((
347 end
348 )))|(% colspan="1" %)(% colspan="1" %)
349 (((
350 Float
351 )))|(% colspan="1" %)(% colspan="1" %)
352 (((
353 The end position of the path.
354
355 When the position value is the same as the value of this, the object will be position at the end of the path.
356 )))
357 |(% colspan="1" %)(% colspan="1" %)
358 (((
359 length
360 )))|(% colspan="1" %)(% colspan="1" %)
361 (((
362 Float
363 )))|(% colspan="1" %)(% colspan="1" %)
364 (((
365 The length of the path.
366
367 Can be used instead the absolute end position. In this case the end position is calculated as
368 end = start+length
369 )))
370 |(% colspan="1" %)(% colspan="1" %)
371 (((
372 position
373 )))|(% colspan="1" %)(% colspan="1" %)
374 (((
375 Float
376 )))|(% colspan="1" %)(% colspan="1" %)
377 (((
378 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.
379
380 The value should be between start and end of the path
381 )))
382 |(% colspan="1" %)(% colspan="1" %)
383 (((
384 autoOrientation
385 )))|(% colspan="1" %)(% colspan="1" %)
386 (((
387 Boolean, true / false
388 )))|(% colspan="1" %)(% colspan="1" %)
389 (((
390 Determines if the object should also align its rotation to the path
391 )))
392 |(% colspan="1" %)(% colspan="1" %)
393 (((
394 angleOffset
395 )))|(% colspan="1" %)(% colspan="1" %)
396 (((
397 Integer
398 )))|(% colspan="1" %)(% colspan="1" %)
399 (((
400 When autoOrientation is true, this offset in degrees is added to the calculated rotation on the path.
401
402 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.
403 )))
404 |(((
405 angle
406 )))|(((
407 see rotate animation
408 )))|(((
409 see rotate animation
410 )))
411 |(% colspan="1" %)(% colspan="1" %)
412 (((
413 anchorX
414 )))|(% colspan="1" %)(% colspan="1" %)
415 (((
416 see rotate animation
417 )))|(% colspan="1" %)(% colspan="1" %)
418 (((
419 see rotate animation
420 )))
421 |(% colspan="1" %)(% colspan="1" %)
422 (((
423 anchorY
424 )))|(% colspan="1" %)(% colspan="1" %)
425 (((
426 see rotate animation
427 )))|(% colspan="1" %)(% colspan="1" %)
428 (((
429 see rotate animation
430 )))
431
432 === Attribute Values ===
433
434 Attributes can be set to a single constant value, a single variable in the simulation or using a more complex mapping from variable values to attribute values as shown in the example below.
435
436 {{code}}
437 image: "Lights.svg"
438
439 animate theRect {
440 apply color using showLight {
441 stroke-color: 0 is "green", 1 is "blue", 2 is "orange" // The attribute is set depending on the value of the variable in the using declaration
442 stroke-opacity: 0-2 is 1-20 // The attribute is set depending on the value of the variable in the using declaration and mapped linearly to the target domain
443 stroke-width: showLight // The attribute is set to the value of a variable in the pool
444 fillColor: "red" // The attribute is set to a constant value
445  } if showLight >= 1
446 }
447 {{/code}}
448
449 There are two keywords for mapping variable values to target values: **others** is used to match all other variable values that are not specified and define a target value for these. **value** refers to the current value of the variable in the using declaration.
450
451 {{code}}
452 image: "Lights.svg"
453
454 animate theRect {
455 apply color using showLight {
456 stroke-width: value // Set the attribute to the current value of the variable
457 stroke-color: 0 is "red", others is "orange" // Define a target value for all other cases
458 opacity: 0-1 is value, others is 0.5 // More complex example that uses both keywords
459 }
460 }
461 {{/code}}
462
463 === Interaction with the Simulation ===
464
465 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:
466
467 {{code title="Interaction example"}}
468 image: "Lights.svg"
469
470 animate theRect {
471 apply color using showLight {
472 fillColor: 0 is "red", 1 is "yellow", 2 is "green"
473 } if showLight >= 1
474 }
475
476 perform on click from theRect {
477 showLight = 1
478 step simulation
479 } if showLight != 1
480 {{/code}}
481
482 This illustrates that animations and interactions can be used with the same SVG element, which is //theRect// in this case.
483
484 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.
485
486 ==== Color Functions ====
487
488 There are also pre-defined functions to interact with the visualization environment. In the following example the variables **color, a, r, g** and **b** are set to the corresponding color values of the pixel on position **x** and **y** in the svg image. The pixel position is determined by the document size of the svg, which can be defined for example in Inkscape (//File > Document Properties//).
489
490 {{code}}
491 image: "image.svg"
492
493 // Get the color of the pixel at position (x, y)
494 perform {
495 color = getColor(x, y)
496 a = getAlpha(x, y)
497 r = getRed(x, y)
498 g = getGreen(x, y)
499 b = getBlue(x, y)
500 }
501
502 // Illustrate the position by moving an svg element there
503 animate theDot {
504 apply move {
505 x: x
506 y: y
507 absolute: true
508 }
509 }
510 {{/code}}
511
512
513 === Example Model ===
514
515 Create an empty SCChart and fill it with the following content:
516
517 {{code language="sct"}}
518 scchart TrafficLight {
519 output int showLight
520
521 initial state init
522 go to init do showLight += 1; showLight = showLight % 3
523 }
524 {{/code}}
525
526 This model will set the variable **showLight** successively to 0, 1 and 2.
527
528
529 see rotate animation

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage