..  $Id$
    
    This is the new unified mapscript documentation prepared using
    reStructured Text.

    ***************************************************************
    RULE #1: No tabs in this document!
    RULE #2: Indent is 4 characters.
    RULE #3: There is no rule 3.

    Thank you.
    ***************************************************************
    
    reStructured Text is part of the Python docutils module
    
        http://docutils.sourceforge.net/
    
    Documentation on reStructured Text is found at

        http://docutils.sourceforge.net/rst.html

    First reST note is about comments: a double period begins a comment
    block (like a /* in C) and a double period on a line all by itself
    closes the comment block.
..

..  Below is our main heading (becomes H1).  Note that we require empty
    lines between every different reST element such as the empty line
    between the end of this comment and the begining of the heading.
..

*****************************************************************************
 Python Appendix
*****************************************************************************

:Author: Sean Gillies
:Contact: sgillies@frii.com
:Revision: $Revision$
:Date: $Date$

..  The next heading encountered becomes our H2
..

.. sectnum::

.. contents::
    :depth: 2
    :backlinks: top

=============================================================================
 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