This document describes the format of the configuration file that is used by the programs mapclust, mapdiff, maplink, mapmap, maprgb, and mapvec.

See also: example.cfg

See mapmap for testing.

The configuration file consist of a collection of settings. Each setting consists of a name in lower case followed by a colon, followed by one or more values. There may be no space before the colon. Settings without values are ignored. Example:

    # comment lines and empty lines are ignored

    # 'name' is set to 'value'
    name: value

    # no value, ignored
    anothername:

A remark on filenames: Any filenames without an absolute pathname are resolved relative to the directory in which the program is run, not relative to the directory in which the configuration file resides.

A remarks on sizes: all absolute sizes are in PostScript points. 72 points is equal to 1 inch.

Three files should be defined:

transform:

value: filename
The name of a file with a piece of PostScript code defining a linear transform function, named Map, that translates a pair of map coordinates into a pair of image coordinates.
You can use the mapsetup program to create this file.

labels:

value: filename
The name of a label file.

coordinates:

value: filename
The name of a coordinate file.

Three more files:

clipping:

value: filename
default: none
The name of a file with a piece of PostScript code defining the clipping region. Only the area within this region will be painted.
You can use the mapsetup program to create this file.

map:

value: filename
default: none
The name of a file with a piece of PostScript code for drawing the lines of the map, such as borders.
You can use the mapsetup program to create this file.

othermarkers:

value: filename
default: none
The name of a file with a list of locations that should be treated differently from the general settings, as defined by the option markers. Each line in the file has a value followed by a label, separated by space(s) or tab(s).
The label is the name of a location, as defined in the label file.
The value says what to do with this location.
If the value is -1, the location should be ignored completely. This is particularly useful if you have two locations with identical coordinates, since only one result per location can be shown anyway, and the algorithm for triangulation (dividing the map into regions surrounding each location) may fail on identical locations.
If the value is zero or positive, an integer value from 0 to 255 inclusive, it is meant as a substitute for the default marker setting. The value is the sum of zero or more of these numbers:
1: put dot
2: put location number
4: put label
8: draw polygon
16: put cluster symbol (mapclust only)
32: put cluster number (mapclust only)
64: draw data island (mapclust, mapmap, maprgb)
128: draw data island as diamond (requires 64 as well)
For data island, see also options islandr and islandlw.
With mapdiff, the number 64 has the same effect as value -1. In other words, data from islands is ignored completely.

Other settings:

backrgb:

value: three real numbers between 0 and 1
default: .9 .9 .9
These are the red, green and blue colour components for the background colour. This colour is used for areas of the map for which no data is available.

aspect:

value: a real number, 1 or greater
default: 1
This value defines the aspect ratio between the horizontal and vertical coordinates. Useful if you are using coordinates defined as longitude and latitude. The program mapsetup can give you a useful value.
Coordinates are always used in a rectangular grid. You won't get curved lines along the longitude. If the distortion is unacceptable, you may want to translate all coordinates to some rectangular representation, such as UTM coordinates.

markers:

value, zero or more of: dot label number poly
default: nothing
This determines how locations are marked on the map. You should not combine dot and number.
If you define label the names of the locations are printed. Where each label is positioned is determined by the third and fourth number in the coordinate file. These two values are called dx and dy. A dx value of -1 means the label will be put left of the coordinates of the location. If the value is 1, it will be put at the right side. Any value in between will shift the label somewhere in between. You can use values outside the range -1 to 1 to move the label further away. The value for dy determines the vertical position. -1 means below, 1 means above the location. You may run the programs for creating maps several times, and based on the results adjust the dx and dy values in the coordinate file to get the labels positioned so they won't overlap.

missing:

value, one of: ignore preserve
default: preserve
The label file and the coordinate file should define the same set of locations. However, the datafile (the cluster file used by mapclust, or the vector file used by maprgb) can use a smaller set of locations. This options determines what happens to the locations that are not present in the datafile.
ignore: The program will act as if the locations don't exist. Their space will be occupied by locations that do exist (have data).
preserve: The program will leave the areas for the locations with missing data open, creating gaps on the map.

fillmargin:

value: a positive value

default: 0.5
This value determines how far painting extends beyond the extreme locations, as a fraction of the distance between the extreme locations.
Increase this value if parts along the edge of the map are not painted.

limit:

value: a positive value

default: 50
If you don't have a clipping file, or if the value of uselimit is yes, this value will be used to limit the area around each location that is painted. The value is the radius of the circle centred around the location to which painting will be restricted.
It might be best to start with a small value, such as 10, then draw a map, and increase the value if there are gaps left between the locations.

uselimit:

value, one of: yes no
If yes, limit the area around each location that is painted, even if you do have a clipping file.

boundingbox:

value: four integer numbers

default: 0 0 595 842
These four values determine the outer boundaries of the image. The image created is Encapsulated PostScript, meaning, the image can be imported into other documents. This only works correctly if the boundingbox is set correct, so the importing program knows how large the image is, and how it is positioned.
The four numbers are: the left x-coordinate, the bottom y-coordinate, the right x-coordinate, the top x-coordinate.
You can view an image with a program like GSview or GV, and use your mouse to point at the borders. The coordinates will be displayed by the program. (These programs themselves can use the boundingbox values to crop the displayed images.)
It is best to set the boundingbox last, once all other options are tested and have their final settings. Changing values in the transform file also effects the size of the image.

fontname:

value: a valid fontname known to PostScript
default: Helvetica
Fonts that can be used include, serif: Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic; sans serif: Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique; mono spaced: Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique.

fontmatrix:

value: font matrix
default: [ 8 0 0 8 0 0 ]
Actually, this can be any PostScript code that returns a font matrix. To put it simple, if you want a font of size 10, use:

    [ 10 0 0 10 0 0 ]

If you want a font scaled 10 in height but only 8 in width, use:

    [ 8 0 0 10 0 0 ]

Unless you want a slanted, rotated or otherwise distorted font, don't change the zeros.

pslevel:

value: 1 or 2
default: 1
This option determines what PostScript language level to use. Level 1 is very old, and the chance it is still in use is minimal. If you choose level 2 the file will be slightly smaller. If you choose level 1, the result will work on both level 1 and level 2 PostScript devices. Note that if you use patterns with mapclust (option -p), the setting will be changed to level 2 automaticly, and the result won't work on a level 1 PostScript device.

fillstyle:

value: fill or eofill
default: fill
Change the rule for filling and clipping:
fill: Non-zero winding number rule
eofill: Even-odd rule

radius:

value: a positive real number
default: 2.5
This is the size of the black dots, if you use dot markers.

white:

value: a positive real number
default: 1
This is the width of the white line around the black dots, if you use dot markers.

xgap:

value: a positive real number or 0
default: 4
This is the amount of horizontal space a label is set from the centre of the location if the dx position is set to -1 or 1. See markers.

ygap:

value: a positive real number or 0
default: 4
This is the amount of vertical space a label is set from the centre of the location if the dy position is set to -1 or 1. See markers.

linewidth:

value: a positive real number
default: .5
The line width used when drawing polygons. See markers.

islandr:

value: a positive real number
default: 10
The radius of markers used for data islands. See also othermarkers.

islandlw:

value: a non-negative real number
default: 1
Line width for markers of data islands. If this value is 0, no line will be drawn. See also othermarkers.

borderwidth:

value: a positive real number
default: 2
This is the line width for borders between clusters. For maplink, this is the width of the links.

borderrgb:

value: three real numbers between 0 and 1
default: 0 0 1
These are the red, green and blue colour components for the borders between clusters.

symbolsize:

value: a positive real number
default: 5
This is the size of symbols.

symbollinewidth:

value: a positive real number
default: .3
This is the line width used in symbols.

The PostScript files created by the map programs are highly structured. Settings are documented. If you know something about PostScript, you can read and edit these files for fine tuning, or adding things. Things you should look at in particular are the function Map which is included at the top of the file between a %%BeginDocument / %%EndDocument pair, several setting that follow immediately, and the array named PP a bit further down.