Python MapScript Appendix

Author:Sean Gillies Revision:$Revision$ Date:$Date$

Contents

• Python MapScript Appendix
  • Introduction
  • Classes
  • Exception Handling

Introduction

The Python MapScript module contains some class extension methods that have not yet been implemented for other languages.

Classes

References to sections below will be added here as the documentation grows.

imageObj

The Python Imaging Library, http://www.pythonware.com/products/pil/, is an indispensible tool for image manipulation. The extensions to imageObj are all geared towards better integration of PIL in MapScript applications.

imageObj Methods

imageObj( PyObject arg1, PyObject arg2 [, PyObject arg3 ] ) : imageObj

Create a new instance which is either empty or read from a Python file-like object that refers to a GD format image.

The constructor has 2 different modes. In the blank image mode, arg1 and arg2 should be the desired width and height in pixels, and the optional arg3 should be either an instance of outputFormatObj or a GD driver name as a shortcut to a format. In the image file mode, arg1 should be a filename or a Python file or file-like object. If the file-like object does not have a “seek” attribute (such as a urllib resource handle), then a GD driver name must be provided as arg2.

Here’s an example of creating a 320 pixel wide by 240 pixel high JPEG using the constructor’s blank image mode:

image = mapscript.imageObj(320, 240, 'GD/JPEG')

In image file mode, interesting values of arg1 to try are instances of StringIO:

s = StringIO()
pil_image.save(s)    # Save an image manipulated with PIL
ms_image = imageObj(s)

Or the file-like object returned from urlopen

url = urllib.urlopen('http://mapserver.gis.umn.edu/bugs/ant.jpg')
ms_image = imageObj(url, 'GD/JPEG')

write( [ PyObject file ] ) : void

Write image data to a Python file-like object. Default is stdout.

pointObj

pointObj Methods

__str__() : string

Return a string formatted like

{ 'x': %f , 'y': %f }

with the coordinate values substituted appropriately. Usage example:

>>> p = mapscript.pointObj(1, 1)
>>> str(p)
{ 'x': 1.000000 , 'y': 1.000000 }

Note that the return value can be conveniently eval’d into a Python dictionary:

>>> p_dict = eval(str(p))
>>> p_dict['x']
1.000000

rectObj

rectObj Methods

__contains__( pointObj point ) : boolean

Returns True if point is inside the rectangle, otherwise returns False.

>>> r = mapscript.rectObj(0, 0, 1, 1)
>>> p = mapscript.pointObj(2, 0)       # outside
>>> p in r
False
>>> p not in r
True

__str__() : string

Return a string formatted like

{ 'minx': %f , 'miny': %f , 'maxx': %f , 'maxy': %f }

with the bounding values substituted appropriately. Usage example:

>>> r = mapscript.rectObj(0, 0, 1, 1)
>>> str(r)
{ 'minx': 0.000000 , 'miny': 0.000000 , 'maxx': 1.000000 , 'maxy': 1.000000 }

Note that the return value can be conveniently eval’d into a Python dictionary:

>>> r_dict = eval(str(r))
>>> r_dict['minx']
0.000000

Exception Handling

The Python MapScript module maps a few MapServer errors into Python exceptions. Attempting to load a non-existent mapfile raises an ‘IOError’, for example

>>> import mapscript
>>> mapfile = '/no/such/file.map'
>>> m = mapscript.mapObj(mapfile)
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
  File "/usr/lib/python2.3/site-packages/mapscript.py", line 799, in __init__
    newobj = _mapscript.new_mapObj(*args)
IOError: msLoadMap(): Unable to access file. (/no/such/file.map)
>>>

The message of the error is written by ‘msSetError’ and so is the same message that CGI mapserv users see in error logs.