PHP MapScript Version 3.4 Documentation
See also:
* the Perl MapScript documentation:
http://mapserver.gis.umn.edu/doc33/mapscript.html
* the MapServer Map File documentation:
http://mapserver.gis.umn.edu/doc33/mapfile.html
* and the rest of the MapServer 3.3 documentation:
http://mapserver.gis.umn.edu/doc33/
Very important note: Constant names and class member variable names are
case-sensitive in PHP.
Constants:
----------
The following MapServer constants are available:
Boolean values:
MS_TRUE, MS_FALSE, MS_ON, MS_OFF, MS_YES, MS_NO
Map units:
MS_INCHES, MS_FEET, MS_MILES, MS_METERS, MS_KILOMETERS, MS_DD,
MS_PIXELS
Layer types:
MS_POINT, MS_LINE, MS_POLYGON, MS_POLYLINE, MS_RASTER,
MS_ANNOTATION, MS_NULL
Layer Status:
MS_ON, MS_OFF, MS_DEFAULT, MS_QUERY, MS_EMBED
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
Bitmap font styles:
MS_TINY , MS_SMALL, MS_MEDIUM, MS_LARGE, MS_GIANT
Shapefile types:
MS_SHP_POINT, MS_SHP_ARC, MS_SHP_POLYGON, MS_SHP_MULTIPOINT
Query/join types:
MS_SINGLE, MS_MULTIPLE
Querymap styles:
MS_NORMAL, MS_HILITE, MS_SELECTED, MS_INVERTED
Connection Types:
MS_LOCAL, MS_SDE, MS_OGR
Output Image Types:
MS_GIF, MS_PNG, MS_JPEG
MapObj Class:
-------------
Constructor:
mapObj ms_newMapObj(string map_file_name)
Returns a new object to deal with a MapServer map file.
Members:
int numlayers (read-only)
string name
int status
int width
int height
int transparent
int interlace
rectObj extent;
double cellsize
int units (map units type)
double scale
string shapepath
string tile
int keysizex
int keysizey
int keyspacingx
int keyspacingy
webObj web
referenceMapObj reference
colorObj imagecolor
Methods:
int set(string property_name, new_value)
Set map object property to new value. Returns -1 on error.
int addColor(int r, int g, int b)
Add a color to map's palette. Returns color index.
int getsymbolbyname(string symbol_name)
Returns the symbol index using the name.
void preparequery()
Calculate the scale of the map and assign it to the map->scale.
imageObj prepareImage()
Return handle on blank image object.
imageObj draw()
Render map and return handle on image object.
imageObj drawquerymap()
Render a query map and return handle on image object.
imageObj drawLegend()
Render legend and return handle on image object.
imageObj drawReferenceMap()
Render reference map and return handle on image object.
imageObj drawScaleBar()
Render scale bar and return handle on image object.
int embedlegend(imageObj image)
embeds a legend. Actually the legend is just added to the label
cache so you must invoke drawLabelCache() to actually do the
rendering (unless postlabelcache is set in which case it is drawn
right away).
int embedScalebar(imageObj image)
embeds a scalebar. Actually the scalebar is just added to the label
cache so you must invoke drawLabelCache() to actually do the rendering
(unless postlabelcache is set in which case it is drawn right away).
int drawLabelCache(imageObj image)
Renders the labels for a map. Returns -1 on error.
layerObj getLayer(int index)
Returns a layerObj from the map given an index value (0=first layer)
layerObj getLayerByName(string layer_name)
Returns a layerObj from the map given a layer name.
colorObj getcolorbyindex(int iCloIndex)
Returns a colorObj corresponding to the color index in the palette
void setextent(double minx, double miny, double maxx, double maxy)
Set the map extents using the georef extents passed in argument.
void zoompoint(int nZoomFactor, pointObj oPixelPos, int nImageWidth,
int nImageHeight, rectObj oGeorefExt)
Zoom to a given XY postion;
Parmeters are :
- Zoom factor : positive values do zoom in, negative values
zoom out. Factor of 1 will recenter.
- Pixel position (pointObj) : x, y coordinates of the click,
with (0,0) at the top-left
- Width : width in pixel of the current image.
- Height : Height in pixel of the current image.
- Georef extent (rectObj) : current georef extents.
- MaxGeoref extent (rectObj) : (optional) maximum georef extents.
If provided then it will be impossible to zoom/pan outside of
those extents.
void zoomrectange(rectObj oPixelExt, int nImageWidth, int nImageHeight,
rectObj oGeorefExt)
Set the map extents to a given extents.
Parmeters are :
- Pixel Extents, with (0,0) at the top-left
- Width : width in pixel of the current image.
- Height : Height in pixel of the current image.
- Georef extent (rectObj) : current georef extents.
void zoomscale(int nScale, pointObj oPixelPos, int nImageWidth,
int nImageHeight, rectObj oGeorefExt)
Zoom in or out to a given XY postion so that the map is displayed
at specified scale.
Parmeters are :
- Scale : Scale at which the map should be displayed.
- Pixel position (pointObj) : x, y coordinates of the click,
with (0,0) at the top-left
- Width : width in pixel of the current image.
- Height : Height in pixel of the current image.
- Georef extent (rectObj) : current georef extents.
- MaxGeoref extent (rectObj) : (optional) maximum georef extents.
If provided then it will be impossible to zoom/pan outside of
those extents.
queryResultObj queryUsingPoint(pointObj point, int type, double buffer)
Query all selected layers in map at point location specified in
georeferenced map coordinates (i.e. not pixels).
Returns a queryResultObj on success, or 0 if nothing was found.
Type is MS_SINGLE or MS_MULTIPLE depending on number of results
you want.
Passing buffer <=0 defaults to tolerances set in the map file
(in pixels) but you can use a constant buffer (specified in
ground units) instead.
Note that to be queryable a layer must have a QUERYITEM and at least
one QUERY object.
queryresultObj queryUsingRect(rectObj rect)
Query all selected layers in map using a rectangle specified in
georeferenced map coordinates (i.e. not pixels).
Returns a queryResultObj on success, or 0 if nothing was found.
Note that to be queryable a layer must have a QUERYITEM and at least
one QUERY object.
int queryUsingFeatures(queryResultObj pQuery)
Generates a result set based on a previous set of results. At present
the results MUST be based on a polygon layer. Holes and disjoint
polygons should now be handled correctly.
queryresultObj queryUsingShape(shapeObj shape)
Generates a result set based on a single shape, the shape is assumed
to be a polygon at this point.
int save(string filename)
Save current map object state to a file. Returns -1 on error.
int setProjection(string proj_params)
Set map projection and coordinate system. Parameters are given as
a single string of comma-delimited PROJ.4 parameters.
int classify(string expression)
Return the first class index which matches the string passed
in parameters. If there is an empty expression class, the index
will be returned.
LayerObj Class:
---------------
Constructor:
Layer Objects can be returned by the MapObj class, or can be created
using:
layerObj ms_newLayerObj(MapObj map)
Members:
int numclasses (read-only)
int index (read-only)
string queryitem (read-only)
string numqueries (read-only)
int status
string classitem
string name
string group
string description
string legend
string data
int type
double tolerance
int toleranceunits
double symbolscale
double minscale
double maxscale
double labelminscale
double labelmaxscale
int maxfeatures
int offsite
int annotate
int transform
int labelcache
int postlabelcache
string labelitem
string labelsizeitem
string labelangleitem
string tileitem
string tileindex
string header
string footer
string connection
int connectiontype
Methods:
int set(string property_name, new_value)
Set object property to a new value. Returns -1 on error.
int draw(imageObj image)
Draw a single layer, add labels to cache if required.
Returns -1 on error.
classObj getClass(int classIndex)
Returns a classObj from the layer given an index value (0=first class)
queryResultObj queryUsingPoint(pointObj point, int type, double buffer)
Query layer at point location specified in georeferenced map
coordinates (i.e. not pixels).
Returns a queryResultObj on success, or 0 if nothing was found.
Type is MS_SINGLE or MS_MULTIPLE depending on number of results
you want.
Passing buffer <=0 defaults to tolerances set in the map file
(in pixels) but you can use a constant buffer (specified in
ground units) instead.
Note that to be queryable a layer must have a QUERYITEM and at least
one QUERY object.
queryResultObj queryUsingRect(rectObj rect)
Query layer using a rectangle specified in georeferenced map
coordinates (i.e. not pixels).
Returns a queryResultObj on success, or 0 if nothing was found.
Note that to be queryable a layer must have a QUERYITEM and at least
one QUERY object.
int queryUsingFeatures(queryResultObj pQuery)
Generates a result set based on a previous set of results. At present
the results MUST be based on a polygon layer. Holes and disjoint
polygons should now be handled correctly.
queryresultObj queryUsingShape(shapeObj shape)
Generates a result set based on a single shape, the shape is assumed
to be a polygon at this point.
int setProjection(string proj_params)
Set layer projection and coordinate system. Parameters are given as
a single string of comma-delimited PROJ.4 parameters.
int addFeature(shapeObj shape)
Add a new feature in a layer. Returns -1 on error.
ClassObj Class:
---------------
Constructor:
Class Objects can be returned by the LayerObj class, or can be created
using:
classObj ms_newClassObj(layerObj layer)
Members:
string name
int color
int backgroundcolor
int outlinecolor
int overlaycolor
int overlaybackgroundcolor
int overlayoutlinecolor
int symbol
int size
int sizescaled
int minsize
int maxsize
int overlaysymbol
int overlaysize
int overlaysizescaled
int overlayminsize
int overlaymaxsize
labelObj label
Methods:
int set(string property_name, new_value)
Set object property to a new value. Returns -1 on error.
int setexpression(string expression)
Set the expression string for the class object.
int settext(string text)
Set the text string for the class object.
ImageObj Class:
---------------
Constructor:
Instances of ImageObj are always created by the map class methods.
Members:
int width (read-only)
int height (read-only)
string imagepath
string imageurl
Methods:
void free()
Destroys resources used by an image object.
The saveImage() and saveWebImage() methods are different depending on the
version of GD that is used:
With GD 1.2, 1.3, 1.6:
int saveImage(string filename, int transparent, int interlace)
Writes image object to specifed filename..
Passing an empty filename sends output to stdout. In this case,
the PHP header() function should be used to set the documents's
content-type prior to calling saveImage().
The function returns -1 on error. On success, it returns either 0
if writing to an external file, or the number of bytes written if
output is sent to stdout.
string saveWebImage(int transparent, int interlace)
Writes image to temp directory. Returns image URL.
With GD 1.8 (only if JPEG enabled in GD 1.8):
int saveImage(string filename, int type, int transparent, int interlace,
int quality)
Writes image object to specifed filename.
Passing an empty filename sends output to stdout. In this case,
the PHP header() function should be used to set the documents's
content-type prior to calling saveImage().
Type can be either MS_PNG or MS_JPEG
Quality should be a value in the range 0-95, higher value implies
higher image quality and larger image sizes.
If quality is negative, then the default IJG JPEG quality value is
used.
The function returns -1 on error. On success, it returns either 0
if writing to an external file, or the number of bytes written if
output is sent to stdout.
string saveWebImage(int type, int transparent, int interlace, int quality)
Writes image to temp directory. Returns image URL.
Type can be either MS_PNG or MS_JPEG
Quality should be a value in the range 0-95, higher value implies
higher image quality and larger image sizes.
If quality is negative, then the default IJG JPEG quality value is
used.
LabelObj Class:
---------------
Constructor:
LabelObj are always embedded inside other classes.
Members:
string font
int type
int color
int outlinecolor
int shadowcolor
int shadowsizex
int shadowsizey
int backgroundcolor
int backgroundshadowcolor
int backgroundshadowsizex
int backgroundshadowsizey
int size
int sizescaled
int minsize
int maxsize
int position
int offsetx
int offsety
double angle
int autoangle
int buffer
int antialias
int wrap
int minfeaturesize
int autominfeaturesize
int mindistance
int partials
int force
Methods:
int set(string property_name, new_value)
Set object property to a new value. Returns -1 on error.
webObj Class
-----------
Constructor:
Instances of webObjare always are always embedded inside the mapObj.
Members:
string log;
string imagepath
string template
string imageurl
string header
string footer
string empty (read-only)
string error (read-only)
string mintemplate
string maxtemplate
double minscale
double maxscale
rectObj extent (read-only)
Methods:
int set(string property_name, new_value)
Set object property to a new value. Returns -1 on error.
referenceMapObj Class
--------------------
Constructor:
Instances of referenceMapObj are always embedded inside the mapObj.
Members:
string image
int width
int height
int status
rectObj extent (read-only)
ColorObj color (read-only)
ColorObj outlinecolor (read-only)
Method :
int set(string property_name, new_value)
Set object property to a new value. Returns -1 on error.
ColorObj Class:
---------------
Constructor:
Instances of ColorObj are always embedded inside other classes.
Members:
int red
int green
int blue
Methods:
void setRGB(int red, int green, int blue)
Set red, green, blue values.
QueryResultObj Class:
---------------------
Constructor:
There is no public constructor, instances of QueryResultObj objects are
always returned by the MapObj and LayerObj query methods.
Members:
int numresults (read-only)
int numquerylayers (read-only)
int numlayers (read-only)
int currentlayer
int currentshape
int currenttile
Methods:
int set(string property_name, new_value)
Set object property to a new value. Returns -1 on error.
ShapeResultObj next()
Returns the next result record in a ShapeResultObj.
The last ShapeResultObj will have all its members set to -1.
void rewind()
Move the cursor back to the first result record.
This is the same as setting currentlayer=currentshape=currenttile=0
void free()
Destroys resources used by a QueryResultObj.
QueryObj Class:
---------------------
Constructor:
QueryObj ms_newQueryObj(layerObj layer)
Members:
string template
Methods:
int set(string property_name, new_value)
Set object property to a new value. Returns -1 on error.
int setexpression(string expression)
Set the expression string for the query object.
ShapeResultObj Class:
---------------------
Constructor:
There is no public constructor, instances of ShapeResultObj objects are
always returned by QueryResultObj methods.
Members:
int layer (read-only)
int tile (read-only)
int shape (read-only)
int query (read-only)
Methods:
No methods.
PointObj Class:
---------------
Constructor:
PointObj ms_newPointObj()
Members:
double x
double y
Methods:
int setXY(double x, double y)
Set X,Y coordinate values.
int draw(mapObj map, layerObj layer, imageObj img,
string class_name, string text)
Draws the individual point using layer. The class_name is used
to classify the point based on the classes defined for the layer.
The text string is used to annotate the point.
Returns 0 on success, -1 on error.
double distanceToPoint(pointObj poPoint)
Calculates distance between two points.
double distanceToLine(pointObject p1, pointObject p2)
Calculates distance between a point ad a lined defined by the
two points passed in argument.
double distanceToShape(shapeObj shape)
Calculates the minimum distance between a point and a shape.
void free()
Releases all resources used by the object.
LineObj Class:
--------------
Constructor:
LineObj ms_newLineObj()
Members:
int numpoints (read-only)
Methods:
int add(pointObj point)
Add a point to the end of line.
int addXY(double x, double y)
Add a point to the end of line.
PointObj point(int i)
Returns a reference to point number i. Reference is valid only
during the life of the lineObj that contains the point.
void free()
Destroys resources used by a line object.
ShapeObj Class:
--------------
Constructor:
ShapeObj ms_newShapeObj(int type)
Members:
int type (read-only)
int numlines (read-only)
rectObj bounds
Methods:
int add(lineObj line)
Add a line (i.e. a part) to the shape.
LineObj line(int i)
Returns a reference to line number i. Reference is valid only
during the life of the shapeObj that contains the point.
int draw(mapObj map, layerObj layer, imageObj img,
string class_name, string text)
Draws the individual shape using layer. The class_name is used
to classify the shape based on the classes defined for the layer.
The text string is used to annotate the shape.
Returns 0 on success, -1 on error.
boolean contains(pointObj point)
Returns MS_TRUE if the point is in a polygone shape. Else MS_FALSE.
boolean intersects(shapeObj pShape))
Returns MS_TRUE or false if the two shapes intersect. Else MS_FALSE.
void free()
Destroys resources used by a shape object.
RectObj Class:
--------------
Constructor:
RectObj are sometimes embedded inside other objects. New ones can
also be created with:
RectObj ms_newRectObj()
Members:
double minx
double miny
double maxx
double maxy
Methods:
int set(string property_name, new_value)
Set object property to a new value. Returns -1 on error.
void setextent(double minx, double miny, double maxx, double maxy)
Set the rectangle extents.
int draw(mapObj map, layerObj layer, imageObj img,
string class_name, string text)
Draws the individual rectangle using layer. The class_name is used
to classify the rectangle based on the classes defined for the layer.
The text string is used to annotate the rectangle.
Returns 0 on success, -1 on error.
double fit(int width, int height)
Adjust extents of the rectangle to fit the width/height specified.
void free()
Destroys resources used by a rect object.
ShapefileObj Class:
-------------------
Constructor:
shapefileObj ms_newShapefileObj(string filename, int type)
Opens a shapefile and returns a new object to deal with it.
Filename should be passed with no extension.
To create a new file (or overwrite an existing one), type should
be one of MS_SHP_POINT, MS_SHP_ARC, MS_SHP_POLYGON or
MS_SHP_MULTIPOINT.
Pass type as -1 to open an existing file for read-only access,
and type=-2 to open an existing file for update (append).
Members:
int numshapes (read-only)
int type (read-only)
string source (read-only)
rectObj bounds (read-only)
Methods:
shapeObj getShape(int i)
Retrieve shape by index.
shapeObj getTransformed(mapObj map, int i)
Retrieve shape by index.
rectObj getExtent(int i)
Retrieve a shape's bounding box by index.
int addShape(shapeObj shape)
Appends a shape to an open shapefile.
void free()
Closes a shape file (and commits all changes in write mode) and
releases all resources used by the object.
|