//////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2010, 2026 Contributors to the Eclipse Foundation
//
// See the NOTICE file(s) distributed with this work for additional
// information regarding copyright ownership.
//
// This program and the accompanying materials are made available
// under the terms of the MIT License which is available at
// https://opensource.org/licenses/MIT
//
// SPDX-License-Identifier: MIT
//////////////////////////////////////////////////////////////////////////////

include::../_part_attributes.asciidoc[]

:leveloffset: -2

[[lang-tut-svg-chapter-visualization]]
== SVG visualization

indexterm:[SVG,visualization]
When simulating a model, it is often useful to be able to see the state of the model.
For instance, the <<tools-cifsim-chapter-index,CIF simulator>> supports several forms of <<tools-cifsim-output-chapter-index,simulation output>>, such as printing state changes to the console.
While this provides useful information, it is not easy to decipher the precise state of a (sub-)system.
Also, it does not give a graphical overview of the current state of the system.

Therefore, CIF supports _SVG visualization_, which allows the user to make an image of the system, and have that image be updated during for instance simulation, based on the current state of the system.
This allows the user to see changes in the state of the system, in a graphical representation of that system.
This makes it much easier to get a global overview of the system during simulation.
Since the user makes the image, the representation directly corresponds to the way the user sees the system.

[[lang-tut-svg-chapter-visualization-svg]]
=== Scalable Vector Graphics (SVG)

indexterm:[SVG]
indexterm:[SVG visualization,SVG standard]
indexterm:[SVG,W3C]
SVG visualization in CIF uses SVG images.
SVG stands for Scalable Vector Graphics.
link:https://www.w3.org/TR/SVG11/[SVG] is a widely-deployed royalty-free standard for two-dimensional vector graphics, developed by the link:https://www.w3.org/[World Wide Web Consortium] (W3C).
CIF supports version 1.1 of the SVG standard.

SVG images consist of three types of objects: vector graphic shapes (rectangles, circles, etc.), raster images, and text.
The benefit of vector images formats over raster image formats, is that raster images are created with a fixed size, while vector images contain a description of the image and can be rendered at any size without loss of quality.

indexterm:[SVG,XML]
SVG image files are stored in an link:https://en.wikipedia.org/wiki/XML[XML]-based file format.
This means that they can be edited with any text editor.
However, it is often more convenient to edit them with a drawing program that supports vector graphics, such as link:https://www.adobe.com/products/illustrator.html[Adobe Illustrator] or <<lang-tut-svg-chapter-inkscape,Inkscape>>.
Most modern web browsers can also be used to view SVG images.

Since SVG images are essentially XML files, we get all the benefits of XML for free.
One of those benefits is that XML files represent tree structures, which can be easily manipulated by applications.
This is essential for SVG visualization.
Upon changes to the state of a CIF model, information from the model's state can be used to modify the XML tree.
Changes to the XML tree then result in an updated SVG image.
This way the image can be continuously adapted based on state changes, leading to an animated image.

indexterm:[SVG,id]

[[lang-tut-svg-chapter-visualization-svg-id]]
In order to be able to modify particular objects (shapes, text labels, etc.) of the SVG image, the objects that make up the image should be identifiable.
Here we once again reap the benefits of XML.
All nodes (called elements) in the XML tree can have an `id` attribute that specifies the id (also called name or identity) of the element.
As such, all SVG objects can be identified using their unique id.

indexterm:[SVG,tutorial]
indexterm:[tutorial,SVG]
The website of Jakob Jenkov has a very nice link:http://tutorials.jenkov.com/svg[SVG Tutorial], its different elements and their attributes.

[[lang-tut-svg-chapter-visualization-cifsvg]]
=== CIF/SVG declarations

indexterm:[SVG declaration]
indexterm:[SVG,declarations]
indexterm:[I/O declaration,SVG declaration]
indexterm:[CIF/SVG declaration]
The connection between the state of the CIF model and the SVG image can be specified by using CIF/SVG declarations (sometimes also called SVG declarations, for simplicity).
Such declarations can be specified directly in the CIF model.

The following types of CIF/SVG declarations are available:

* An SVG file declaration specifies which SVG image file to use.
* A CIF/SVG output mapping specifies how to update a certain property of an element of an SVG image, based on the state of the model.
* A CIF/SVG copy declaration specifies that a part of an SVG image should be copied.
* A CIF/SVG move declaration specifies that a part of an SVG image should be moved.
* A CIF/SVG input mapping specifies how interaction with an SVG image can be used to affect the behavior of the model.
SVG interaction is explained in a later tutorial lesson.

These declarations are all demonstrated in later lessons by means of examples.
These examples also show some often used SVG elements and attributes, as well as some tips and tricks on how to handle common challenges.

Furthermore, examples of SVG visualization are available in other parts of the CIF documentation:

* <<sbe-in-practice-example>>

The <<lang-ref-svg-cifsvg,details of the different CIF/SVG declarations>> can be found in the CIF reference manual.
