generate files needed by mapclust, mapdiff, mapmap, maprgb, and mapvec

mapsetup [-b int] [-L] [-p] -c clipping [-m map]

mapsetup [-b int] [-L] [-p] -l locations

-b int

margin, default 100 for clipping, 150 for locations

-c filename

file with geographic data used for clipping

-L

coordinates are in longitude/latitude
a suitable aspect ratio will be calculated

-l filename

file with coordinates

-m filename

file with geographic data used for drawing

-p

papersize 'letter', default is 'a4'

This program creates one, two or three files with fragments of PostScript code, needed by the programs mapclust, mapdiff, mapmap, and maprgb, and mapvec:

transform file

This file is always needed, and will always be created by mapsetup.

clipping file

This file will only be created if the option -c is used.

map file

This file will only be created if the option -m is used.

If the option -L is used, it is assumed that all coordinated are given as pairs of longitude and latitude, and a suitable aspect ratio will be suggested, which can be used in the configuration file. Using this aspect ratio, the projection of countries away from the equator will look more or less natural. If the projection doesn't look natural enough, you can map all coordinates onto a more suitable projection using the program ll2grid.

The transform file defines a function that translates map coordinates to image coordinates. To create this function, mapsetup scans all input files given with the options -c, -l and -m, to find the minimum and maximum x- and y-coordinates. These extreme values are used to position the image on the centre of the page.

You should use the options -c and/or -m if you can. If not, use the option -l.

Unless a margin is specified with the option -b, a margin of 100 PostScript points is used (72 points is 1 inch) if info for clipping and/or map are present (options -c and/or -m), otherwise, a margin of 150 is used. In the latter case, the extra space is needed because painting will extend outward from each location.

The image is centred on a page of size A4, unless you use the option -p, in which case the papersize will be letter.

A clipping file defines the boundaries for the area that will be painted, for instance, the border of a country. You don't actually need this to use the software, but the maps don't look as good without it.

The data used for creating the clipping file is just a list of coordinate pairs, X and Y, stored in a file. The file can be divided in sections. Each section defines a polygon: straight lines are used to link one coordinate to the next.

You may get the data you need from a GIS database. Don't go for the very fine-grained polygons. If there are too many points used to define the clipping path, you may exceed the capacity of the PostScript device (or PDF device, after conversion).

For clipping purposes, each section should describe a single, closed area. Don't forget to repeat the first coordinate pair at the end of the section. You can have multiple sections to describe multiple areas, such as a country with an island off the cost of the main land.

It is also possible to cut out a region from another region, such as a large lake within a country.

The order of coordinates is important. You should always run areas that are supposed to be painted in one direction (clockwise), and regions that need to be cut out in the opposite direction (anti-clockwise).

One section (country, island, lake) consists of consecutive lines with coordinate pairs. A section ends when there is a line without coordinate pairs. If you want the input file to be used by the R program (with the polygon function), you should separate one section from the next with a line that has: NA NA

In this input file only, end of line comments are allowed. These comments will be copied to the output file, and can be helpful if you want to edit the result.

Here is an example, followed by the input file that can be used to create the clipping file:

    10 10   # begin big square, bottom left corner
    10 40   # line up (clockwise)
    40 40   # line right
    40 10   # line down
    10 10   # line left
    NA NA   # end big square
    50 30   # begin small square, bottom left corner
    50 40   # line up (clockwise)
    60 40   # line right
    60 30   # line down
    50 30   # line left
    NA NA   # end small square
    20 20   # begin hole in big square, bottom left
    30 20   # line right (anti-clockwise)
    30 30   # line up
    20 30   # line left
    20 20   # line down
	    # end hole in big square

The map file is used to draw lines onto the map, such as borders.

The input file used to create the map file is just like the input file used to create the clipping file. In this case, you don't have to worry about clockwise or anti-clockwise running polygons. Polygons don't have to be closed either. You can add lines for other things such as internal (state) borders, canals, whatever you like.

But you can use just the same data file to create both clipping file and map file. The result will be a map with lines running along all the borders, and no other lines.

The rest is for PostScript programmers only:

The map file draws all lines first as a continuous white line with linewidth 1.5, and then again in black with linewidth 0.5. You may want to edit the file to change this, to change line styles and colours, differentiating between different pieces.

You may want to add text. This simple example will print the text Island just below the little square in the map example above. The function Map translates map coordinates to image coordinates:

    50 30 Map moveto
    0 -12 rmoveto
    (Island) show