Perl MapScript Reference

Abstract: Work In Progress
This document is a reference to the Perl MapScript syntax for MapServer version 3.5.
Last Updated: 5/9/2002 by Lowell Filak
Medina County Engineer's Office
Medina, Ohio
United States


Table of Contents:

Introduction
Usage
Constants
Classes/Objects
mapObj(ect)
layerObj(ect)
classObj(ect)
colorObj(ect)
DBFInfo
errorObj(ect)
featureListNodeObj(ect)
itemObj(ect)
labelCacheMemberObj(ect)
labelCacheObj(ect)
labelObj(ect)
legendObj(ect)
lineObj(ect)
markerCacheMemberObj(ect)
pointObj(ect)
projectionObj(ect)
queryMapObj(ect)
rectObj(ect)
referenceMapObj(ect)
resultCacheMemberObj(ect)
resultCacheObj(ect)
scalebarObj(ect)
shapefileObj(ect)
shapeObj(ect)
symbolSetObj(ect)
webObj(ect)
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 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;
$map = new mapObj('example.map) or die('Unable to open mapfile.');
$img = $map->draw() or die('Unable to draw map');
mapscript::msSaveImage($img, 'example.png', 2, $map->{interlace}, $map->{transparent}, 95);

Usage:
Perl - use mapscript;

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

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

general error codes

MS_NOERR
MS_IOERR
MS_MEMERR
MS_TYPEERR
MS_DBFERR
MS_GDERR
MS_IDENTERR
MS_EOFERR
MS_PROJERR
MS_MISCERR
MS_CGIERR
MS_WEBERR
MS_IMGERR
MS_HASERR
MS_JOINERR
MS_NOTFOUND
MS_SHPERR
MS_PARSEERR
MS_SDEERR
MS_OGRERR
MS_QUERYERR
MS_WMSERR
MS_WMSCONNERR
MS_ORACLESPATIALERR
MS_NUMERRORCODES
MESSAGELENGTH
ROUTINELENGTH

Example: $mapscript::MS_ON or $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

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

mapObj holds all mapfile parameters
layerObj holds all layer parameters
exists within a mapObj
classObj holds all class parameters
exists within a layerObj
colorObj
DBFInfo
errorObj
featureListNodeObj
itemObj
labelCacheMemberObj holds a single element from the label cache
labelCacheObj
labelObj
legendObj
lineObj made up of pointObjs
may or may not be a closed ring
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
symbolSetObj
webObj

mapObj:

Constructor:
new mapObj(mapfile name)

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

Members: See the mapfile documentation for a list of parameters that can be changed.
To get/set layer parameters you'll need to use one of the methods defined below.
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.
  • extent - rectObj - rw.
  • height - integer - rw.
  • imagecolor - colorObj - rw.
  • imagequality - integer - rw.
  • imagetype - integer - rw.
  • interlace - integer - rw.
  • labelcache - labelCacheObj - rw.
  • latlon - projectionObj - rw.
  • layerorder - integer - rw.
  • layers - layerObj - rw.
  • legend - legendObj - rw.
  • name - character - rw.
  • numlayers - integer - ro - number of layers in the map.
  • palette - paletteObj - rw - paletteObj is used to hold colors while a mapfile is read.
  • projection - projectionObj - rw.
  • reference - referenceMapObj - rw.
  • resolution - integer - rw.
  • scale - double - rw.
  • scalebar - scalebarObj - rw.
  • shapepath - character - rw.
  • status - integer - rw.
  • transparent - integer - rw.
  • units - MS_UNITS - rw.
  • 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: Type Method Description Returns Notes
    integer addColor(integer red,integer green,integer blue) Adds a color to the maps palette. color index Color values can range from 0 to 255. Must be called prior to draw() or prepareImage().
    image draw() Renders a map. map image
    integer drawLabelCache(image) Renders the labels for a map. Done as part of the draw() method but may need called when using other object draw methods.
    image drawLegend() Renders a legend. legend image
    image drawQuery() Renders a query map. query map image
    image drawReferenceMap() Renders a reference map. reference map image
    image drawScalebar Renders a scalebar. scalebar image
    integer embedLegend(image) Embeds a legend in a map. Adds legend to label cache. Invoke drawLabelCache(image) to render (unless postlabelcache is set).
    integer embedScalebar(image) Embeds a scalebar in a map. Adds scalebar to label cache. Invoke drawLabelCache(image) to render (unless postlabelcache is set).
    integer getImageToVar(image,character varname)
    layerObj getLayer(integer index) Retrieves a layer by index. layerObj Layer indexes start with 0. Total number of layers in a mapfile is $map->{numlayers};.
    layerObj getLayerByName(character name) Retrieves a layer by name. layerObj If multiple layers exist with the same name the first occurence is returned.
    character getMetaData(character name)
    character getProjection()
    integer getSymbolByName(character name) Retrieves the symbol index by name. -1 if symbol is not found
    labelCacheMemberObj 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.
    image prepareImage() Initializes an image for drawing a map. blank image Must be called prior to calling the draw methods for other objects (not draw()).
    void prepareQuery()
    integer 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. "mode" is MS_SINGLE or MS_MULTIPLE. Defaults to tolerances set in the mapfile but can use a constant buffer instead.
    integer 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 setMetaData(char name,char value)
    integer setProjection(char parameters) Sets the projection and coordinate system for the map. Parameters are given as a single string of comma delimited PROJ.4 parameters, ie. "proj=utm,ellps=GRS80,zone=15,north,no_defs".
    integer setWKTProjection(char string)

    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";
              }
            }
          }

    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: See the mapfile documentation for a list of parameters that can be changed.
  • annotate - integer - rw.
  • class - classObj - rw.
  • classitem - character - rw.
  • classitemindex - integer - rw.
  • connection - character - rw.
  • connectiontype - MS_CONNECTION_TYPE - rw.
  • currentfeature - featureListNodeObj - rw.
  • data - character - rw.
  • dump - integer - rw.
  • features - featureListNodeObj - rw.
  • filteritem - character - rw.
  • filteritemindex - integer - rw.
  • footer - character - rw.
  • group - character - rw.
  • header - character - rw.
  • index - integer - rw.
  • items - character - rw.
  • iteminfo - void - 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.
  • metadata - hashTableObj (hash) - rw.
  • minscale - double - rw.
  • name - character - rw.
  • numclasses - integer - ro - number of classes in the layer.
  • numitems - integer - rw.
  • offsite - integer - rw - color index to treat as transparent.
  • ogrlayerinfo - void - rw.
  • oraclespatiallayerinfo - void - rw.
  • postgislayerinfo - void - rw.
  • postlabelcache - integer - rw.
  • projection - projectionObj - rw.
  • requires -aracter - rw.
  • resultcache - resultCacheObj - rw.
  • sdelayerinfo - void - rw.
  • shpfile - shapefileObj - rw.
  • sizeunits - integer - rw.
  • status - integer - rw.
  • styleitem - character - rw.
  • styleitemindex - integer - rw.
  • symbolscale - double - rw.
  • template - character - rw..
  • tileindex - character - rw.
  • tileitem - character - rw.
  • tileitemindex - integer - rw.
  • tileshpfile - shapefileObj - rw.
  • tolerance - double - rw.
  • toleranceunits - integer - rw.
  • transform - integer - rw.
  • type - MS_LAYER_TYPE - rw.
  • units - integer - rw.

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

    Methods: Type Method Description Returns Notes
    integer addFeature(shapeObj shape) -1 on failure
    void close()
    integer draw(mapObj, image) Draws a single layer and adds labels to the cache if required.
    integer drawQuery(mapObj, image)
    classObj 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 $class->{numclasses}.
    character getItem(integer) Returns an existing item name.
    character getMetaData(character name)
    character getProjection()
    resultCacheMemberObj getResult(integer member) Retrieves the nth member of the result cache created by the previous query, ie. queryByPoint.
    integer getShape(shapeObj,integer tileindex,integer shapeindex)
    integer 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. "type" is MS_SINGLE or MS_MULTIPLE. Defaults to tolerances set in the mapfile but can use a constant buffer instead.
    integer 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 map. Parameters are given as a single string of comma delimited PROJ.4 parameters, ie. "proj=utm,ellps=GRS80,zone=15,north,no_defs".
    integer setMetaData(character name,character value) MS_FAILURE,MS_SUCCESS
    integer setWKTProjection(character string)
    character getWMSFeatureInfoURL(mapObj,integer click_x,integer click_y,integer feature_count,character info_format)

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


    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.
  • maxsize - integer - rw.
  • metadata - hashTableObj(hash) - rw.
  • minsize - integer - rw.
  • name - character - rw.
  • 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.
  • type - integer - rw.

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

    Methods: Type Method Description Returns Notes
    integer setExpression(character string)
    character getMetaData(character name)
    integer setMetaData(character name,character value) MS_FAILURE,MS_SUCCESS
    integer setText(layerObj,character string)

    Example:


    colorObj:

    Constructor:
    n/a

    Example:

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

  • Example:

    Methods: Type Method Description Returns Notes
    none

    Example:


    DBFInfo:

    Constructor:
    n/a

    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.
  • panFieldDecimals - integer - ro.
  • panFieldOffset - integer - ro.
  • panFieldSize - integer - ro.
  • pachFieldType - character - ro.
  • pszCurrentRecord - character - ro.
  • pszHeader - character - ro.

  • Examples: See Method Examples below.

    Methods: Type Method Description Returns Notes
    integer getFieldDecimals(int)
    character getFieldName(int)
    integer getFieldWidth(int)
    integer getFieldType(int) 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 = $shapefile->{hDBF};
          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)
          }


    errorObj:

    Constructor:
    n/a

    Example:

    Members:
  • code - integer - rw.
  • message - character - ro.
  • routine - character - ro.

  • Example:

    Methods: Type Method Description Returns Notes
    none

    Example:


    featureListNodeObj:

    Constructor:
    n/a

    Example:

    Members:
  • next - featureListNodeObj - rw.
  • shape - shapeObj - rw.

  • Example:

    Methods: Type Method Description Returns Notes
    none

    Example:


    itemObj:

    Constructor:
    n/a

    Example:

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

  • Example:

    Methods: Type Method Description Returns Notes
    none

    Example:


    labelCacheMemberObj:

    Constructor:
    n/a

    Example:

    Members:
  • class - classObj - rw.
  • classidx - integer - rw.
  • featuresize - double - rw.
  • layeridx - integer - rw.
  • point - pointObj - rw.
  • poly - shapeObj - rw.
  • shapeidx - integer - rw.
  • status - integer - rw.
  • string - character - rw.
  • tileidx - integer - rw.

  • Example:

    Methods: Type 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: Type Method Description Returns Notes
    none

    Example:


    labelObj:

    Constructor:
    n/a

    Example:

    Members:
  • angle - double - rw.
  • antialias - integer - rw.
  • autoangle - integer - rw.
  • autominfeaturesize - integer - rw.
  • backgroundcolor - integer - rw.
  • backgroundshadowcolor - integer - rw.
  • backgroundshadowsizex - integer - rw.
  • backgroundshadowsizey - integer - rw.
  • buffer - integer - rw.
  • color - integer - rw.
  • font - character - rw.
  • force - integer - rw.
  • mindistance - integer - rw.
  • minfeaturesize - integer - rw.
  • maxsize - integer - rw.
  • minsize - integer - rw.
  • offsetx - integer - rw.
  • offsety - integer - rw.
  • outlinecolor - integer - rw.
  • partials - integer - rw.
  • 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: Type Method Description Returns Notes
    none

    Example:


    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.
  • position - integer - rw.
  • postlabelcache - integer - rw.
  • status - integer - rw.
  • transparent - integer - rw.
  • width - integer - rw.

  • Example:

    Methods: Type 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: Type Method Description Returns Notes
    integer add(pointObj) Adds a point to the end of the line. -1 on failure
    pointObj get(integer)
    integer project(projectionObj in,projectionObj out)

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


    markerCacheMemberObj:

    Constructor:
    n/a

    Example:

    Members:
  • id - integer - rw.
  • poly - shapeObj - rw.

  • Example:

    Methods: Type Method Description Returns Notes
    none

    Example:


    pointObj:

    Constructor:
    new pointObj()

    Example: $point = new pointObj();

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

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

    Methods: Type Method Description Returns Notes
    double distanceToLine(pointObj a,pointObj b)
    double distanceToShape(shapeObj) -1 if shape type is not recognized
    double distanceToPoint(pointObj)
    integer draw(mapObj,layerObj,image,integer class_index,character text) Draws an individual point using layerObj. 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.
    integer project(pointObj in,pointObj out)

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


    projectionObj:

    Constructor:
    n/a

    Example:

    Members:
  • args - character - rw.
  • numargs - integer - rw.
  • proj - void - rw.

  • Example:

    Methods: Type Method Description Returns Notes
    none

    Example:


    queryMapObj:

    Constructor:
    n/a

    Example:

    Members:
  • color - integer - rw.
  • height - integer - rw.
  • status - integer - rw.
  • style - integer - rw.
  • width - integer - rw.

  • Example:

    Methods: Type Method Description Returns Notes
    none

    Example:


    rectObj:

    Constructor:
    new rectObj()

    Example: $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: Type Method Description Returns Notes
    integer draw(mapObj,layerObj,image,integer class_index,character text) Draws an individual rectangle using layerObj. 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.
    double fit(integer width,integer height) Adjusts a rectangle to fit a size.
    integer project(projectionObj in,projectionObj out)

    Example:


    referenceMapObj:

    Constructor:
    n/a

    Example:

    Members:
  • color - colorObj - rw.
  • extent - rectObj - rw.
  • height - integer - rw.
  • image - character - rw.
  • outlinecolor - colorObj - rw.
  • status - integer - rw.
  • width - integer - rw.

  • Example:

    Methods: Type 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: Type Method Description Returns Notes
    None

    Example:


    resultCacheObj:

    Constructor:
    n/a

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

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

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

    Methods: Type 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.
  • postlabelcache - integer - rw.
  • status - integer - rw.
  • style - integer - rw.
  • transparent - integer - rw.
  • units - integer - rw.
  • width - integer - rw.

  • Example:

    Methods: Type 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.
  • hDBF - DBFInfo - ro.
  • hSHP - SHPHandle - ro - Shapefile pointer.
  • lastshape - integer - ro.
  • numshapes - integer - ro - number of shapes in the shapefile.
  • shapepath - character - ro.
  • source - character - ro.
  • status - character - ro.
  • statusbounds - rectObj - ro.
  • 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: Type Method Description Returns Notes
    integer add(shapeObj) Appends a shape to an open file.
    integer addPoint(pointObj)
    integer get(integer index,shapeObj) Retrieves a shape by index. -1 if index is < 0 or >= number of shapes
    void getExtent(integer index,rectObj) Retrieves a shape bounding box by index.
    integer getPoint(integer index,pointObj) -1 if index is < 0 or >= number of shapes
    integer getTransformed(mapObj,integer index,shapeObj) -1 if index is < 0 or >= number of shapes

    Example: $shapefile->add($shape);
    This example saves a selected polygon shape into a newshape file so the single shape can be drawn seperately from the rest of the map, aka. highlighting.
          #
          # 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;
          #
          # Get place-holder layer.
          my $sellayer = $map->getLayerByName('selectd');
          #
          # Turn it on.
          $sellayer->{status} = $mapscript::MS_ON;
          #
          # Set the data path to the new shapefile.
          $sellayer->{data} = $newshpfname;
          #
          # Draw the map.
          $img = $map->draw();
        


    shapeObj:

    Constructor:
    new shapeObj(type)

    Examples: $shape = new shapeObj(-1);
    The type parameter is just a general type used to make MapScript less bulky.
    With it MapScript can make decisions in a few comparison methods without requiring specific methods.
    Valid values are -1, MS_SHAPE_POINT, MS_SHAPE_LINE, & MS_SHAPE_POLYGON.
    Other shape creation methods (see shapefileObj) populate this parameter correctly.
    $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: Type Method Description Returns Notes
    integer add(lineObj) Adds a line to the shape.
    integer contains(pointObj) -1 if shape is not polygon
    integer copy(shapeObj destination)
    integer draw(mapObj,layerObj,image) Draws an individual shape using layerObj.
    lineObj get(integer index)
    character getValue(integer index) returns an existing value.
    integer intersects(shapeObj) -1 if shape is not line or polygon
    integer project(projectionObj in,projectionObj out)
    void setBounds()

    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 = $ishp->{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";
            #
            # 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";
            }
          }
          print "\n";
        
          for($i=0; $i<$numshapes; i++) {
            $shapefile->get($i, $shape);
            ...
          }


    symbolSetObj:

    Constructor:
    n/a

    Example:

    Members:
  • filename - character - rw.
  • imagecache - imageCacheObj - rw - imagecache.
  • imagecachesize - integer - rw.
  • numsymbols - integer - rw.
  • symbol - symbolObj - ro - a symbol.

  • Example:

    Methods: Type Method Description Returns Notes
    none

    Example:


    webObj:

    Constructor:
    n/a

    Example:

    Members:
  • empty - character - rw.
  • error - character - rw.
  • extent - rectObj - rw.
  • footer - character - rw.
  • header - character - rw.
  • imagepath - character - rw.
  • imageurl - caracter - rw.
  • log - character - rw.
  • maxscale - double - rw.
  • maxtemplate - character - rw.
  • metadata - hashTableObj(hash) - rw.
  • minscale - double - rw.
  • mintemplate - character - rw.
  • template - character - rw.

  • Example:

    Methods: Type 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:
    MapScript supplies a few miscelaneous functions for image handling.
    msSaveImage(image, filename, filetype, 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.
    msFreeImage(image); Free the memory associated with an image.
    msGetVersion();


    Error Handling:
    Current error handling supports returned codes (where applicable) and general error codes.
    msSetError(code,message,routine);
    msWriteError(file);