Perl MapScript Reference

Abstract:
This document is a reference to the Perl MapScript syntax for MapServer version 3.6.x.
Important Note for 3.6.4: The version of Swig used to build the Perl/Python/Tcl interfaces is different than in previous releases.
As a result: "$map = new mapObj(...);" becomes "$map = new mapscript::mapObj(...);"

Be Sure to see the Wiki for Build, Install, Samples, & Debugging Help.
Last Updated: 2/19/2003 by Lowell Filak
Medina County Engineer's Office
Medina, Ohio
United States


Table of Contents:

Introduction
Usage
Constants
Classes/Objects
classObj
colorObj
DBFInfo
imageObj
itemObj
labelCacheMemberObj
labelCacheObj
labelObj
layerObj
legendObj
lineObj
mapObj
markerCacheMemberObj
pointObj
projectionObj
queryMapObj
rectObj
referenceMapObj
resultCacheMemberObj
resultCacheObj
scalebarObj
shapefileObj
shapeObj
styleObj
webObj
Miscellaneous Commands
Miscellaneous Functions
Error Handling

Introduction:
MapScript is a scripting interface for the MapServer. It allows users to more
easily build custom applications by hiding much of the complexity of the C API
behind a simple object-oriented scripting interface. MapScript currently exists
as a module in many languages, see for the main documentation.

The organization of MapScript is very close to that of a mapfile. It does NOT
give you the functionality of the MapServer CGI program, rather it gives you
the necessary pieces to build your own custom versions for use on the web or as
a standalone program. Here is a simple perl example that loads a mapfile,
creates an image and saves it:

#!/usr/bin/perl
use mapscript;
my $map = new mapObj('boundary.map') or die('Unable to open mapfile.');
my $img = $map->draw() or die('Unable to draw map');
my $void = $img->saveImage('example.png', $mapscript::MS_PNG, $map->{transparent}, $map->{interlace}, 0);

Usage:
Perl - use mapscript;

Constants:
Many mapfile paramters take constant values.
The following constants are available in MapScript:

logical control/boolean values MS_VERSION - character (3.6.1)
MS_TRUE/MS_ON/MS_YES - integer (1)
MS_FALSE/MS_OFF/MS_NO - integer (0)
logical control/status values MS_DEFAULT (layer) - integer (2)
MS_EMBED (legend & scalebar) - integer (3)
MS_DELETE (layer) - integer (4)
map units MS_INCHES - integer
MS_FEET - integer
MS_MILES - integer
MS_METERS - integer
MS_KILOMETERS - integer
MS_DD - integer
MS_PIXELS - integer
layer types MS_LAYER_POINT - integer
MS_LAYER_LINE - integer
MS_LAYER_POLYGON - integer
MS_LAYER_RASTER - integer
MS_LAYER_ANNOTATION - integer
MS_LAYER_QUERY - integer
MS_LAYER_CIRCLE - integer
font types MS_TRUETYPE - integer
MS_BITMAP - integer
label positions MS_UL - integer
MS_LR - integer
MS_UR - integer
MS_LL - integer
MS_CR - integer
MS_CL - integer
MS_UC - integer
MS_LC - integer
MS_CC - integer
MS_AUTO - integer
MS_XY - integer (arrangement matters for auto placement, don't change it)
label size (bitmap only) MS_TINY - integer
MS_SMALL - integer
MS_MEDIUM - integer
MS_LARGE - integer
MS_GIANT - integer
shape types MS_SHAPE_POINT - integer
MS_SHAPE_LINE - integer
MS_SHAPE_POLYGON - integer
MS_SHAPE_NULL - integer
shapefile types MS_SHAPEFILE_POINT (1)
MS_SHAPEFILE_ARC (3)
MS_SHAPEFILE_POLYGON (5)
MS_SHAPEFILE_MULTIPOINT (8)
query/join types/modes MS_SINGLE - integer (0)
MS_MULTIPLE - integer (1)
file types MS_FILE_MAP - integer
MS_FILE_SYMBOL - integer
MS_FILE_DEFAULT - integer (MS_FILE_MAP)
querymap styles MS_NORMAL - integer
MS_HILITE - integer
MS_SELECTED - integer
connection type MS_INLINE - integer
MS_SHAPEFILE - integer
MS_TILED_SHAPEFILE - integer
MS_SDE - integer
MS_OGR - integer
MS_POSTGIS - integer
MS_WMS - integer
MS_ORACLESPATIAL - integer
image type MS_GIF - integer (0)
MS_PNG - integer (1)
MS_JPEG - integer (2)
MS_WBMP - integer (3)
MS_GML - integer (4)
line joins & caps MS_CJC_NONE - integer
MS_CJC_BEVEL - integer
MS_CJC_BUTT - integer
MS_CJC_MITER - integer
MS_CJC_ROUND - integer
MS_CJC_SQUARE - integer
MS_CJC_TRIANGLE - integer
return codes MS_SUCCESS - integer
MS_FAILURE - integer
MS_DONE - integer

Example: $layer->{status}=$mapscript::MS_ON; or $layer->{status}=$mapscript::MS_OFF;.

Classes/Objects:
Access to the mapserver API is provided largely through a series of classes.
These classes allow the programmer to:

- manipulate virtually all aspects of a mapfile
- draw entire maps, layers or individual shapes
- perform spatial queries using points, areas or other features
- read/write shapefiles
- perform attribute queries
- read/write dbf files (for limited use only, please use XBase or DBI/XBase)

The main MapScript classes are given in the table below.
Each class is described in detail later in this document.

classObj holds all class parameters
exists within a layerObj
colorObj
DBFInfo
imageObj
itemObj
labelCacheMemberObj holds a single element from the label cache
labelCacheObj
labelObj
layerObj holds all layer parameters
exists within a mapObj
legendObj
lineObj made up of pointObjs
may or may not be a closed ring
mapObj holds all mapfile parameters
markerCacheMemberObj
pointObj simple class to hold a 2-D point
projectionObj
queryMapObj
rectObj class used to represent a 2-D rectangle
defined using minimum and maximum x and y coordinates
referenceMapObj
resultCacheMemberObj
resultCacheObj
scalebarObj
shapefileObj class used to access spatial information (i.e. features) stored in an ESRI shapefile
shapeObj made up of lineObjs
styleObj
webObj


classObj:

Constructor:
new classObj(layerObj)

Example: $class = new classObj($layer);
Provides access to all class parameters (color, symbol, label, & etc...).
Normally you obtain a classObj from an existing class within a layer, however, you can create a new class.

Members: See the mapfile documentation for a list of parameters that can be changed.
  • backgroundcolor - integer - rw.
  • color - integer - rw.
  • joins - joinObj - rw - see the mapfile documentation.
  • label - labelObj - rw.
  • maxscale - double - .
  • maxsize - integer - rw.
  • minscale - double - .
  • minsize - integer - rw.
  • name - character - rw - should be unique within a layer.
  • numjoins - integer - rw.
  • outlinecolor - integer - rw.
  • overlaybackgroundcolor - integer - rw.
  • overlaycolor - integer - rw.
  • overlaymaxsize - integer - rw.
  • overlayminsize - integer - rw.
  • overlayoutlinecolor - integer - rw.
  • overlaysize - integer - rw.
  • overlaysizescaled - integer - rw.
  • overlaysymbol - integer - rw.
  • overlaysymbolname - character - rw.
  • size - integer - rw.
  • sizescaled - integer - rw.
  • status - integer - rw.
  • symbol - integer - rw.
  • symbolname - character - rw.
  • template - character - rw.
  • title - character - - used for legend labelling.
  • type - integer - rw.

  • Examples: $class->{label}->{autoangle} = 1;
    $class->{label}->{sizescaled} = 8;

    Methods: Method Description Returns Notes
    createLegendIcon(mapObj, layerObj, width, height); imageObj
    drawLegendIcon(mapObj, layerObj, width, height, dstImage, dstX, dstY) integer
    setExpression(character string) integer
    getMetaData(character name) character
    setMetaData(character name,character value) integer MS_FAILURE,MS_SUCCESS
    setText(layerObj,character string) integer

    Examples: $class->setExpression("\"${string_variable}\"");
    $class->setExpression('/^{A-Z}/');
    $class->setExpression('([LENGTH] gt 50 and [AREA] < 150000)');
    $class->setExpression('N');


    colorObj:

    Constructor:
    n/a

    Example:

    Members:
  • blue - integer - rw.
  • green - integer - rw..
  • red - integer - rw.

  • Example:

    Methods: Method Description Returns Notes
    none

    Example:


    DBFInfo:

    Constructor/Destructor:
    mapscript::msDBFOpen(filename, 'r+b')/mapscript::msDBFClose(hDBF);

    Example:

    Members:
  • bCurrentRecordModified - integer - ro.
  • bNoHeader - integer - ro.
  • bUpdated - integer - ro.
  • fp - file - ro.
  • nCurrentRecord - integer - ro.
  • nFields - integer - ro.
  • nHeaderLength - integer - ro.
  • nRecordLength - integer - ro.
  • nRecords - integer - ro.
  • nStringFieldLen - integer - ro.
  • panFieldDecimals - integer - ro.
  • panFieldOffset - integer - ro.
  • panFieldSize - integer - ro.
  • pachFieldType - character - ro.
  • pszCurrentRecord - character - ro.
  • pszHeader - character - ro.
  • pszStringField - character - ro.

  • Examples: See Method Examples below.

    Methods: Method Description Returns Notes
    getFieldDecimals(integer field) integer
    getFieldName(integer field) character
    getFieldWidth(integer field) integer
    getFieldType(integer field) integer 0=String, 1=Integer, 2=Double, 3=Invalid

    Examples: This example is the shpinfo.pl sample rewritten to use mapscript DBFInfo instead of the seperate XBase/Xbase module.
          #!/usr/bin/perl
          use mapscript;
          use Getopt::Long;
          %shptypes = ( '1' => 'point',
                     '3' => 'arc',
                     '5' => 'polygon',
                     '8' => 'multipoint'
                   );
          %typetypes = ( '0' => 'String',
                      '1' => 'Integer',
                      '2' => 'Double',
                      '3' => 'Invalid'
                    );
          &GetOptions("file=s", \$file);
          if(!$file) {
            print "Syntax: shpinfo.pl -file=[filename]\n";
            exit 0;
          }
          $shapefile = new shapefileObj($file, -1) or die "Unable to open shapefile $file.";
          print "Shapefile $file:\n\n";
          print "\ttype: ". $shptypes{$shapefile->{type}} ."\n";
          print "\tnumber of features: ". $shapefile->{numshapes} ."\n";
          printf "\tbounds: (%f,%f) (%f,%f)\n", $shapefile->{bounds}->{minx}, $shapefile->{bounds}->{miny}, $shapefile->{bounds}->{maxx}, $shapefile->{bounds}->{maxy};
          #
          $table = mapscript::msDBFOpen("$file.dbf","r+b");
          print "\nDBFInfo table $file.dbf:\n\n";
          print "\tnumber of records: ". $table->{nRecords} ."\n";
          my $nofields = $table->{nFields};
          print "\tnumber of fields: ". $nofields ."\n\n";
          print "\tName             Type    Length Decimals\n";
          print "\t---------------- ------- ------ --------\n";
          for ($i=0; $i<$nofields; $i++) {
            printf "\t%-16s %-7s %6d %8d\n", $table->getFieldName($i), $typetypes{$table->getFieldType($i)}, $table->getFieldWidth($i); $table->getFieldDecimals($i)
          }


    imageObj:

    Constructor:
    new imageObj(width, height)

    Example: $image = new imageObj(600, 600);

    Members:
  • height - integer - rw.
  • imagepath - character - rw.
  • imageurl - character - rw.
  • width - integer - rw.

  • Example:

    Methods: Method Description Returns Notes
    free() void
    saveImage(character filenam, type, transparent, interlace, quality) void

    Example: $image->saveImage('out.png', $mapscript::MS_PNG, $map->{transparent}, $map->{interlace}, 0);

    itemObj:

    Constructor:
    n/a

    Example:

    Members:
  • index - integer - rw.
  • name - character - rw.
  • numdecimals - integer - rw.
  • size - integer - rw.
  • type - integer - rw.

  • Example:

    Methods: Method Description Returns Notes
    none

    Example:


    labelCacheMemberObj:

    Constructor:
    n/a

    Example:

    Members:
  • class - classObj - rw - the entire class is stored for variences between labels.
  • classidx - integer - rw.
  • featuresize - double - rw.
  • layeridx - integer - rw - indexes.
  • point - pointObj - rw - label point.
  • poly - shapeObj - rw - label bounding box.
  • shapeidx - integer - rw.
  • status - integer - rw - has the label been drawn or not.
  • string - character - rw.
  • tileidx - integer - rw.

  • Example:

    Methods: Method Description Returns Notes
    none

    Example:


    labelCacheObj:

    Constructor:
    n/a

    Example:

    Members:
  • cachesize - integer - rw.
  • labels - labelCacheMemberObj - rw.
  • markers - markerCacheMemberObj - rw.
  • markercachesize - integer - rw.
  • numlabels - integer - rw.
  • nummarkers - integer - rw.

  • Example:

    Methods: Method Description Returns Notes
    freeCache() void

    Example:


    labelObj:

    Constructor:
    n/a

    Example:

    Members:
  • angle - double - rw.
  • antialias - integer - rw.
  • autoangle - integer - rw - true or false.
  • autominfeaturesize - integer - rw - true or false.
  • backgroundcolor - integer - rw.
  • backgroundshadowcolor - integer - rw.
  • backgroundshadowsizex - integer - rw.
  • backgroundshadowsizey - integer - rw.
  • buffer - integer - rw - space to reserve around a label.
  • color - integer - rw.
  • font - character - rw.
  • force - integer - rw - labels Must be drawn.
  • mindistance - integer - rw.
  • minfeaturesize - integer - rw - minimum feature size (in pixels) to label.
  • maxsize - integer - rw.
  • minsize - integer - rw.
  • offsetx - integer - rw.
  • offsety - integer - rw.
  • outlinecolor - integer - rw.
  • partials - integer - rw - can labels run off an image.
  • position - integer - rw.
  • shadowcolor - integer - rw.
  • shadowsizex - integer - rw.
  • shadowsizey - integer - rw.
  • size - integer - rw.
  • sizescaled - integer - rw.
  • type - MS_FONT_TYPE - rw.
  • wrap - character - rw.

  • Example:

    Methods: Method Description Returns Notes
    none

    Example:


    layerObj:

    Constructor:
    new layerObj(mapObj)

    Example: $layer = new layerObj($map);
    Normally you obtain layerObj from an existing layer within a map, however you can create a new layer.

    Members:
  • annotate - integer - rw - boolean flag for annotation.
  • classitem - character - rw - .DBF item to be used for symbol lookup.
  • classitemindex - integer - rw.
  • connection - character - rw.
  • connectiontype - MS_CONNECTION_TYPE - rw.
  • data - character - rw - filename, can be relative or full path.
  • dump - integer - rw.
  • filteritem - character - rw.
  • filteritemindex - integer - rw.
  • footer - character - rw - only used with multi result queries.
  • group - character - rw - should not be unique.
  • header - character - rw.
  • index - integer - rw.
  • items - character - rw.
  • labelangleitem - character - rw.
  • labelangleitemindex - integer - rw.
  • labelcache - integer - rw.
  • labelitem - character - rw.
  • labelitemindex - integer - rw.
  • labelmaxscale - double - rw.
  • labelminscale - double - rw.
  • labelrequires - character - rw.
  • labelsizeitem - character - rw.
  • labelsizeitemindex - integer - rw.
  • maxfeatures - integer - rw.
  • maxscale - double - rw.
  • minscale - double - rw.
  • name - character - rw - should be unique.
  • numclasses - integer - ro - number of classes in the layer.
  • numitems - integer - rw.
  • offsite - integer - rw - color index to treat as transparent for raster layers.
  • postlabelcache - integer - rw - on or off.
  • requires - character - rw - context expressions, simple enough to not use expressionObj.
  • resultcache - resultCacheObj - rw - holds the results of a query against this layer.
  • sizeunits - integer - rw - applies to all classes.
  • status - integer - rw - on or off.
  • styleitem - character - rw - item to be used for style lookup - can also be 'AUTO'.
  • styleitemindex - integer - rw.
  • symbolscale - double - rw - scale at which symbols are default size.
  • template - character - rw - global template, used across all classes.
  • tileindex - character - rw - layer index file for tiling support.
  • tileitem - character - rw.
  • tileitemindex - integer - rw.
  • tolerance - double - rw - search buffer for point and line queries (in toleranceunits).
  • toleranceunits - integer - rw.
  • transform - integer - rw - does this layer have to be transformed to file coordinates.
  • transparency - integer - rw - transparency value 0-100.
  • type - MS_LAYER_TYPE - rw.
  • units - integer - rw - units of the projection.

  • Examples: $num_classes = $layer->{numclasses};
    $result_cache = $layer->{resultcache};

    Methods: Method Description Returns Notes
    addFeature(shapeObj shape) integer, -1 on failure
    close() void
    draw(mapObj, imageObj) Draws a single layer and adds labels to the cache if required. integer
    drawQuery(mapObj, imageObj) integer
    getClass(integer index) Retrieves a classObj given an index value. classObj Class index values start at 0. Total number of classes defined in a layer is $layer->{numclasses}.
    getItem(integer) Returns an existing item name. character
    getMetaData(character name) character
    getProjection() character
    getResult(integer member) Retrieves the nth member of the result cache created by the previous query, ie. queryByPoint. resultCacheMemberObj
    getShape(shapeObj, integer tileindex, integer shapeindex) integer See open() & close().
    Seems to equate to new shapefileObj(), get(), & undef.
    open(character path) integer
    queryByAttributes(mapObj, integer mode) integer
    queryByFeatures(mapObj, integer slayer) Queries a single layer using another set of results. integer
    queryByPoint(mapObj,pointObj,integer mode,double buffer) Queries a single layer using a point. integer "mode" is MS_SINGLE or MS_MULTIPLE. Defaults to tolerances set in the mapfile but can use a constant buffer instead.
    queryByRect(mapObj,rectObj) Queries a single layer using a rectangle. integer
    queryByShape(mapObj,shapeObj) integer
    setFilter(character string filter) integer
    setProjection(character string parameters) Sets the projection and coordinate system for the layer. integer Parameters are given as a single string of comma delimited PROJ.4 parameters, ie. "proj=utm,ellps=GRS80,zone=15,north,no_defs".
    setMetaData(character name,character value) integer - MS_FAILURE,MS_SUCCESS
    setWKTProjection(character string) integer
    getWMSFeatureInfoURL(mapObj,integer click_x,integer click_y,integer feature_count,character info_format) character

    Example: $qryresult = $layer->queryByPoint($map,$point,$mapscript::MS_SINGLE,0);
    $resultmember = $layer->getResult(0);

    $query = "(([AREA]>500000 AND [AREA]<=1000000) AND ([CODE]=311 OR [CODE]=312))";
    $layer->setFilter($query);
    (thanks to Armin Burger)


    legendObj:

    Constructor:
    n/a

    Example:

    Members:
  • height - integer - rw.
  • imagecolor - colorObj - rw.
  • interlace - integer - rw.
  • keysizex - integer - rw.
  • keysizey - integer - rw.
  • keyspacingx - integer - rw.
  • keyspacingy - integer - rw.
  • label - labelObj - rw.
  • outlinecolor - integer - rw - color of outline of box, -1 for no outline.
  • position - integer - rw - for embeded legends.
  • postlabelcache - integer - rw.
  • status - integer - rw - ON, OFF or EMBED.
  • template - character - rw.
  • transparent - integer - rw.
  • width - integer - rw.

  • Example:

    Methods: Method Description Returns Notes
    none

    Example:


    lineObj:

    Constructor:
    new lineObj()

    Example: $line = new lineObj();

    Members:
  • numpoints - integer - rw - number of points in this line.
  • point - pointObj - rw.

  • Examples: $numpoints = $line->{numpoints};

    Methods: Method Description Returns Notes
    add(pointObj) Adds a point to the end of the line. integer, -1 on failure
    get(integer) pointObj
    project(projectionObj in,projectionObj out) integer

    Example:
          for($j=0; $j<$numpoints; $j++) {
            $point = $line->get($j);
          }


    mapObj:

    Constructor:
    new mapObj(mapfile name)

    Example: $map = new mapObj('demo.map');
    If the filename is undefined an empty mapObj is created and initialized.

    Members:
    Parameters that consist of a list (eg. size) can be accessed using individual list members- see below.
    All parameter names are to be given in lowercase.
  • cellsize - double - rw - in map units.
  • extent - rectObj - rw - map extent array.
  • height - integer - rw.
  • imagecolor - colorObj - rw - holds the initial image color value.
  • imagequality - integer - rw.
  • imagetype - integer - rw.
  • interlace - integer - rw.
  • labelcache - labelCacheObj - rw.
  • layerorder - integer - rw.
  • layers - layerObj - rw.
  • legend - legendObj - rw.
  • name - character - rw - small identifier for naming etc.
  • numlayers - integer - ro - number of layers in the map.
  • palette - paletteObj - rw - paletteObj is used to hold colors while a mapfile is read.
  • querymap - queryMapObj - rw.
  • reference - referenceMapObj - rw.
  • resolution - integer - rw.
  • scale - double - rw - scale of the output image.
  • scalebar - scalebarObj - rw.
  • shapepath - character - rw - where are the shape files located.
  • status - integer - rw - map creation on or off.
  • transparent - integer - rw.
  • units - MS_UNITS - rw - units of the projection.
  • web - webObj - rw.
  • width - integer - rw.
  • map, legend, scalebar, and reference map size use height and width
  • legend keysize use keysizex and keysizey
  • legend keyspacing use keyspacingx and keyspacingy

  • Examples: $minx = $map->{extent}->{minx};
    $map->{interlace} = $mapscript::MS_TRUE;
    $map->{legend}->{keysizex} = 18;
    $map->{legend}->{keyspacingx} = 4;
    $map->{legend}->{label}->{font} = "congobold";
    $map->{legend}->{label}->{sizescaled} = 8; (TT font you use needs to be loaded on your system first.)
    $map->{legend}->{label}->{type}=$mapscript::MS_TRUETYPE;
    $map->{name} = 'example.map';
    $num_layers = $map->{numlayers};
    $map->{scalebar}->{color} = $map->addColor(255,255,255);
    $map->{scalebar}->{width} = 50;

    Methods: Method Description Returns Notes
    addColor(integer red,integer green,integer blue) Adds a color to the maps palette. integer Color values can range from 0 to 255. Must be called prior to draw() or prepareImage().
    draw() Renders a map. imageObj
    drawLabelCache(imageObj) Renders the labels for a map. integer Done as part of the draw() method but may need called when using other object draw methods.
    drawLegend() Renders a legend. imageObj
    drawQuery() Renders a query map. imageObj
    drawReferenceMap() Renders a reference map. imageObj
    drawScalebar Renders a scalebar. imageObj
    embedLegend(imageObj) Embeds a legend in a map. integer Adds legend to label cache. Invoke drawLabelCache(imageObj) to render (unless postlabelcache is set).
    embedScalebar(image) Embeds a scalebar in a map. integer Adds scalebar to label cache. Invoke drawLabelCache(imageObj) to render (unless postlabelcache is set).
    getImageToVar(imageObj,character varname) integer
    getLayer(integer index) Retrieves a layer by index. layerObj Layer indexes start with 0. Total number of layers in a mapfile is $map->{numlayers};.
    getLayerByName(character name) Retrieves a layer by name. layerObj If multiple layers exist with the same name the first occurence is returned.
    getLayersdrawingOrder() integer
    getMetaData(character name) character
    mapObj_getNumSymbols() integer
    getProjection() character
    getSymbolByName(character name) Retrieves the symbol index by name. integer -1 if symbol is not found
    moveLayerdown(layerindex) integer
    moveLayerup(layerindex) integer
    nextLabel() Allows you to step through the label cache. labelCacheMemberObj One reason to do this would be to produce an imagemap based on annotation or post process a map by avoiding text.
    prepareImage() Initializes an image for drawing a map. imageObj Must be called prior to calling the draw methods for other objects (not draw()).
    prepareQuery() void
    processLegendTemplate(names,values,numentries) character
    processQueryTemplate(names,values,numentries) character
    processTemplate(bGenerateImages,names,values,numentries) character
    queryByFeatures(int slayer) Queries a group of layers using another set of results. integer
    queryByPoint(point,int mode,double buffer) Queries a group of layers using a point. integer "mode" is MS_SINGLE or MS_MULTIPLE. Defaults to tolerances set in the mapfile but can use a constant buffer instead.
    queryByRect(rectObj) Queries a group of layers using a rectangle. integer
    queryByShape(shapeObj) integer
    save(char filename) Writes the contents of a mapfile to disk. integer
    saveQuery(char filename) integer
    saveQueryAsGML(char filename) integer
    setLayersdrawingOrder(panIndexes) integer
    setMetaData(char name,char value) integer
    setProjection(string parameters) Sets the projection and coordinate system for the map. integer Parameters are given as a single string of comma delimited PROJ.4 parameters, ie. "proj=utm,ellps=GRS80,zone=15,north,no_defs".
    setSymbolSet(szFileName) integer
    setWKTProjection(char string) integer

    Example: Prints the string and bounding polygon(s) for all labels in the cache that are actually drawn.
          while ( $label = $map->nextLabel()) {
            if ( $label->{status} ) {
              print $label->{string} . "\n";
              $shape = $label->{poly};
              for ( $i=0; $i<$shape->{numlines}; i++ ) {
                $part = $shape->get($i);
                for ( $j=0; $j<$part->{numpoints}; $j++) {
                  $point = $part->get($j);
                  print $point->{x} . "," . $point->{y} . " ";
                }
                print "\n";
              }
            }
          }


    markerCacheMemberObj:

    Constructor:
    n/a

    Example:

    Members:
  • id - integer - rw.
  • poly - shapeObj - rw - marker bounding box (POINT layers only).

  • Example:

    Methods: Method Description Returns Notes
    none

    Example:


    pointObj:

    Constructor:
    new pointObj()

    Example: $point = new pointObj();

    Members:
  • m - double - rw.
  • x - double - rw - x coordinate.
  • y - double - rw - y coordinate.

  • Examples: $point->{x} = 100;
    $pointx = $point->{x};
    $pointy = $point->{y};

    Methods: Method Description Returns Notes
    distanceToLine(pointObj a,pointObj b) double
    distanceToPoint(pointObj) double
    distanceToShape(shapeObj) double, -1 if shape type is not recognized
    draw(mapObj,layerObj,imageObj,integer classindex,character text) Draws an individual point using layerObj. integer The class_index is used to classify the point based on the classes defined for layerObj.
    The text string is used to annotate the point.
    project(projectionObj in,projectionObj out) integer

    Examples:
          my $distance = $point->distanceToPoint($garagepoint);
        


    projectionObj:

    Constructor:
    new projectionObj(string)

    Example: my $projection = new projectionObj('proj=utm,ellps=GRS80,zone=15,north,no_defs');

    Members:
  • args - character - rw - variable number of projection args.
  • numargs - integer - rw - actual number of projection args.
  • proj - void - rw.

  • Example:

    Methods: Method Description Returns Notes
    none

    Example:


    queryMapObj:

    Constructor:
    n/a

    Example:

    Members:
  • color - integer - rw.
  • height - integer - rw.
  • status - integer - rw.
  • style - integer - rw - HILITE, SELECTED or NORMAL.
  • width - integer - rw.

  • Example:

    Methods: Method Description Returns Notes
    none

    Example:


    rectObj:

    Constructor:
    new rectObj()

    Example: my $rectangle = new rectObj();

    Members:
  • minx - double - rw - left.
  • miny - double - rw - lower.
  • maxx - double - rw - right.
  • maxy - double - rw - upper.

  • Example: $rectangle->{minx} = 0;
    $rectangle->{miny} = 0;
    $rectangle->{maxx} = 10;
    $rectangle->{maxy} = 10;

    Methods: Method Description Returns Notes
    draw(mapObj,layerObj,imageObj,integer classindex,character text) Draws an individual rectangle using layerObj. integer, 0 on success The class_index is used to classify the feature based on the classes defined for layerObj.
    The text string is used to annotate the shape.
    fit(integer width,integer height) Adjusts a rectangle to fit a size. double
    project(projectionObj in,projectionObj out) integer

    Example:


    referenceMapObj:

    Constructor:
    n/a

    Example:

    Members:
  • color - colorObj - rw.
  • extent - rectObj - rw.
  • height - integer - rw.
  • image - character - rw.
  • maxboxsize - integer - rw.
  • marker - integer - rw.
  • markername - character - rw.
  • markersize - integer - rw.
  • minboxsize - integer - rw.
  • outlinecolor - colorObj - rw.
  • status - integer - rw.
  • width - integer - rw.

  • Example:

    Methods: Method Description Returns Notes
    none

    Example:


    resultCacheMemberObj:

    Constructor:
    n/a

    Example: $resultmember = $layer->getResult(0);

    Members:
  • classindex - character - rw.
  • shapeindex - integer - rw.
  • tileindex - integer - rw.

  • Example: $shaperecnum = $resultmember->{shapeindex};

    Methods: Method Description Returns Notes
    None

    Example:


    resultCacheObj:

    Constructor:
    n/a

    Example: $resultcache = $layer->{resultcache};

    Members:
  • bounds - rectObj - rw.
  • numresults - integer - rw - total number of matching records.

  • Example: $resultsfnd = $resultcache->{numresults};

    Methods: Method Description Returns Notes
    None

    Example:


    scalebarObj:

    Constructor:
    n/a

    Example:

    Members:
  • backgroundcolor - integer - rw.
  • color - integer - rw.
  • height - integer - rw.
  • imagecolor - colorObj - rw.
  • interlace - integer - rw.
  • intervals - integer - rw.
  • label - labelObj - rw.
  • outlinecolor - integer - rw.
  • position - integer - rw - for embeded scalebars.
  • postlabelcache - integer - rw.
  • status - integer - rw - ON, OFF or EMBED.
  • style - integer - rw.
  • transparent - integer - rw.
  • units - integer - rw.
  • width - integer - rw.

  • Example:

    Methods: Method Description Returns Notes
    none

    Example:


    shapefileObj:

    Constructor:
    new shapefileObj(filename,type)

    Example: $shapefile = new shapefileObj('lakes',-1) or die "Unable to open lakes shapefile";
    No extension is necessary.
    For existing files type should be -1.
    To create an empty file type can be MS_SHAPEFILE_POINT, MS_SHAPEFILE_ARC, MS_SHAPEFILE_POLYGON, or MS_SHAPEFILE_MULTIPOINT.
    To Close a shapefile you've opened you need to undefine the reference, ie. "undef $shapefile;" or "$shapefile = '';".

    Members:
  • bounds - rectObj - ro - The shapefiles bounding box.
  • lastshape - integer - ro.
  • numshapes - integer - ro - number of shapes in the shapefile.
  • shapepath - character - ro.
  • source - character - ro - full path to shapefile.
  • status - character - ro.
  • statusbounds - rectObj - roi - holds extent associated with the status vector.
  • type - integer - ro - type of shapefile.

  • Examples: $extents = $shapefile->{bounds};
    $minx = $extents->{minx};
    $miny = $extents->{miny};
    $maxx = $extents->{maxx};
    $maxy = $extents->{maxy};
    $numshapes = $shapefile->{numshapes};
    $typeno = $shapefile->{type};

    Methods: Method Description Returns Notes
    add(shapeObj) Appends a shape to an open file. integer
    addPoint(pointObj) integer
    get(integer index,shapeObj) Retrieves a shape by index. integer, -1 if index is < 0 or >= number of shapes
    getExtent(integer index,rectObj) Retrieves a shape bounding box by index. void
    getPoint(integer index,pointObj) integer, -1 if index is < 0 or >= number of shapes
    getTransformed(mapObj,integer index,shapeObj) integer, -1 if index is < 0 or >= number of shapes

    Example: $shapefile->add($shape);
    This example saves a selected polygon shape into a new shapefile.
          #
          # Open the map.
          my $map = new mapObj('your.map');
          #
          # Create the layer object to query.
          my $layer = new layerObj($map);
          #
          # Create a new shapefile for the selection set.
          my $newshpf = new shapefileObj("$newshpfname", 5);
          #
          # Set index value for selected shape.
          my $poly = 400;
          #
          # Create a shapefile object for getting queried shape.
          my $shpf = new shapefileObj("data_shapefile", -1);
          #
          # Create shape object for storing queried shape.
          my $shp = new shapeObj(-1);
          #
          # Retrieve shape into shape object.
          $shpf->get($poly, $shp);
          #
          # Put shape into new shapefile.
          $newshpf->add($shp);
          #
          # Create dbf to go with new.
          @toucherror = system("touch $newshpfname.dbf");
          #
          # Get the extent of the new shapefile.
          my $newrect = $newshpf->{bounds};
          my $newminx = $newrect->{minx};
          my $newminy = $newrect->{miny};
          my $newmaxx = $newrect->{maxx};
          my $newmaxy = $newrect->{maxy};
          #
          # Close new shapefile.
          undef $newshpf;
        


    shapeObj:

    Constructor:
    new shapeObj(type)

    Examples: $shape = new shapeObj(-1);
    $shape = new shapeObj($mapscript::MS_SHAPE_POLYGON);

    Members:
  • bounds - rectObj - rw - the shapes bounding box.
  • classindex - integer - rw.
  • index - integer - rw.
  • line - lineObj - rw.
  • numlines - integer - rw - number of lines in this shape.
  • numvalues - integer - rw.
  • text - character - rw.
  • tileindex - integer - rw.
  • type - integer - rw - generic type (MS_SHAPE_POINT, MS_SHAPE_LINE, MS_SHAPE_POLYGON) of this shape.
  • values - character - rw.

  • Examples: $extents = $shape->{bounds};
    $minx = $shape->{bounds}->{minx};
    $miny = $shape->{bounds}->{miny};
    $maxx = $shape->{bounds}->{maxx};
    $maxy = $shape->{bounds}->{maxy};
    $numlines = $shape->{numlines};

    Methods: Method Description Returns Notes
    add(lineObj) Adds a line to the shape. integer
    contains(pointObj) integer, -1 if shape is not polygon
    copy(shapeObj destination) integer
    draw(mapObj,layerObj,imageObj) Draws an individual shape using layerObj. integer
    get(integer index) lineObj
    getValue(integer index) returns an existing value. character
    intersects(shapeObj) integer, -1 if shape is not line or polygon
    project(projectionObj in,projectionObj out) integer
    setBounds() void

    Examples: This example retrieves all of the x,y's for all the lines in a polygon shape.
          #
          # Create shape object.
          $shp = new shapeObj(-1);
          #
          # Retrieve shape into shape object.
          $shpfile->get(1,$shp);
          #
          # How many lines in shape.
          my $num_lines = $shp->{numlines};
          #
          # Loop through each line.
          for ( $line_num=0; $line_num<$num_lines; $line_num++ ) {
            #
            # Get line.
            my $line = new lineObj();
            $line = $ishp->get($line_num);
            print "Got Line #$line_num\n";
            #
            # How many points in line.
            my $num_points = $line->{numpoints};
            #
            # Loop through each point.
            for ( $point_num=0; $point_num<$num_points; $point_num++ ) {
              #
              # Get the point.
              my $point = new pointObj();
              $point = $line->get($point_num);
              print "Got Point #$point_num";
              $px = $point->{x};
              $py = $point->{y};
              print " X=$px Y=$py\n";
            }
          }
          print "\n";
        
          for($i=0; $i<$numshapes; i++) {
            $shapefile->get($i, $shape);
            ...
          }


    styleObj:

    Constructor:
    n/a

    Example:

    Members:
  • background - integer - rw.
  • color - integer - rw.
  • maxsize - integer - rw.
  • minsize - minsize - rw.
  • outlinecolor - integer - rw.
  • size - integer - rw.
  • sizescaled - integer - rw.
  • symbol - integer - rw.
  • symbolname - character - rw.

  • Example:

    Methods: Method Description Returns Notes
    none

    Example:


    webObj:

    Constructor:
    n/a

    Example:

    Members:
  • empty - character - rw.
  • error - character - rw - error handling.
  • extent - rectObj - rw - clipping extent.
  • footer - character - rw.
  • header - character - rw.
  • imagepath - character - rw.
  • imageurl - caracter - rw.
  • log - character - rw.
  • maxscale - double - rw.
  • maxtemplate - character - rw.
  • minscale - double - rw.
  • mintemplate - character - rw.
  • template - character - rw.

  • Example:

    Methods: Method Description Returns Notes
    none

    Example:


    Miscellaneous Commands:
    The MapServer distribution supplies the following command of interest.
    shp2pdf -m [mapfile] -o [pdf] -l [layers] Saves a mapfile as a pdf.

    Example:
          #
          # Save the current map.
          $map->save("tobepdf.map");
          #
          # Convert the map to pdf.
          @topdferror = system("shp2pdf -m tobepdf.map -o map.pdf");
        


    Miscellaneous Functions:
    GetMapserverUnitUsingProj(psProj); returns integer.
    msDBFAddField(hDBF,field_name,field_type,field_width,decimal_places); returns integer.
    msDBFClose(hDBF); returns void.
    msDBFCreate(dbf_filename); returns hDBF.
    msDBFGetFieldCount(hDBF); returns integer.
    msDBFGetFieldInfo(hDBFi,field_index,field_name,field_width,decimal_places); returns FTDouble, FTInteger, FTString.
    msDBFGetItemIndex(dbf_filename,item name); returns integer.
    msDBFGetItemIndexes(dbf_filename,items,number_of_items); returns integer.
    msDBFGetItems(dbf_filename); returns character.
    msDBFGetRecordCount(dbf_filename); returns integer.
    msDBFGetValueList(dbf_filename,record_number,item_indexes,number_of_items); returns character.
    msDBFGetValues(dbf_filename,record_number); returns character.
    msDBFOpen(dbf_filename,access_mode); Returns hDBF
    access_mode is one of: rb+, r+b, or r+
    msDBFReadDoubleAttribute(hdbf,shape_index,field_index); returns double
    msDBFReadStringAttribute(hDBF,shape_index,field_index); returns character
    msDBFReadIntegerAttribute(hDBF,shape_index,field_index); returns integer.
    msDBFWriteDoubleAttribute(hDBF,shape_index,field_index,new_double_value); returns integer
    msDBFWriteIntegerAttribute(hDBF,shape_index,field_index,new_integer_value); returns integer
    msDBFWriteStringAttribute(hDBF,shape_index,field_index,new_string_value); returns integer
    msFreeImage(imgObj); Frees the memory associated with an image.
    msGetVersion();
    msSaveImage(imgObj,filename,type,transparent,interlace,quality); Saves an image to a file.
    Set filename to undef to save to stdout.
    The transparent and interlace flags are boolean values.
    The filetype is $mapscript::MS_GIF=GIF, $mapscript::MS_PNG=PNG, $mapscript::MS_JPEG=JPEG, $mapscript::MS_WBMP=WBMP.
    The quality is 0-95. Ignored for all but JPEG.


    Error Handling:
    Current error handling supports returned codes (where applicable).
    Please see the wiki.