|Home | Products | Issue Tracker | FAQ | Download|
Signals the start of a CLASS object.
Inside a layer, only a single class will be used for the rendering of a feature. Each feature is tested against each class in the order in which they are defined in the mapfile. The first class that matches the its min/max scale constraints and its EXPRESSION check for the current feature will be used for rendering.
Signals the start of a CLUSTER object.
The CLUSTER configuration option provides to combine multiple features from the layer into single (aggregated) features based on their relative positions. Supported only for POINT layers.
Signals the start of a COMPOSITE object.
One or more COMPOSITE blocks can be used to signal that rendering should be done in a temporary image and merged onto the final map image in a final step. The options defined inside the COMPOSITE block will determine how this merging should be done (e.g. by appying opacity, composition operator, or pixel filters)
Database connection string to retrieve remote data.
An SDE connection string consists of a hostname, instance name, database name, username and password separated by commas.
A PostGIS connection string is basically a regular PostgreSQL connection string, it takes the form of “user=nobody password=****** dbname=dbname host=localhost port=5432”
An Oracle connection string: user/pass[@db]
Vector Data for specific connection information for various data sources.
Type of connection. Default is local. See additional documentation for any other type.
mygis is another connectiontype, but it is deprecated; please see the MySQL section of the Vector Data document for connection details.
Full filename of the spatial data to process. No file extension is necessary for shapefiles. Can be specified relative to the SHAPEPATH option from the Map Object.
If this is an SDE layer, the parameter should include the name of the layer as well as the geometry column, i.e. “mylayer,shape,myversion”.
If this is a PostGIS layer, the parameter should be in the form of “<columnname> from <tablename>”, where “columnname” is the name of the column containing the geometry objects and “tablename” is the name of the table from which the geometry data will be read.
For Oracle, use “shape FROM table” or “shape FROM (SELECT statement)” or even more complex Oracle compliant queries! Note that there are important performance impacts when using spatial subqueries however. Try using MapServer’s FILTER whenever possible instead. You can also see the SQL submitted by forcing an error, for instance by submitting a DATA parameter you know won’t work, using for example a bad column name.
Vector Data for specific connection information for various data sources.
Enables debugging of a layer in the current map.
Debugging with MapServer versions >= 5.0:
Verbose output is generated and sent to the standard error output (STDERR) or the MapServer errorfile if one is set using the “MS_ERRORFILE” environment variable. You can set the environment variable by using the CONFIG parameter at the MAP level of the mapfile, such as:
CONFIG "MS_ERRORFILE" "/ms4w/tmp/ms_error.txt"
You can also set the environment variable in Apache by adding the following to your httpd.conf:
SetEnv MS_ERRORFILE "/ms4w/tmp/ms_error.txt"
Once the environment variable is set, the DEBUG mapfile parameter can be used to control the level of debugging output. Here is a description of the possible DEBUG values:
You can also set the debug level by using the “MS_DEBUGLEVEL” environment variable.
The DEBUG setting can also be specified for the entire map, by setting the DEBUG parameter in the MAP object.
For more details on this debugging mechanism, please see MS RFC 28: Redesign of LOG/DEBUG output mechanisms.
Debugging with MapServer versions < 5:
Verbose output is generated and sent to the standard error output (STDERR) or the MapServer logfile if one is set using the LOG parameter in the WEB object. Apache users will see timing details for drawing in Apache’s error_log file. Requires MapServer to be built with the DEBUG=MSDEBUG option (–with-debug configure option).
Since 6.0, DUMP is not used anymore. LAYER METADATA is used instead.
Switch to allow MapServer to return data in GML format. Useful when used with WMS GetFeatureInfo operations. “false” by default.
Deprecated since version 6.0: LAYER METADATA is used instead.
This parameter allows for data specific attribute filtering that is done at the same time spatial filtering is done, but before any CLASS expressions are evaluated. For OGR and shapefiles the string is simply a mapserver regular expression. For spatial databases the string is a SQL WHERE clause that is valid with respect to the underlying database.
For example: FILTER ([type]=’road’ and [size]<2)
Used to indicate that the current feature will be transformed. Introduced in version 6.4.
<expression>: Applies the given expression to the geometry.
(smoothsia([shape], smoothing_size, smoothing_iteration, preprocessing)): will smooth a geometry ([shape]) using the SIA algorithm
There is a difference between STYLE and LAYER GEOMTRANSFORM. LAYER-level will receive ground coordinates (meters, degress, etc) and STYLE-level will receive pixel coordinates. The argument to methods such as simplify() must be in the same units as the coordinates of the shapes at that point of the rendering workflow, i.e. pixels at the STYLE-level and in ground units at the LAYER-level.
LAYER NAME "my_layer" TYPE LINE STATUS DEFAULT DATA "lines.shp" GEOMTRANSFORM (simplify([shape], 10)) ## 10 ground units CLASS STYLE GEOMTRANSFORM (buffer([shape], 5) ## 5 pixels WIDTH 2 COLOR 255 0 0 END END END
The [map_cellsize] variable is available if you need to pass a pixel value at the LAYER-level.
LAYER NAME "my_layer" TYPE LINE STATUS DEFAULT DATA "lines.shp" UNITS meters # 10 * [map_cellsize] == 10 pixels converted to ground units GEOMTRANSFORM (simplify([shape], [map_cellsize]*10)) ...
To get this variable working in the math expression parser, the [map_cellsize] has to be converted into the layer ground unit. If you choose to use [map_cellsize] in your GEOMTRANSFORM expression, you must explicitly set the UNITS option in the layer.
New in version 7.0.
Requires V8 MapScript Support.
Name of a group that this layer belongs to. The group name can then be reference as a regular layer name in the template files, allowing to do things like turning on and off a group of layers at once.
If a group name is present in the LAYERS parameter of a CGI request, all the layers of the group are returned (the STATUS of the LAYERs have no effect).
(As of MapServer 5.0 this parameter is no longer available. Please see the LABEL object’s ANGLE parameter) For MapServer versions < 5.0, this is the item name in attribute table to use for class annotation angles. Values should be in degrees.
Deprecated since version 5.0.
Minimum scale at which this LAYER is labeled. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated LABELMAXSCALE parameter.
Maximum scale at which this LAYER is labeled. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated LABELMINSCALE parameter.
Sets context for labeling this layer, for example:
means that this layer would NOT be labeled if a layer named “orthoquads” is on. The expression consists of a boolean expression based on the status of other layers, each [layer name] substring is replaced by a 0 or a 1 depending on that layer’s STATUS and then evaluated as normal. Logical operators AND and OR can be used.
(As of MapServer 5.0 this parameter is no longer available. Please see the LABEL object’s SIZE parameter) For MapServer versions < 5.0, this is the item name in attribute table to use for class annotation sizes. Values should be in pixels.
Deprecated since version 5.0.
The data from the current layer will only be rendered where it intersects features from the [layername] layer. [layername] must reference the NAME of another LAYER defined in the current mapfile. can be any kind of mapserver layer, i.e. vector or raster. If the current layer has labelling configured, then only labels who’s label-point fall inside the unmasked area will be added to the labelcache (the actual glyphs for the label may be rendered ontop of the masked-out area.
Unless you want the features of [layername] to actually appear on the generated map, [layername] should usually be set to STATUS OFF.
Maximum width, in the map’s geographic units, at which this LAYER is drawn. If MAXSCALEDENOM is also specified then MAXSCALEDENOM will be used instead.
The width of a map in geographic units can be found by calculating the following from the extents:
[maxx] - [minx]
New in version 5.4.0.
Minimum scale at which this LAYER is drawn. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000.
New in version 5.0.0: Replaced MAXSCALE.
This keyword allows for arbitrary data to be stored as name value pairs. This is used with OGC WMS to define things such as layer title. It can also allow more flexibility in creating templates, as anything you put in here will be accessible via template tags.
METADATA "title" "My layer title" "author" "Me!" END
Minimum width, in the map’s geographic units, at which this LAYER is drawn. If MINSCALEDENOM is also specified then MINSCALEDENOM will be used instead.
The width of a map in geographic units can be found by calculating the following from the extents:[maxx] - [minx]
New in version 5.4.0.
Maximum scale at which this LAYER is drawn. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated MINSCALE parameter.
Deprecated since version 7.0: Use a COMPOSITE block instead.
Additional library to load by MapServer, for this layer. This is commonly used to load specific support for SDE and Microsoft SQL Server layers, such as:
CONNECTIONTYPE PLUGIN CONNECTION "hostname,port:xxx,database,username,password" PLUGIN "C:/ms4w/Apache/specialplugins/msplugin_sde_92.dll" DATA "layername,geometrycolumn,SDE.DEFAULT"
Passes a processing directive to be used with this layer. The supported processing directives vary by layer type, and the underlying driver that processes them.
Attributes Directive - The ITEMS processing option allows to specify the name of attributes for inline layers or specify the subset of the attributes to be used by the layer, such as:
Connection Pooling Directive - This is where you can enable connection pooling for certain layer layer types. Connection pooling will allow MapServer to share the handle to an open database or layer connection throughout a single map draw process. Additionally, if you have FastCGI enabled, the connection handle will stay open indefinitely, or according to the options specified in the FastCGI configuration. Oracle Spatial, ArcSDE, OGR and PostGIS/PostgreSQL currently support this approach.
Label Directive - The LABEL_NO_CLIP processing option can be used to skip clipping of shapes when determining associated label anchor points. This avoids changes in label position as extents change between map draws. It also avoids duplicate labels where features appear in multiple adjacent tiles when creating tiled maps.
Line Rendering Directive - The POLYLINE_NO_CLIP processing option can be used to skip clipping of shapes when rendering styled lines (dashed or styled with symbols). This avoids changes in the line styling as extents change between map draws. It also avoids edge effects where features appear in multiple adjacent tiles when creating tiled maps.
OGR Styles Directive - This directive can be used for obtaining label styles through MapScript. For more information see the MapServer’s OGR document.
AGG renderer tweaking - This directive can be used for setting the linear gamma to be used when rendering polygon features. The default value of 0.75 (that can be overriden at the OUTPUTFORMAT level) can be set to a lower value to limit/remove the faint outlines that appear between adjacent polygons. A value of 0.5 is usually good enough.
Raster Directives - All raster processing options are described in Raster Data. Here we see the SCALE and BANDs directives used to autoscale raster data and alter the band mapping.
PROCESSING "SCALE=AUTO" PROCESSING "BANDS=3,2,1"
Sets the current status of the layer. Often modified by MapServer itself. Default turns the layer on permanently.
In CGI mode, layers with STATUS DEFAULT cannot be turned off using normal mechanisms. It is recommended to set layers to STATUS DEFAULT while debugging a problem, but set them back to ON/OFF in normal use.
For WMS, layers in the server mapfile with STATUS DEFAULT are always sent to the client.
The STATUS of the individual layers of a GROUP has no effect when the group name is present in the LAYERS parameter of a CGI request - all the layers of the group will be returned.
<attribute>: Item to use for feature specific styling. The style information may be represented by a separate attribute (style string) attached to the feature. MapServer supports the following style string representations:
MapServer STYLE definition - The style string can be represented as a MapServer STYLE block according to the following example:
STYLE BACKGROUNDCOLOR 128 0 0 COLOR 0 0 208 END
MapServer CLASS definition - By specifying the entire CLASS instead of a single style allows to use further options (like setting expressions, label attributes, multiple styles) on a per feature basis.
OGR Style String - MapServer support rendering the OGR style string format according to the OGR - Feature Style Specification documentation. Currently only a few data sources support storing the styles along with the features (like MapInfo, AutoCAD DXF, Microstation DGN), however those styles can easily be transferred to many other data sources as a separate attribute by using the ogr2ogr command line tool as follows:
ogr2ogr -sql "select *, OGR_STYLE from srclayer" "dstlayer" "srclayer"
New in version 6.6.
Requires V8 MapScript Support.
The scale at which symbols and/or text appear full size. 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. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated SYMBOLSCALE parameter.
Name of the tileindex file or layer. A tileindex is similar to an ArcInfo library index. The tileindex contains polygon features for each tile. The item that contains the location of the tiled data is given using the TILEITEM parameter. When a file is used as the tileindex for shapefile or raster layers, the tileindex should be a shapefile. For CONNECTIONTYPE OGR layers, any OGR supported datasource can be a tileindex. Normally the location should contain the path to the tile file relative to the shapepath, not relative to the tileindex itself. If the DATA parameter contains a value then it is added to the end of the location. When a tileindex layer is used, it works similarly to directly referring to a file, but any supported feature source can be used (ie. postgres, oracle).
All files in the tileindex should have the same coordinate system, and for vector files the same set of attributes in the same order.
Starting with MapServer 6.4, raster layers can use a tileindex with tiles of different projections. For that, the TILESRS parameter must be specified.
Name of the attribute that contains the SRS of an individual tile. That SRS can be expressed in WKT format, as an EPSG:XXXX code or as a PROJ.4 string. If the tileindex contains rasters in different projections, this option must be specified. If the tileindex has been generated with gdaltindex (GDAL >= 2.0), the value of TILESRS is the value of the -src_srs_name option of gdaltindex. See Tileindexes with tiles in different projections
This option is currently available only on raster layers.
TRANSPARENCY [integer|alpha] - deprecated
Deprecated since version 5.0: Use OPACITY instead.
Deprecated since version 7.0: Use COMPOSITE instead.
Tells 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 left hand corner of the image, contrary to most map coordinate systems.
Version 4.10 introduces the ability to define features with coordinates given in pixels (or percentages, see UNITS), most often inline features, relative to something other than the UL corner of an image. That is what ‘TRANSFORM FALSE’ means. By setting an alternative origin it allows you to anchor something like a copyright statement to another portion of the image in a way that is independent of image size.
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.
In order to differentiate between POLYGONs and POLYLINEs (which do not exist as a type), simply respectively use or omit the COLOR keyword when classifying. If you use it, it’s a polygon with a fill color, otherwise it’s a polyline with only an OUTLINECOLOR.
A circle must be defined by a a minimum bounding rectangle. That is, two points that define the smallest square that can contain it. These two points are the two opposite corners of said box. The following is an example using inline points to draw a circle:
LAYER NAME 'inline_circles' TYPE CIRCLE STATUS ON FEATURE POINTS 74.01 -53.8 110.7 -22.16 END END CLASS STYLE COLOR 0 0 255 END END END
TYPE query means the layer can be queried but not drawn.
TYPE annotation has been deprecated since version 6.2. Identical functionality can be obtained by adding LABEL level STYLE blocks, and do not require loading the datasets twice in two different layers as was the case with layers of TYPE annotation.
The Dynamic Charting HowTo for TYPE chart.
Signals the start of a VALIDATION block.
As of MapServer 5.4.0, VALIDATION blocks are the preferred mechanism for specifying validation patterns for CGI param runtime substitutions. See Run-time Substitution.