4.11.
MapObj Class
Document Actions
Constructor, members, and methods.
- Constant names and class member variable names are case-sensitive in PHP.
- Several MapScript functions (all those that access files in the back end such as ms_newMapObj(), drawMap(), etc.) will affect the value of the current working directory (CWD) in the PHP environment. This will be fixed eventually but in the meantime you should be careful about these side-effects.
Constructor:
mapObj ms_newMapObj(string map_file_name [, string new_map_path])
Returns a new object to deal with a MapServer map file.
By default, the SYMBOLSET, FONTSET, and other paths in the mapfile
are relative to the mapfile location. If new_map_path is provided
then this directory will be used as the base path for all the
relative paths inside the mapfile.
Members:
int numlayers (read-only)
string name
int status
int debug
int width (see setSize())
int height (see setSize())
int maxsize
outputformatObj outputformat
double resolution (pixels per inch, defaults to 72)
rectObj extent;
double cellsize
int units (map units type)
double scaledenom (read-only, set by drawMap())
double scale (Deprecated in v5.0. Use scaledenom instead)
string shapepath
int keysizex
int keysizey
int keyspacingx
int keyspacingy
webObj web
referenceMapObj reference
colorObj imagecolor
scalebarObj scalebar
legendObj legend
string symbolsetfilename (read-only, set by setSymbolSet())
string fontsetfilename (read-only, set by setFontSet())
labelcacheObj labelcache (no members. Used only to be able to free the
the label cache (ex : map->labelcache->free())
int transparent (deprecated, use outputFormatObj)
int interlace (deprecated, use outputFormatObj)
int imagetype (deprecated, use outputFormatObj)
int imagequality (deprecated, use outputFormatObj)
Methods:
mapObj clone()
Returns a handle to a new mapObj which is a clone of the current
mapObj. All parameters in the current mapObj are copied to the
new mapObj. Returns NULL (0) on error.
int set(string property_name, new_value)
Set map object property to new value. Returns -1 on error.
int getsymbolbyname(string symbol_name)
Returns the symbol index using the name.
symbol getsymbolobjectbyid(int symbolid)
Returns the symbol object using a symbol id. Refer to
the symbol object reference section for more details.
void preparequery()
Calculate the scale of the map and set map->scaledenom.
imageObj prepareImage()
Return handle on blank image object.
imageObj draw()
Render map and return handle on image object.
imageObj drawQuery()
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.
Returns FALSE if layer doesn't exist.
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.
int setRotation(double rotation_angle)
Set map rotation angle. The map view rectangle (specified in
EXTENTS) will be rotated by the indicated angle in the counter-
clockwise direction. Note that this implies the rendered map
will be rotated by the angle in the clockwise direction.
Returns MS_SUCCESS or MS_FAILURE.
int setSize(int width, int height)
Set the map width and height. This method updates the internal
geotransform and other data structures required for map rotation
so it should be used instead of setting the width and height members
directly.
Returns MS_SUCCESS or MS_FAILURE.
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 zoomrectangle(rectObj oPixelExt, int nImageWidth, int nImageHeight,
rectObj oGeorefExt)
Set the map extents to a given extents.
Parmeters are :
- oPixelExt (rect object) : Pixel Extents, with (0,0) at the top-left
The rectangle contains the coordinates of the LL and UR coordinates
in pixel. (the maxy in the rect object should be < miny value)
------- UR (values in the rect object : maxx, maxy)
| |
| |
| |
------
LL (values in the rectobject minx, miny)
- Width : width in pixel of the current image.
- Height : Height in pixel of the current image.
- Georef extent (rectObj) : current georef extents.
void zoomscale(double nScaleDenom, pointObj oPixelPos, int nImageWidth,
int nImageHeight, rectObj oGeorefExt [, rectObj oMaxGeorefExt])
Zoom in or out to a given XY position so that the map is displayed
at specified scale.
Parmeters are :
- ScaleDenom : Scale denominator of the 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.
int queryByPoint(pointObj point, int mode, double buffer)
Query all selected layers in map at point location specified in
georeferenced map coordinates (i.e. not pixels).
The query is performed on all the shapes that are part of a CLASS
that contains a TEMPLATE value or that match any class in a
layer that contains a LAYER TEMPLATE value.
Mode is MS_SINGLE or MS_MULTIPLE depending on number of results
you want.
Passing buffer -1 defaults to tolerances set in the map file
(in pixels) but you can use a constant buffer (specified in
ground units) instead.
Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing
was found or if some other error happened (note that the error
message in case nothing was found can be avoided in PHP using
the '@' control operator).
int queryByRect(rectObj rect)
Query all selected layers in map using a rectangle specified in
georeferenced map coordinates (i.e. not pixels).
The query is performed on all the shapes that are part of a CLASS
that contains a TEMPLATE value or that match any class in a
layer that contains a LAYER TEMPLATE value.
Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing
was found or if some other error happened (note that the error
message in case nothing was found can be avoided in PHP using
the '@' control operator).
int queryByShape(shapeObj shape)
Query all selected layers in map based on a single shape, the
shape has to be a polygon at this point.
Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing
was found or if some other error happened (note that the error
message in case nothing was found can be avoided in PHP using
the '@' control operator).
int queryByFeatures(int slayer)
Perform a query based on a previous set of results from
a layer. At present the results MUST be based on a polygon layer.
Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing
was found or if some other error happened (note that the error
message in case nothing was found can be avoided in PHP using
the '@' control operator).
int queryByIndex(layerindex, tileindex, shapeindex, addtoquery)
Add a specific shape on a given layer to the query result.
If addtoquery (which is a non mandatory argument) is set to MS_TRUE,
the shape will be added to the existing query list. Default behavaior
is to free the existing query list and add only the new shape.
int savequery(filename)
Save the current query in a file. Returns MS_SUCESS or MS_FAILURE.
Can be used with loadquery
int loadquery(filename)
Loads a query from a file. Returns MS_SUCESS or MS_FAILURE.
To be used with savequery.
void freequery(layerindex)
Frees the query result on a specified layer. If the layerindex is -1,
all queries on layers will be freed.
int save(string filename)
Save current map object state to a file. Returns -1 on error.
Use absolute path. If a relative path is used, then it will be
relative to the mapfile location.
string getProjection()
Returns a string represenation of the projection. If no
projection is set, MS_FALSE is returned.
int setProjection(string proj_params, boolean bSetUnitsAndExtents)
Set map projection and coordinate system. Parameters are given as
a single string of comma-delimited PROJ.4 parameters.
The argument : bSetUnitsAndExtents is used to automatically update
the map units and extents based on the new projection. Possible
values are MS_TRUE and MS_FALSE. By defualt it is set at MS_FALSE
int setWKTProjection(string proj_params, boolean bSetUnitsAndExtents)
Same as setProjection(), but takes an OGC WKT projection
definition string as input.
int getMetaData(string name)
Fetch metadata entry by name (stored in the WEB object in the map
file). Returns "" if no entry matches the name. Note that the
search is case sensitive.
int setMetaData(string name, string value)
Set a metadata entry for the map (stored in the WEB object in the map
file). Returns MS_SUCCESS/MS_FAILURE.
int removeMetaData(string name)
Remove a metadata entry for the map (stored in the WEB object in the map
file). Returns MS_SUCCESS/MS_FAILURE.
array getLayersIndexByGroup(string groupname)
Return an array containing all the layer's indexes given
a group name.
array getAllGroupNames()
Return an array containing all the group names used in the
layers.
array getAllLayerNames()
Return an array containing all the layer names.
boolean moveLayerUp(int layerindex)
Move layer up in the hierarcy of drawing.
boolean moveLayerDown(int layerindex)
Move layer down in the hierarcy of drawing.
array getlayersdrawingorder()
Return an array containing layer's index in the order which they
are drawn.
boolean setlayersdrawingorder(array layeryindex)
Set the layer's order array. The argument passed must be a valid
array with all the layer's index.
Return TRUE on success or else FALSE.
string processtemplate(array params, boolean generateimages)
Process the template file specified in the web object and return
the resut in a buffer.
The processing consists of opening the template file and replace
all the tags found in it.
Only tags that have an equivalent element in the map object are
replaced (ex [scaledenom]).
The are two expetions to the previous statement :
- [img], [scalebar], [ref], [legend] would be replaced with the
appropriate url if the parameter generateimages is set to
MS_TRUE. (Note : the images corresponding to the diffrent objects
are generated if the object is set to MS_ON in the map file)
- the user can use the params parameter to specify tags and
their values. For example if the user have a specific tag call
[my_tag] and would like it to be replaced by "value_of_my_tag"
he would do :
$tmparray["my_tag"] = "value_of_my_tag";
$map->processtemplate($tmparray, MS_FALSE);
string processquerytemplate(array params, boolean generateimages)
Process query template files and return the resut in a buffer.
Second argument generateimages is not manadatory. If not given
It will be set to TRUE.
See also : processtemplate function.
string processlegendtemplate(array params)
Process legend template files and return the resut in a buffer.
See also : processtemplate function.
int setSymbolSet(string fileName)
Load and set a symbol file dynamictly.
int getNumSymbols()
Return the number of symbols in map.
int setFontSet(string fileName)
Load and set a new fontset.
int selectOutputFormat(string type)
Selects the output format to be used in the map.
Returns MS_SUCCESS/MS_FAILURE.
Note : the type used should correspond to one of the output
formats declared in the map file.
The type argument passed is compared with the mimetype
parameter in the output format structure and then to
the name parameter in the structure.
int saveMapContext(string filename)
Available only if WMS support is enabled.
Save current map object state in WMS Map Context format.
Only WMS layers are saved in the WMS Map Context XML file.
Returns MS_SUCCESS/MS_FAILURE.
int loadMapContext(string filename [, boolean unique_layer_name])
Available only if WMS support is enabled.
Load a WMS Map Context XML file into the current mapObj.
If the map already contains some layers then the layers defined
in the WMS Map context document are added to the current map.
The 2nd argument unique_layer_name is optional and if set to
MS_TRUE layers created will have a unique name (unique prefix
added to the name). If set to MS_FALSE the layer name will be the
the same name as in the context. The default value is MS_FALSE.
Returns MS_SUCCESS/MS_FAILURE.
int applySLD(string sldxml)
Apply the SLD document to the map file. The matching between the
sld document and the map file will be done using the layer's name.
See SLD How to for more information on the SLD support.
int applySLDURL(string sldurl)
Apply the SLD document pointed by the URL to the map file. The
matching between the sld document and the map file will be done
using the layer's name.
See SLD How to for more information on the SLD support.
string generateSLD()
Returns an SLD XML string based on all the classes found in all
the layers.
string getconfigoption(string key)
Returns the config value associated with the key.
Returns an empty sting if key not found.
int setconfigoption(string key, string value)
Sets a config parameter using the key and the value passed
int applyconfigoptions()
Applies the config options set in the map file. For example
seeting the PROJ_LIB using the setconfigoption only modifies
the value in the map object. applyconfigoptions will actually
change the PROJ_LIB value that will be used when dealing with
projection.
int loadowsparameters(owsrequest request, string version)
Load OWS request parameters (BBOX, LAYERS, &c.) into map. Returns
MS_SUCCESS or MS_FAILURE.
2nd argument version is not mandatory. If not given, the version
will be set to 1.1.1
int owsdispatch(owsrequest request)
Processes and executes the passed OpenGIS Web Services request on the
map. Returns MS_DONE (2) if there is no valid OWS request in the req
object, MS_SUCCESS (0) if an OWS request was successfully processed and
MS_FAILURE (1) if an OWS request was not successfully processed. OWS
requests include WMS, WFS, WCS and SOS requests supported by MapServer.
Results of a dispatched request are written to stdout and can be captured
using the msIO services (ie. ms_ioinstallstdouttobuffer() and
ms_iogetstdoutbufferstring())
int insertLayer( layerObj layer [, int nIndex=-1 ] )
Insert a copy of *layer* into the Map at index *nIndex*. The default
value of *nIndex* is -1, which means the last possible index. Returns
the index of the new Layer, or -1 in the case of a failure.
