mmsvg

Topics covered in this chapter:

The mmsvg package provides a set procedures which allow users to display graphs of functions, diagrams, networks, various shapes etc. in SVG format. To use this module the following line must be included in the header of the Mosel model file:

uses "mmsvg"

mmsvg requires a webbrowser in order to be able to display graphics. Running a Mosel model that uses the svgrefresh routine provided by this module opens a window in the default browser that is configured on the system. In the absence of a webbrowser, it is still possible to generate graphics and save them to file via svgsave.

SVG graph structure

The SVG graph format is an XML format, that is, the elements of a graph are organized in a hierarchical tree structure. mmsvg structures graphical objects in three levels:

1. SVG graph
2. object group
3. graphical object

Each individual graphical object (line, polygon, text etc.) must be created within an object group. By default this is the last group that has been added to the graph, but some other object reference can be stated. A default graph object is always present and object groups are created within this default graph.

Object groups

Object groups are identified via a string ID that is specified by the user at their creation, this ID must be unique. Each object group receives an entry in the legend of the graph. Typically a group serves to represent a collection of graphical objects that are logically related. The style defined for a group is applied to all its objects unless it is overwritten by individual settings, meaning that it is usually more efficient to state generally valid style settings for an entire group instead of repeating them for each individual object.

At the creation of a group, optionally a group color can be specified. If no color is given, then a default color will be selected from a built-in list of color values.

Graphical objects are displayed in the order of definition of object groups, and within each group in the order of their definition.

SVG styling

Style definitions can be applied to all levels of SVG elements, to the graph, object groups, or for individual objects. mmsvg defines a set of property constants but other SVG styling options can equally be used by directly stating their name in the svgset[graph]style routines. For a complete list of SVG style properties and their permissible values the reader is refered to the SVG property specifications at https://www.w3.org/TR/SVG/propidx.html.

SVG_COLOR

Default color name (for object groups)

SVG_DECORATION

Text decoration; possible values include 'none', 'underline', 'overline', 'line-through', 'blink'

SVG_FILL

Fill color name

SVG_FILLOPACITY

Fill opacity; values between 0.0 and 1.0

SVG_FONT

Whitespace separated list of font settings

SVG_FONTFAMILY

Font family definition; this can be generic families ('serif', 'sans-serif', 'cursive', 'fantasy', 'monospace') or specific font names

SVG_FONTSIZE

Font size; constants ('xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large) or percentage value or length ( e.g. in 'em', 'pt', 'px', 'cm')

SVG_FONTSTYLE

Font style; values 'normal', 'italic', 'oblique'

SVG_FONTWEIGHT

Font weight; numbers 100,...900 or constants ('bold', 'bolder', 'lighter', 'normal')

SVG_OPACITY

Generic opacity setting; values between 0.0 and 1.0

SVG_STROKE

Color for lines and borders

SVG_STROKEDASH

Line style; comma-separated list of lengths or percentages specifying lengths of alternating dashes and gaps

SVG_STROKEOPACITY

Stroke opacity, values between 0.0 and 1.0

SVG_STROKEWIDTH

Stroke width; percentage or length

SVG_TEXTANCHOR

Vertical alignment of text; possible values include 'start', 'middle', 'end'

Other predefined constants are SVG_CURRENT for the current color and SVG_NONE.

mmsvg defines the following color constants (applicable to the properties SVG_COLOR, SVG_FILL, SVG_STROKE) that can be used in place of SVG color keywords or color definitions generated via the svgcolor routine:

• SVG_BLACK, SVG_BLUE, SVG_BROWN, SVG_CYAN, SVG_GOLD, SVG_GRAY, SVG_GREEN, SVG_LIME, SVG_MAGENTA, SVG_ORANGE, SVG_PINK, SVG_PURPLE, SVG_RED, SVG_SILVER, SVG_WHITE, SVG_YELLOW

For a full list of SVG color keywords and their definitions please see https://www.w3.org/TR/SVG/types.html.

The complete set of style properties specified for a graph, object group or individual objects can be retrieved via the routines svggetstylesheet and svggetgraphstylesheet, for example in order to copy them to some other object via svgsetstylesheet or svgsetgraphstylesheet respectively.

Interaction with the graphical display

The command svgrefresh sends the current graph and any additional files that might have been added to it (see svgaddfile) to the built-in server that handles the coordination with the display and triggers an update of the graphical display. The end of the model execution will also terminate the display, unless a call to the routine svgwaitclose is added at the end of the model, in which case the model waits for the closing of the display window.

Inserting a call to the routine svgpause into a model will pause its execution at this point until the user hits the 'Continue' button in the graphical display. Typically, this feature will be used to allow the user time for visual inspection of the output if a model iteratively generates graphics or updates to a graphic.

Example

The following example shows how to define a few simple graphical objects, saves the resulting graphic to a file and also displays it in a webbrowser. The model waits until the browser is closed.

model "svg example"
 uses "mmsvg"

! **** Line objects ****
 svgaddgroup("gl", "Lines")              ! Group with automatic color
 svgaddline(10,10,250,10)                ! Simple line with default style
 PointList:=sum(i in 1..20)[i*10,40+round(20*random)]
 svgaddline(PointList)                   ! Polyline
 l:=svggetlastobj                        ! Retrieve object reference
 svgsetstyle(l, SVG_STROKE, SVG_MAGENTA) ! Change line color
 svgsetstyle(l, SVG_STROKEDASH, "1,1")   ! Dotted line

! **** Various shapes ****
 svgaddgroup("gs", "Shapes", SVG_GREY)   ! Group with user-defined color
 svgaddrectangle(275,25,250,250)         ! Draw a square
 svgsetstyle(svggetlastobj, SVG_STROKEWIDTH, 3)    ! Wider border
 svgaddcircle(400,150,75)                ! Draw a circle
 svgsetstyle(svggetlastobj, SVG_FILL, SVG_CURRENT) ! Fill with group color
 svgaddpolygon([200,400,200,350,300,300,500,350,600,350,600,400])
 svgsetstyle(svggetlastobj, SVG_FILL, SVG_GREEN)   ! Fill with user color

! **** Pie chart ****
 forall(i in 1..6) svgaddgroup("gp"+i,"Pie"+i)     ! Pie slices with auto-colors
 setrandseed(3); ttl:=0.0
 forall(i in 1..5) do
   rd:=random/6
   svgaddpie("gp"+i, 150, 525, 100, ttl, ttl+rd)
   ttl+=rd
 end-do
 svgaddpie("gp6", 150, 525, 100, ttl, 1)

! **** Text objects ****
 svgaddgroup("gt", "Text", SVG_BLACK)    ! Group with user-defined color
 svgaddtext(20, 100, "Text with default formatting")
 svgaddtext(20, 120, "Formatted text")
 t:=svggetlastobj
 svgsetstyle(t, SVG_FONTSIZE, "20pt")
 svgsetstyle(t, SVG_FONTSTYLE, "italic")
 svgsetstyle(t, SVG_FONTWEIGHT, "bold")
 svgsetstyle(t, SVG_COLOR, SVG_BLUE)
 svgaddxmltext(20, 150, 'XML formatted text:
   <tspan font-size="large"> large</tspan>
   <tspan text-decoration="underline">underlined</tspan>
   <tspan stroke="red"> red</tspan>')

 svgsetgraphviewbox(0,0,610,635)        ! Optional: specify graph size

 svgsave("svgexpl.svg")                 ! Save graphic to file

 svgrefresh                             ! Display graphic
 svgwaitclose                           ! Wait until window is closed
end-model

Figure 17.1: Graphical output produced by the example