DrawNET IV This file contains a minimal documentation of the formats used by the tool to encode both formalisms and models. In particular, Section (I)-(V) describe the formalism, while sections (VI) and (VII) focus on the model. Section (VIII) briefly describes the files that compose the project. (I) Formalism elements A formalism is described by an array of Javascrip objects, following the conventions below. The array is contained in a variable named "elementTypes". Each row of the array should contain the following properties: --> t: Type of the formalism element. Currently only two are supported: t: "n" --> Node of the graph t: "e" --> Edge of the graph --> d: Data: graphical description of the element. It is an object, with different fields for edges and nodes. See below the options available (II). --> ft: Formalism Type: the name of the type for the element in the formalism. The model will use this to address the type of one primitive. It is also meant to be the name that will be used to address the corresponding model primitive in the tool that will have to compute a solution. The name should follow the conventions of a programming language variable. --> l: Label: a short string describing the type of this element. It will be used in the GUI to identify this type --> tt: Tool Tip: a slightly longer description of this formalism element, that that will be displayed in the tool, to help the final user understanding the purpose of this element --> p: Properties: the list of the properties of the element. See below (III). (II) Graphical description of formalism elements Nodes and edges uses a different format for this attribute. They are described below respectively in Section (II.A) and (II.B) (II.A) Graphical description for nodes The appareance of a node is described by a javascript object. There are different types of basic shapes available. There is a set of common properties, plus other that depends on the type of basic shape being used. (II.A.1) Common propeties These properties are mandatory, and must be specified for every element type. --> sh: A short string defining the type of shape. Currnetly: sh: "s" -> Square sh: "c" -> Circle sh: "r" -> Rectangle sh: "e" -> Ellipse sh: "p" -> SVG path sh: "t" -> String of text sh: "i" -> Image sh: "g" -> Group of primitives --> hbw: Highlight Bounding-box Width: defines the width of the bounding box, to highlight the object when selected. --> hbh: Highlight Bounding-box Height: defines the height of the bounding box, to highlight the object when selected. (II.A.2) Fill and stroke settings Elements of type "s", "c", "r", "e", "p" and "t", are characterized by common color definition attributes. If not specified, they use a default value. --> fcol: Fill Color. The HTML color used to specify the fill (internal) color of the shape. Not defining the attribute, makes the primitive trasparent. --> scol: Stroke Color. The HTML color used to specify the stroke (border) color of the shape. Not defining the attribute, makes the shape without a contour. --> swidth: Stroke width. If a stroke color is defined, this defines the thickness of the contour of the object. It is specified in pixels, default is 1. --> sDash: The dash structure of the line. An array of numerical values, used to specify the continuity of the lines. It can be used to create dashed lines, dotted lines, dash/dotted lines of various size. See the approrpiate canvas documentation, for example: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash The default is a continuous line. (II.A.3) Square and circles for types "s" and "c" --> sz: Size of the primitive: edge in case of a square, diameter in case of a circle (II.A.3) Rectangles and Ellipses for types "r" and "e" --> w: Horizontal width of the rectangle, or horizontal diameter of the ellipse --> h: Vertical height of the rectangle, or vetical diameter of the ellipse (II.A.4) SVG paths Custom shapes can be defined using SVG paths and type "p". --> d: String containing the SVG path definition. The common SVG syntax is used, see for example: https://www.w3schools.com/graphics/svg_path.asp Coordinate (0,0) corresponds to the starting point of the primitive, and it is the position of the node in the graph representing the mode. The following SVG path commands are supported: m, M: Move to position l, L: Draw a line to position h, H: Draw an horizontal line v, H: Draw a vertical line c, C: Draw a Bezier curve segment Capital letters are absolute coordinates, while lower-case are used to specify movements relative to the previous position. SVG path commands s, S, q, Q, t, T, a and A are not supported yet. (II.A.5) Texts Texts can be written using type "t". The followin attributes are all mandatory. --> txt: A string containing the text to be displayed --> font: The HTML font name of the font to be used. Examples can be see here: https://www.w3schools.com/cssref/css_websafe_fonts.php --> sz: Size of the font (in pixels) --> w: The horizontal displacement of the text. --> h: The vertical displacement of the text. (II.A.6) Images Images can be used with type "i". --> img: It can contain either the URL of the image to load, or a Javascript object containing the image to display. --> w: Width of the image to display --> h: Height of the image to display (II.A.7) Groups More complex shapes can be created by combining several of the previous primitives in a group using type "g". --> d: An array of javascript objects containing shapes defined according to the syntax previoulsy described. In addition to the properties specified in Section (II.A.1) to (II.A.6), two new properties must be added: --> x: Horizontal displacement of the graphic primitive --> y: Vertical displacement of the graphic primitive (II.B) Graphical description for edges Edges are drawn by redrawing the same line several times, each time with different graphical settings. Each stroke is specified using an object containg the parameters "scol", "swidth" and "sDash" defined in Section (II.A.2). Moreover, several different strokes settings can be given to differentiate the appareance of the ark whether it is selected, or the mouse is hovering on it. If not specified, a default color is used. --> lNorm: Array containing the objects defining the normal appareance of the edge --> lHov: Array containing the the appareance of the edge when the mouse is hovering over it --> lSel: Array containing the the appareance of the edge when it is selected --> lHovSel: Array containing the the appareance of the edge when it is selected and the mouse is hovering over it In addition, arrows at the start of an edge, at its end, or in between when it is broken, can be specified using the same shape definitions given in Section (II.B). --> sArr: Object containig the shape to be drawn at the start of the arc. --> eArr: Object containig the shape to be drawn at the end of the arc. --> easArr: Object containig the shape to be drawn where a broken arrow interrupts an edge. --> basArr: Object containig the shape to be drawn where a broken arrow continues from the fracture. (III) Properties Properties of formalsims elements are contained in an array called "propertyCollection". Each element of the array, contains an object, describing a property, using the attributes defined below. For each formalism element, the attribute "p", introduced in Section (I), is an array of integer numbers that identify the position inside the "proprtyCollection" array of the properties associated to it. In this way, different elements can have the same properties: for example, both a single server and a delay station of a Queuing Network, will use a "service time distribution" attribute to describe their behavour. Since using numbers in defining a formalism might not be optimal, the suggestion is to create a "Map" structure that allows to use a symbolic value to retireve the current position inside the array. Each property type is defined by the following attributes: --> n: Name: a symbolic name, that follows the naming conventions of variables in a programming language, that identifies the considered property. --> t: Index of the type of the property. It will be defined in Section (IV). --> l: Label: a short string describing the type of this property. It will be used in the GUI to identify it. --> tt: Tool Tip: a slightly longer description of this property, that will be displayed in the tool, to help the final user understanding the purpose of this element. --> d: The default value of the properties. It is used by the tool to initialize a new node or arc added to the model. (IV) Property Types Model primitives, can have different attributes characterized by the same type of values, even if with totally different meanings. For example, the service time distribution of a queuing station is something completely different, from a modelling point of view, with respect to the inter arrival time distribution of a node representing arrivals to the system. However both values are the same: the are both descriptions of probability distributions. The Property Types array defines the types used in the formalism. Each entry of an array represents a different concept that could be used to specify the value of a property of a model primitive. The field "t" of a property definition in the "propretyCollection" array is an integer identifying the position in the property types array that defines the types of values that can be assigned to the property of modelling primitive. The property defintion array is called "propertyTypes", and each element is an object, described by the following attributes: --> n: Name: A symbolic name given to the property type --> t: Type: A string defining the basic type of this property type definition. Currently supported values are the following: t: "i" --> Integer values t: "f" --> Floating point values t: "s" --> String values t: "e" --> Enumeration values t: "g" --> Group values - used to represent strucutres --> r: An array of restrictions to better specify this type. Its implementation depends on the basic type assigned to this type definition. Se below in Sections (IV.A) to (IV.C). (IV.A) Elements with no restrictions Currently, Integer "i", Floating points "f" and string values "s", do not support any restriction. In future releases, the idea is to allow descriptions to define constraints such as ranges. For example, describe positive ingers, or floating point values in the range 0...1 to denote a probability. (IV.B) Restrictions for enumeration values Attribute "r" of an an Enumeration value t: "e", contains an array of objects, each one representing a possible value for the enumeration. In particular, each option is characterized by the following attributes: --> op: Option: a symbolic name, that will be assigned to the variable corresponding to this enumeration, when the considered option is selected. --> l: Label: a short string describing the corresponding option. It will be used in the GUI to identify it. --> tt: Tool Tip: a slightly longer description of this option, that will be displayed in the tool, to help the final user understanding the purpose of this element. (IV.C) Restrictions for group types For group values, t: "g", the value of the restriction property "r", is an array of integers. Each integer identifies a row of the "propertyCollection" array. In this way, each field of a structure can be definied exactly as a new property of the formalism element. The downside, is that this value should be filled after the "propertyCollection" collection array, which could add a small level of complexity to manual formalism definition. The default value for group property types is an object, where each field corresponds to the attribute "n" of the elements indexed by the restriction array. The value associated to each field provides its default value. (IV.D) Future extensions Future extensions will include a "Union" type, that will combine the enumeration with the group property features, to allow the user to specify different parameters depending on the value choosen in the enumeration, a "Pointer" type, to allow the user to select one element of the model as a value for the corresponding property, and an "Array" type (both of fixed or variable size). Also "Boolean" values, "Vector" and "Matrices" will be implemented. (V) Files Currently, the formalism is specified in a file called "formalism.js", which is loaded at the start-up of the tool. Since it is a Javascript file, it can exploit Javascript to simplify the mapping of index values, with symbolic constants. In particular, the suggestion is to use a mapping structure for both the Properties Definition, as outlined in Section (III), and for the property types. An initial model is currently loaded from file "m0.js", to provide a start-up scenario for a model. The format of the model is defined in Section (VI). (VI) Model Models are defined in an array of objects called "graph". Each modelling object has the following attributes. --> id: ID: an integer identifying the position of the element inside the array. It must start from 0, and correspond to the exact position where the corresponding modelling primitive is stored. I.e.: graph[i].id = i; --> n: Name: a symbolic identfier given to the modelling primitive. It must follow the same rules as the naming convention of variables. --> t: Type: an integer corresponding to the row in the "elementTypes" array of the formalsim type associated to the corresponding element. A special value t: -1 is used to denote deleted elements, according to the data structure defined in Section (VII). --> r: References: number of other nodes connected to this one. For edges, currently it is always equal to 2. For nodes, it corresponds to the sum of the number of incoming and outgoing arcs. This value is automaticcaly handled by the tool. --> bbox: Bounding Box: this describe a rectangle that completely encompasses the graphical representation of the considered modelling primitive. This attribute is automatically handled by the tool, and it is used to support the R-tree data structure that the tool exploits to increase the graphic processing of the visual representation of the model. It is an object with the following fields: --> x: Horizontal position of the Bounding-box. --> y: Vertical position of the Bounding-box. --> w: Width of the Bounding-box. --> h: Height of the Bounding-box. --> s: An object specifying the visual attributes of the tool. Its implementation is different between nodes and edges, according to the descriptions given respectively in Sections (VI.A) and (VI.B). --> p: The values of the properties defined by the model and assigned to this element of the model. It will be described in Section (VI.C). (VI.A) Graphical specification for nodes The attribute "s" of nodes, defines the graphical transformations that are applied to it to place it on screen. It also contains other values used to simplify the interaction with edges. They are the following: --> tx: Translation along the x axis. Basically, the horizontal position of the node. --> ty: Translation along the y axis. Basically, the vertical position of the node. --> rot: Rotation of the node (in radians) --> sx: Scaling factor along the x axis. --> sy: Scaling factor along the y axis. --> in: An array of integers, that includes the index (in the "graph[]" array) of the arcs that ends on this node. --> out: An array of integers, that includes the index (in the "graph[]" array) of the arcs that starts from this node. (VI.B) Graphical specification for edges The attribute "s" of edges, defines the shape of the curve, and the indices of the nodes it connects. --> from: The index (in the "graph[]" array) of the node from which this edge starts. --> to: The index (in the "graph[]" array) of the node on which this edge ends. --> points: An array of Bezier curves segments that defines the shape of the edge. Each Bezier curve is specified by an object with the following attributes: --> x1, y1: The coordinates of the starting point of the edge --> x2, y2: The coordinates of the ending point of the edge --> xc1, yc1: The coordinates of the first control point of the edge --> xc2, yc2: The coordinates of the second control point of the edge --> t1, t1: An integer that defines how the GUI handles the intial and final points. The value is a number in the range 0..7 defined by the sum of the following values: +1 : Tangent is unlocked in that point +2 : Currently not used, but the idea was to be able to lock only the direction of a tangent but not its length. +4 : The arc is "broken" on that point. (VI.C) Values of properties defined by the formalism Attribute "p" assigns values to the properties associated to the element in the formalism. It is an object, where each field corresponds to the attribute "n" of the elements indexed by the restriction array. The value associated to each field is the one given to the property of the element. For integers and floating point numbers, it is a number. For strings and enumerations, it is a string: in particular for enumerations, it corresponds to the "op" field of the option currently selected. For group, the value is an object where each field coresponds to one property of the considered data structure. (VII) Additional variables, attributes and the data structure for the deleted nodes In addition to the "graph" array, a model specifies these two variables to help the process of adding a new model element: graphFirstFree: The id of the row in the graph array that includes the current top of the empty model elements list (See below). namesFirstFree: The first number that will be appended to a new modelling primitive added to the model. Each model has always and empty node, with the following definition: {"id":...,"s":{"next":-1},"t":-1,"r":1,"bbox":{"x":0,"y":0,"w":0,"h":0}, n:"","p":{}} Whenever an element is deleted from the model, it is not removed. It is replaced with an element similar to the one above, creating a list of free nodes. The "s" attribut, now contains a "next" property, that points to the next available element in the "graph" array. The value of "graphFirstFree" always points to the first element of the list. The last element of the list has the "next" property equal to -1. When a new model primitive is added, the tool first searches the list to see if there is a spot left by a previously created element to be reused. Only when there are no more free slots, the GUI allocates a new one. Finally, during the execution of the GUI, nodes have these attributes that are dynamically added and changed: hovering: A boolean value that tells whether the mouse is currently over the element selected: A boolean value that tells if the element is selected (VIII) Project files The source is currently composed by the following files. (VIII.A) Main folder DrawNET-4.html --> The starting point of the project. Currently, it loads the formalism contained in formalism.js and as start-up model, the one contained in m0.js DrawNET-4.css --> The CSS used by the basic style of the tool jquery-uicss --> The tool uses JQuery-UI for the dialogs. This is its default style-sheet formlism.js --> The default formalsim definition m0.js --> The initial model definition Micro Documentation.txt --> This file fonts/ --> The fonts used by the tool fonts/MaterialIcons-Regular.ttf --> The only font currently required images/ --> The images required by the tool images/ui-icons_* --> The default images required by JQuery-UI libs/ --> Third party libraries used by the tool - See (VIII.B) below modules/ --> The Javascript files that composes the tool. - See (VIII.C) (VIII.B) Third party libraries The Tool currently uses these third party libraries: jquery-3.7.1.min.js --> The JQuery library: https://jquery.com/ It is used to dynamically create the HTML page containing the canvas and the other components of the tool. jquery-3.7.1.min.js --> The JQuery User Interface library: https://jqueryui.com/ It is used to dynamically create the dialog boxes used to enter properties values in the tool. jsbezier.js --> the jsBezier curves library: https://github.com/jsplumb/jsBezier It is used to support the calculations for the Bezier curves that the tool uses to draw arcs rtree.js --> the library to support the RTree data structure https://github.com/imbcmdth/RTree It is used to support the RTree data structure that the tool uses to accelerate the access to the element on the canvas. Using this data structure the tool can handled model composed by thousands of nodes and arcs. (VIII.C) The primary modules of the tools. The user interfaces is divede into several modules, all written in Javascript, and contained inside the modules/ folder. In particular, the files are meant to group elements related to the following functionalities. main.js --> The file tha creates all the objects and installs handlers for the events listened by the tool draw.js --> The procedure that writes the content of the main canvas at the center of the screen. In particular it handles selection of objects, group manipulators an interaction with objects at the high level. FSM.js --> User interaction is controlled by a Finite State Machines, that decides in which sequence actions can be done by the user. At each point in time the user has the UI in a given state, and actions such as pressing buttons change the state to obtain given functionalities. All the states are handled in this file. history.js --> The tool natively supports UNDO and REDO features. This is done by modifying the model using a set of commands. The other modules produces for each intervention by the user two commands: one that performs the action, and the other that reverts it. This modules handles the execution of these commands, as well as keeping their history to allow UNDO and REDO. model.js --> This module contains the functions that modfies a model, allowing to add and delete elements, as well as chainging their properties and serialize them. metaEtypes.js --> All modelling elements can be currently of two different meta-types: Nodes and Edges. Each one has to provide a set of interaction functionality to the GUI, and configure different elements according to the definition given in the formalism. This module handles these functionalities. A THIRD META TYPE is planned to support sub-models, but NOT IMPLEMENTED YET extragraph.js --> This is a collection of graphic functionalities, such as drawing arrows, compute the new points in a spline that has been stretched, doing the computations to account for rotations and change of scales. The idea is to group these functions in a separate module, to reduce the complexity of the other modules that require them. menu.js --> Handles the main menu at the top of the screen, allowing to dinamically define the available features and commands. In particular, it constructs all the menus and sub-menus, and it allows navigation among them. controls.js --> Handles the menu on the right that shows the modelling primitives according to the definitions given by the formalism. config.js --> This file contains the definition of a set of configuration parameters that can be used to change the interaction interface of the tool.