Map Files

Map Object

  • extent [minx] [miny] [maxx] [maxy]: The spatial extent of the map to be created. Most often set by the mapserv program. Inital value serves as a default.
  • fontset [filename]: Full filename of fontset file to use.
  • imagecolor [r] [g] [b]: Color to initialize the map with (i.e. background).
  • interlace [on|off]: Should interlaced images be output. Default is on.
  • layer: Signals the start of a layer object.
  • legend: Signals the start of a legend object.
  • lineset [filename]: Full filename of lineset file to use.
  • markerset [filename]: Full filename of markerset file to use.
  • name [string]: Prefix attached to maps, scalebar and lengends created using this file. Should be just a couple of characters.
  • querymap: Signals the start of a querymap object.
  • reference: Signals the start of a reference map object.
  • scale [double]: Computed scale of the map. Set most often by the application.
  • scalebar: Signals the start of a scalebar object.
  • shadeset [filename]:: Full filename of shadeset file to use.
  • shapepath [path]: Path to a collection of shapefiles or tiles.
  • size [cols] [rows]: Size, in pixels, of image.
  • status [on|off]: Is map drawing active? Sometimes you may only want a legend or a scalebar.
  • tile [string]: Name of a directory containing shapefiles (see shapepath).
  • transparent [on|off]: Should the background color for the maps be transparent. Default is off.
  • units [feet|inches|kilometers|meters|miles|dd]: Units of the map coordinates. Used for scalebar and scale computations.
  • web: Signals the start of a web object.
  • Label Object

    Defines how specific object, layer, scalebar or legend is labeled. Starts with the keyword label and terminates with the keyword end. Note that scalebars only support bitmapped fonts.

  • antialias: Should text be antialiased. Note that this requires more available colors and results in slightly larger output images.
  • buffer [integer]: Padding (in pixels) around labels. Useful for maintaining spacing around text to enhance readability. Available only for cached labels. Default is 0.
  • backgroundcolor [r] [g] [b]: Color to draw one pixel text outline with. Off by default.
  • color [r] [g] [b]: Color to draw text with.
  • font [filename]: Font alias (a defined in the fontset) to use for labeling.
  • mindistance [integer]: Minimum distance between duplicate labels. Given in pixels.
  • minfeaturesize [integer|auto]: Minimum size a feature must be to be labeled . Given in pixels. Presently only line and line annotation features are affected by this limit. Auto keyword tells MapServer to only label features that are larger than their corresponding label. Available only for cached labels.
  • maxscale [double]: Maximum scale at which labels are drawn.
  • maxsize [integer]: Maximum font size to use when scaling text (pixels). Default is 256.
  • minscale [double]: Minimum scale at which labels are drawn.
  • minsize [integer]: Minimum font size to use when scaling text (pixels). Default is 4.
  • offset [x] [y]: Offset values for a label relative to the lower left hand corner of the label and the label point. Given in pixels. In the case of rotated text specify the values as if all labels are horizontal and any rotation will be compensated for.
  • partials [true|false]: Can text run of the edge of the map. Default is true.
  • position [ul|uc|ur|cl|cc|cr|ll|lc|lr|auto]: Position of label relative to a label point (layers only). First letter is Y position (upper, center or lower), second is X position (left, center or right). Very similar to ArcPlot "textpostion" command. Auto tells the MapServer to calculate a label position that does not interfere with other labels. With points and polygons the MapServer selects from the 8 outer positions (ie. exluding cc), lines only use uc and lc, until it finds a position that doesn't collide with labels that have already been drawn. If all positions cause overlap, then the label is not drawn. Auto placement is only available for cached labels. The position keyword applies to layer labels only (i.e. not legends or scalebars).
  • size [integer or tiny|small|medium|large|giant]: Text size. If using a TrueType font then the size is specified in pixels or points. If using built-in bitmap fonts then the size is one of the 5 listed keywords.
  • type [bitmap|truetype]: Sets the type of font to use. Generally, bitmap fonts are faster to draw than TrueType fonts. However, TrueType fonts are scalable and are available in a variety of faces.
  • wrap [character]: Character that represents and end-of-line condition in label text, thus resulting in a multiline label. Multiline labels are placed correctly
  • Layer Object

    Defines how an individual layer is handled. Starts with the keyword layer and terminates with the keyword end. Layers are the basic tool for putting a map together. The order in the map file is significant. The layers are drawn in the order they are defined and are queried in reverse order. Labels are entered into the label cache in the order the layers are processed as well. Most important annotation should be listed first in the map file to ensure it is drawn if labeloverlap is false.

  • classitem [string]: Item name in attribute table to use for class lookups.
  • data [filename]: Full filename of the spatial data to process. No file extention is necessary for shapefiles. May be a relative filename when used with the shapepath or tile options mentioned above.
  • description [string]: A short description of this layer. This can be accessed by template files as a means of creating specialized title, etc.
  • feature: Signals the start of an inline feature object.
  • footer [filename]: Template to use after a layers set of results have been sent. Multiresult query modes only.
  • group [name]:
  • header [filename]: Template to use before a layers set of results have been sent. Multiresult query modes only.
  • index [filename]: Full filename for the index or tile definition for this layer. Similar to an Arc/Info library index, this shapefile contains polygon features for each tile. Each feature must have an attribute named "location" that contains the path to the tile sub-directory. See the notes section above for information on relative and absolute paths.
  • labelangleitem [string]: Item name in attribute table to use for class annotation angles. Values should be in degrees.
  • labelcache [on|off] Specifies whether labels should be drawn as the features for this layer are drawn or whether they should be cached and drawn after all layers have been drawn. Default is on. Label overlap removal, auto placement etc., are only available when the label cache is active.
  • labelitem [string]: Item name in attribute table to use for class annotation.
  • labelmaxscale [double]: Maximum scale at which this layer is labeled.
  • labelminscale [double]: Minimum scale at which this layer is labeled.
  • labelsizeitem [string]: Item name in attribute table to use for class annotation sizes. Values should be in pixels.
  • maxfeatures [integer]: Specifies the number of features that should be drawn for this layer in the CURRENT window. Has some interesting uses with annotation and with sorted data (i.e. lakes by area).
  • maxscale [double]: Maximum scale at which this layer is drawn.
  • minscale [double]: Minimum scale at which this layer is drawn.
  • name [string]: Short name for this layer. Limit is 20 characters. This name is the link between the map file and web interfaces that refer to this name. They must be identical. The name should be unique. Use the "group" option to associate layers with each other.
  • query: Signals the start of a query object.
  • queryitem [string]: Item name in attribute table to use for queries or query lookups.
  • symbolscale [double]: The scale at which symbols and/or text appear fullsize. This allows for dynamic scaling of objects based on the scale of the map. If not set then this layer will always appear at the same size. Scaling only takes place within the limits of minsize and maxsize as described above.
  • status [on|off|default|queryonly]: Sets the current status of the layer. Often modified by the MapServer program. Default turns the layer on permanently. Queryonly means the layer can be queried but not drawn.
  • tolerance [integer]: Sensitivity for image based queries (i.e. via mouse). Given in pixels with a default of 3 pixels. To restrict polygon searches so that the mouse click must occur in the polygon set the tolerance to zero.
  • transform [true|false]: Tells the MapServer whether or not a particular layer needs to be transformed from some coordinate system to image coordinates. Default is true. This allows you to create shapefiles in image/graphics coordinates and therefore have features that will always be displayed in the same location on every map. Ideal for placing logos or text in maps. Remember that the graphics coordinate system has an origin in the upper lefthand corner of the image, contrary to most map coordinate systems.
  • type [point|line|polyline|polygon|annotation|raster]: Specifies how the data should be drawn. Need not be the same as the shapefile type. For example, a polygon shapefile may be drawn as a point layer, but a point shapefile may not be drawn as a polygon layer. Common sense rules. Annotation means that a label point will be calculated for the features, but the feature itself will not be drawn although a marker symbol can be optionally drawn. This allows for advanced labeling like numbered highway shields. Points are labeled at that point. Polygons are labeled using, firest a centroid, and if that doesn't fall in the polygon a scanline approach is used to gaurantee the label point falls within the feature. Lines are labeled at the middle of the longest arc in the visible portion of the line.
  • Class Object

    Used to define thematic classes for a given layer and each (vector) layer must have at least one class. In cases with more than one class, membership is determined using attribute values and regular expressions. Starts with the keyword class and terminates with the keyword end.

  • backgroundcolor [r] [g] [b]: Color to use for non-transparent symbols.
  • color [r] [g] [b]: Color to use for drawing features.
  • expression [string]: Three types of expressions are now supported to define class membership. String comparisons, regular expressions, and simple logical expressions. If no expression is given then all features are said to belong to this class.
  • - String comparisions are case sensitive and are the fastest to evaluate. No special delimiters necessary although strings must be quoted if they contain special characters.

     - Regular expressions function just like previous versions of MapServer. However, you must now delimit a regular expression using /regex/. No quotes should be used.

     - Logical expressions allow you to build fairly complex tests based on one or more attributes and therefore are only available with shapefiles. Logical expressions are delimited by (expression). Attribute names are delimited by [attribute]. These names are case sensitive and must match the items names in the shapefile. For example ([AGE] > 50 and '[COLOR]' eq 'RED' - note the use of quotes). The logical operators you'd expect are supported: or, and, lt, gt, ge, le and eq. You may also use numeric operators within an expression to define simple models. As you might expect this level of flexibility is slower to process.

    String comparisons and regular expressions work from the classitem defined at the layer level. You may mix expression types within the classes of a layer.
  • label: Signals the start of a label object.
  • maxsize [integer]: Maximum size in pixels to draw a symbol. Default is 50.
  • minsize [integer]: Minimum size in pixels to draw a symbol. Default is 0.
  • name [string]: Name to use in legends for this class. If not set the class won't show up in a legend.
  • outlinecolor [r] [g] [b]: Color to use for outlining polygons and certain marker symbols. Line symbols do not support outline colors.
  • size [integer]: Height, in pixels, of the symbol/pattern to be used. Only useful with scalable symbols. The default is 1.
  • symbol [integer]: The symbol number, from the symbol file, to use for all features if attribute tables are not used. Default is 0, which results in a single pixel, single width line or solid polygon fill depending on layer type.
  • text [string]: Static text to label features in this class with. This overrides values obtained from the attribute labelitem The string may be given as an expression deliniated using ()'s. This allows you to concatenate multiple attributes into a single label. For example, ([firstname], [lastname]).
  • Feature Object

    Used to define inline features. You can use inline features when it's not possible (or too much trouble) to create a shapefile. Inline features can also be built via urls or forms. Starts with the keyword feature and terminates with the keyword end.

  • points:
  • class [string]: String to use to classify this feature. In cases where a layer has multiple classes defined the class string is evaluated against the class expressions. This is effectively the same as pulling data from an attribute in a shapefile (see classitem in the class object).
  • text [string]: String to use for labeling this feature.
  • Legend Object

    Defines how a legend is to be built. Legned components are built automatically from class object definitions from individual layers. Starts with the keyword legend and terminates with the keyword end. The size of the legend image is not known prior to creation so be carefull not to hardcode width and height in the img tag in the template file. Future versions will make the image size available. Multiline labels are supported (see label object), but do not render correctly in the current version.

  • embed [true|false]: Is the legend image to be embeded. Default is false.
  • imagecolor [r] [g] [b]: Color to initialize the legend with (i.e. background).
  • label: Signals the start of a label object.
  • outlinecolor [r] [g] [b]: Color to use for outlining symbol key boxes.
  • position [ul|uc|ur|ll|lc|lr]: Where to place an embeded legend in the image. Default is lr.
  • size [x][y]: Size of symbol key boxes in pixels. Default is 20 by 10.
  • spacing [x][y]: Spacing between symbol key boxes (y) and labels (x) in pixels. Default is 5 by 5.
  • status [on|off]: Is the legend image to be created. Default is off.
  • Query Object

    Defines how a specific query is handled. Starts with the keyword query and terminates with the keyword end.

  • expression [string]: Regular expression that defines membership in this query.
  • join: Signals the start of a join object.
  • template [filename|url]: Template file or url to use in presenting the results to the user.
  • QueryMap Object

    Defines a mechanism to map the results of a query. Starts with the keyword querymap and terminates with the keyword end.

    Join Object

    Defines how a specific join is handled. Starts with the keyword join and terminates with the keyword end. Joins are defined within a query object.

  • from [item]: Join item in the shapefile.
  • name [string]: Unique name for this join. Required value.
  • table [file]: Name of XBase file (must be fullpath) to join to.
  • template [filename]: Template to use with one-to-many joins. The template is processed once for each record and can only contain substitutions for items in the joined table.
  • to [item]: Join item in the table to be joined.
  • type [multiple|single]: The type of join. Default is single (i.e. one-to-one).
  • Reference Map Object

    Defines how reference maps are to be created. Starts with the keyword reference and terminates with the keyword end. Three types of reference maps are supported. The most common would be one showing the extent of an map in an interactive interface. It is also possible to request reference maps as part of a query. Point queries will generate an image with a marker (see below) placed at the query point. Region based queries will depict the extent of the area of interest. Finally, feature based queries will display the selection feature(s) used.

  • color [r][g][b]: Color that the reference box is drawn in. Set any component to -1 for no fill.
  • extent [minx] [miny] [maxx] [maxy]: The spatial extent of the base reference image.
  • image [filename]: Full filename of the base reference image. Must be a GIF image.
  • outlinecolor [r][g][b]: Color to use for outlining the reference box. Set any component to -1 for no outline.
  • size [cols] [rows]: Size, in pixels, of the base reference image.
  • status [on|off]: Is the reference map to be created. Default is off.
  • Scalebar Object

    Defines how a scalebar should be built. Starts with the keyword scalebar and terminates with the keyword end. Scalebars currently do not make use of TrueType fonts. The size of the scalebar image is not known prior to creation so be carefull not to hardcode width and height in the img tag in the template file. Future versions will make the image size available.

  • backgroundcolor [r] [g] [b]: Color to use for scalebar backgound, not the image background.
  • color [r] [g] [b]: Color to use for drawing all features if attribute tables are not used.
  • embed [true|false]: Is the scalebar image to be embeded. Default is false.
  • imagecolor [r] [g] [b]: Color to initialize the scalebar with (i.e. background).
  • intervals [integer]: Number of intervals to break the scalebar into. Default is 4.
  • label: Signals the start of a label object.
  • outlinecolor [r] [g] [b]: Color to use for outlining individual intervals. Set any component to -1 for none which is the default.
  • position [ul|uc|ur|ll|lc|lr]: Where to place an embeded scalebar in the image. Default is lr.
  • size [cols] [rows]: Size, in pixels, of the scalebar. X secifies the rough width of the scalebar itself, so actual width may vary a bit. Y specifies the thickness of the bar itself. Neither takes into account labeling.
  • status [on|off]: Is the scalebar image to be created? Default is off.
  • style [integer]: Chooses the scalebar style. Valid styles are 0 and 1.
  • units [feet|inches|kilometers|meters|miles]: Output scalebar units, default is miles. Used in conjunction with the map's units to develop the actual graphic. Note that decimal degrees are not valid scalebar units.
  • Web Object

    Defines how a web interface will operate. Starts with the keyword web and terminates with the keyword end.

  • footer [filename]: Template to use after anything else is sent. Multiresult query modes only.
  • header [filename]: Template to use before after everything else has been sent. This option is only available with queries.
  • imagepath [path]: Path to the temporary directory for writing temporary files and images. Must be writable by the user the web server is running as. Must end with a / or \ depending on platform. Previously set in the mapserv.ini file.
  • imageurl [path]: Base URL for imgpath. Not really needed as you can address this easily in a template. Must end with a /. Previously set in the mapserv.ini file.
  • log [filename]: File to log MapServer activity in. Must be writable by the user the web server is running as. Previously set in the mapserv.ini file.
  • maxscale [double]: Maximum scale at which this interface is valid. When a user requests a map at a smaller scale a generic MapServer error is returned. The maxtemplate could be used to provide a more user-friendly message.
  • maxtemplate [filename|url]: Template file or url to use in presenting the results to the user when above the maxscale. Useful for nesting interfaces.
  • minscale [double]: Minimum scale at which this interface is valid. When a user requests a map at a larger scale a generic MapServer error is returned. The maxtemplate could be used to provide a more user-friendly message.
  • mintemplate [filename|url]: Template file or url to use in presenting the results to the user when below the minscale. Useful for nesting interfaces.

  • template [filename|url]: Template file or url to use in presenting the results to the user in an interactive mode (i.e. map generates map and so on...).