1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
.. $Id: imagery-HOWTO.txt,v 1.4 2005/03/20 19:47:16 sean Exp $
===========================================================================
Copyright (c) 2004 Sean Gillies.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
===========================================================================
..
*****************************************************************************
Mapscript Imagery HOWTO
*****************************************************************************
:Author: Sean Gillies
:Contact: sgillies@frii.com
:Revision: $Revision: 1.4 $
:Date: $Date: 2005/03/20 19:47:16 $
.. The next heading encountered becomes our H2
..
.. sectnum::
.. contents::
:depth: 2
:backlinks: top
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 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 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 'getBytes' method which
is preferred to 'write' for MapServer 4.5/6. By default, the filehandle is
'stdout'::
# Send an image to a web browser
print 'Content-type: ' + map_image.format.mimetype + '\n'
print map_image.getBytes()
This method is not fully functional for all SWIG mapscript languages. See the
API Reference (mapscript.txt) for details. The 'getBytes' method is new in 4.5.
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.
|
