VisB: Difference between revisions

Line 161: Line 161:
Some examples can be found [https://gitlab.cs.uni-duesseldorf.de/general/stups/visb-visualisation-examples here].
Some examples can be found [https://gitlab.cs.uni-duesseldorf.de/general/stups/visb-visualisation-examples here].
More details and examples will be added later.
More details and examples will be added later.
=== VisB Tips and Tricks ===
It is sometimes useful to use simple coordinates for your VisB items and B expressions, e.g. x coordinates of 0..100.
You can quite often do this and use the SVG  <b>transform</b> attribute to scale and move the SVG object to the right place.
The simple  [https://gitlab.cs.uni-duesseldorf.de/general/stups/visb-visualisation-examples train VisB example] shows how to do this.
In essence your SVG file can contain this:
<pre>
  <polygon id = "ttd_polyline"
      points="0,0 100,0"
      stroke="gray" fill="none"
      transform="translate(10,22.5)" />
</pre>
and the VisB JSON file contains this, making use of LibrarySVG.def (automatically available) external function <b>svg_axis</b>:
<pre>
    {
      "id":"ttd_polyline",
      "attr":"points",
      "value":"svg_axis({0} \\/ ran(%tt.(tt:TTDS|1+max(TTD_TrackElements(tt)))),100.0/real(TrackElementNumber+1),100.0,2.0)",
      "comment":"show ticks for TTD Limits"
    },
</pre>


=== Citing VisB ===
=== Citing VisB ===

Revision as of 09:29, 2 February 2021

VisB

VisB is a plugin for ProB2-UI, the new user interface of ProB based on JavaFX and the ProB2-Java-API . It is included in the latest Snapshot builds of ProB2-UI, but can be downloaded at https://www3.hhu.de/stups/downloads/prob2/plugins/ for older version of ProB2-UI.

An article about VisB has been published in the ABZ'2020 proceedings.

Using VisB

To start VisB choose the "Open VisB" command in the Visualisation menu.

You can now choose a JSON file which builds on top of a SVG graphics file. The JSON file contains a reference to a SVG file, along with entries to modify attributes based on the current state of a B model and entries which specify how VisB should react to clicks on the SVG. The SVG file should contain object ids which are referenced in the JSON file.

Here is a sample file:

{
  "svg":"Train2.svg",
  "items":[
    {
      "id":"Train1_rect",
      "attr":"visibility",
      "value":"IF 1:TRAIN THEN \"visible\" ELSE \"hidden\" END"
    },
    {
      "id":"Train1_rect",
      "attr":"fill",
      "value":"IF train_speed(1)>0 THEN \"blue\" ELSE \"orange\" END"
    },
    {
      "id":"Train1_rect",
      "attr":"x",
      "value":"train_back_loc(1)*10+20"
    },
    {
      "id":"Train1_rect",
      "attr":"width",
      "value":"train_length(1)*10"
    }
    ],
  "events":[
    {
      "id":"Train1_rect",
      "event":"Train_Move1",
      "predicates":[
        "1=1"
      ]
    }
    ]
}

VisB Attributes

The main VisB Json file should contain an svg attribute with a relative or absolute path to the SVG file to be shown. One can also include subsidiary VisB Json files using the include attribute with again a relative or absolut path to another Json file:

{
  "svg":"my_svg_file.svg",
  "include":"subsidiary_visb_file.json",
  "items":[
...
}

The svg attribute in subsidiary files will be ignored. You can override the VisB items in the included file (i.e., a VisB item for an id and attribute in the top-level file will override items for the same id and attribute in the included files).


For VisB items every entry needs

  • id, this is the identifier of an object in the associated SVG file
  • attr a valid SVG attribute
  • value a B formula which will be evaluated in the current state of a model and yields a new value for the above attribute.

For VisB event every entry needs

  • id, this is the identifier of an object in the associated SVG file
  • event a valid B operation or event of the loaded formal model
  • predicates an optional list of B predicates, which can be used to set parameters of the B operation that is executed upon a click

Additionally VisB now recognises for both items and events:

  • ignore, if this attribute is present the item will be ignored
  • repeat, if this attribute is present the item will be replicated (see below). This construct requires a list of strings.
  • for, if this attribute is present the item will be replicated (see below). The for construct requires from and to with integer values as sub arguments.
  • optional, if this boolean attribute is true an event will be ignored if the event name is not a valid top-level event/operation in the model. An item will be ignored if the identifiers in the formula do not exists (i.e., errors during type checking will be ignored)

Other attributes will be ignored. E.g, one can use a comment attribute to add comments to the VisB items.

When executing an event, VisB now performs the following replacements within the predicates of the event:

  • %shiftKey is replaced by TRUE if the shift key was pressed during the click, FALSE otherwise
  • %metaKey is replaced by TRUE if the shift key was pressed during the click, FALSE otherwise
  • %pageX is replaced by the x coordinate of the click relative to the top-left of the entire VisB SVG
  • %pageY is replaced by the y coordinate of the click relative to the top-left of the entire VisB SVG

Finally, events can now be associated with various hovers. For this you just need to add an attribute hovers which contains a list of JSON objects with the following attributes:

  • id, this is the identifier of an object in the associated SVG file; this attribut is optional; if it is not present the id specified in the VisB event will be used.
  • attr a valid SVG attribute
  • enter a value which will be used when the mouse enters the area of the object
  • leave a value which will be used to restore the attribute when the mouse leaves the area

Note that the enter and leave values have to be static at the moment; in future we plan to allow B formulas here and also apply the repetition/replacement mechanism specified above. If you just wish to attach a hover to an SVG object (and no B operation/event) you can set the event field of the VisB event to the empty string ("event":""). You should not use attributes for the hover which are set by VisB items.

Here is an example VisB event with hovers:

 {
      "id": "button",
      "event": "toggle_button",
      "hovers": [{ "attr":"stroke-width", "enter":"6", "leave":"1"},
                 { "attr":"opacity", "enter":"0.8", "leave":"1.0"}]
    }

Replication

You can use the repeat and for attributes to replicate a VisB item or event. Replication consists in duplicating the item or event, and replacing %0 within the identifier and value attributes of the time with the repeated string or integer.

For example, the repeat instruction below will result in the creation of three VisB items, one for id txt_ttd1, for txt_ttd2, and one for txt_ttd3. The value formula for txt_ttd1 is "IF 1: dom(TTD) THEN visb_ttd_back(%0) ELSE -1000 END".

    {
     "repeat": ["1","2","3"],
      "id":"txt_ttd%0",
      "attr":"x",
      "value":"IF %0: dom(TTD) THEN visb_ttd_back(%0) ELSE -1000 END"
    },

A for loop can be used instead for the above example as follows:

    {
     "for": {"from":1, "to":3},
      "id":"txt_ttd%0",
      "attr":"x",
      "value":"IF %0: dom(TTD) THEN visb_ttd_back(%0) ELSE -1000 END"
    },

It is possible to apply both repeat and for attributes at the same time, as this example shows. (The exact details of multiple iterations for a VisB item might change in future.)

  {
     "repeat": [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20],
     "for": {"from":1, "to":20},
      "id": "tile%1x%0",
      "event": "TryQueen",
      "hovers": [{ "attr":"opacity", "enter":"0.5", "leave":"1"}],
      "predicates" : ["i=%1","j=%0"] 
    }

VisB Examples

Some examples can be found here. More details and examples will be added later.


VisB Tips and Tricks

It is sometimes useful to use simple coordinates for your VisB items and B expressions, e.g. x coordinates of 0..100. You can quite often do this and use the SVG transform attribute to scale and move the SVG object to the right place. The simple train VisB example shows how to do this. In essence your SVG file can contain this:

  <polygon id = "ttd_polyline"
       points="0,0 100,0"
       stroke="gray" fill="none"
       transform="translate(10,22.5)" />

and the VisB JSON file contains this, making use of LibrarySVG.def (automatically available) external function svg_axis:

    {
      "id":"ttd_polyline",
      "attr":"points",
      "value":"svg_axis({0} \\/ ran(%tt.(tt:TTDS|1+max(TTD_TrackElements(tt)))),100.0/real(TrackElementNumber+1),100.0,2.0)",
      "comment":"show ticks for TTD Limits"
    },

Citing VisB

This is the Bibtex entry for an article about VisB in the ABZ'2020 proceedings:

@inproceedings{WerthLeuschel:abz2020,
  author    = {Michelle Werth and Michael Leuschel},
  title     = {{VisB}: A Lightweight Tool to Visualize Formal Models with {SVG} Graphics},
  booktitle = {Proceedings ABZ 2020},
  editor="Raschke, Alexander and M{\'e}ry, Dominique and Houdek, Frank",
  year      = {2020},
  series = {LNCS 12071},
  pages = "260--265",
  isbn="978-3-030-48077-6"
}


Installing VisB Plugin for older ProB2-UI versions

To install VisB in the JavaFX-based ProB2-UI you need to:

1. Choose "Plugin Menu" in the Advanced menu 2. Click on the "Add Plugin..." button. 3. Select the VisB JAR file you have downloaded from https://www3.hhu.de/stups/downloads/prob2/plugins/ 4. Choose the "Open VisB" command in the Advanced menu to start VisB