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

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

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.

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.

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

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