This will page will provide some basic tips for working with MapFiles. A more complete reference of the MapFile format is available on the
MapFile Complete Reference page. For information on the MapFile Generator, see the
tutorial.
Note about the Format
- MapFiles are simple text documents.
- Sections are delimited by a keyword and a corresponding 'END' statement.
- Comments are signified by a '#' character.
The Basics: the 'Map' Section
The 'MAP' object is the root level element of a MapFile. It contains all of the settings, including information about the individual layers. A few key settings are:
- IMAGETYPE - sets the output format of the image (e.g. 'png', 'jpeg', etc.)
- IMAGECOLOR - sets the background color of the image (format is "R G B", "255 255 255" would be white)
- EXTENT - sets the intial extents of the map. These are what your map will start at when initially loaded (unless the extents are programatically set).
- SHAPEPATH - A directory path which stores shapefiles for your layers (more below)
Adding Layers to a map
The 'LAYER' object stores information about a layer in the map (data source, symbology, etc.). A few important settings are:
- NAME - A descriptive name for the layer. Will show up the Legend.
- STATUS - Set whether this layer is enabled in the map. Values are 'ON', 'OFF', 'DEFAULT'.
- MINSCALE/MAXSCALE - Set the scale at which the layer will be rendered
- TYPE - Specifies how the underlying data should be drawn (i.e. polygon, point, etc.)
Accessing Data Sources, By Example
Below are a couple of examples of how to specify data sources within 'LAYER' objects.
Note: Connection info in MapFiles can be encrypted. Read more...
1) Shapefiles
Given that the SHAPEPATH keyword was set in the map as mentioned above, A shapefile can be used as so:
DATA city_limits
This would use the file 'city_limits.shp'.
2) PostGIS
An example for connecting to a PostGIS table would be like so:
CONNECTIONTYPE postgis
CONNECTION "user=myuser password=mypass dbname=mydb"
DATA "the_geom from city_limits"
3) ArcSDE
An example for connecting to ArcSDE would be like so:
CONNECTIONTYPE PLUGIN
PLUGIN "C:\Program Files\MapDotNet Server\v6.1.1\MapDotNetServer Web Service\bin\plugins\ArcSDE_9.1\msplugin_sde_91.dll"
CONNECTION "myserver,port:myserverport,mydb,myuser,mypass"
DATA "CSH.CSHUSER.CITY_BOUNDARY,SHAPE,SDE.DEFAULT"
PROCESSING "CLOSE_CONNECTION=DEFER"
For an ArcSDE raster layer, beginning at MapDotNet Server version 6.5, instead use only a DATA entry in LAYER object in your mapfile:
DATA "SDE:myserver,port,mydb,myuser,mypass,SDERASTERLAYERNAME,RASTERCOLUMN"
You will also need to create an environment variable called
GDAL_DRIVER_PATH
Set its value to the location of the appropriate GDAL plugin.
C:\Program Files\MapDotNetServer\v6.5\MapDotNetServerWCFHost\Bin\gdal\plugins\ArcSDE_9.1\
The ArcSDE examples use SDE 9.1. There are SDE and GDAL plugins for 9.0 and 9.2 as well, and all that needs to be changed is the PLUGIN path.
4) SpatialDB
An example for connecting to SpatialDB would be like so:
CONNECTIONTYPE spatialdb
CONNECTION "server=myserver;database= mydb;integrated security=false;uid= myuser;pwd= mypass;"
DATA "geometry from scratchpoint"
5) Oracle 10G/11G
CONNECTIONTYPE PLUGIN
PLUGIN "C:\Program Files\MapDotNet Server\v6.5\MapDotNetServer Web Service\bin\plugins\Oracle\msplugin_oracle.dll"
CONNECTION "
myuser/mypass@mydb"
DATA "SHAPE FROM mylake"
Note: 'mydb' would need to be configured in the TNSNAMES file in the Oracle client.
6) Microsoft SQL Server 2008
CONNECTIONTYPE PLUGIN
PLUGIN "C:\Program Files\MapDotNet Server\v6.5\MapDotNetServer Web Service\bin\plugins\MSSQL_2008\msplugin_mssql2008.dll"
CONNECTION "server=myserver;uid=myuser;pwd=mypass;database=mydb;Integrated Security=false"
DATA "the_geom from majorst"
Symbology
Symbology in mapfiles is controlled through the 'CLASS' object. Each layer must have at least one, and multiple can supplied to support complex theming. These class objects may contain one or more STYLE objects to control appearance. Some of the important 'CLASS' settings are:
- NAME - The name of the class as will show in the Legend.
- MINSCALE/MAXSCALE - same as layer
- EXPRESSION - This can be used with multiple classes for example:
EXPRESSION city_type eq 'Capital'
With this you could create unique symbology for rendering these shapes. More complicated expressions are possible, see the MapFile Reference for details. Alternatively, you can use EXPRESSION in coordination with the CLASSITEM property. Set this to the field your want to query and then you can use expression like so:
EXPRESSION 'Capital'
This is a little faster than the explicit version.
To set the actual symbology, we can configure the 'STYLE' object with these settings:
- COLOR - sets the color of the shapes (format is "R G B", "255 255 255" would be white)
- OUTLINECOLOR - sets the color to outline polygons (format is "R G B", "255 255 255" would be white). Note: To render a polygon with both a color and and outline color, two separate STYLE objects must be define, one containing the color, the other the outline.
- WIDTH - the width in pixels to draw a line
Labeling
Labeling for features is set through the 'LABEL' object beneath 'CLASS' objects. First, you must set the FONTSET setting beneath the MAP object:
MAP
FONTSET "../MapDotNetServer Data/fonts.txt"
...
This file should contain of paths to available truetype fonts, for example:
vera ./vera.ttf
verabold ./veraBd.ttf
Next, within the 'LAYER' object we want to render labels for, we can add a few settings:
- LABELITEM - This is the field in the underlying data source to render as the label
- LABELMINSCALE/LABELMAXSCALE - behaves just as MINSCALE/MAXSCALE.
Finally, we add the 'LABEL' object to our 'CLASS' objects. The most important settings are:
- COLOR - sets the color of the text (format is "R G B", "255 255 255" would be white)
- MINDISTANCE - The minimum distance in pixels between duplicate labels (useful for multipolygons)
- TYPE - The type of font 'bitmap' or 'truetype'
- SIZE - the font size in pixels or (tiny|small|medium|large|giant)
- FONT - the font name as specified in the FONTSET file (e.g. "verdana" for above)
- POSITION - position of label relative to labeling point (see reference for details)
- ANGLE - Angle to draw the label, or 'auto' for line features.
- PARTIALS - Set whether labels can extend off the edge of the map (true/false)
Projection and reprojecting on-the-fly
Data in maps can be reprojected by configurations with the mapFile. To do this we will use the 'PROJECTION' object. (Note: A map is not required to supply a projection)
First, we will set the projection for the map. This will serve as the output projection:
PROJECTION
"proj=utm"
"ellps=GRS80"
"datum=NAD83"
"zone=15"
"units=m"
"north"
"no_defs"
END
The projection object uses Proj4 projection strings. In accordance with this, we need to set the UNITS. For the above projection, we use meters:
UNITS meters
Finally, we set the projection for the layer that we want to reproject. This is the input projection. Note that all layers without a projection object will be assumed to be in the map's projection and thus not reprojected.
LAYER
PROJECTION
...
Note: reprojecting data on-the-fly can affect performance, so it is recommended that data be stored in the format that you want to present it.
Example mapFile
This example contains one layer with some pretty complex theming.
MAP
EXTENT -84.286 30.434 -84.274 30.44
SIZE 100 100
#default image size IMAGECOLOR 255 255 255
UNITS dd
IMAGETYPE png
FONTSET "../MapDotNetServer Data/fonts.txt"
WEB
# These are set by the mapFile Generator
IMAGEPATH "..\\MapDotNetServer Output\\"
IMAGEURL "../MapDotNetServer Output/"
END
# Symbol used by classes
SYMBOL
NAME "circle"
TYPE ellipse
FILLED true
POINTS 1 1 END
END #end symbol
LAYER
NAME "Roads"
STATUS ON
TYPE LINE
CONNECTIONTYPE postgis
CONNECTION "user=postgres password=******* dbname=postgis host=localhost port=5432"
DATA "the_geom from sp_leon_streets_wgs84"
LABELITEM "fullname"
LABELCACHE ON
CLASSITEM "class" # field used by EXPRESSION in class objects
CLASS # This class handles regular roads zoomed out from a distance
EXPRESSION /^[1,6,8,10,20,50,60,70]/
NAME "Streets"
MAXSCALE 150000
MINSCALE 30001
STYLE
SYMBOL 'circle'
COLOR 167 128 89
SIZE 1 # note the small size
END
END
CLASS # This class handles regular roads at mid-range
EXPRESSION /^[1,6,8,10,20,50,60,70]/
NAME "Streets"
MAXSCALE 30000
MINSCALE 5001
STYLE
SYMBOL 'circle'
COLOR 167 128 89
SIZE 6
END
STYLE # More complex symbology provides outline effect
SYMBOL 'circle'
COLOR 250 250 250
SIZE 4
END
END
CLASS # This class handles regular roads at close-range
EXPRESSION /^[1,6,8,10,20,50,60,70]/
NAME "Streets"
MAXSCALE 5000
MINSCALE 1
STYLE
SYMBOL 'circle'
COLOR 167 128 89
SIZE 14
END
STYLE
SYMBOL 'circle'
COLOR 250 250 250
SIZE 12
END
LABEL # Label only at close range
OUTLINECOLOR 255 255 255
MINDISTANCE 200
COLOR 0 0 0
TYPE TRUETYPE
SIZE 8
FONT "verdana"
POSITION cc
ANGLE AUTO
PARTIALS FALSE
END #end label
END
# Begin classes for state roads
CLASS
EXPRESSION /^[40]/
NAME "State Roads"
MAXSCALE 500001
MINSCALE 30001
STYLE
SYMBOL 'circle'
COLOR 167 128 89
SIZE 6
END
STYLE
SYMBOL 'circle'
COLOR 247 206 140
SIZE 4
END
END
CLASS
EXPRESSION /^[40]/
NAME "State Roads"
MAXSCALE 30000
MINSCALE 5001
STYLE
SYMBOL 'circle'
COLOR 167 128 89
SIZE 6
END
STYLE
SYMBOL 'circle'
COLOR 247 206 140
SIZE 4
END
LABEL
MINDISTANCE 200
OUTLINECOLOR 255 255 255
COLOR 0 0 0
TYPE TRUETYPE
SIZE 8
FONT "verdana"
POSITION cc
ANGLE AUTO
PARTIALS FALSE
END
END
CLASS
EXPRESSION /^[40]/
NAME "State Roads"
MAXSCALE 5000
MINSCALE 1
STYLE
SYMBOL 'circle'
COLOR 167 128 89
SIZE 14
END
STYLE
SYMBOL 'circle'
COLOR 247 206 140
SIZE 12
END
LABEL
MINDISTANCE 200
OUTLINECOLOR 255 255 255
COLOR 0 0 0
TYPE TRUETYPE
SIZE 8
FONT "verdana"
POSITION cc
ANGLE AUTO
PARTIALS FALSE
END
END
# Begin classes for Interstates
CLASS
EXPRESSION /^[30]/
NAME "Interstate Roads"
MAXSCALE 1000000
MINSCALE 500001
STYLE
SYMBOL 'circle'
COLOR 167 128 89
SIZE 6
END
STYLE
SYMBOL 'circle'
COLOR 255 250 115
SIZE 4
END
END
CLASS
EXPRESSION /^[30]/
NAME "Interstate Roads"
MAXSCALE 500001
MINSCALE 30001
STYLE
SYMBOL 'circle'
COLOR 167 128 89
SIZE 6
END
STYLE
SYMBOL 'circle'
COLOR 255 250 115
SIZE 4
END
END
CLASS
EXPRESSION /^[30]/
NAME "Interstate Roads"
MAXSCALE 30000
MINSCALE 1
STYLE
SYMBOL 'circle'
COLOR 167 128 89
SIZE 6
END
STYLE
SYMBOL 'circle'
COLOR 255 250 115
SIZE 4
END
END
END
END
This produces:
