|
|
Home | Docs | Issue Tracker | FAQ | Download |
|
|
| Author: | Sean Gillies |
|---|---|
| Revision: | $Revision$ |
| Date: | $Date$ |
| Last Updated: | 2008/07/15 |
Table of Contents
The MapScript HOWTO docs are intended to complement the API reference with examples of usage for specific subjects. All examples in this document refer to the mapfile and testing layers distributed with MapServer 4.2+ and found under mapserver/tests.
All examples will use a pseudocode that is consistent with the language independent API reference. Each line is a statement. For object attributes and methods we use the dot, ‘.’, operator. Creation and deletion of objects will be indicated by ‘new’ and ‘del’ keywords. Other than that, the pseudocode looks a lot like Python.
The most common use of MapServer and MapScript is to create map imagery using the built-in GD format drivers: GD/GIF, GD/PNG, GD/PNG24, and GD/JPEG. This imagery might be saved to a file on disk or be streamed directly to another device.
Imagery is represented in MapScript by the imageObj class. Please see the API Reference (MapScript.txt) for class attribute and method details.
The mapObj class has two methods that return instances of imageObj: ‘draw’, and ‘prepareImage’. The first returns a full-fledged map image just as one would obtain from the mapserv CGI program
test_map = MapScript.mapObj('tests/test.map')
map_image = test_map.draw()
A properly sized and formatted blank image, without any layers, symbols, or labels, will be generated by ‘prepareImage’
blank_image = test_map.prepareImage()
The imageObj class constructor creates new instances without need of a map
format = MapScript.outputFormatObj('GD/JPEG')
image = MapScript.imageObj(300, 200, format) # 300 wide, 200 high JPEG
and can even initialize from a file on disk
# First three args are overriden by attributes of the disk image file
disk_image = MapScript.imageObj(-1, -1, NULL, 'tests/test.png')
Imagery is saved to disk by using the ‘save’ method. By accessing the ‘extension’ attribute of an image’s format, the proper file extension can be used without making any assumptions
filename = 'test.' + map_image.format.extension
map_image.save(filename)
If the image is using a GDAL/GTiff-based format, a GeoTIFF file can be created on disk by adding a mapObj as a second optional argument to ‘save’
map_image.save(filename, test_map)
An image can be dumped to an open filehandle using the ‘write’ method. By default, the filehandle is ‘stdout’
# Send an image to a web browser
print "Content-type: " + map_image.format.mimetype + "\n\n"
map_image.write()
This method is not fully functional for all SWIG MapScript languages. See the API Reference (MapScript.txt) for details. The ‘write’ method is new in 4.4.
The symbolObj::getImage() method will return an instance of imageObj for pixmap symbols
symbol = test_map.symbolset.getSymbolByName('home-png')
image = symbol.getImage()
There is a symmetric ‘setImage’ method which loads imagery into a symbol, allowing pixmap symbols to be created dynamically
new_symbol = MapScript.symbolObj('from_image')
new_symbol.type = MapScript.MS_SYMBOL_PIXMAP
new_symbol.setImage(image)
index = test_map.symbolset.appendSymbol(new_symbol)
The get/setImage methods are new in MapServer 4.4.