.. index:: single: MAP .. _map: ***************************************************************************** MAP ***************************************************************************** .. note:: The map object is started with the word `MAP`, and ended with the word `END`. .. index:: pair: MAP; ANGLE ANGLE [double] Angle, given in degrees, to rotate the map. Default is 0. The rendered map will rotate in a clockwise direction. The following are important notes: - Requires a :ref:`projection` object specified at the MAP level and for each :ref:`layer` object (even if all layers are in the same projection). - Requires :ref:`MapScript ` (:ref:`SWIG `, :ref:`PHP MapScript `). Does not work with :ref:`CGI ` mode. - If using the :ref:`LABEL` object's ANGLE or the :ref:`LAYER` object's `LABELANGLEITEM` parameters as well, these parameters are relative to the map's orientation (i.e. they are computed after the `MAP` object's `ANGLE`). For example, if you have specified an `ANGLE` for the map of 45, and then have a layer `LABELANGLEITEM` value of 45, the resulting label will not appear rotated (because the resulting map is rotated clockwise 45 degrees and the label is rotated counter-clockwise 45 degrees). - More information can be found on the MapRotation `Wiki Page`_. .. _`Wiki Page`: http://trac.osgeo.org/mapserver/wiki/MapRotation .. index:: pair: MAP; CONFIG CONFIG [key] [value] This can be used to specify several values at run-time, for both MapServer and GDAL/OGR libraries. Developers: values will be passed on to CPLSetConfigOption(). Details on GDAL/OGR options are found in their associated driver documentation pages (`GDAL`_/`OGR`_). The following options are available specifically for MapServer: .. index:: triple: MAP; CONFIG; CGI_CONTEXT_URL CGI_CONTEXT_URL [value] This `CONFIG` parameter can be used to enable loading a map context from a URL. See the :ref:`Map Context HowTo` for more info. .. index:: triple: MAP; CONFIG; MS_ENCRYPTION_KEY MS_ENCRYPTION_KEY [filename] This `CONFIG` parameter can be used to specify an encryption key that is used with MapServer's :ref:`msencypt utility`. .. index:: triple: MAP; CONFIG; MS_ERRORFILE MS_ERRORFILE [filename] This `CONFIG` parameter can be used to write MapServer errors to a file (as of MapServer 5.0). With MapServer 5.x, a full path (absolute reference) is required, including the filename. Starting with MapServer 6.0, a filename with relative path can be passed via this `CONFIG` directive, in which case the filename is relative to the mapfile location. Note that setting MS_ERRORFILE via an environment variable always requires an absolute path since there would be no mapfile to make the path relative to. For more on this see the `DEBUG` parameter below. .. index:: triple: MAP; CONFIG; MS_NONSQUARE MS_NONSQUARE [yes|no] This `CONFIG` parameter can be used to allow non-square pixels (meaning that the pixels represent non-square regions). For "MS_NONSQUARE" "yes" to work, the :ref:`MAP`, and each :ref:`LAYER` will have to have a :ref:`PROJECTION` object. .. note:: Has no effect for WMS. .. index:: triple: MAP; CONFIG; ON_MISSING_DATA ON_MISSING_DATA [FAIL|LOG|IGNORE] This `CONFIG` parameter can be used to tell MapServer how to handle missing data in tile indexes (as of MapServer 5.3-dev, r8015). Previous MapServer versions required a compile-time switch ("IGNORE_MISSING_DATA"), but this is no longer required. FAIL This will cause MapServer to throw an error and exit (to crash, in other words) on a missing file in a tile index. This is the default. .. code-block:: mapfile CONFIG "ON_MISSING_DATA" "FAIL" LOG This will cause MapServer to log the error message for a missing file in a tile index, and continue with the map creation. Note: `DEBUG` parameter and CONFIG "MS_ERRORFILE" need to be set for logging to occur, so please see the `DEBUG` parameter below for more information. .. code-block:: mapfile CONFIG "ON_MISSING_DATA" "LOG" IGNORE This will cause MapServer to not report or log any errors for missing files, and map creation will occur normally. .. code-block:: mapfile CONFIG "ON_MISSING_DATA" "IGNORE" .. index:: triple: MAP; CONFIG; PROJ_LIB PROJ_LIB [path] This `CONFIG` parameter can be used to define the location of your EPSG files for the :term:`Proj.4` library. Setting the [key] to PROJ_LIB and the [value] to the location of your EPSG files will force PROJ.4 to use this value. Using `CONFIG` allows you to avoid setting environment variables to point to your PROJ_LIB directory. Here are some examples: 1. Unix .. code-block:: mapfile CONFIG "PROJ_LIB" "/usr/local/share/proj/" 2. Windows .. code-block:: mapfile CONFIG "PROJ_LIB" "C:/somedir/proj/nad/" .. index:: pair: MAP; DATAPATTERN .. _DATAPATTERN: DATAPATTERN [regular expression] This defines a regular expression to be applied to requests to change `DATA` parameters via URL requests (i.e. map_layername_data=...). If a pattern doesn't exist then web users can't monkey with support files via URLs. This allows you to isolate one application from another if you desire, with the default operation being very conservative. See also TEMPLATEPATTERN_. .. index:: pair: MAP; DEBUG DEBUG [off|on|0|1|2|3|4|5] Enables debugging of all of the layers 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: .. code-block:: mapfile 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: - **DEBUG O or OFF** - only msSetError() calls are logged to MS_ERRORFILE. No msDebug() output at all. This is the default and corresponds to the original behavior of MS_ERRORFILE in MapServer 4.x. - **DEBUG 1 or ON** - includes all output from *DEBUG 0* plus msDebug() warnings about common pitfalls, failed assertions or non-fatal error situations (e.g. missing or invalid values for some parameters, missing shapefiles in tileindex, timeout error from remote WMS/WFS servers, etc.). - **DEBUG 2** - includes all output from *DEBUG 1* plus notices and timing information useful for tuning mapfiles and applications. - **DEBUG 3** - all of *DEBUG 2* plus some debug output useful in troubleshooting problems such as WMS connection URLs being called, database connection calls, etc. This is the recommended level for debugging mapfiles. - **DEBUG 4** - *DEBUG 3* plus even more details... - **DEBUG 5** - *DEBUG 4* plus any msDebug() output that might be more useful to the developers than to the users. You can also set the debug level by using the "MS_DEBUGLEVEL" environment variable. The `DEBUG` setting can also be specified for a layer, by setting the `DEBUG` parameter in the :ref:`LAYER` object. For more details on this debugging mechanism, please see the :ref:`debugging` document. *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). .. index:: pair: MAP; DEFRESOLUTIONx DEFRESOLUTION [int] Sets the reference resolution (pixels per inch) used for symbology. Default is 72. Used to automatically scale the symbology when :ref:`RESOLUTION ` is changed, so the map maintains the same look at each resolution. The scale factor is `RESOLUTION` / `DEFRESOLUTION`. .. versionadded:: 5.6 .. index:: pair: MAP; EXTENT EXTENT [minx] [miny] [maxx] [maxy] The spatial extent of the map to be created. In most cases you will need to specify this, although MapServer can sometimes (expensively) calculate one if it is not specified. :ref:`FONTSET` [filename] Filename of fontset file to use. Can be a path relative to the mapfile, or a full path. .. index:: pair: MAP; IMAGECOLOR IMAGECOLOR [r] [g] [b] Color to initialize the map with (i.e. background color). When transparency is enabled (*TRANSPARENT ON* in :ref:`OUTPUTFORMAT`) for the typical case of 8-bit pseudocolored map generation, this color will be marked as transparent in the output file palette. Any other map components drawn in this color will also be transparent, so for map generation with transparency it is best to use an otherwise unused color as the background color. IMAGEQUALITY [int] *Deprecated* Use **FORMATOPTION "QUALITY=n"** in the :ref:`OUTPUTFORMAT` declaration to specify compression quality for JPEG output. .. deprecated:: 4.6 .. index:: pair: MAP; IMAGETYPE .. index:: triple: MAP; IMAGETYPE; jpeg .. index:: triple: MAP; IMAGETYPE; pdf .. index:: triple: MAP; IMAGETYPE; png .. index:: triple: MAP; IMAGETYPE; svg .. _imagetype: IMAGETYPE [jpeg|pdf|png|svg|...|userdefined] Output format (raster or vector) to generate. The name used here must match the 'NAME' of a user defined or internally available :ref:`OUTPUTFORMAT`. For a complete list of available `IMAGEFORMAT`\s, see the :ref:`OUTPUTFORMAT` section. INTERLACE [on|off] *Deprecated* Use **FORMATOPTION "INTERLACE=ON"** in the :ref:`OUTPUTFORMAT` declaration to specify if the output images should be interlaced. .. deprecated:: 4.6 .. index:: pair: MAP; LAYER :ref:`LAYER` Signals the start of a :ref:`LAYER` object. .. index:: pair: MAP; LEGEND :ref:`LEGEND` Signals the start of a :ref:`LEGEND` object. .. index:: pair: MAP; MAXSIZE MAXSIZE [integer] Sets the maximum size of the map image. This will override the default value. For example, setting this to 2048 means that you can have up to 2048 pixels in both dimensions (i.e. max of 2048x2048). Default is 2048. .. index:: pair: MAP; NAME NAME [name] Prefix attached to map, scalebar and legend GIF filenames created using this mapfile. It should be kept short. .. index:: pair: MAP; PROJECTION :ref:`PROJECTION` Signals the start of a :ref:`PROJECTION` object. .. index:: pair: MAP; QUERYMAP :ref:`QUERYMAP` Signals the start of a :ref:`QUERYMAP` object. .. index:: pair: MAP; REFERENCE :ref:`REFERENCE` Signals the start of a :ref:`REFERENCE` MAP object. .. index:: pair: MAP; RESOLUTION .. _resolution-parameter: RESOLUTION [int] Sets the pixels per inch for output, only affects scale computations. Default is 72. .. index:: pair: MAP; SCALEDENOM SCALEDENOM [double] Computed scale of the map. Set most often by the application. 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 `SCALE` parameter. .. seealso:: :term:`Map Scale` SCALE [double] - deprecated Since MapServer 5.0 the proper parameter to use is `SCALEDENOM` instead. The deprecated `SCALE` is the computed scale of the map. Set most often by the application. 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. .. deprecated:: 5.0 .. index:: pair: MAP; SCALEBAR SCALEBAR Signals the start of a :ref:`SCALEBAR` object. .. index:: pair: MAP; SHAPEPATH SHAPEPATH [filename] Path to the directory holding the shapefiles or tiles. There can be further subdirectories under `SHAPEPATH`. .. index:: pair: MAP; SIZE SIZE [x][y] Size in pixels of the output image (i.e. the map). .. index:: pair: MAP; STATUS STATUS [on|off] Is the map active? Sometimes you may wish to turn this off to use only the reference map or scale bar. .. index:: pair: MAP; SYMBOLSET .. _SYMBOLSET: SYMBOLSET [filename] Filename of the symbolset to use. Can be a path relative to the mapfile, or a full path. .. note:: The `SYMBOLSET` file must start with the word `SYMBOLSET` and end with the word `END`. :ref:`SYMBOL` Signals the start of a :ref:`SYMBOL` object. .. index:: pair: MAP; TEMPLATEPATTERN .. _TEMPLATEPATTERN: TEMPLATEPATTERN [regular expression] This defines a regular expression to be applied to requests to change the `TEMPLATE` parameters via URL requests (i.e. map_layername_template=...). If a pattern doesn't exist then web users can't monkey with support files via URLs. This allows you to isolate one application from another if you desire, with the default operation being very conservative. See also DATAPATTERN_. TRANSPARENT [on|off] .. deprecated:: 4.6 Use *TRANSPARENT ON* in the :ref:`OUTPUTFORMAT` declaration to specify if the output images should be transparent. .. index:: pair: MAP; UNITS .. index:: triple: MAP; UNITS; dd .. index:: triple: MAP; UNITS; feet .. index:: triple: MAP; UNITS; inches .. index:: triple: MAP; UNITS; kilometers .. index:: triple: MAP; UNITS; meters .. index:: triple: MAP; UNITS; miles .. index:: triple: MAP; UNITS; nauticalmiles UNITS [dd|feet|inches|kilometers|meters|miles|nauticalmiles] Units of the map coordinates. Used for scalebar and scale computations. `Nauticalmiles` was added in MapServer 5.6. .. index:: pair: MAP; WEB :ref:`WEB` Signals the start of a :ref:`WEB` object. .. _`GDAL`: http://www.gdal.org/formats_list.html .. _`OGR`: http://www.gdal.org/ogr/ogr_formats.html