Running models : Working with visualization tools : Layers

Layer display

The layer display tool differs from Simile's other display tools in that it allows a number of different types of display to be superimposed to create a composite image of processes in a 2-D modelled world. When the layer display is selected, a blank window appears in the run environment, and the 'Add' menu is replaced by a 'Layers' menu which allows the modeller to add instances of layer tools to the display, and to manipulate existing layers.

There are currently four different layer tools:

As of Simile v6.9 there are also a set of '2-D shapes' tools, for adding layers consisting of circles, lines or ellipses. These are analogous to the corresponding object types in the 3-D Shapes tool.

The spatial grid and polygon maps are similar to the corresponding stand-alone spatial grid and polygon tools, with the exception that they cannot be used to change values of model components. The background photo tool simply allows an image to be displayed behind anything that is added by the other tools, and the moving individuals tool displays icons (specified as series of Tk canvas drawing commands) for members of a submodel which includes values representing their co-ordinates in a 2-D space.

Layers menu

When the layer tool is first added, the layers menu will consist of a single entry labelled "Add new layer here". This cascades to a set of menus listing the available layer tools according to their source, like the menu for selecting the regular helper tools. Once a layer tool is added, the modeller will be prompted to select files and/or click on model components whose values will control the layer display, after which the layer will be added to the display. The layers menu now has a new entry for this layer, with 'Add new layer here' entries above and below it.

Once layers have been added, the menu lists all the existing layers, with 'Add new layer here' entries above, below and between them to allow new layers to be added at any position in the stack. Selecting the entry for an existing layer cascades to options to move the layer to the top or bottom of the stack, up or down one level, delete it or open its properties dialogue. A layer's properties dialogue will have a set of input widgets, some of which are unique to the layer type, and some common between various layer tools. The common ones are:

  • Select colours: This allows the colours representing the different model values (as shown in the legend) to be changed.
  • Range: The range of values covered by the colour spectrum can be widened or narrowed.
  • Offset and scale: Normally, data with the same numerical X and Y coordinates will display at the same point in the window in any layer tool, but these values adjust the display position of each layer. They can be used to compensate for different coordinate units being used in different parts of your model, or to show different maps side by side in the same window.
  • Legend side: For tools that can display a legend, this selects at which side of the window it appears, if at all. If multiple legends are added to the same side, the ones for the higher layers will be drawn on the inside.

In: Contents >> Running models >> Working with helpers

Working with visualization tools : Layers : Spatial grid map

Spatial grid map


This layer tool is very similar to the spatial grid display, with a couple of exceptions:

  • It cannot be used to set the values of model components
  • If used with a component in a hexagonal grid, the cells will be shown in a 'brickwork' pattern corresponding to the centres of the hexagons.

This tool may also be slower than the spatial grid display, since a more complex image scaling operation is required to get the grid to the exact scale to match other components.

In: Contents >> Running models >> Working with helpers >> Layer tool

Working with visualization tools : Layers : Polygon map

Polygon map

This layer tool is generally similar to the polygon helper, and is set up in a similar way. The differences are as follows:

  • It can be set to redraw the polygon outlines at each display interval, to cope with models in which polygons appear and disappear, or change shape
  • It cannot be used to set values of model components
  • The value for the colour is selected first. If this is from a hexagonal grid submodel, there is no need to provide vertex coordinates -- the helper generates the hexagon outlines itself.
  • The properties dialogue allows a stipple pattern to be chosen for filling the polygons. This allows lower layers to be partially seen through them.

This tool is faster than the old polygon helper with large numbers of polygons.

In: Contents >> Running models >> Working with helpers >> Layer tool

Working with visualisation tools : Layers : 2-D Shapes

2-D Shape Layer


This layer tool is similar to the stand-alone 3-D shape viewer, but displays 2-D shapes in a layer rather than projected 3-D shapes. Whereas one instance of the 3-D shape viewer can display sets of shapes corresponding to several sets of model valriables, each instance of the shape viewer layer only displays a set for one group of model variables. If multiple sets of shapes are required, each one can be added in the same view as a separate layer.


The shapes that can be added are circle, ellipse or line. Each has a separate submenu entry for adding it, so once it is added, the modeller is prompted for the information that enables the display to be set up. X and Y co-ordinates are set from components in the model, or fixed numeric values can be entered in an input field. If a model component is chosen for the colour of a shape, the colour legend editor appears in order to record how the model values will be converted into colours for the corresponding components.

Working with visualisation tools : Layers : Spatial input layer

Spatial input layer

This layer helper allows spatial input to be sent to a model during execution. When it is added as a layer, the modeller is requested to select three variable parameters from the model. These must be scalar with numerical units.


The first two of these will hold the X and Y coordinates of a position in the field of view of the layer tool. They are not changed until the modeller clicks or drags within the tool. At that point they will be continually updated with the pointer position within the layer tool until the unclick. The final variable is set to zero at any time when a click or drag is not in progress. It is set to 1 when a click occurs and is incremented by 1 whenever the pointer coordinates change during a drag. This is so the model can keep track of the speed or duration of the drag. It is set to zero again on the unclick.


This tool does not itself display anything within the layer helper area. Normally it would be added to a layer tool which is also showing a spatial grid covering the area in which the coordinates could be expected to fall, so the tool could be 'zoomed to fit' resulting in the input pointer layer also extending over the right range of coordinates. If there is no actual grid to display, the area covered by the input tool could be set by adding four 'line' layers, each with a single line corresponding to one side of the rectangle containing the desired input coordinates. These coordinates could be entered directly to the layer tool as numbers, or got from model variables.

Working with visualization tools : Layers : Background photo

Background photo

This is not really a visualization tool at all -- it just allows an image to be displayed as a background to the layers. Generally the image will be some form of map that corresponds to the data in the model. Because the pixel pitch of the image may not correspond to the position data in the model, the properties dialogue allows an offset and scale to be set for the image display. Thus the tool also allows the whole layer display to be annotated with small images.

When the tool is selected, a file selection dialogue appears for choosing the image file, which immediately displays. Its offset and scale are then adjusted via its properties dialogue. To change the image, delete the layer and add a new one.

In: Contents >> Running models >> Working with helpers >> Layer tool

Working with visualization tools : Layers : Show moving individuals

Show moving individuals

If a model includes a group of submodel instances representing mobile individuals, it may be desirable to display them on a map background using icons. That is what this layer tool is for. It can draw a lot of copies of an icon representing an individual at positions specified by model data. It can also vary the size and orientation of the icons according to data from the model.

The image data file

In order to do this, the icon must be expressed as a series of canvas drawing commands in the Tk language. Tk is the standard graphics extension for scripting languages including Tcl, Perl, Python and Ruby. An example file to draw the ants in the image on the Layer tool page is included in Simile's examples directory, and the images for Simile's population channels are also encoded in this way. These files typically have the extension .cnv. It is hoped to offer a Paintbox-style drawing tool for creating images in this format in the near future.

The file consists of a series of commands to draw the icon on a canvas referred to as $c. This will cause it to be drawn in the layer display when sourced by this tool's code. If the ability to rotate the icon is to be used, then only canvas objects that can be drawn at any angle should be included, i.e., avoid arcs and ovals (unless circular) and rectangles. As well as drawing commands, the file should include an instruction to set the hotspot -- this is the point in the image that will be positioned on the map point given by the model data, as a pair of integers, e.g.,

set hotspot {100 150}

Similarly the scale should be set, i,e., the number of canvas units of the drawing commands corresponding to one unit of map space. A large value will mean the image is drawn small, and is useful for precision because positions and line thicknesses in the image file must be integers.

set scale 10

It should also set the axis direction, in which the image as drawn by the canvas commands appears to be facing. This can either be a compass point (ne, sw, etc), an hour on the clock face (6h, 9h, etc) or a number which will be treated as the number of radians the axis lies anticlockwise from the x axis. e.g., these three forms are valid and equivalent:

set axis n

set axis 12h

set axis 1.57

Setting up the tool

When the layer is selected, a file selection dialogue appears for choosing the image file. Once the file is selected, its contents are loaded into the helper setup, so the file is not consulted again -- if the image is altered, the layer must be deleted and re-created to display the new version of the image. Now you will be prompted to click on model components for the x and y coordinates of the individuals' positions on the map. These have to be supplied. You will be prompted to click on two more model components to specify the size and orientation of the individuals. If you do not wish the icons to be changed in size, just click on one of the components you have already clicked on at this point, and the size will not be altered. The value of the orientation component can be a number, which is interpreted as the number of radians anticlockwise from the x axis which the image will be shown facing. Alternatively it can be a member one of the enumerated types used to index the neighbour directions in the special-purpose submodels, in which case the image will be drawn facing in that direction. In either case, if the value of the direction component is the same as the axis direction in the model file, the icon is drawn unrotated. If no rotation is to be done, select a component that has already been selected for x or y position as the rotation.

In: Contents >> Running models >> Working with helpers >> Layer tool