Map api

Module | Error | Map | Layer

Map API

A Map object represents a parsed mapserver map file.

Constructor:

var mapserver = require('mapserver');
var map = new mapserver.Map(/* map file path */, /* relative to path */);

Use the javascript new operator on mapserver.Map. The constructor takes two optional arguments. If no arguments are present, an empty map object is created. The first argument is the path to a map file to load. The second argument is the path to folder that the map file will use for resolving relative paths in the map file. By default, mapserver will use the folder that the map file is in for resolving relative paths.

Read/Write Properties:

The following properties are available on a Map object. Note that changing values for some of these properties may affect the values of other properties at the time the map is drawn. For instance changing map.width may change the map's extents, cellsize and scaledenom but the values of those properties will not be reflected until you call one of the drawMap or recompute methods.

• width - read/write integer, the width in pixels of the image to generate for this map when it is drawn
• height - read/write integer, the height in pixels of the image to generate for this map when it is drawn
• status - read/write integer, the status of the map, either MS_ON or MS_OFF
• maxsize - read/write integer, the largest value of width and height allowed, default is typically 2048. Setting this to a larger number allows larger maps to be requested, be careful to ensure your infrastructure can handle it
• units read/write integer, the units of the map extents, one of MS_INCHES, MS_FEET, MS_MILES, MS_METERS, MS_KILOMETERS, MS_DD, MS_PIXELS, MS_PERCENTAGES, or MS_NAUTICALMILES.
• resolution read/write integer, the resolution in dots per inch to be used in calculating ground scale (affects value of scaledenom after drawMap or recompute). Also used in conjunction with defresolution to calculate automatic scaling of styles to preserve representation at different DPIs.
• defresolution read/write integer, defaults to 72. When resolution is different from defresolution, styles are scaled by the ratio of these to numbers to preserve visual representation.
• shapepath read/write string, the filesystem path relative to the mappath at which data will be found by layers that have file-based data.
• mappath - read/write string, the filesystem path relative to the current working directory which mapserver will compute relative paths for resources such as shapepath.
• extent - an object with properties minx, miny, maxx and maxy. Use map.extent.minx to access the left edge of the map, for example. Use map.recompute() to ensure that these values accurately represent what will be drawn. You can update the map extent directly on this object one dimension at a time, or use the setExtent method to update them together.

Read Only Properties

• cellsize - read-only double, the number of ground units per pixel. This value is only computed after you call drawMap or recompute.
• scaledenom - read-only double, the denominator for the ground scale of the map typically expressed as 1/scaledenom which means that 1 unit on the map represents scaledenom units on the ground in any unit system you care to use (inches, centimeters etc).
• outputformat - read-only string, the name of the currently selected output format.
• layers - read-only array, an array of layers in the map.

Object Methods:

clone()

Clones the map object. This is important if you want to handle parallel asynchronous draw calls to the same in-memory map object. See the mapserv example.

recompute()

Recomputes the map's extent, cellsize and scaledenom from the current settings for width, height, resolution, and extent (extent will be adjusted to fit aspect ratio of the width and height). Returns true.

drawMap( callback)

renders an image based on the Map's current state and returns a Buffer object suitable for output via a callback function. The callback function should expect two arguments, an error object and a buffer. If an error happens in rendering the map, the first argument will be the error that happened and the second will be undefined. If there is no error, then the error object will be false and the second will be a valid buffer containing the image.

setExtent( minx, miny, maxx, maxy)

Set the extent of the map. Note that setting the extent does not guarantee that the map will draw exactly the extent you request. The extent will be adjusted to match the aspect ratio of the map's width and height. Call map.recompute() to adjust the extent after you set it if you really need to know what it will be.

selectOutputFormat( imagetype)

Set the output format to use for rendering the map. The output format can be one of the predefined output format names or mime types, or one defined in your map file. If the output format is not available, this method will throw an error.