MapScript Image Generation¶
- Author:
Sean Gillies
- Author:
Seth Girvin
- Contact:
sethg at geographika.co.uk
- Last Updated:
2021-05-22
Introduction¶
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 and found in source control
under Mapserver/tests
.
The examples below are written in Python. All MapScript languages use the same API, but will need to be rewritten using the relevant language's syntax.
Imagery Overview¶
The most common use of MapServer and MapScript is to create map imagery
using the built-in format drivers such as AGG/PNG
, AGG/JPEG
, and CAIRO/PNG
.
This imagery might be saved to a file on disk or be streamed directly to
another device.
The imageObj Class¶
Imagery is represented in MapScript by the imageObj
class.
Creating imageObj from a mapObj¶
The mapObj
class has two methods that return instances of imageObj
: mapObj.draw()
,
and mapObj.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 mapObj.prepareImage()
:
blank_image = test_map.prepareImage()
Creating a new imageObj¶
The imageObj class constructor creates new instances without need of a map:
format = mapscript.outputFormatObj('AGG/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 overridden by attributes of the disk image file
disk_image = mapscript.imageObj(-1, -1, None, 'tests/test.png')
Image Output¶
Creating files on disk¶
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)
Direct Output¶
An image can be dumped to an open filehandle using the mapObj.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 SWIG API reference for more details.
Images and Symbols¶
The symbolObj.getImage()
method will return an instance of imageObj
: for
pixmap symbols:
symbol = test_map.symbolset.getSymbolByName('home-png')
input_format = mapscript.outputFormatObj('AGG/PNG')
image = symbol.getImage(input_format)
There is a symmetric symbolObj.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)
test_map.symbolset.save('tests/output_symbols.txt')