The query feature requires a TEMPLATE object in the CLASS object of your LAYER definition. The value points to a html fragment using MapServer template syntax.

Example MapFile fragment:

LAYER
  NAME Parcel9
  TYPE POLYGON
  STATUS OFF
  DATA Parcels/area09_parcels
  CLASS
    STYLE
      OUTLINECOLOR 128 128 128
      COLOR 153 205 255
    END
    TEMPLATE "templates/Parcels/area09_parcels.html"
  END

  HEADER "templates/Parcels/area09_parcels_header.html"
  FOOTER "templates/Parcels/area09_parcels_footer.html"

END

Example Template:

<tr>
  <td>[lrn]</td>
  <td>[PIN]</td>
</tr>

The [lrn] is a special keyword that indicates the resulting line number which starts at 1. [PIN] is the name of a feature attribute.

WEB Object

...(snip) .. EMPTY optional URL to forward users to if a query fails. If not defined the value for ERROR is used.

Value: [url]

ERROR optional, however highly suggested! URL to forward users to if an error occurs. Ugly old MapServer error messages will appear if this is not defined.

Values: [url]

LOG optional File to log MapServer activity in. Must be writable by the user the web server is running as.

Value: [filename]

"Mapping Hacks" by Schuyler Erle, Rich Gibson, and Jo Walsh is available from O'Reilly.

"Web Mapping Illustrated" by Tyler Mitchell is available from O'Reilly. Introduces MapServer and many other related technologies including, GDAL/OGR, MapScript, PostGIS, map projections, etc.

"MapServer: Open Source GIS Development" by Bill Kropla.

See the Win32 Compilation Howto.

MapServer's version numbering scheme is very similar to Linux's. For example, a MapServer version number of 4.2.5 can be decoded as such:

• 4: Major version number. MapServer releases a major version every two to three years.
• 2: Minor version number. Increments in minor version number almost always relate to additions in functionality.
• 5: Revision number. Revisions are bug fixes only. No new functionality is provided in revisions.

From a developer's standpoint, MapServer version numbering scheme is also like Linux. Even minor version numbers (0..2..4..6) relate to release versions, and odd minor versions (1..3..5..7) correspond to developmental versions.

Q: Is MapServer thread-safe?

A: Generally, no (but see the next question). Many components of MapServer use static or global data that could potentially be modified by another thread. Under heavy load these unlikely events become inevitable, and could result in sporadic errors.

Q: Is it possible to safely use any of MapServer in a multi-threaded application?

A: Some of it, yes, with care. Or with Python :) Programmers must either avoid using the unsafe components of MapServer or carefully place locks around them. Python's global interpreter lock immunizes against MapServer threading problems; since no mapscript code ever releases the GIL all mapscript functions or methods are effectively atomic. Users of mapscript and Java, .NET, mod_perl, or mod_php do not have this extra layer of protection.

A: Which components are to be avoided?

Q: Below are lists of unsafe and unprotected components and unsafe but locked components.

Unsafe:

• OGR layers: use unsafe CPL services
• Cartoline rendering: static data
• Imagemap output: static data
• SWF output: static data and use of unsafe msGetBasename()
• SVG output: static data
• WMS/WFS server: static data used for state of dispatcher
• Forcing a temporary file base (an obscure feature): static data
• MyGIS: some static data

Unsafe, but locked:

• Map config file loading: global parser
• Setting class and and layer filter expressions (global parser)
• Class expression evaluation (global parser)
• Setting map and layer projections (PROJ)
• Raster layer rendering and querying (GDAL)
• Database Connections (mappool.c)
• PostGIS support
• Oracle Spatial (use a single environment handle for connection)
• SDE support (global layer cache)
• Error handling (static repository of the error objects)
• WMS/WFS client connections: potential race condition in Curl initialization
• Plugin layers (static repository of the loaded dll-s)

Rather coarse locks are in place for the above. Only a single thread can use the global parser at a time, and only one thread can access GDAL raster data at a time. Performance is exchanged for safety.

WEB Object

...(snip) .. EMPTY optional URL to forward users to if a query fails. If not defined the value for ERROR is used.

Value: [url]

ERROR optional, however highly suggested! URL to forward users to if an error occurs. Ugly old MapServer error messages will appear if this is not defined.

Values: [url]

LOG optional File to log MapServer activity in. Must be writable by the user the web server is running as.

Value: [filename]

• Tuning your mapfile for performance
• Optimizing the performance of vector data sources
• Optimizing the performance of raster data sources
• Tileindexes for mosaicing and performance

• First ands foremost is hardware. An extra GB of RAM will give your map performance increases beyond anything you're likely to achieve by tweaking your data. With the price of RAM these days, it's cheap and easy to speed up every map with one inexpensive upgrade.
• Use the scientific method. Change one thing at a time, and see what effect it had. Try disabling all layers and enabling them one at a time until you discover which layer is being problematic.
• You can use the shp2img program to time your results. This runs from the command line and draws an image of your entire map. Since it's run from the command line, it is immune to net lag and will give more consistent measurements that your web browser.

There's confusion over what POLYLINE means in MapServer and via ESRI. In MapServer POLYLINE simply means a linear representation of POLYGON data. With ESRI polyline means multi-line. Old versions of the Shapefile techical description don't even refer to polyline shapefiles, just line. So, ESRI polyline shapefiles are just linework and can only be drawn and labeled as LINE layers. Those shapefiles don't have feature closure enforced as polygon shapefiles do which is why the distinction is so important. I suppose there is a better choice than POLYLINE but I don't know what it would be.

Note that the only difference between POLYLINE and LINE layers is how they are labeled.

Q: Is MapServer thread-safe?

A: Generally, no (but see the next question). Many components of MapServer use static or global data that could potentially be modified by another thread. Under heavy load these unlikely events become inevitable, and could result in sporadic errors.

Q: Is it possible to safely use any of MapServer in a multi-threaded application?

A: Some of it, yes, with care. Or with Python :) Programmers must either avoid using the unsafe components of MapServer or carefully place locks around them. Python's global interpreter lock immunizes against MapServer threading problems; since no mapscript code ever releases the GIL all mapscript functions or methods are effectively atomic. Users of mapscript and Java, .NET, mod_perl, or mod_php do not have this extra layer of protection.

A: Which components are to be avoided?

Q: Below are lists of unsafe and unprotected components and unsafe but locked components.

Unsafe:

• OGR layers: use unsafe CPL services
• Cartoline rendering: static data
• Imagemap output: static data
• SWF output: static data and use of unsafe msGetBasename()
• SVG output: static data
• WMS/WFS server: static data used for state of dispatcher
• Forcing a temporary file base (an obscure feature): static data
• MyGIS: some static data

Unsafe, but locked:

• Map config file loading: global parser
• Setting class and and layer filter expressions (global parser)
• Class expression evaluation (global parser)
• Setting map and layer projections (PROJ)
• Raster layer rendering and querying (GDAL)
• Database Connections (mappool.c)
• PostGIS support
• Oracle Spatial (use a single environment handle for connection)
• SDE support (global layer cache)
• Error handling (static repository of the error objects)
• WMS/WFS client connections: potential race condition in Curl initialization
• Plugin layers (static repository of the loaded dll-s)

Rather coarse locks are in place for the above. Only a single thread can use the global parser at a time, and only one thread can access GDAL raster data at a time. Performance is exchanged for safety.

No.

Reverse geocoding is an activity where you take a list of street features that you already have and generate postal addresses from them. This kind of spatial functionality is provided by proprietary packages such as the ESRI suite of tools, as well as services such as those provided by GDT. MapServer is for map rendering, and it does not provide for advanced spatial operations such as this.

No.

Geocoding is an activity where you take a list of addresses and generate lat/lon points for them. This kind of spatial functionality is provided by proprietary packages such as the ESRI suite of tools, as well as services such as those provided by GDT. MapServer is for map rendering, and it does not provide for advanced spatial operations such as this.

If you are using MapScript, there is a free geocder available through XMLRPC and SOAP at http://geocoder.us . You could hook you application up to use this service to provide lat/lon pairs for addresses, and then use MapServer to display those points.

You must set the symbol for the LAYER to be 'circle' and then you can set the symbol SIZE to be the width you want. A 'circle' symbol can be defined as:

SYMBOL
  NAME 'circle'
  TYPE ELLIPSE
  FILLED TRUE
  POINTS 1 1 END
END

The default output format for MapServer is 8bit pseudo-colored PNG or GIF. Inherently there will be some color degredation in converting a 24bit image (16 million colors) image into 8bit (256 colors).

But in order to ensure fast rendering MapServer uses quite a simple method to do the transformation, converting pixels to the nearest color in a 175 color colorcube. This will usually result in blotchy color in a fairly smoothly varying image.

Solutions include:

• Select 24bit output. This might be as easy as "IMAGETYPE JPEG" in your MAP section.
• Enable dithering (PROCESSING "DITHER=YES") to produce a better color appearance.
• Preprocess your image to 8bit before using it in MapServer with an external application like the GDAL rgb2pct.py script.

For more information review the Raster HOWTO document.

Although Mapscript can generate the map in any desired image format it sufficient to only consider the three most prevalent ones: JPEG, PNG, and GIF.

JPEG is an image format that uses a lossy compression algorithm to reduce an image's file size and is mostly used when loss of detail through compression is either not noticeable or negligible, as in most photos. Maps on the other hand mainly consist of fine lines and areas solidly filled in one colour, which is something JPEG is not known for displaying very well. In addition, maps, unless they include some aerial or satellite imagery, generally only use very few different colours. JPEG with its 24bit colour depth capable of displaying around 16.7 million colours is simple not suitable for this purpose. GIF and PNG however use an indexed colour palette which can be optimized for any number (up to 256) of colours which makes them the perfect solution for icons, logos, charts or maps. The following comparison (generated file sizes only; not file generation duration) will therefore only include these two file formats:

PIL does not support interlaced PNGs at this time (no timetable on when it actually will either). To be able to read PNGs in PIL, they must not be interlaced. Modify your OUTPUTFORAT with a FORMATOPTION like so:

OUTPUTFORMAT
  NAME png
  DRIVER "GD/PNG"
  MIMETYPE "image/png"
  IMAGEMODE RGB
  EXTENSION "png"
  FORMATOPTION "INTERLACE=OFF"
END

In order to render some classes of symbols properly in 24bit output, such as symbols from true type fonts, it is necessary to force rendering to occur in RGBA. This can be accomplished by including the "TRANSPARENCY ALPHA" line in the layer definition. Don't use this unnecessarily as there is a performance penalty.

This problem also affects PNG24 output or any RGB output format. 8bit (PC256) or RGBA output types are already ok.

You can use an inline feature, with the FEATURE object, to make a point on your map. Use the TEXT parameter of the FEATURE object for the actual text of the notice, and a LABEL object to style the notice.

LAYER
  NAME copyright
  STATUS ON
  TYPE annotation
  TRANSFORM ll #set the image origin to be lower left
  FEATURE
    POINTS
      60 -10 #set the offset from lower left position in pixels
    END
    TEXT "© xyz company 2006" #this is your displaying text
  END   
  CLASS
    LABEL #defines the font, colors etc. of the text
      FONT "sans"
      TYPE TRUETYPE
      SIZE 8
      BUFFER 1
      COLOR 0 0 0
      BACKGROUNDCOLOR 255 255 255
      FORCE TRUE
    END
  END 
  UNITS PIXELS #sets the units for the feature object
END

Result

For historical reasons, width has two meanings within the context of filling polygons and stroke widths for the outline. If a polygon is filled, then the width defines the width of the symbol inside the filled polygon. In this event, the outline width is disregarded, and it is always set to 1. To acheive the effect of both a fill and an outline width, you need to use two styles in your class.

STYLE # solid fill
  COLOR 255 0 0
END
STYLE # thick outline (could use a circle symbol with size too)
  OUTLINECOLOR 0 0 0
  WIDTH 3
  ANTIALIAS TRUE
END

The easiest way to produce antialiased lines is to:

• use a 24-bit output image type (IMAGEMODE RGB (or RGBA))
• set TRANSPARENCY ALPHA in the layer using antialiased lines
• set ANTIALIAS TRUE in the STYLE element of the CLASS with antialiased lines

The following mapfile snippets enable antialiased county borders:

...
IMAGETYPE png24
...
OUTPUTFORMAT
  NAME png24
  DRIVER "GD/PNG"
  MIMETYPE "image/png"
  IMAGEMODE RGB
  EXTENSION "png"
END
...
LAYER
  NAME counties
  TYPE line
  STATUS default
  DATA "bdry_counln2"
  TRANSPARENCY alpha
  SYMBOLSCALE 5000000
  CLASS
    STYLE
       WIDTH 3
       COLOR 1 1 1
       ANTIALIAS true
    END
  END
END
...

Note that the bdry_counln2 shapefile referenced in the counties layer is a line shapefile. A polygon shapefile could be substituted with roughly the same results, though owing to the nature of shapefiles each border would be rendered twice and the resulting output line would likely appear to be slightly thicker. Alternatively, one could use a polygon shapefile, set TYPE to POLYGON, and use OUTLINECOLOR in place of COLOR in the STYLE element.

Note that you can tweak the combination of STYLE->WIDTH and SYMBOLSCALE to modify line widths in your output images.

Apparently cartoline symbols can be used to achieve fancier effects.

• Web Map Service (OGC:WMS) 1.0.0, 1.0.7, 1.1.0 and 1.1.1
• Web Feature Service (OGC:WFS) 1.0.0, 1.1.0
• Web Coverage Service (OGC:WCS) 1.0.0, 1.1.0
• Geography Markup Language (OGC:GML) 2.1.2, 3.1.0 Level 0 Profile
• Web Map Context Documents (OGC:WMC) 1.0.0, 1.1.0
• Styled Layer Descriptor (OGC:SLD) 1.0.0
• Filter Encoding Specification (OGC:FES) 1.0.0
• Sensor Observation Service (OGC:SOS) 0.1.2b, 1.0.0
• OWS Common (OGC:OWS) 1.0.0, 1.1.0

Some ArcIMS sites are not set up to stretch the returned image to fit the requested envelope by default. This results in a map with data layers that overlay well in the center of the map, but not towards the edges. This can be solved by adding "reaspect=false" to the request (by tacking it on to the connection string).

For example, if your mapfile is in a projection other than EPSG:4326, the following layer will not render correcly:

LAYER
      NAME "hillshade"
      TYPE RASTER
      STATUS OFF
      TRANSPARENCY 70
      CONNECTIONTYPE WMS
      CONNECTION "http://gisdata.usgs.net:80/servlet19/com.esri.wms.Esrimap/USGS_WMS_NED?"
      PROJECTION
              "init=epsg:4326"
      END
      METADATA
              "wms_srs" "EPSG:4326"
              "wms_title" "US_NED_Shaded_Relief"
              "wms_name" "US_NED_Shaded_Relief"
              "wms_server_version" "1.1.1"
              "wms_format" "image/png"
      END
END

Adding "reaspect=false" to the connection string solves the problem:

LAYER
      NAME "hillshade"
      TYPE RASTER
      STATUS OFF
      TRANSPARENCY 70
      CONNECTIONTYPE WMS
      CONNECTION "http://gisdata.usgs.net:80/servlet19/com.esri.wms.Esrimap/USGS_WMS_NED?reaspect=false"
      PROJECTION
              "init=epsg:4326"
      END
      METADATA
              "wms_srs" "EPSG:4326"
              "wms_title" "US_NED_Shaded_Relief"
              "wms_name" "US_NED_Shaded_Relief"
              "wms_server_version" "1.1.1"
              "wms_format" "image/png"
      END
END

The OGC:WMS 1.1.0 and 1.1.1 specifications (which are both supported by MapServer) state that, for GetCapabilities responses, the OGC:WMS server returns a specific MIME type (i.e. application/vnd.ogc.xml (see subclause 6.5.3 of OGC:WMS 1.1.1.

A MIME type is passed from the web server to the client (in your case, a web browser), from which a client can decide how to process it.

Example 1: if using a web browser, if a web server returns an HTTP Header of "Content-type:image/png", then the web browser will know that this is a PNG image and display it accordingly.

Example 2: if using a web browser, if a web server returns an HTTP Header of "Content-type:text/html", then the web browser will know that this is an HTML page and display it accordingly (i.e. tables, divs, etc.)

Basically, what is happening is that the OGC:WMS is returning, in the headers of the HTTP response, a MIME type which your web browser does not understand, which usually prompts a dialog box on whether to open or download the content (i.e. Content-type:application/vnd.ogc.wms_xml).

You could configure your web browser to handle the application/vnd.ogc.wms_xml MIME type a certain way (i.e. open in Notepad, etc.).

This was a major change for WMS Server support in MapServer 5.0. MapServer WMS Server GetMap requests now require the following additional parameters:

• srs
• bbox
• width
• height
• format
• styles

Note that these parameters were always required in all versions of the WMS specification, but MapServer previously had not required them in a client request (even though most OGC WMS clients would issue them anyway to be consistent with the WMS spec).

The request below now constitutes a valid GetMap request:

http://wms.example.com/wms?service=WMS&version=1.1.1&request=GetMap&layers=foo&srs=EPSG:4326&bbox=-180,-90,180,90&format=image/png&width=400&height=300&styles=default

Which is consistent with the WMS specification.

More information on these parameters can be found in the WMS Server howto and the OGC WMS 1.1.1 specification

For more detailed information, see ticket 1088

UPDATE: STYLES, though a required WMS parameter, is now optional again in MapServer. For more detailed inforamation, see ticket 2427

There is a text file "epsg" in your PROJ4 installation (e.g. "/usr/local/share/proj/epsg") which contain the EPSG information used by PROJ4. In Windows, this is often located in C:\proj\nad or is found with an environment variable called PROJ_LIB.

http://spatialreference.org allows you to search for EPSG codes.

You can also have a look at: http://ocean.csl.co.uk

More information to EPSG: http://www.epsg.org

More information to PROJ4: http://proj.maptools.org

With ogr2ogr of course! ogr2ogr is a powerful utility that will transform the projections of your shapefiles when passed the appropriate parameters. In my case, I was using Mapserver to serve data in RI State Plane Feet. In order to do so, the data had to first be converted to meters. Here is the command I used:

ogr2ogr -t_srs EPSG:32130 output.shp input.shp

Since my data already had a projection defined, I did not need to explicitly state a source projection. This command uses the EPSG definition for NAD83 Rhode Island (32130) and performs the feet to meters conversion.

Now say my data wasn't already projected? Here's how we deal with that:

ogr2ogr -s_srs "+proj=tmerc +lat_0=41.08333333333334 +lon_0=-71.5 +k=0.999994 +x_0=100000 +y_0=0 +ellps=GRS80 +datum=NAD83 +to_meter=0.3408 +no_defs" -t_srs EPSG:32130 output.shp input.shp

Let's examine what is going on here:

The -s_srs parameter explicitly defines a projection for the data. The parameters used here were taken out of the EPSG definition (in this case, 32130) in the epsg file(see the projection FAQ for more details on locating EPSG definitions). The entry for RI in the epsg file is as follows:

# NAD83 / Rhode Island
<32130> +proj=tmerc +lat_0=41.08333333333334 +lon_0=-71.5 +k=0.999994 +x_0=100000 +y_0=0 +ellps=GRS80 +datum=NAD83 +units=m +no_defs  no_defs <>

You can see how the definition in the initial command is formulated. Notice that the "+units=m" parameter has been changed to “+to_meter=0.3408”. This is important for the conversion. Where did the value of 0.3408 come from you ask? From the EPSG file! It has many goodies buried in it so by simply running 'grep "to_meter" epsg’ you can refresh your memory if you need to.

The next parameter in the command is "-t_srs EPSG:32130". This command tells ogr2ogr to transform the data to the EPSG code of 32130. After this is declared, all you need to do is declare a file name for your new shape file and to set which file is being used as the input (note: make sure you don’t confuse the order of these two).

Hit enter, bombs away, and enjoy your new data in meters!

The default output format for MapServer is 8bit pseudo-colored PNG or GIF. Inherently there will be some color degredation in converting a 24bit image (16 million colors) image into 8bit (256 colors).

But in order to ensure fast rendering MapServer uses quite a simple method to do the transformation, converting pixels to the nearest color in a 175 color colorcube. This will usually result in blotchy color in a fairly smoothly varying image.

Solutions include:

• Select 24bit output. This might be as easy as "IMAGETYPE JPEG" in your MAP section.
• Enable dithering (PROCESSING "DITHER=YES") to produce a better color appearance.
• Preprocess your image to 8bit before using it in MapServer with an external application like the GDAL rgb2pct.py script.

For more information review the Raster HOWTO document.