..  $Id$
    
    This is the mapscript imagery HOWTO for mapserver 4.4.
    
    ***************************************************************
    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.
..

*****************************************************************************
 Mapscript Imagery HOWTO
*****************************************************************************

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

All examples in this document refer to the mapfile and testing layers
distributed with MapServer 4.2+ and found under mapserver/tests.

Pseudocode
----------

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.

Imagery Overview
================

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.

The imageObj Class
------------------

Imagery is represented in mapscript by the imageObj class.  Please see the
API Reference (mapscript.txt) for class attribute and method details.

Creating imageObj from a mapObj
-------------------------------

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()

Creating a new imageObj
-----------------------

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')


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 the GDAL/GTiff 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 '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.
    

Images and Symbols
==================

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.