OSGeo - User contributions [en]

User:Mikee63

2009-06-03T09:18:04Z

Wiki-Mikee63:

<table><tr><td valign="top">[[Image:Example.jpg]]<td><td><CODE>
Mike Elstermann 
Teamleiter Softwareentwicklung 
Kompetenzzentrum Geo-Systeme 
IT-Consult Halle GmbH 
Bornknechtstraße 5 
06108 Halle (Saale) 
Telefon: +49 345 581 7128 
Telefax: +49 345 581 1737 
PC-Fax: +49 345 581 78 7128 
E-Mail: mike.elstermann@itc-halle.de 
http://www.mikee.de 
http://halgis.halle.de 
http://umweltatlas.halle.de 
</CODE>
</td></tr></table>

HBUMNMapServer ger Capter 2

2009-04-03T08:10:11Z

Wiki-Mikee63: /* TrueType-Symbole */

[[User:Lars]] (logging, includes, fastcgi) 
[[User:Simon Appelt]] (Web-Sektion, Layer, Weitere Layer-Optionen)
= [[HBUMNMapServer_ger_Capter_1 | Einführung]] =
= Mapfile =
\index{Mapfile}

Das Mapfile wird Ihnen größte Freude bereiten. Sie werden die meisten Ihrer Fehler damit machen, und die meiste Zeit, die Sie mit dem MapServer überhaupt verbringen, wird das Editieren Ihrer Mapfiles zum Inhalt haben.

==Bedeutung des Mapfiles==

Das Mapfile ist die zentrale Layout- und Konfigurationsdatei einer MapServer-Anwendung,sozusagen das "Herz". Sie beschreibt Inhalt und Darstellung der fertigen Karte und enthält zusätzliche Informationen, um Maßstäbe, Legenden und Referenzkarten passend zur fertigen Karte zu erstellen.

Auch die Metadaten, die zur OGC-konformen Funktionsweise benötigt werden, sind im Mapfile angegeben.

Bevor wir jedoch in alle Details des Mapfiles einsteigen, werfen wir einen Blick auf die generelle Funktionsweise des MapServers.

===MapServer als CGI===

Dies ist der "Standard"-Weg, den MapServer zu benutzen: indem er als Programm in einem Webserver wie beispielsweise dem Apache residiert. Über den URL bekommt das Programm Parameter zugewiesen und ändert seine Ausgabe anhand dieser Parameter.

Ein Beispiel. Ein typischer URL sieht etwa folgendermaßen aus:

 <code>
http://www.example.com/cgi-bin/mapserv \
? map=/usr/local/www/mapfile.map
</code> 

Das ganze ist für den Druck umgebrochen, es handelt sich um eine einzige Zeile, und die Leestellen im URL sind ebenfalls nur für die Lesbarkeit hinzugefügt. Backslashes an den Enden zeigen an, dass die Zeile noch nicht beendet ist. Diese Unix-typische Notation wird im folgenden im ganzen Buch Verwendung finden.

Beachten Sie bitte, dass die Domain =example.com= für anschauliche Zwecke in der Literatur~[[rfc2606]] reserviert ist und Ihnen ''kein Ergebnis'' bei einem Aufruf anzeigen wird. Ersetzen Sie diesen Domainnamen durch den tatsächlichen Namen Ihres Hosts.

Der MapServer, das eigentliche Programm, das die Arbeit macht, liegt offensichtlich in einem =cgi-bin= genannten Verzeichnis des Webservers. Ruft man ihn einfach ohne Parameter auf, also etwa folgendermaßen:

 <code>
http://www.example.com/cgi-bin/mapserv
</code> 

dann sollte man als Antwort folgendes in seinem Browser sehen:

 <code>
No query information to decode. QUERY_STRING is set, but empty.
</code> 

\begin{figure}
\begin{center}
\mmfig{0.35}{motzing}{Der MapServer motzt herum; genau das, was man am Anfang sehen möchte.}
\end{center}
\end{figure}

Also wie in Abbildung~\ref{motzing}. Wie reagiert man darauf? Indem man sich freut, denn alles ist in Ordnung; hurra, er kann schon rummotzen! Dies ist die Meldung, die man sehen möchte. MapServer beschwert sich lediglich, dass er keine Parameter zur Verarbeitung genannt bekommen hat. Nach einer neuen Installation ist diese Meldung nach dem ersten Testaufruf das gewünschte Ergebnis.

Der erste Parameter wird mit einem Fragezeichen =?= eingeleitet, alle weiteren werden mit einem Kaufmanns-Und =\&= voneinander getrennt.

Zwingend notwendig ist die Angabe eines Mapfiles über den Parameter =map== \footnote{Man kann diese Preisgabe des Ortes, an dem das Mapfile liegt, auch nach außen verbergen. Mehr dazu später.}, damit dem MapServer bekannt ist, welches Layout für die Karte zur Anwendung kommen soll.

Liegt Ihr Mapfile unter Unix etwa unter =/usr/local/maps/mymap.map= , so wäre also folgender Aufruf korrekt:

 <code>
http://www.example.com/cgi-bin/mapserv?map=/usr/local/maps/mymap.map
</code> 

Pfade unter Windows werden ebenfalls so angegeben, wie Sie es gewohnt sind, also beispielweise mit =C:= am Anfang.

===Die Modi===

MapServer kennt nun verschiedene Betriebs''modi'' , die über den Parameter =mode== notiert werden. Es gibt die folgenden Modi:

*=browse= : Läßt Sie die Karte browsen. Das bedeutet im wesentlichen, dass MapServer die Templates berücksichtigt, die im Mapfile angegeben sind, und somit HTML-Dateien mit Navigationselementen ausliefert. Wenn kein Modus angegeben ist, geht MapServer immer von =browse= aus. Was es mit Templates genau auf sich hat, erfahren Sie in Abschnitt~20 ab Seite~\pageref{text:mapfile:templates}.
*=map= : Dieser Modus läßt den MapServer Template-Angaben ignorieren und nur die Karte ausliefern. Zum Testen Ihres Mapfiles ist dies wahrscheinlich genau der Modus, den Sie haben möchten.
*=query= : Dieser Modus und seine Funktion, das Abfragen von Daten, die der Karte zugrunde liegen, werden ab Seite~\pageref{text:mapfile:queries} beschrieben.
*=nquery= : Wo =query= immer nur ein Ergebnis zurückliefern kann, kann =nquery= mehrere Ergebnisse liefern, sowohl im gleichen Layer als auch aus verschiedenen Layern (und auch beides zusammen, natürlich). Die Template-Angaben für diesen Modus können recht umfangreich sein.

Wenn Sie also Ihr Mapfile =mymap.map= im Modus =map= aufrufen wollten -- wodurch lediglich eine Karte, aber kein HTML-Interface produziert würde --, würden Sie folgendes notieren:

 <code>
http://www.example.com/cgi-bin/mapserv \
? map=/usr/local/maps/mymap.map \
& mode=map
</code> 

===Die weiteren Parameter===

Alle Variablen, die das Aussehen einer Karte beeinflussen können, werden über solche Parameter übergeben. Das schließt das Mapfile und den Modus mit ein, und darüberhinaus \ldots\ nun, eben alles andere, inklusive der Kartenebenen, die Sie sehen möchten, die Eckpunkte des gewünschten Kartenausschnitts, und noch diverse andere Dinge mehr. Da kann ein URL schnell einmal wie folgt aussehen:

 <code>
http://www.example.com/cgi-bin/mapserv \
? map=/usr/local/maps/mymap.map \
& mode=map \
& layer=postleitzahlen&layer=fluesse&layer=strassen \
& imgext=18.0+9.0+30.0+15.0
</code> 

Und sie kann noch viel viel länger werden. Und Ihr erster Gedanke, wenn Sie das sehen, ist natürlich vollkommen korrekt: Das will kein Mensch jedesmal eintippen müssen.

Daher werden diese Parameter für gewöhnlich über Eingaben in einem HTML-Formular generiert. Dazu gehört dann beispielsweise auch die Karte, die Sie im Browserfenster anklicken. Diese Formulare werden aus den Templates generiert, die weiter oben schon einmal erwähnt worden sind.

Für das erste setzen wir uns ausschließlich mit der Gestaltung der Karte auseinander, wofür Sie nur den Modus =map= ohne zusätzliche Parameter benötigten. Wenn ab Seite~\pageref{text:mapfile:templates} die Templates dazukommen, wird Ihr Wissen um eine Navigation in der Karte erweitert. Ab Seite~\pageref{text:mapfile:cgiparams} finden Sie schließlich eine Aufzählung aller möglichen CGI-Parameter.

Neben der CGI-Fassung gibt es zwei weitere Wege, die Funktionalitäten des MapServers zu nutzen. Beide unterscheiden sich zum Teil radikal von der Weise, die in diesem Kapitel behandelt wird.

\subsubsection*{Der OGC-konforme MapServer}\index{OGC}

Der OGC-konforme MapServer arbeitet ebenfalls als CGI-Programm und muß vor allen Dingen mit Metadaten versorgt werden, die dann bei der Kommunikation mit anderen Servern und mit Client-Appli\-ka\-tio\-nen verwendet werden.

Leider weicht sowohl die Notation des aufrufenden URL als auch die Notation der Metadaten im Mapfile ein wenig von der des MapServers im 'Normalbetrieb' ab, was nicht zur Lesbarkeit der ganzen Datei beiträgt. Die Unterschiede in der Notation werden im entsprechenden Kapitel ab Seite~\pageref{text:ogc} natürlich erläutert.

\subsubsection*{MapScript}\index{MapScript}

MapScript muß nicht gezwungenermaßen mit einem Mapfile arbeiten, z.B. wenn man damit nur Shapefiles bearbeiten möchte. Sobald man beginnt, mit Karten arbeiten zu wollen, wird man jedoch auch mit MapScript ein Mapfile laden, das dann verwendet werden kann.

Alle Sektionen im Mapfile werden dann als Objekte in einer Programmiersprache behandelt. Grundsätzlich ist nicht einmal ein Webserver vonnöten, auch lokale Applikationen lassen sich mit MapScript realisieren.

Am häufigsten sieht man MapScript jedoch in seiner Variante für PHP im Einsatz, die dann natürlich wieder in Webservern läuft. Als Beispiel konzentrieren wir uns in diesem Handbuch auf eben diese Version von MapScript.

==Grundlegender Aufbau des Mapfiles==

Werfen wir zuerst einen ganz allgemeinen Blick darauf, wie Inhalte im Mapfile notiert werden, bevor dann näher beschrieben wird, welche Einträge es denn gibt.

Das Mapfile besteht aus einzelnen Blöcken, die mit einem Schlüsselwort beginnen und mit einem =END= abgeschlossen werden:

 <code>
WEB
...
END
</code> 

Dieses Beispiel zeigt den Beginn und das Ende eines =WEB= -Blocks. Innerhalb eines solchen Blocks folgen Deklarationen von Schlüsselworten und dazugehörigen Werten, oder wieder neue Blöcke. Beispiele für Blöcke in Blöcken sind Classes innerhalb von Layern.

Ausnahmen für diese Notation sind der Header des Mapfiles und das Mapfile selber, das zwar mit einem END abgeschlossen werden muss, aber kein einleitendes Schlüsselwort kennt.

Wann immer im folgenden drei Punkte in Beispielen zu sehen sind, sollen diese Punkte nicht tatsächlich eingegeben werden; es handelt sich vielmehr um Platzhalter, die zeigen, dass etwas weggelassen worden ist.

Es können drei verschiedene Dinge als Werte notiert werden: Schlüsselworte, Zahlen oder Zeichenketten.

 <code>
SCHLÜSSELWORT SCHLÜSSEL
STATUS ON

SCHLÜSSELWORT "ZEICHENKETTE"
DATA "myshapefile"

SCHLÜSSELWORT ZAHL [ZAHL ...]
EXTENT 0 0 4000 4000
</code> 

Im Gegensatz zu Schlüsselworten und Zeichenketten ist es bei Zahlen in den meisten Fällen nötig, mehr als nur eine zu schreiben. So benötigt man für den Extent einer Karte stets vier Zahlen, die die beiden Koordinaten jeweils eines Eckpunktes bezeichnen.

Zeichenketten sollten generell nicht mit Zahlen beginnen: =zweiterlayer= ist als Layername in Ordnung, =2terlayer= nicht.

Ausnahmen dazu bilden Angaben zu Projektionen von Karten und Layern und die Metadaten in diversen Sektionen. Deren Notation wird in den entsprechenden Abschnitten näher beschrieben.

Zwei Arten von Angaben verdienen besondere Beachtung: Pfade in das Dateisystem und Farben.

\subsubsection*{Notation von Pfaden}

Pfade können absolute oder relative Angaben sein. Absolute Angaben sehen etwa folgendermaßen aus:

 <code>
SHAPEPATH "c:\mapserver\daten"
SHAPEPATH "/usr/local/GIS/daten/"
</code> 

Absolute Pfade heißen so, weil sie den vollständigen Pfad von der Wurzel des Dateisystems bis hin zur Datei angeben.

Relative Pfade bewegen sich immer in Relation zu etwas, in unserem Fall zum Mapfile:

 <code>
SHAPEPATH "daten/"
</code> 

In diesem Fall gibt es also im Verzeichnis des Mapfiles ein Unterverzeichnis mit dem Namen =daten= .

\subsubsection*{Farbwerte}

Farben werden als RGB-Werte angegeben, also bestehend aus ihren jeweiligen Anteilen von Rot, Grün und Blau, in Werten von 0 bis 255\footnote{Dadurch lassen sich theoretisch <math>2^{24}</math> Farben, also die bekannten 16 Millionen darstellen}. Einige Beispiele:

 <code>
COLOR 0 0 0 # schwarz
COLOR 255 255 255 # weiß
COLOR 255 0 0 # rot
COLOR 0 255 0 # grün
COLOR 0 0 255 # blau
</code> 

Und so weiter. Farben, bei denen alle drei Zahlen gleich sind, ergeben Grautöne. Im Web finden sich einige Farb- und Umrechnungstabellen.

Beachten Sie bitte: Ohne weitere Angaben zum Ausgabeformat -- siehe Seite~\pageref{text:mapfile:ausgabeformate} -- produziert MapServer nur Bilder mit einer Palette von 256 Farben. Mehr über Farben in MapServer erfahren Sie in eben diesem Abschnitt.

==Der Header==
\index{Header}\index{Mapfile!Header}(3)

Der Header im Mapfile enthält globale Angaben, die sich auf alle Sektionen im
Mapfile beziehen oder das Aussehen des fertigen Bildes bestimmen, das produziert
werden soll. Der Header ist die einzige Sektion, die nicht durch ein END
abgeschlossen wird. Er besitzt auch kein einleitendes Schlüsselwort.

Ein Beispiel für einen kompletten Header\footnote{Um keinen Fehler im Modus =map= zu produzieren, reichen eigentlich schon SIZE und EXTENT, zusammen mit einem END für ein vollständiges Mapfile.}:

 <code>
NAME "brandenburg"
EXTENT 0.0 0.0 1.0 1.0
SIZE 450 450
SHAPEPATH "daten/brandenburg/"
</code> 

Sie können die folgenden Angaben im Header Ihres Mapfiles machen:

*=NAME <name>= Ein Name als Beschreibung der Karte. Dieser Name sollte einzigartig sein und im weiteren nicht als Name für Layer verwendet werden. Der Name der Karte wird für WMS-konforme Aufrufe verwendet -- siehe auch das entsprechende Kapitel --, als auch als Prefix für die Namen temporär erzeugter Dateien des MapServer.
*=STATUS <ON|OFF>= : Der Status der Karte, ob an oder aus. Da man ein Mapfile normalerweise schreibt, um eine Karte anzuzeigen, drängt sich =ON= geradezu auf.\\ Ausschalten will man das nur dann, wenn man nur die anderen Elemente benutzen will, die man im Mapfile definiert, also zum Beispiel Maßstäbe und Legenden.
*=EXTENT <minx miny maxx maxy>= : Eine Bounding Box um die Daten herum. Wird im URL für den MapServer keine Bounding Box explizit angegeben, ist diese Angabe im Mapfile eine Standardeinstellung, die automatisch verwendet wird. Dieser Wert muß zwingendermaßen vorhanden sein.\\ Sorgen Sie dafür, dass hier ein sinnvoller Wert steht. MapServer ist nicht in der Lage, aus den vorliegenden Daten einen 'Default'-Extent zu ermitteln. Auf das Problem angesprochen, meinten die Entwickler, so ein Feature auch nicht implementieren zu wollen, zumal einige Datenformate gar keinen Extent speichern und das Errechnen aus den Daten selbst viel zu aufwendig wäre.
*=SIZE <width height>= : Die Größe des zu produzierenden Bildes, anzugeben in Breite und Höhe in Pixeln. Auch dies ist eine Voreinstellung, die Verwendung findet, wenn es keine andere explizite Angabe gibt. Die Größe des zu produzierenden Bildes ist auf 2048 Pixel im Quadrat beschränkt.
*=SHAPEPATH <path>= : Der Ort im Dateisystem, an dem die Daten liegen. Kann ein relativer Pfad zum Mapfile sein, oder ein absoluter, der irgendwo anders in das lokale Dateisystem weist.
*=SYMBOLSET <filename>= : Die Datei, in der Symbole definiert werden. Was es mit Symbolen auf sich hat, und wie Symbole im Mapfile selber anstatt in einer separaten Datei notiert werden können, erfahren Sie in Abschnitt~17.
*=FONTSET <filename>= : Die Datei, die Aliase für TrueType-Schriften enthält. Zum Aufbau dieser Datei und der Verwendung von Schriften im MapServer siehe den Abschnitt ab Seite~\pageref{text:mapfile:fonts}.
*=IMAGECOLOR <red green blue>= : Hintergrundfarbe des fertigen Kartenbildes, in RGB-Werten.
*=IMAGEFORMAT <name>= : Name des Ausgabeformats, das produziert werden soll. Muß ein interner Name für ein Bildformat sein, oder der Name eines Ausgabeformates, der mit einer =OUTPUTFORMAT= -Sektion definiert worden ist. Mehr zu Ausgabeformaten finden Sie ab Seite~\pageref{text:mapfile:ausgabeformate}.

\subsubsection*{Das Wort MAP}

Sie können ein Mapfile auch mit dem Schlüsselwort =MAP= einleiten:

 <code>
MAP
NAME "brandenburg"
SIZE 400 400
...
END
</code> 

Das ist nicht notwendig. Sie können so allerdings dem abschließenden =END= am Ende des Mapfiles sozusagen einen Startparameter zur Seite stellen. Es sieht hübscher aus, hat aber keine Funktion.

==Die Web-Sektion==
\index{Web}\index{Mapfile!Web}

Der Web-Block im Mapfile definiert das Verhalten des MapServer-Interface nach außen und beinhaltet URLs für verschiedene Gelegenheiten, einige interne Informationen, die nicht nach außen weitergegeben werden, sowie eventuell Metadaten für verschiedene Anwendungsfälle, für gewöhnlich zum Beispiel für OGC-konformes Verhalten.

Der Web-Block wird mit den Schlüsselwort =WEB= eingeleitet und durch ein =END= abgeschlossen.

'Web' ist als Name eigentlich irreführend, da die Daten in diesem Abschnitt nicht notwendigerweise nur von Web-Diensten genutzt werden. Aber der MapServer wurde als Web-Applikation entwickelt, und daher ist es unwahrscheinlich, dass sich an dieser Benennung etwas ändern wird.

Die folgenden Elemente können in der Web-Sektion verwendet werden:

*=ERROR <url>= \index{ERROR}: Definiert einen URL, an den der Benutzer weitergeleitet wird, wenn ein Fehler in der MapServer-Applikation auftritt. Kann eine absolute URL sein, die mit =http://= eingeleitet wird, oder ein Pfad relativ zur Lage des Mapfiles. Wird =ERROR= nicht definiert, wird einfach nur die Fehlernachricht als Text ausgegeben.\\ Beachten Sie dabei, dass das für das Debuggen während der Entwicklung Ihrer Anwendung nicht begehrenswert ist, da keine der MapServer-Fehlermeldungen mehr ausgegeben werden. Das will man für gewöhnlich nur für das fertige System haben, sobald man seine Benutzer nicht mehr mit den Fehlermeldungen des MapServers konfrontieren möchte, sondern mit einer hübschen Fehlerseite.
*=EMPTY <url>= \index{EMPTY}: URL, an den der Benutzer weitergeleitet wird, wenn ein Query keine Resultate erbracht hat. Wenn =EMPTY= nicht definiert ist, wird dafür der Wert von =ERROR= benutzt.
*=FOOTER <filename>= \index{FOOTER}: Der Fußteil einer fertigen Ausgabe. Kommt nur bei Queries zur Anwendung, die mehrere Ergebnisse zurückliefern sollen.
*=HEADER <filename>= \index{HEADER}: Der Kopfteil einer fertigen Ausgabe. Kommt nur bei Queries zur Anwendung, die mehrere Ergebnisse zurückliefern sollen.
*=TEMPLATE <url|filename>= \index{TEMPLATE}: Das Template, das das eigentliche Interface zum Benutzer darstellt. Darstellung der Karte und die Navigation darin werden durch das Template übernommen. Der Aufbau eines Templates wird detailliert in Abschnitt~20 behandelt.
*=IMAGEPATH= \index{IMAGEPATH}: Der Pfad zu dem Verzeichnis, in dem die vom MapServer generierten Bilder abgelegt werden sollen. Dieser Pfad muß auf dem System existieren und muß vom Webserver (bzw. von dem Benutzer, mit dessen Rechten der Webserver läuft) beschreibbar sein. Diese Angabe muß mit dem Verzeichnistrenner der jeweiligen Plattform enden, also =/= auf Unix-Systemen und so weiter.
*=IMAGEURL= \index{IMAGEURL}: Der URL zum genannten =IMAGEPATH= . =IMAGEURL= wird vom Webbrowser zurückgegeben und muß daher im Webserver so konfiguriert sein, dass =IMAGEURL= auf =IMAGEPATH= abgebildet wird. Auf Unix-Systemen wird meistens der URL =/tmp= auf das lokale Verzeichnis =/tmp/= (oder auch =/var/tmp/= ) abgebildet. Damit gibt man jedoch auch sein temporäres Verzeichnis dem öffentlichen Zugriff preis. Sinnvoller ist es, ein eigenes Verzeichnis für diese Dateien anzulegen. Mehr Überlegungen zu diesem Thema finden Sie in Anhang~\ref{anhang:sicherheit}.
*=LOG <filename>= \index{LOG}: Die Logdatei für den MapServer. Diese Datei muß auf dem System existieren und muss vom Webserver (bzw. von dem Benutzer, mit dessen Rechten der Webserver läuft) beschreibbar sein. Mehr zu Log-Dateien erfahren Sie weiter unten in Abschnitt~31.
*=METADATA<filename>= \index{LOG}: Die Sektion Metadata ermöglicht es, weiterführende Informationen über den WMS-Dienst bereitzustellen, um nach aussen eine gewisse Transparents zu schaffen. So gibt es zum Beispiel den erforderlichen Parameter "wms_title", über dem das Kind einen Namen bekommt. Nähre Information zu den einzelenen Parametern, finden Sie im Kapitell 3, Sektion 3.2.3 WMS-Metadaten im Mapfile.
*=MINSCALEDENOM= \index{MINSCALE}: Der minimale =SCALE= , in dem Karten zu sehen sind. Wird eine Karte mit einem kleineren =SCALE= vom Client angefordert, liefert MapServer eine Karte in dem =SCALE= zurück, der =MINSCALE= entspricht. Mehr zur Verwendung von =SCALE= -ähnlichen Parametern im Mapfile finden Sie in Sektion~19.
*=MAXSCALEDENOM= \index{MAXSCALE}: Der maximale =SCALE= , in dem Karten zu sehen sind. Wird eine Karte mit einem größeren =SCALE= vom Client angefordert, liefert MapServer eine Karte in dem =SCALE= zurück, der =MAXSCALE= entspricht. Mehr zur Verwendung von =SCALE= -ähnlichen Parametern im Mapfile finden Sie in Sektion~19.
*=MINTEMPLATE= \index{MINTEMPLATE}: Template, das anstelle von =TEMPLATE= benutzt werden soll, wenn der Client eine Karte angefordert hat, deren =SCALE= unter =MINSCALEDENOM= liegt. Mit einem solchen Template lassen sich Applikationen ineinander verschachteln, indem ab bestimmten Zoomtiefen einfach andere Templates benutzt werden.
*=MAXTEMPLATE= \index{MAXTEMPLATE}: Template, das anstelle von =TEMPLATE= benutzt werden soll, wenn der Client eine Karte angefordert hat, deren =SCALE= über =MAXSCALEDENOM= liegt. Mit einem solchen Template lassen sich Applikationen ineinander verschachteln, indem ab bestimmten Zoomtiefen einfach andere Templates benutzt werden.

Der Parameter =IMAGEQUALITY= , mit dem sich Kompressionsraten für produzierte JPEG-Bilder setzen ließ, wird nicht mehr unterstützt. Verwenden Sie stattdessen einen entsprechenden Parameter in einer =OUTPUTFORMAT= -Sektion (siehe weiter hinten). Das gleiche gilt für =INTERLACED= .

==Layer==
\index{Layer}\index{Mapfile!Layer}

MapServer organisiert seine Daten in Schichten, die übereinander liegen -- eben den Layern. Diese Schichten werden dann zu einem fertigen Bild zusammengefügt. Einzelne Sets von Raster- oder Polygondaten müssen jeweils in einen eigenen Layer eingebunden werden. Über die Layer werden auch Queries definiert, die dazu verwendet werden, Anfragen an zusätzlich gespeicherte Daten zu stellen. Auf diese Weise können beispielsweise Flächen angeklickt und detaillierte Informationen zu diesen angezeigt werden.

Bei nicht-OGC-konformen MapServern spielt die Reihenfolge der Layer im Mapfile eine wichtige Rolle.
Dies können sie sich wie eine Art Stapelverarbeitung vorstellen. Der Layer, der oben auf dem Stapel liegt, wird als erstes abgearbeitet und gezeichnet, somit liegt dieser in der Kartendarstellung ganz unten. Rasterbilder bieten sich meist als unterster Layer an. Auf den ersten Layer wird dann der zweite Layer im Mapfile gezeichnet, und so weiter.

Wir betrachten im folgenden den Aufbau eines Vektorlayers mit Zugriff auf ein Shapfile. Rasterdaten werden in Abschnitt~7 besprochen.

*=NAME <name>= : Ein Name als Beschreibung des Layers. Mehrere Layer können identische Namen tragen und werden dann als ein einziger Layer behandelt. Diese Vorgehensweise wird manchmal für Beschriftungen (Annotationen, siehe weiter hinten) gewählt, um in einem Zug den Layer samt Beschriftung ein- oder ausblenden zu können. Ansonsten sollte der Name so gewählt werden, dass er eindeutig ist. Um mögliche Fehlerquellen bei der Wahl des Layernames von vornherein zu vermeiden,
ist es empfehlenswert den Layernamen so zu bestimmen, dass weder Sonderzeichen, noch Zahlen und Umlaute enthalten sind.

*=DATA <filename>= : Der Dateiname des Shapefiles. Dieser Name ist relativ zum =SHAPEPATH= im Header des Mapfiles. Die Zeichenkette hier wird also einfach angehangen. Der Name sollte ohne den Anhang ''.shp'' angegeben werden. Bitte beachten Sie, dass die zum Shapefile gehörige ''.dbf'' -Datei immer vorhanden sein muss, auch wenn man nicht auf ihren Inhalt zugreift. Das gleiche gilt natürlich auch für die Indexdatei mit der Endung ''.shx'' , nur wird diese ja beim Zugriff auf das Shape tatsächlich verwendet. Des weiteren können Sie hier auch einfach den absoluten Pfadnamen einer Datei angeben.
*=STATUS <ON|OFF|DEFAULT>= : Der Status des Layers. Es gilt drei verschiedene Stadien zu unterscheiden. =DEFAULT= stellt den betreffenden Layer auf jeden Fall dar, unabhängig davon, ob der Benutzer ihn über den URL anfordert. Auf diese Weise läßt sich die Darstellung beispielsweise eines Hintergrundbildes erzwingen, ohne dass man ihn von außen abschalten kann. =OFF= stellt den Layer gar nicht da, unabhängig davon, ob er von außen angefordert worden ist. =ON= hingegen macht den Layer darstellbar, und er wird angezeigt, wenn er über den entsprechenden Parameter des URL angefordert worden ist.
*=TYPE <POINT|LINE|POLYGON>= : Für Vektorlayer kommen nur diese drei verschiedenen Typen in Frage. Punktlayer sind offensichtlich nur für Punktdaten geeignet. Generell lassen sich Linien- und Vektordaten als das jeweils andere darstellen. Das wirkt sich im wesentlich auf die Art und Weise aus, mit der MapServer die Definitionen in den Klassen des Layers interpretiert. Mehr dazu im Abschnitt über Classes.

Beachten Sie bitte, dass in den Layer-Sektionen mit diesen Angaben noch keine Aussagen über das Layout der Daten gemacht werden. Diese Aussagen werden erst in den Klassen innerhalb eines Layers getroffen!

===Gruppierungen von Layern===
(4)
\index{Groups}\index{Layer!Groups}

Zuweilen möchte man mehrere Layer gleichzeitig ansprechen, indem man sie beispielsweise in einem Schwung an- und wieder ausschaltet. Wenn man für jeden dieser Layer einen eigenen Eintrag in der Navigation zuläßt, kann es schnell unübersichtlich werden.

Eine Möglichkeit ist, zusammengehörigen Layern den gleichen Namen zu geben. Wenn man also drei Layer hat, die beispielsweise Landstraßen, Autobahnen und Bundesstraßen darstellen, kann man sie alle drei =strasse= nennen und ist fertig.

Das widerspricht jedoch ein wenig der Idee, drei verschiedene Layer zu haben. Man hätte dann ebenso gut alle Daten in einem Shapefile unterbringen und die Art der Darstellung mit entsprechenden Classes über die Daten in der ''.dbf'' -Datei erledigen können.

Das Schlüsselwort =GROUP= erlaubt die Gruppierung von Layern unter Beibehaltung ihrer Namen mitsamt der Möglichkeit, sie alle auf einmal ansprechen zu können. Man schaue sich folgendes Fragment an:

 <code>
LAYER
NAME "autobahnen"
GROUP "strassen"
...
END

LAYER
NAME "bundesstrassen"
GROUP "strassen"
...
END

LAYER
NAME "landstrassen"
GROUP "strassen"
...
END
</code> 

Nun ist es möglich, im URL eines MapServer-Aufrufs weiterhin folgendes zu schreiben:

 <code>
...&layer=landstrassen&layer=autobahnen&...
</code> 

Zusätzlich gewinnt man aber auch die folgende Notation:

 <code>
...&layer=strassen&...
</code> 

===Weitere Layer-Optionen===

Im folgenden eine Liste aller weiteren Schlüsselworte, die in Layern Verwendung finden können. Falls Sie dieses Buch von vorne nach hinten durchlesen\footnote{Sowas soll's geben.}, werden Sie einige der Begriffe wahrscheinlich noch nicht kennen. Sie sollten dann später noch einmal hierher zurückkehren und sich die Bedeutung der Dinge klarmachen.

*=REQUIRES <expression>= Legt bestimmte Voraussetzungen fest, unter denen ein Layer angezeigt wird. Ein Beispiel: <code> LAYER NAME "gruenflaechen" STATUS ON REQUIRES "[parks] != 1" ... END </code> Dieser Layer würde also nur dann angezeigt, wenn ein anderer Layer mit dem Namen =parks= ''nicht'' zu sehen ist. Logische Operatoren wie =AND= und =OR= können hier Verwendung finden.
*=MAXSCALE <double>= Der maximale SCALE, bei dem der Layer noch gezeichnet werden soll. Dieser Wert ist unter Umständen nicht vertrauenswürdig -- siehe auch den Abschnitt~19 über Maßstäbe.
*=MINSCALE <double>= Das gleiche für einen minimalen SCALE.
*=LABELANGLEITEM <colname>= Gibt bei einem Shapefile die Spalte in der ''.dbf'' -Datei an, in der ein Winkel stehen soll, um den ein Label im Layer gedreht werden soll.
*=LABELMAXSCALE <integer>= Der maximale SCALE, in dem Labels in diesem Layer gezeichnet werden sollen. Anmerkungen zu diesem Wert siehe weiter oben.
*=LABELMINSCALE <integer>= Der minimale SCALE, bei dem Labels in diesem Layer noch gezeichnet werden sollen.
*=LABELREQUIRES <expression>= Siehe weiter oben das =REQUIRES= -Schlüsselwort; wirkt sich aber nur auf die Label in einem Layer aus.
*=MAXFEATURES <integer>= Die maximale Anzahl an Features, die in diesem Layer gezeichnet werden sollen.
*=OFFSITE <integer>= Kommt nur bei Rasterbildern zur Anwendung und gibt die Nummer der Farbe in der Farbpalette an, die transparent geschaltet werden soll.
*=POSTLABELCACHE <true|false>= Gibt an, ob der Layer vor oder nach allen Labels gezeichnet werden soll. Voreinstellung ist =false= .
*=SYMBOLSCALE <double>= Der SCALE, bei dem Labels (und Symbole) in ihrer vollen Größe gezeichnet werden. Auf diese Weise erreicht man Beschriftungen, die beim Herein- und Herauszoomen mitskalieren.
*=TRANSFORM <true|false>= Definiert, ob ein Layer von dem Koordinatensystem seiner Daten in ein Bildkoordinatensystem transformiert werden soll. Voreinstellung ist =true= . Eine nützliche Funktion, wenn man Bilder an festen Stellen in jeder Karte einbinden möchte, beispielsweise Nordpfeile oder Logos.
*=CLASSITEM <colname>=
*=CLASSGROUP <name>=
*=CONNECTIONTYP<local|sde|ogr|postgis|oraclespatial|wms>=
*=CONNECTION <string>=
*=DEBUG<off|on|0|1|2|3|4|5>= Der DEBUG Befehl kommt dann zum Einsatz, sobald sie ihr Mapfile speziell testen möchten. So geben die einzelnen Level detailierte Antworten,zum Beispiel über die Darstellungsdauer des einzelnen Layer. Um den DEBUG Parameter verwendeen zu können, muss im Vorfeld im oberen MAP-Teil ein MS_ERRORFILE definiert werden, über dem die Ausgabedatei bestimmt wird. Näheres dazu finden sie im Kapitel 12 Logging.
*=DUMP<true|false>= Ist default mäßig auf =false=, sollten sie später mit WMS GetFeatureInfo arbeiten empfiehlt es sich, diesen Parameter auf =true= zusetzen, damit der MapServer die Anfrage bearbeiten kann. Die Antwort liefert der MapServer als GML Datei.
*=FILTER<string>=
*=FILTERITEM<attribute>=
*=LABELCACHE<on|off>=
*=LABELITEM<colname>= Mit diesem Befehl, lassen sich ihre Vektordaten beschriften (labeln), hierfür geben sie die Spalte, aus der gewünschten Datenquelle, an in der sich der gewünschte, darzustellende Zeichensatz befindet. Zur Beschriftung mit Inhalten aus mehreren Datenspalten kann der TEXT-Eintrag in der CLASS genutzt werden in der Form: TEXT ([colname 1], [colname 2]). Möglich ist damit auch, dynamische Einträge aus den Tabellenspalten mit fixen Textbestandteilen zu mischen. In diesen Fällen kann LABELITEM entfallen.

 <code>
Bsp. 1: Mischung aus zwei Tabellenspalten
CLASS
...
TEXT ([stadtteil]-[stadtviertel])
END

oder
Bsp. 2: Mischung aus einer Tabellenspalte und fixen Text (''GK:'')

CLASS
...
TEXT (GK:[gk-zone])
END
</code> 

*=OPACITY<integer|alpha>= Definiert die Tranpsarents eines Layers, hierbei können sie mit zwei unterschiedlichen Operanten arbeiten. Die am häufigsten verwendete Methode ist die Angabe des Wertebereichs von 0 bis 100 als Integerzahl, wobei 100 den Layer komplett transparent darstellt. Die zweite Möglichkeit kommt eher selten zum Einsatz, dabei wird...
*=PROCESSING<string>=
*=REQUIRES<expression>=
*=SIZEUNITS<pixels|feet|inches|kilometers|meters|miles>=
*=STYLEITEM<attribute]>=
*=TILEINDEX<filename|layername>=
*=TILEITEM<attribute>=
*=TOLERANCE<double>=
*=TOLERANCEUNITS<pixels|feet|inches|kilometers|meters|miles|dd>=
*=UNITS<feet|inches|kilometers|meters|miles|dd|pixels|percentages>=
*=HEADER<filename>=
*=FOOTER<filename>=

=== Diagramme ===

...

==Classes==
\index{Classes}\index{Klassen}\index{Mapfile!Classes}

''Hinweis'' : Beachten Sie auf alle Fälle die Hinweise in Abschnitt~6, insbesondere, wenn Sie bisher älteren MapServer-Versionen als 4.0 gearbeitet haben.

Classes residieren ausschließlich innerhalb eines Layers. Sie definieren, wie die Daten innerhalb eines Layers tatsächlich dargestellt werden.

Zur Illustration ein erstes kleines Beispiel:

 <code>
LAYER
NAME "fluesse"
DATA "shapes/fluesse"
TYPE LINE
STATUS ON
CLASS
COLOR 0 0 255
END
END
</code> 

In diesem Vektorlayer gibt es lediglich eine einzige Class, was bedeutet, dass alle Shapes aus dem Shapefile auf die gleiche Weise dargestellt werden. In diesem Fall sind sie blau eingefärbt.

Beachten Sie, dass Sie zur Einfärbung von Linien und Punkten das Attribut =COLOR= benutzen müssen, wohingegen dieser Wert bei Polygonen die Füllfarbe bezeichnet. Der Rand des Polygons wird durch =OUTLINECOLOR= angesprochen.

\subsection*{Datenabhängiges Einfärben}

Wozu aber nun Classes einführen, wenn man diese Angaben auch direkt in den Layer schreiben könnte? Weil man durch Classes themenbezogene Darstellungen erreichen kann. Sehen wir uns das folgende Beispiel an:

 <code>
LAYER
NAME "fluesse"
DATA "shapes/fluesse"
TYPE LINE
STATUS ON
CLASSITEM "NAME"
CLASS
EXPRESSION "Wolga"
COLOR 255 31 31
END
CLASS
EXPRESSION /./
COLOR 31 31 255
END
END
</code> 

Wir sehen zuerst ein neues Schlüsselwort, =CLASSITEM= . Die Zeichenkette dahinter benennt die Spalte in der ''.dbf'' -Tabelle, anhand derer wir im folgenden filtern wollen. Alle Angaben in den Classes, die sich in diesem Layer befinden, orientieren sich an der Spalte mit diesem Namen.

In der ersten Class befindet sich eine =EXPRESSION= , ein Ausdruck. Damit ein Feature mit den Angaben in dieser Klasse dargestellt wird, muß das =CLASSITEM= auf diesen Ausdruck passen. Oder für das Beispiel: die erste Klasse findet Anwendung auf alle Shapes im Shapefile, deren NAME in der ''.dbf'' -Datei 'Wolga' lautet.

Die Classes in einem Layer werden von oben nach unten abgearbeitet, und die erste passende Class wird zur Darstellung verwendet.

Der Ausdruck in der letzten Class in diesem Beispiel bedeutet übrigens 'alle Zeichen'. Jeder mögliche Inhalt einer Spalte passt auf diesen Ausdruck. Es ergibt Sinn, eine solche 'Catch all'-Class anzulegen, um allen Features ein Standardaussehen zu verpassen, die nicht von einer der vorherigen Class abgedeckt worden sind. Eine Erklärung der möglichen Ausdrücke erfolgt im nächsten Abschnitt.

\subsection*{Mögliche Ausdrücke}

Es gibt drei verschiedene Weisen, eine =EXPRESSION= zu formulieren: mit Zeichenketten, mit regulären Ausdrücken und schließlich mit logischen Ausdrücken.

Zeichenketten sind bereits im obigen Beispiel zu sehen gewesen. Die Einträge in den Spalten der ''.dbf'' -Datei werden darauf geprüft, ob sie ''genau'' diesen Wert enthalten. Diese Art von =EXPRESSION= ist durch den MapServer am schnellsten abzuarbeiten.

Logische Ausdrücke sind Ausdrücke, die durch logische Operatoren gebildet werden können. Dazu gehören Konstrukte für gleich, ungleich, größer als, kleiner als und so weiter; darüber hinaus und, oder, nicht, und alle Kombinationen, die sich daraus ergeben. Dabei können weitere Spaltennamen in der .dbf-Datei referenziert werden. Als Beispiel ein Ausschnitt aus einem Layer:

 <code>
CLASSITEM "NAME"
CLASS
EXPRESSION ([NAME] eq "Wolga" and [SIZE] < 10)
COLOR 255 0 0
END
CLASS
EXPRESSION /^A.+e<math>/
COLOR 0 0 255
END
CLASS
EXPRESSION /./
OUTLINECOLOR 128 128 128
END
</code> 

Die erste Klasse findet Anwendung auf alle Shapes, deren Spalte =NAME= im .dbf-File den Eintrag ''Wolga'' haben und gleichzeitig einen kleineren Wert als ''10'' in der Spalte =SIZE= .

Obwohl diese Ausdrücke schon eine Menge Flexibilität bieten, kann man noch einen Schritt weiter gehen, wie man in der zweiten Klasse sehen kann. Die Art des dortigen Ausdrucks ist Informatikern als sogenannter regulärer Ausdruck bekannt. Der Ausdruck passt auf alle Einträge in der =NAME= -Spalte, auf die folgendes zutrifft: der erste Buchstabe ist ein großes ''A'' , das von einer beliebigen Anzahl beliebiger Zeichen (mindestens jedoch einem) gefolgt wird, abgeschlossen durch ein kleines ''e'' .

Die letzte Regel zeigt ebenfalls einen regulären Ausdruck. Er passt auf jedes beliebige Zeichen. Da die Classes von oben nach unten auf der Suche nach der ersten passenden Regel für ein Feature abgesucht werden, handelt es sich um eine sogenannte ''catch all'' -Regel, die auf alles zutrifft, was nicht vorher schon irgendwo gepasst hat.

Reguläre Ausdrücke sind ein ungemein mächtiges Werkzeug, das jedoch etwas Mühe zu Lernen erfordern kann. MapServer verwendet POSIX-konforme reguläre Ausdrücke, die auf jedem Unix-System in einer =man= -Page~[[man:7:regex]] erklärt werden.

=== Gruppierungen von Classes ===

...

==Styles==
(6)\index{Styles}\index{Mapfile!Styles}

Mit MapServer 4.0 ist eine weitere Art eingeführt worden, die Darstellung eines Layers zu notieren. Um genau zu sein, sollte diese Art langsam aber sicher bevorzugt werden, zumal sie auch zusätzliche Vorteile bietet.

Aber zunächst sollen Sie natürlich erfahren, um was es geht. MapServer kennt ein neues Objekt, also eine Sektion, mit dem Namen =STYLE= . Diese Sektion trit nur innerhalb von Classes auf und wird selbstverständlich jeweils mit einem =END= abgeschlossen. Das ganze soll den Zweck haben, den gestalterischen Part einer Class vom logischen zu trennen. Anstatt also folgendes zu notieren:

 <code>
CLASS
EXPRESSION ([NAME] eq "Havel" and [SIZE] > 20)
SYMBOL "punkt"
COLOR 32 64 218
END
</code> 

würden Sie in Zukunft folgendes schreiben:

 <code>
CLASS
EXPRESSION ([NAME] eq "Havel" and [SIZE] > 20)
STYLE
SYMBOL "punkt"
COLOR 32 64 218
END
END
</code> 

Im Moment können Sie noch beides verwenden. Im Sinne einer sauberen Arbeitsweise sollte Sie allerdings dazu übergehen, Styles zu benutzen und die Parameter, die für die Darstellung zuständig sind, nicht mehr direkt in den Classes zu notieren.

Die folgenden Parameter wandern in die Style-Sektion einer Class:

*=ANTIALIAS=
*=BACKGROUNDCOLOR=
*=COLOR=
*=MAXSIZE=
*=MINSIZE=
*=OFFSET=
*=OUTLINECOLOR=
*=SIZE=
*=SYMBOL=

Die Notierung der Parameter erfolgt wie weiter vorne ab Seite~\pageref{text:mapfile:class:parameters} beschrieben.

Warum sollte man das haben wollen? Es soll in Zukunft möglich sein, Styles mit Namen zu versehen, und dadurch Styles im gesamten Mapfile durch eben ihren Namen zu referenzieren. Dadurch kann bei umfangreichen Mapfiles einiges an Schreibarbeit eingespart werden. Insbesondere wird aber zukünftig Arbeit einsparen, weil Sie dann nur noch Styles von einem Mapfile ins andere Kopieren müssen, ohne auch noch an einer Class herumhantieren zu müssen.

Des weiteren kann man mehrere Styles in einer Class haben, sie werden der Reihe nach von oben nach unten ausgewertet; dabei wird, wie schon bei den Layern im Mapfile, der oberste Style zuerst gezeichnet. Dadurch ist es endlich möglich, mehr als die bisherigen 2 Symbole übereinander zu legen, wie es bisher mit =SYMBOL= und =OVERLAYSYMBOL= geschehen ist.

Außerdem -- dieser Teil ist allerdings reine Spekulation des Autors -- dürfte eine Abspaltung des darstellenden Teils einer Class die Implementierung der so genannten ''styled layer descriptors'' vereinfachen, einem OGC-Standard~[[pdf:spec:sld10]], mit dem sich die Darstellung von Kartenfeatures über URL-Parameter beeinflussen läßt.

==Rasterdaten==
(7)
\index{Rasterdaten}\index{Mapfile!Rasterdaten}

Rasterdaten sind alle Arten von Daten, deren Dimensionen in Länge und Breite in Pixeln gemessen werden kann, vulgo: Bildformate. Die Bildformate, die von MapServer unterstützt werden, müssen in zwei Kategorien eingeteilt werden: die von der Software lesbaren (Input) und die Ausgabeformate (Output).

Als Ausgabe liefert MapServer Bilder, die von Webbrowsern darstellbar sind. Da sich MapServer dabei auf die Grafikbibliothek GD stützt, ist er auf deren Fähigkeiten angewiesen.

Ein typischer Rasterlayer wird im Mapfile etwa auf folgende Art angelegt:

 <code>
LAYER
NAME "brandenburg_luftbild"
DATA "bilder/brandenburg.tif"
TYPE RASTER
STATUS ON
END
</code> 

In diesem Beispiel wird ein ''tiff'' -Bild eingebunden, das anscheinend ein Luftbild der Region Brandenburg zum Inhalt hat. Der =TYPE= des Layers ist als =RASTER= angegeben.

Welche Formate eingelesen werden können, ist im wesentlichen eine Frage, die bei der Konfiguration noch vor der Kompilierung der Software geklärt wird. Einige Formate können dabei als eingebaut angesehen werden, indem der MapServer direkt auf die entsprechenden Bibliotheken zugreift. Andere Formate werden über die Rasterbibliothek GDAL gehandhabt.

Welche Formate Ihr MapServer handhaben kann, können Sie durch das Ausführen des CGI-Binaries auf der Kommandozeile mit dem Kommandozeilenschalter
''-v'' herausfinden:

 <code>
thfischer@grobi # ./mapserv -v
MapServer version 4.0 OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF
OUTPUT=SWF SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER
SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT
INPUT=EPPL7 INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE
</code> 

In diesem Beispiel sehen wir =.jpeg= als (lesend) unterstütztes Rasterformate. Weitere Formate können durch Verwendung der GDAL-Schnittstelle angesprochen werden, insbesondere findet hier das Lesen von =.tif= -Bildern über GDAL statt. Mehr zu diesen Bibliotheken finden Sie weiter hinten im Buch.

Beachten Sie, dass es für Rasterdaten keine Queries auf den Layer geben kann, da mit den gängigen Rasterformaten keine Metadaten gespeichert werden.

===Bildkataloge===
(8)
\index{Rasterdaten!Kataloge}\index{Bildkataloge}

Bilddaten können sehr schnell sehr groß werden. Detaillierte Rasterbilder können viele Megabyte, wenn nicht gar Gigabyte groß werden. Solche Datenmengen sind nur schwierig zu handhaben, sowohl für den MapServer als auch, was die Verwaltung angeht. Um die Verarbeitung zu beschleunigen und die Handhabung zu vereinfachen, kann man sich so genannter Bildkataloge bedienen.

Des weiteren kann es natürlich passieren, dass man seine Daten gleich in mehreren Bildern bekommt, aber sicherlich nicht für jedes Bild einen eigenen Layer im Mapfile anlegen möchte. Man könnte die Layer natürlich mittels =GROUP= zusammenfassen; aber man müßte eben immer noch alle Layer ins Mapfile eintragen.

Das Format von MapServer-Bildkatalogen verwendet keinen verbreiteten Standard, der dazu führen würde, dass Sie die Bildkataloge auch mit anderen Programmen einlesen könnten. Allerdings verläßt sich MapServer auf standardisierte Datenformate, sodass eine Konvertierung von dieser Seite aus keine Schwierigkeiten bereiten sollte.

Dabei werden alle Bilder (sie müssen mit Worldfiles georeferenziert sein) über ein Shapefile verortet. Das Shapefile erhält dabei die Koordinaten der einzelnen Bilder, die ''.dbf'' -Datei der Reihe nach die dazugehörigen Dateinamen der Bilder.

Die Notation solcher Kataloge im Mapfile erfolgt folgendermaßen:

 <code>
LAYER
NAME "luftbild"
TYPE RASTER
STATUS ON
TILEINDEX "luftbildshape"
TILEITEM "IMAGEFILENAME"
END
</code> 

In diesem Beispiel trägt das Katalog-Shapefile den Namen =luftbildshape= . Mit =TILEITEM= gibt man an, wie die Spalte in der ''.dbf'' -Datei heißt, die die Dateinamen der Rasterbilder trägt.

Das Erzeugen von Bildkatalogen muß durch zusätzliche Software geschehen. Die Bibliothek GDAL bringt dafür ein Werkzeug namens =gdaltindex= mit -- siehe Seite~\pageref{text:tools:gdaltindex}

Durch den Aufbau mittels eines Shapefiles lassen sich die einzelnen Kacheln selber übrigens sehr schön visualisieren, indem man das betreffende Shape als Layer einbindet.

===Rasterdaten klassifizieren===

Rasterdaten können, ähnlich wie Vektordaten, klassifiziert werden. Dabei werden alle Pixel einer bestimmten Farbe (oder einer bestimmten Menge von Farben) auf eine andere Farbe abgebildet. Das macht man gerne bei 1-Bit-Bildern. Diese bestehen nur aus zwei Farben (also schwarz und weiß). Man färbt dann alle schwarzen Pixel in der gewählten Farbe ein, und schaltet dann die weißen Pixel für gewöhnlich transparent. Auf diese Weise lassen sich viele solcher Bilder in Schichten übereinander legen.

Es können aber auch Bilder mit 256 Farben klassifiziert werden.

Schauen wir uns ein Beispiel an:

 <code>
LAYER
NAME "grundwasser"
TYPE RASTER
STATUS ON
CLASSITEM "[pixel]"
CLASS
EXPRESSION ([pixel] < 128)
COLOR 255 0 0
END
CLASS
EXPRESSION ([pixel] >= 128)
COLOR 0 0 255
END
END
</code> 

Das =CLASSITEM= , nach dem wir filtern möchten, trägt den Namen =pixel= und repräsentiert die Nummer der Farbe in der Farbpalette des Bildes. Das funktioniert im Moment übrigens nur bei GD-Ausgabetreibern korrekt; der GDAL-Treiber\footnote{Zu Ausgabeformaten und -treibern siehe auch Seite~\pageref{text:mapfile:ausgabeformate}.} biegt vor der Bearbeitung des Bildes die Farbpaletten um, sodass man sich nicht auf die Position in der Farbpalette verlassen kann.

Die erste Class verleiht nun den ersten 128 Farben in der Farbpalette des Bildes ein grelles Rot, alle anderen Pixel werden durch die zweite Class blau dargestellt.

FIXME: ist das analog für truecolor-bilder etc.?

===Umprojizieren von Rasterdaten===

Der Gedanke läuft einem zuwider, wenn man sich die Mathematik klar macht. Man betrachte ein 4000 mal 4000 großes Tiff-Bild. Wenn man dieses Bild komplett umprojizieren möchte, müssen also 16 Millionen Pixel darauf geprüft werden, ob sie im neuen Zielbild liegen. Und wenn wir nun annehmen, dass wir 16 mal 16 solcher Kacheln haben, landen wir bei über 4 Milliarden Pixeln. Dass diese Berechnung eine Weile dauert, ist auf den ersten Blick ersichtlich.

Wenn Sie es jedoch einmal ausprobieren, werden Sie erstaunt sein, wie schnell MapServer Ihnen eine umprojizierte Karte liefert. Leider immer noch nicht schnell genug, wie man es im Dauerbetrieb, beispielsweise auf einer Website, haben will. Sie können sehr wohl mit der Geschwindigkeit vor Ihren Freunden angeben. Für den Dauerbetrieb lohnt es sich aber, die Projektion für Ihre Daten vorher zu machen.

Gleiche Überlegungen gelten übrigens auch für verschiedene Zoomstufen. Es lohnt sich durchaus, im Vorhinein zu überlegen, welche Zoomstufen am häufigsten zu sehen sein werden, um dann mit =MINSCALE= und =MAXSCALE= für diese Stufen verschiedene Datensätze anzuzeigen. Weitere Überlegungen zur Performance von MapServer-Anwendungen finden Sie ab Seite~\pageref{anhang:performance}.

===Rasterdaten mit GDAL===

\begin{figure}
\begin{center}
\mmfig{0.65}{gtopo30}{Die GTOPO30-Daten, hier ein Ausschnitt des Kanals zwischen Frankreich und Großbritannien.}
\end{center}
\end{figure}

Die Bibliothek GDAL ist für das Einlesen von Rasterdaten in MapServer zuständig, die über die 'herkömmlichen' Formate wie TIFF, JPEG, PNG und so weiter hinausgehen. Eine Liste von unterstützten Formaten finden Sie auf der GDAL-Website~[[http:website:gdal]]. Für diverse Formate müssen Sie unter Umständen die eine oder andere Zusatzbibliothek installiert haben. Bei Fragen oder Problemen hilft entweder ebenfalls die GDAL-Site weiter, oder eine Anfrage auf der MapServer-Mailingliste.

Die Notation von GDAL-gelesenen Rasterdaten weicht glücklicherweise überhaupt nicht von der von herkömmlichen Rasterdaten ab. Als Beispiel sollen hier die GTOPO30-Daten herhalten, die man sich von~[[ftp:gtopo30]] herunterladen kann\footnote{Achtung, falls Sie es auf den kompletten Datensatz für die ganze Welt abgesehen haben sollten: vollständig entpackt handelt es sich um 2,1 GB Daten. Beachten Sie bitte, dass es sich dabei um =Textdateien= handelt, die Bearbeitung also durchaus zeitintensiv ist.}.

Interessant sind für die Notation die Dateien mit der Endung =.DEM= . Die Abkürzung steht für ''digital elevation model'' , also für digitales Höhenmodell.

Sie können diese Daten in ein Unterverzeichnis entpacken -- nennen wir es =gtopo30= -- und dann ''gdaltindex'' für das Erzeugen eines Bildkatalogs aufrufen:

 <code>
# gdaltindex gtopo30.shp gtopo30/*.DEM
</code> 

Haben Sie das getan, können Sie sich einfach einen Layer wie folgt konstruieren:

 <code>
LAYER
NAME "gtopo30"
TYPE RASTER
STATUS ON
TILEINDEX "gtopo30"
END
</code> 

Und damit sind Sie dann auch schon fertig! Das Ergebnis sind dann beispielsweise aus wie in Abbildung~\ref{gtopo30}. Das DEM-Format wird behandelt wie jedes andere Rasterformat auch. Dem entsprechend können Sie eine einzelne dieser DEM-Dateien auch wie gewohnt folgendermaßen einbinden:

 <code>
LAYER
NAME "gtopo30"
TYPE RASTER
STATUS ON
DATA "gtopo30/W180S60.DEM"
END
</code> 

==Vektordaten==
\index{Vektordaten}

In seinen 'Jugendzeiten' war MapServer im wesentlichen darauf ausgelegt, Shapefiles darzustellen. Das macht sich insbesondere bei der Notation im Mapfile bemerkbar, wo bei Vektordaten einige Shapfile-spezifische Termini verwendet werden.

Zuerst ein Beispiel für Vektordaten in einem Layer:

 <code>
LAYER
NAME "gruenflaechen"
TYPE POLYGON
STATUS ON
DATA "gruenflaechen_0323333"
CLASS
EXPRESSION /./
COLOR 255 240 128
OUTLINECOLOR 128 120 64
END
END
</code> 

Der Typ eines Vektorlayers kann =POINT= , =LINE= oder =POLYGON= sein. Beachten Sie dabei, dass die beiden letztgenannten intern im wesentlichen gleich sind und daher in einigen Fällen austauschbar sind.

=DATA= verweist in diesem Fall auf ein Shapefile mit dem angegebenen Namen. Dieser Name ist relativ zum =SHAPEPATH= im Header des Mapfiles.

Das war auch schon alles, was es zur Notation von Shapefile-Layern im Mapfile zu sagen gibt. MapServer ist in der Lage, über Zusatzbibliotheken weitere Vektorformate zusätzliche zu Shapefiles einzulesen und zu verarbeiten.

===Indizes für Shapefiles===
\index{Index}\index{Index!Shapefiles}(9)

Mit sogenannten Quadtree-Indizes läßt sich die Bearbeitung von Shapefiles erheblich beschleunigen. Wie solche Indizes für den MapServer erstellt werden, erfahren Sie auf Seite~\pageref{text:tools:shptree}, wo das Werkzeug =shptree= vorgestellt wird. Hier soll nur kurz die dahinter stehende Idee erläutert werden.

In einem Shapfile, das beispielsweise 100 Shapes hat, muß für einen gegebenen Ausschnitt geprüft werden, ob das Shape ganz oder in Teilen in diesem Ausschnitt liegt und demnach angezeigt werden soll. Das geschieht über die Bounding Box eines Shapes, die mit im Shapefile gespeichert ist.

Ein Quadtree-Index folgt dem Gedanken, die Fläche des Shapefiles in vier Teile einzuteilen, und die darin liegenden Shapes in einem Index festzuhalten. Bei einem Zugriff wird zuerst die Fläche gesucht, in der der Ausschnitt liegt, und somit die Anzahl der zu prüfenden Shapes vermindert.

Die einzelnen Flächen lassen sich danach noch einmal in vier Unterflächen aufteilen (und diese wiederum in vier Unterflächen, und so weiter), sodass bei der Darstellung eine baumartige Struktur entsteht.

Die Größe und Lage der einzelnen Flächen muß übrigens nicht genau jeweils ein Viertel der größeren Fläche einnehmen. Die einzelnen Flächen werden nach Anzahl der darin liegenden Shapes gewichtet.

===GRID-Layer===
\index{Graticules}\index{Grids}(10)

Ein Gitternetz kann in einer Karte zur Orientierung wertvoll sein. Leider hat man nicht immer ein entsprechendes Shapefile zur Hand. Abhilfe schaffen sogenannte Graticule-Layer, mit denen sich ein solches Gitternetz einfach definieren läßt.

Betrachten wir einen solchen Layer anhand eines Beispiels:

 <code>
LAYER
NAME "gitternetz"
TYPE LINE
STATUS ON
GRID
END
CLASS
COLOR 0 0 0
LABEL
TYPE BITMAP
SIZE TINY
COLOR 0 0 0
END
END
PROJECTION
"init=epsg:4326"
END
END
</code> 

Zwei Dinge fallen sofort auf. Zuerst einmal sieht man keine =DATA= -Angabe. Brauchen wir an dieser Stelle auch gar nicht, da unser Gitter für jeden Kartenaufruf dynamisch generiert werden soll.

Außerdem findet man eine neue Sektion =GRID= . In dieser Sektion werden die Eigenschaften des Gitters gesetzt.

Der Typ eines Gitterlayers ist =LINE= . Die Gestaltung des Gitters wird wie gewohnt in einer Class vorgenommen, und das Gitter kann beschriftet werden. Die Labels für die Beschriftung erscheinen immer an allen vier Seiten einer Karte. Für TrueType-Fonts empfiehlt sich eine sehr kleine Schriftgröße, da diese Beschriftung sonst sehr schnell aufdringlich wirken kann.

Der =PROJECTION= -Block gibt die Projektion des Gitters an. Der Layer wird dann so behandelt, als würde es sich bei der Datenquelle um ein Shapefile handeln, das in eben dieser Projektion vorliegt. Ohne Projektionsblock erhalten Sie ein einfaches rechteckiges Gitter; mit Projektion ist das Gitter natürlich entsprechend verzerrt.

Beachten Sie, dass die Beschriftung des Gitters immer im Koordinatensystem der Quellprojektion erfolgt. Wenn Sie also beispielsweise den EPSG-Code 4326 als Projektion für Ihren Gitterlayer angeben, so wird dieses Gitter in Gradangaben beschriftet werden, selbst wenn Sie eine Karte mit Gauss-Krüger-Koordinaten erzeugen.

Innerhalb des =GRID= -Blocks können Sie die folgenden Angaben machen, die allesamt nur eine einzelne Zahl als Parameter erwarten:

*=MINSUBDIVIDE= und =MAXSUBDIVIDE= : Jede der Kurven (Linien), aus denen das Gitter besteht, wird als separate Linie behandelt und besteht somit aus einzelnen Punkten. Je mehr Punkte für eine Linie gezeichnet werden müssen, desto mehr Prozessorzeit kostet das offensichtlich. Mit diesen beiden Parametern können Sie festlegen, aus wievielen Punkte eine Linie minimal beziehungsweise maximal zusammengesetzt sein darf. Sind die beiden Werte gleich, bestehen die Linien immer aus genausovielen Punkten wie angegeben.
*=MININTERVAL= und =MAXINTERVAL= : Mit diesen beiden Parameter können Sie ein minimales bzw. ein maximales Intervall zwischen zwei Kurven des Gitters angeben. Die Angabe wird im Koordinatensystem des Gitters gemacht.
*=MINARCS= und =MAXARCS= : Setzt die minimale bzw. maximale Anzahl von Kurven pro Achse. Beachten Sie bitte, dass bei diesen beiden Parametern und den beiden vorhergehenden ''versucht'' wird, den Vorgaben nachzukommen. Sollten die von Ihnen notierten Werte nicht zum gewünschten Ergebnis führen, sollten Sie ein wenig experimentieren, um ein Gefühl dafür zu bekommen, wie sich der Code bei verschiedenen Werten verhält.

==Projektionen==
(11)
\index{Projektion}\index{Mapfile!Projektion}(12)

Zuerst die These: die Erde ist eine Kugel. Diese Kugel muß für eine Karte auf eine Ebene abgebildet werden. Das gilt für eine Papierkarte ebenso wie für einen Computerbildschirm. Wenn man jetzt bedenkt, dass es viele verschiedene Ideen gibt, Abbildungen von der Kugel auf die Ebene vorzunehmen, und wenn man dann noch einwirft, dass die Erde ja eigentlich gar keine richtige Kugel ist -- dann ist man in der Welt der Projektionen angekommen, die ebenso faszinierend wie enervierend sein kann.

\begin{figure}
\begin{center}
\mmfig{0.75}{projektion}{Ein und dieselbe Datenquelle in zwei verschiedenen Projektionen. Links EPSG:4326, rechts EPSG:31464.}
\end{center}
\end{figure}

Der Effekt, um den es geht, ist in Abbildung~\ref{projektion} zu sehen. Die rechte Darstellung der Datenquelle verwendet die Geo-Koordinaten der Bundeslandgrenzen (Ellipsoid WGS84). Die rechte Darstellung entspricht einer Projektion in die Ebene nach der Gauss-Krüger-Methode, hier im vierten Meridianstreifen.

Der MapServer verwendet für Projektionen eine eigene Bibliothek (''proj.4'' ) die von Haus aus bereits viele Projektionen kennt. Diese Bibliothek unterstützt aber auch EPSG-Codes~[[http:website:epsg]], die seit Einführung der OGC-Konformität die gängige Art und Weise darstellen, Projektionen im Mapfile zu notieren.

Projektionen interessieren an zwei Stellen: einmal bei der Frage, in welchen Projektionen die Daten vorliegen, und in welcher Projektion die fertige Karte dargestellt werden soll. MapServer ist in der Lage, die Projektion von Vektordaten 'on the fly' vorzunehmen. Dabei können die Daten verschiedener Layer durchaus verschiedener Projektion sein. Mit Unterstützung der Bibliothek GDAL ist MapServer auch in der Lage, Rasterdaten umzuprojizieren; die benötigte Rechenleistung dafür ist jedoch beträchtlich, da in einem Rasterbild jeder einzelne Punkt umprojiziert werden muß.

Mehr zur Bibliothek GDAL erfahren Sie in Anhang~\ref{anhang:formate}, in dem die vom MapServer unterstützten Formate vorgestellt werden.

===Notation===

Projektionen sind, wie bereits angemerkt, an zwei Stellen von Bedeutung: erstens wenn festgestellt werden soll, in welcher Projektion bestimmte Daten vorliegen, zweitens bei der Frage, in welcher Projektion die Karte ausgeliefert werden soll.

Dabei können die Projektionen, in denen die Daten vorliegen, auf Layer-Ebene zugewiesen werden. Jeder Layer kann also in einer eigenen Projektion vorliegen. MapServer ist in der Lage, Vektorlayer auf Anfrage umzuprojizieren. Unter Verwendung des Bibliothek GDAL funktioniert das auch für Rasterdaten. Das Umprojizieren von Rasterdaten ist jedoch derart rechenaufwendig, dass man es in den meisten Fällen vermeiden will.

Die Ausgabeprojektion muß verständlicherweise einheitlich sein, denn die fertige Karte kann schließlich nur in einer bestimmten Projektion vorliegen. Eine Ausnahme bildet ein OGC-konformer MapServer, der verschiedene Projektionen nach außen anbieten und über einen URL-Parameter aufgefordert werden kann, eine dieser Projektionen als Ergebnis zu liefern.

Die Notation von Projektionen geschieht über eine eigene Sektion mit dem Namen =PROJECTION= . In dieser Sektion können Projektionen entweder als eine Liste von Parametern für die Projektionsbibliothek proj.4 eingetragen werden, oder mit EPSG-Codes.

Das erste Beispiel zeigt die 'klassische' Notation anhand der Projektionsbibliothek:

 <code>
PROJECTION
"proj=utm"
"ellps=GRS80"
"zone=15"
"north"
"no_defs"
END
</code> 

Die Art der möglichen Parameter für die Projektionsbibliothek proj.4 entnehmen Sie bitte der Dokumentation dieser Software~[[http:website:libproj]].

Die zweite Möglichkeit erschließt sich durch EPSG-Codes:

 <code>
PROJECTION
"init=epsg:12345"
END
</code> 

12345 ersetzen Sie an dieser Stelle selbstverständlich durch den gewünschten EPSG-Code. Intern greift die Projektionsbibliothek an dieser Stelle übrigens auf eine Tabelle zu, die diese Codes dann auf die "`Original"'-Parameter abbildet. Achten Sie unbedingt darauf, =epsg= tatsächlich in Kleinbuchstaben zu notieren. Unter Windows ist das nicht relevant; entwickeln Sie jedoch unter einem anderen System, oder soll Ihre Anwendung portierbar sein, ist das wichtig.

Die Sektion =PROJECTION= kommt für die gesamte Karte nach dem Header im Mapfile zur Anwendung; für die Layer hat die Sektion natürlich innerhalb der =LAYER= -Sektion zu stehen, allerdings außerhalb etwaiger =CLASS= es, =LABEL= s und allem Anderen, das eine eigene Sektion einleitet.

\subsubsection*{Hinweis}(13)

Man möchte eigentlich meinen, dass die EPSG-Codes in Stein gemeißelt sind. Einmal vergeben, würde sich ein solcher Code nicht mehr ändern.

Leider ist diese Annahme ein Irrtum. Die Vergangenheit hat gezeigt, dass es passieren kann, dass Projektionen um mehrere Stellen in der Liste 'verrutschen' können. Zumindest einige deutsche und teilweise auch österreichische Projektionscodes sind in der Vergangenheit bei einem Versionssprung der Projektionsbibliothek nicht mehr vorhanden gewesen. Die interne Liste für den jeweiligen Release von ''proj.4'' wird scriptgesteuert aus der Access-Tabelle generiert, die man auf der Website der EPSG findet. Änderungen in der Tabelle schlagen also sofort auf die Projektionsbibliothek durch.

Bei unerwarteten Fehlermeldungen nach einem Upgrade der Projektionsbibliothek sollten Sie also prüfen, ob Ihre Projektionscodes noch korrekt sind und diese eventuell anpassen.

Dieses unvorhersehbare Verhalten der EPSG kann natürlich zu haarsträubenden Komplikationen bei kaskadierten WMS-Servern führen, wenn nur einer der Server aktualisiert wird.

===Orthographische Projektion===

\begin{figure}
\begin{center}
\mmfig{0.55}{ortho}{Eine orthographische Projektion stellt die Daten in einem Kreis dar, der einer Aufsicht auf einem Globus ähnlich sieht. Leider ist die Funktion in MapServer noch fehlerhaft.}
\end{center}
\end{figure}

Eine orthographische Projektion sieht aus wie ein Blick auf einen Globus. Falls die fertige Karte einen großen Teil der Welt abdeckt, sehen Sie die fertige Karte als Kreis.

Das kann schick aussehen, leider hat der Code für diese Projektion in MapServer noch den einen oder anderen Bug, die dann auftreten, sobald Features dargestellt werden sollen, die teilweise hinter dem Horizont verschwinden. Dann versucht MapServer immer noch Linien zu ziehen, die dann quer durch das ganze Bild gehen.

Zum Zeitpunkt der Drucklegung war die Darstellung leider immer noch fehlerhaft. Dennoch soll Ihnen ein Überblick über die Theorie nicht vorenthalten bleiben.

Als Zielprojektion im Kopf des Mapfiles definieren Sie eine orthographische Projektion wie folgt:

 <code>
PROJECTION
"proj=ortho"
"ellps=WGS84"
"lat_0=0.0"
"lon_0=0.0"
"x_0=0.0"
"y_0=0.0"
END
</code> 

Dabei sind =lat_0= und =lon_0= die Koordinaten des Punktes, der als Mittelpunkt in der Karte zu sehen sein soll, in Längen- und Breitenangabe. Das ist sozusagen der Punkt, an dem Sie direkt auf den Globus schauen. Die beiden verbleibenden Parameter sind eine Verschiebung, jeweils ein Modifikator auf den Rechts- und den Hochwert des Punktes.

Das Ergebnis sieht dann in etwa so aus, wie Sie es in Abbildung~\ref{ortho} sehen können. Wegen der fehlerhaften Implementation ist die Darstellung von Features, die sich über den Horizont erstrecken, allerdings noch mangelhaft.

Und falls Sie später das Kapitel über MapScript lesen und Anregung für eine Übung suchen sollten, wie wäre es damit: erstellen Sie eine MapScript-Seite, die eine Karte in ortographischer Projektion darstellt. Beim Mausklick in die Karte soll allerdings nicht hinein- oder herausgezoomt werden, sondern eben dieser angeklickte Punkt soll als neuer Bezugspunkt für die Projektion dienen. Der 'Globus' wird also anhand des Klicks 'gedreht'. Viel Spaß dabei =:)=

===Projektionen im realen Einsatz===

Der Autor hat schon von Leuten gehört, die meinten, Projektionen würden die Daten 'verfälschen'. Zu einem gewissen Grad ist das sicherlich richtig; im Grunde genommen handelt es sich aber nur um eine andere Art der Darstellung.

Kartographen sind übrigens nicht die einzigen Menschen, die sich mit Projektionen in die Ebene auseinandersetzen müssen. Eine ganze Industrie in Gestalt der Spiele- und Grafikkartenindustrie lebt mit und von dem Problem, (dreidimensionale) Objekte auf eine plane Fläche (den Computerbildschirm) abzubilden.

Falls Sie in Ihrer Anwendung MapServer Daten ''on the fly'' umprojizieren lassen möchten, sollten Sie sich im Vorhinein über Ihre Zielgruppe Gedanken machen. Menschen könnten es Ihnen durchaus übelnehmen, wenn die Karten im Webbrowser wie in Abbildung~\ref{projektion} links aussehen -- nämlich angeblich 'gequetscht'. Denken Sie immer daran, wass die Benutzer wohl als Darstellung aus ihrem Atlas daheim~[[diercke:2002]] gewohnt sein könnten.

==Schriften==
\index{Schriften}\index{Fonts}(14)

MapServer kennt zur Beschriftung von Features zwei Typen von Schriften: Bitmap- und TrueType-Schriften. Während erstere bereits im MapServer `"eingebaut"' sind, sind TrueType-Schriften separate Dateien, die Sie der Anwendung bereitstellen müssen. Hingegen benötigen Bitmap-Schriften keine zusätzliche Vorbereitung, um verwendet zu werden; Sie können direkt mit Abschnitt~15 fortfahren.

Ein weiteres Problem mit TrueType-Schriften können lizenzrechtlicher Natur sein. Ob Sie die Schriftdateien, die Sie für den Gebrauch mit beispielsweise Photoshop gekauft haben, einfach so zur Beschriftung und Veröffentlichung von Karten im Internet verwenden dürfen, müssen Sie individuell mit dem Hersteller der Schriften regeln.

Wie die Symbole für eine Karte werden auch die TrueType-Schriftarten in einer separaten Datei deklariert. Anders als die Symbole für ein Mapfile können die Schriften jedoch nicht alternativ direkt in das Mapfile eingetragen werden; sie müssen immer in einer separaten Datei stehen.

Der Verweis auf eine Schriftendatei erfolgt über das Schlüsselwort ''FONTPATH'' im Header des Mapfiles:

 <code>
...
FONTPATH "fonts/fonts.list"
...
</code> 

Diese Angabe kann sowohl ein absoluter Pfad im System sein, als auch relativ zum Mapfile.

Im Innern ist diese Liste sehr simpel aufgebaut:

 <code>
arial arial.ttf
times times.ttf
...
</code> 

In jeder Zeile steht zuerst ein Alias, gefolgt von mindestens einer Leerstelle (oder einem Tab) und der Name der .ttf-Datei. Das Alias ist ein Name, der im Folgenden im Mapfile verwendet wird, um auf die Schriftart Bezug zu nehmen.

Für Bitmap-Schriften müssen, wie gesagt, keine solche Vorbereitungen getroffen werden.

==Annotationen==
\index{Annotationen}
\index{Beschriftungen}
(15)

Beschriftungen von Layern sind für MapServer wiederum eigene Layer, mit einem eigenen Typ mit dem Namen =ANNOTATION= .

Die Art der Beschriftung (was wann wie beschriftet werden soll und auf welche Art) wird in den Klassen dieses Layers festgelegt. Dadurch erreicht man eine recht hohe Flexibilität, indem man Beschriftungen von Features unabhängig davon darstellen kann, ob das Feature selber zu sehen ist. Und wenn man beides unter den selben Umständen angezeigt haben möchte, verwendet man für beide Layer einfach die gleiche Klassendefinition.

Für eine Oberfläche zur Navigation in der Karte bedeutet das auf der anderen Seite zusätzliche, unerwünschte Komplexität, da die Beschriftungslayer nun unter Umständen durch den Benutzer als eigene Layer an- und abgewählt werden müssen.

Diesen Umstand kann man auf zwei Wegen umgehen. Eine Methode ist, dem Beschriftungslayer den gleichen Namen zu geben, wie dem Layer, der die Daten anzeigt. Dann werden beide Layer über diesen Namen angesprochen. Der zweite Weg ist, beide Layer zu einer =GROUP= zusammenzufassen, über deren Namen man auf beide Layer gleichzeitig zugreifen kann. Mehr über das Gruppieren von Layern erfahren Sie ab Seite~\pageref{text:mapfile:layer:group}

Man könnte auch alle Beschriftungen in einer =GROUP= zusammenfassen, sodass sie sich alle mit einem Mal an- und ausschalten lassen.

Es lassen sich im übrigen nur Vektorlayer beschriften.

Die Notation von Beschriftungslayern sieht wie folgt aus:

 <code>
LAYER
NAME "strassen_annotation"
GROUP "beschriftungen"
TYPE ANNOTATION
...
CLASSITEM "NUMMER"
LABELITEM "NUMMER"
CLASS
...
LABEL
TYPE BITMAP
SIZE NORMAL
COLOR 0 0 0
POSITION CR
PARTIALS TRUE
END
END
END
</code> 

Es werden also diverse Änderungen im Vergleich zu einem dartstellenden Layer vorgenommen. Der Typ des Layers ist =ANNOTATION= .

Das Schlüsselwort =LABELITEM= funktioniert so ähnlich wie =CLASSITEM= . Während letzteres jedoch angibt, anhand welcher Spalte in der ''.dbf'' -Datei die nachfolgenden Classes gefiltert werden sollen, definiert =LABELITEM= die Spalte, aus der der Inhalt für die Beschriftungen geholt werden soll. Auf diese Weise läßt sich also nach einem Kriterium filtern und nach einem anderen beschriften, was die Angelegenheit flexibler gestaltet.

===Die Label-Sektion===
\index{Label}\index{Mapfile!Label}

Die eigentliche Definition einer Beschriftung erfolgt dann in den einzelnen Classes. Im obigen Beispiel werden die im MapServer eingebauten Bitmap-Schriften verwendet. Zur genauen Notation von Bitmap- und TrueType-Schriften siehe auch die nächsten beiden Abschnitte.

Wie so häufig kommt erhöhte Flexibilität auch an dieser Stelle auf Kosten größeren Aufwands. Für jede zu beschriftende Klasse muß eine eigene Label-Sektion eingerichtet werden.

Die folgenden Parameter finden in allen Arten von Labeln Verwendung, unabhängig davon, ob es sich um Bitmap- oder TrueType-Beschriftungen handelt:

*=BACKGROUNDCOLOR <red> <green> <blue>= Mit dieser Option bekommt das Label eine Hintergrundfarbe verpaßt; man sieht dann ein Rechteck in dieser Farbe, in dem sich dann das Label befindet. Voreinstellung ist gar keine Farbe.
*=BACKGROUNDSHADOWCOLOR <red> <green> <blue>= Wirft einen Schatten in der angegebenen Farbe um das eben genannte Rechteck. Voreinstellung ist kein Schattenwurf.
*=BACKGROUNDSHADOWCOLORSIZE <x> <y>= Legt den Offset für den genannten Schatten in x- und y-Richtung fest. Voreinstellung in beide Richtungen ist 1.
*=BUFFER <integer>= Definiert einen Abstand, den andere Beschriftungen zu einem Label mindestens haben müssen, um gezeichnet werden zu können. Erhöht die Lesbarkeit bei vielen Beschriftungen, kann aber zu Problemen führen (siehe Abschnitt~16, ''Hinweise'' ).
*=COLOR <red> <green> <blue>= Die Farbe, in der die Schrift gemalt werden soll.
*=OUTLINECOLOR <red> <green> <blue>= Umrißarbe für die Schrift.
*=FORCE <TRUE|FALSE>= Erzwingt das Zeichnen einer Beschriftung. Dadurch werden Einträge wie =BUFFER= ignoriert. Diese Option ist als Vorgabe nicht aktiviert.
*=POSITION=
*=PARTIALS <TRUE|FALSE>= Unter Umständen liegen einzelne Features so ungünstig, dass seine Beschriftung nur teilweise sichtbar wäre. Mit =PARTIALS= wird festgelegt, ob diese teilweise Beschriftungen angezeigt werden sollen.
*=WRAP <zeichen>= Legt ein Zeichen fest, das als Zeilentrenner interpretiert werden soll. Das Ergebsnis sind mehrzeilige Beschriftungen.

Labels lassen sich außer zur Beschriftung auch bei TrueType-Symbolen verwenden; siehe auch Abschnitt~18

===Bitmap-Schriften===
\index{Bitmap-Schriften}
\index{Beschriftungen!Bitmap}\index{Annotationen!Bitmap}

Bitmap-Schriften skalieren schlecht und sehen, gelinde gesagt, nicht sonderlich gut aus. Sie benötigen jedoch keinen zusätzlichen Aufwand und sind in jeder MapServer-Installation automatisch vorhanden. Auch benötigen sie wesentlich weniger Rechenzeit.

Wenn Sie die Beschriftung nur um der Beschriftung willen einsetzen möchten und keine besonderen Anforderungen an ihr Aussehen stellen, sind Bitmap-Schriften das, was Sie haben möchten.

Ein =ANNOTATION= -Layer mit Bitmap-Schriften sieht beispielsweise folgendermaßen aus:

 <code>
LAYER
NAME "strassen"
STATUS ON
TYPE ANNOTATION
DATA "strassen"
LABELITEM "NUMMER"
CLASS
LABEL
TYPE BITMAP
SIZE SMALL
COLOR 0 0 0
OUTLINECOLOR 255 255 255
END
END
END
</code> 

Jedes Feature wird hier mit einer kleinen, weiß umrandeten, schwarzen Beschriftung versehen.

Die folgenden Optionen sind nur beim Einsatz von Bitmap-Schriften von Belang:

*=SIZE <TINY|SMALL|MEDIUM|LARGE|GIANT= Diese fünf verschiedenen Größen sind fix, und es gibt keine Zwischengrößen. Experimentieren Sie am besten mit allen herum, um ein Gefühl dafür zu kriegen, wie groß sie im Einsatz sind.

===TrueType-Schriften===
\index{TrueType-Schriften}
\index{Beschriftungen!TrueType}\index{Annotationen!TrueType}

TrueType-Schriften skalieren besser als die im MapServer eingebauten Schriftarten und sehen generell besser aus, benötigen jedoch einiges an zusätzlicher Vorbereitung, beispielsweise bei der Installation und weil das Anlegen einer Font-Datei für den MapServer nötig wird. Auch der Aufwand an Rechenzeit ist merklich größer.

Falls Sie jedoch Wert auf qualitativ hochwertige Schriften legen oder gar eine gewisse Stimmung erzeugen möchten -- indem Sie Frakturschriften in den Karten Ihrer mittelalterlichen Rollenspielwelt verwenden, um ein Beispiel zu nennen --, so kommen Sie um TrueType-Schriften nicht herum.

 <code>
LAYER
NAME "strassen"
STATUS ON
TYPE ANNOTATION
DATA "strassen"
LABELITEM "NUMMER"
CLASS
LABEL
TYPE TRUETYPE
FONT "Arial"
SIZE 12
COLOR 0 0 0
OUTLINECOLOR 255 255 255
END
END
END
</code> 

Der Typ des Labels muß natürlich =TRUETYPE= sein. Anstelle eines von fünf festen Strings treten Angaben in Pixeln. Und natürlich muß der Name der Schrift angegeben werden -- dafür wird ein Alias verwendet, der in der Font-Datei definiert worden sein muß (siehe auch Beginn dieser Sektion).

Die folgenden Optionen im Label-Objekt lassen sich nur dann verwenden, wenn TrueType-Schriften zum Einsatz kommen:

*=ANGLE <double>= Eine Winkelangabe in Grad, um die die Beschriftung gedreht werden soll. Kann nur in Linien-Layern benutzt werden. Wird anstatt eines Zahlenwertes =AUTO= verwendet, richtet sich der Text an der Linie aus.
*=ANTIALIAS <TRUE|FALSE>= Schaltet Kantenglättung für Schriften an oder aus.
*=FONT <name>= Name der Schriftart, wie er in der Font-Datei festgelegt worden ist.

=== Beschriftungen ohne Annotationslayer ===

....

=== Der Label-Cache ===

....

===Hinweise===
(16)

Automatische Beschriftungen von ebenso automatisch generierten Karten haben einige Tücken, derer man sich bewußt sein sollte, bevor man vom Ergebnis enttäuscht wird.

Angaben wie das zuvor genannte =BUFFER= beispielsweise bewirken, dass diverse Labels gar nicht erst gezeichnet werden. Das kann zum Beispiel zur Folge haben, dass die kleinen Orte um eine große Stadt durchaus beschriftet werden -- und dann aber kein Platz mehr für eine Beschriftung neben der Stadt ist und diese dann in der fertigen Karte ohne auskommen muß.

Zu allem Überfluss können sich die Labels nach dem nächsten Zoom oder gar nur nach einem Pan so verschoben haben, dass besagte Stadt plötzlich eben doch beschriftet ist. Der Benutzer kann sich dann fragen, welch merkwürdige Karte er da vor sich hat.

Es gibt mehrere Möglichkeiten, mit diesem Phänomen umzugehen. Man kann stundenlang mit Schriftgrößen und Zoomstufen herumexperimentieren -- aber der nächste Benutzer wird eben doch die Einstellung finden, an die man nicht gedacht hat.

Sicherlich sinnvoll ist es, mit =MINSIZE= und =MAXSIZE= Maßstäbe festzulegen, ab denen bestimmte Beschriftungen zulässig werden. Features, die unter allen Umständen beschriftet werden sollen, sollten mit =FORCE TRUE= dazu gezwungen werden.

Die korrekte Vorgehensweise bei diesen Phänomen dürfte von Fall zu Fall unterschiedlich sein; auf alle Fälle sollte man sich aber der Existenz des Problems bewußt und darauf vorbereitet sein, es eventuell in Angriff nehmen zu müssen, falls jemand darauf stößt.

==Symbole==
\index{Symbole}(17)

Symboldateien definieren Darstellungen, die von den normalen Formen abweichen, die also mehr sind als simple Striche für Polygonumrandungen oder Linienvektoren.

Notiert werden Symbole entweder direkt im Mapfile als einzelne Sektionen nach dem Header. Oder aber in einer eigenen Datei, genannt =SYMBOLSET= , die im Header deklariert wird -- siehe auch Seite~\pageref{text:mapfile:header}. Begonnen wird ein Symbol mit =SYMBOL= , abgeschlossen wird es mit =END= .

Farben werden für Symbole nicht in den Symbol-Sektionen definiert, sondern in den Classes, die die Symbole verwenden.

MapServer kennt die folgenden Arten von Symbolen, die in Symboldateien definiert werden können, und die in einer Symbol-Sektion über =TYPE= deklariert werden:

*=VECTOR= Ein oder mehrere Vektoren, die aneinandergefügt ein Symbol ergeben. Dadurch können Rechtecke, Dreiecke und andere geometrische Formen realisiert werden.
*=ELLIPSE= Ellipsen werden über zwei Radien definiert. Sind beide Werte gleich, entsteht ein Kreis. Ergänzt die geometrischen Formen, die mit =VECTOR= möglich sind.
*=PIXMAP= Linien können mit (möglichst kleinen) Bilddateien gezogen werden. Ebenso können Polygone mit solchen Bilder ausgefüllt werden. Das Format dieser Bilder muß vom MapServer unterstützt werden. Das schließt beispielsweise ''.gif'' -Bilder aus, wenn es sich um einen MapServer handelt, der ''.png'' -Bilder generiert.
*=TRUETYPE= Einzelne Symbole aus TrueType-Schriften können zur Annotation von Features in Karten benutzt werden. Es gibt einige TrueType-Zeichensätze, die speziell für die Verwendung in Karten erstellt worden sind.

Ferner können sogenannte Overlaysymbole für Linien definiert werden, bei denen ein Liniensymbol über ein anderes gelegt wird; mehr dazu weiter unten.

Die folgenden Parameter können für Symbole gesetzt sein, wenn es sich nicht um TrueType-Symbole handelt.

*=NAME <name>= Name des Symbols. Sollte immer gesetzt sein, falls man seine Symbole nicht über ihre Nummer innerhalb der Symboldatei referenzieren möchte -- was spätestens dann für Unheil sorgen wird, wenn man zusätzliche Symbole mitten in der Datei einfügt.
*=FILLED <TRUE|FALSE>= Das Symbol soll gefüllt sein.
*=PIXMAP <dateiname>= Eine Bilddatei, die als 'Pinsel' verwendet werden soll. Kommt nur für Symbole vom Typ =PIXMAP= zur Anwendung.
*=STYLE= Eine eigene Sektion innerhalb eines Symbols, die einen Stil für Linien-Symbole definiert. Es handelt sich um einen einzelnen Punkt (referenziert als =SYMBOL 0= ), der je nach Stil an- und wieder ausgeschaltet wird. Zur Verdeutlichung ein Beispiel: <code> STYLE 2 3 2 4 END </code> Mit diesem =STYLE= werden zwei Pixel einer Linie gezeichnet, dann drei Pixel Pause gemacht, dann werden wieder zwei Pixel gezeichnet, woraufhin wieder vier Pixel ausgelassen werden. Danach geht das ganze wieder von vorne los.
*=POINTS= Dies ist eine eigene Sektion innerhalb eines Symbols und beschreibt ein Symbol über Vektoren.
*=TRANSPARENT <index>= Der Index der Farbe in einer Farbpalette, die bei einem Pixmap-Symbol transparent geschaltet werden soll.

\subsubsection*{Points}

Vektor-Symbole werden über eine eigene Sektion innerhalb eines Symbols definiert, die mit =POINTS= beginnt, mit =END= abgeschlossen wird und Paare von Zahlen enthält; Punkte eines Vektors eben.

Ein Beispiel für ein Vektor-Symbol:

 <code>
SYMBOL
TYPE VECTOR
NAME "dreieck"
POINTS
1 1
3 3
3 1
1 1
END
END
</code> 

Dieses Symbol beschreibt ein Dreieck. Beachten Sie, dass Sie für einen geschlossenen Kantenzug immer den ersten Punkt noch einmal als letzten Punkt einfügen müssen.

Punkte, bei denen beide Koordinaten negativ sind, werden als Trenner betrachtet. Dadurch können Sie beispielsweise Kreuze und ähnliches realisieren, also Symbole, die aus mehreren Segmenten bestehen.

===TrueType-Symbole===
\index{TrueType!Symbole}\index{Symbole!TrueType}(18)

TrueType-Schriften als Symbole funktionieren, indem man einzelne Zeichen aus der Schriftart herausgreift, und damit dann einzelne Punkte annotiert, oder das Symbol an einer Linie immer wieder wiederholt.

Beachten Sie, dass Unterstützung für TrueType-Schriften in den MapServer kompiliert sein muss, um diese Art von Beschriftung benutzen zu können.

Die folgenden Parameter in einer Symbol-Sektion kommen nur zum Tragen, wenn es sich um ein TrueType-Symbol handelt:

*=ANTIALIAS <FALSE|TRUE>= Gibt an, ob auf dem Symbol ein Antialiasing stattfinden soll.
*=CHARACTER <index>= Die Nummer des Zeichens innerhalb der TrueType-Datei, das als Symbol benutzt werden soll.
*=FONT <name>= Alias der TrueType-Schriftart, die für das Symbol benutzt werden soll. Dieser Alias muß im =FONTSET= definiert sein.
*=GAP= Der Abstand zwischen zwei TrueType-Symbolen in [pix]. Kommt nur für Linien zur Anwendung. ''(Hinweis: GAP 30 erzwingt einen Abstand von 30 Pixeln, dreht aber alle TTF-Symbole auf 0 Grad, GAP -30 erzwingt ebenfalls einen Abstand von 30 Pixeln, richtet aber die Symbole an der Linie aus!)''

Als Beispiel für ein TrueType-Symbol soll an dieser Stelle die Schriftart WebDings herhalten:

 <code>
SYMBOL
NAME "haus"
TYPE TRUETYPE
FONT "webdings"
ANTIALIAS TRUE
CHARACTER "G"
END
</code> 

Dieses Beispiel greift aus der Schriftart WingDings das Zeichen heraus, das ein kleines Häuschen darstellt. Sie könnten damit beispielsweise Ihre Ferienhäuser in der Karte markieren.

Die Notation =\&\#71;= kennen Sie vielleicht aus HTML-Seiten, wo einzelne Zeichen auf diese Weise notiert werden können. 71 ist die Position des Zeichens in der TrueType-Datei; falls Sie die Position nicht kennen, müssen Sie raten oder ein Programm zurate ziehen, dass Ihnen die einzelnen Zeichen darstellt und deren Position angibt.

===Pixmap-Symbole===

Pixmaps lassen sich entweder an Linien entlangziehen oder zum Füllen von Fläche verwenden. Natürlich kann man mit ihnen auch einzelne Punkte annotieren. Damit können Sie beispielsweise Ihr Firmenlogo an verschiedenen Filialen einblenden:

 <code>
SYMBOL
NAME "logo"
TYPE PIXMAP
IMAGE "firmenlogo.png"
TRANSPARENT 0
END
</code> 

===Overlay-Symbole===
\index{Symbole!Overlay}\index{Overlaysymbole}

Overlaysymbole werden separat in den Klassen eines Layers definiert. Dabei werden ganz einfach die als Overlay deklarierten Symbole über die 'normalen' Symbole gelegt. Anwendung findet so etwas zum Beispiel bei Autobahnen:

 <code>
CLASS
...
SYMBOL 0
SIZE 4
COLOR 0 0 0
OVERLAYSYMBOL 0
OVERLAYSIZE 2
OVERLAYCOLOR 255 0 0
END
</code> 

Das Resultat ist eine vier Pixel breite schwarze Linie, auf der sich eine zwei Pixel breite rote befindet. Anders formuliert: eine zwei Pixel breite rote Linie mit einem schwarzen Rand.

Auf diese Weise kann man beispielsweise auch gestrichelte Linien auf breite Linien legen und damit Mittelstreifen symbolisieren etc.

Es gibt die folgenden Optionen für Overlaysymbole:

*=OVERLAYSYMBOL= : Definiert wie =SYMBOL= , welches Symbol verwendet werden soll.
*=OVERLAYBACKGROUNDCOLOR= : Hintergrundfarbe des Overlaysymbols
*=OVERLAYCOLOR= : Farbe des Symbols
*=OVERLAYMINSIZE= : Minimaler Maßstab, bei dem das Overlaysymbol angezeigt werden soll.
*=OVERLAYMAXSIZE= : Maximaler Maßstab, bei dem das Overlaysymbol angezeigt werden soll.
*=OVERLAYOUTLINECOLOR= : Umrandungsfarbe für das Overlaysymbol
*=OVERLAYSIZE= : Größe des Overlaysymbols.

Diese Angaben sind also allesamt äquivalent zu den Angaben in normalen Symbolen ohne den Zusatz ''OVERLAY'' .

Mit der Ankunft des =STYLE= -Objekts und der entsprechenden Möglichkeit, mehr als zwei Symbole übereinander zu legen, werden die Overlayparameter allerdings wohl ihre Daseinsberechtigung verlieren. Mehr dazu siehe Abschnitt~6.

===Beispiele===

Erfahrungsgemäß bereiten Symbole gerade dem Einsteiger Schwierigkeiten. Daher sehen wir uns einige Beispiele an, die wir nach und nach zu komplexeren Symbolen ausbauen.

Für das einfachste aller Symbole, einen Punkt, wird wohl kein Screenshot benötigt:

 <code>
SYMBOL
NAME "punkt"
TYPE ELLIPSE
POINTS
1 1
END
FILLED TRUE
END
</code> 

Dieses Symbol können Sie nun in einem Layer verwenden, und dann dementsprechend die Dicke der Linie mit =SIZE= festlegen.

''Hinweis'' : Beachten Sie bitte, dass es keinen Unterschied macht, ob Sie =1 1= oder =2 2= in diesem Beispiel schreiben. Es handelt sich hier um Vektoren, dabei spielt der Skalar vor den eigentlichen Koordinaten keine Rolle. =2 2= ist also das gleiche wie zweimal =1 1= , und dieses 'zweimal' wird verworfen. Wichtig ist das Verhältnis der Zahlen zueinander. Wenn Sie also eine Ellipse haben wollen, die doppelt so breit wie hoch ist, schreiben Sie =2 1= . Sie könnten auch =6 3= schreiben, aber dadurch würde die Ellipse in der Karte nicht größer. Die Darstellungsgröße in der Karte wird über den Parameter =SIZE= in der entsprechenden Class geregelt.

Das wichtigste Gestaltungselement bei Linien ist die Möglichkeit, Abstände auf der Linie zu bestimmen. Damit lassen sich zum Beispiel gepunktete (''dotted'' ) oder gestrichelte (''dashed'' ) Linien realisieren. Ein Beispiel für ein Punkt-Symbol für eine Linie gestrichelte und gepunktete Linie:

 <code>
SYMBOL
NAME "funky"
TYPE ELLIPSE
POINTS
1 1
END
FILLED TRUE
STYLE 2 2 1 1
END
</code> 

Dieses Symbol entspricht dem letzten, mit dem Unterschied, dass hier ein =STYLE= verwendet wird. Die Angabe bedeutet, dass die ersten zwei Pixel des Linienzuges gezeichnet werden sollen, die nächsten beiden dann wieder nicht; danach wird ein Pixel gesetzt, der folgende dann wieder nicht. Es wird also immer die bezeichnete Anzahl von Pixeln gesetzt und dann wieder nicht gesetzt. Danach fängt das ganze wieder von vorne an. Beachten Sie bitte, dass die hier benutzte =STYLE= -Eigenschaft nichts mit dem Style-Objekt zu tun hat, wie es weiter vorne beschrieben worden ist.

Auf Beispiele für Overlaysymbole soll hier nicht eingegangen werden, da diese Methode veraltet ist. Stattdessen sollten Style-Objekte in den Classes benutzt werden.

\begin{figure}
\begin{center}
\mmfig{0.65}{symbols-star}{Städte, markiert mit einem sternförmigen Vektorsymbol.}
\end{center}
\end{figure}

Falls Sie mal ein komplexeres Symbol sehen wollen, schauen Sie sich die Sternchen in Abbildung~\ref{symbols-star} an. Die Sterne kommen folgendermaßen zustande:

 <code>
SYMBOL
NAME "stern"
TYPE VECTOR
FILLED TRUE
POINTS
0 .375
.35 .375
.5 0
.65 .375
1 .375
.75 .625
.875 1
.5 .75
.125 1
.25 .625
END
END
</code> 

Es handelt sich also um ein Vektorsymbol, das aus zehn Punkten besteht. Sie können sich beim Entwurf eigener Symbole das ganze auf Karo- oder Millimeterpapier aufmalen und dann die Koordinaten ablesen. Der Ursprung für Ihr Koordinatensystem muß in der linken oberen Ecke liegen. Beachten Sie, dass der höchste Wert in den Koordinaten der Punkte =1= ist. Sie könnten die auch alle Werte beispielsweise mit zwei multiplizieren, und es würde keinen Unterschied machen. Das ist der Effekt der Vektorrechnung, der weiter oben erläutert ist.

\subsubsection*{Markierungen für Gefälle}

Insbesondere während Schulungen wird der Autor gerne gefragt, wie es sich mit der Gestaltung von Höhenlinien verhielte; dabei möchte man beispielsweise in der abfallenden Richtung einer Höhenlinie in regelmäßigen Abständen einen kleinen, parallel zur Linie verlaufenden Strich anbringen, um die Richtung des Gefälles anzuzeigen.

Dazu muß leider gesagt werden, dass diese Art der Gestaltung insbesondere bei Shapefiles ''nicht'' möglich ist, da Shapefiles keine Topologie oder eine Richtungsinformation speichern. Zwar werden Sie GIS-Programme sehen, bei denen sich eine solche Gestaltung vornehmen läßt. Allerdings speichert die betreffende Software dann eine entsprechende Information über die Laufrichtung der Shapes separat ab. Diese Möglichkeit ist MapServer wegen seiner rein darstellerischen Fähigkeiten verschlossen.

==Maßstäbe==
(19)
\index{Maßstab}\index{Scalebar}\index{Mapfile!Maßstab}\index{Mapfile!Scalebar}

Maßstäbe setzen die Größen auf der Karte in eine Relation zur Realität. Dieser Zusammenhang wird einem am Computerbildschirm jedoch zum Verhängnis.

Man sollte nicht auf die Idee kommen, einen Pixelmaßstab auf dem Bildschirm auszumessen, und etwa zu sagen: "`Ah, 10 Pixel sind 100 Meter, und 10 Pixel sind 0.5 Zentimeter, also sind 0.5 Zentimeter 100 Meter."' Ein Maßstab auf dem Bildschirm steht ausschließlich in Relation zur angezeigten Karte, nicht zur realen Welt, da sich Pixel nicht in Zentimeter umrechnen lassen, sondern stets von der Größe des Bildschirms und der verwendeten Auflösung abhängig sind.

Wenn ein Maßstab für 10 Pixel in der Karte 100 Meter in der Realität angibt, dann sind diese zehn Pixel bei 1280x1024 Pixeln Auflösung auf einem 19 Zoll Bildschirm wesentlich kleiner als bei einer Auflösung von 800x600 Pixeln auf einem 14 Zoll Bildschirm.

MapServer geht bei Maßstabsangaben (=SCALE= ) immer von <math>\frac{1}{72}</math> inch pro Pixel aus. Dieser Wert kann allerdings bestenfalls als vage Annäherung betrachtet werden. Bei =SCALE= handelt es sich immer um den Kehrwert eines Maßstabes. Wenn Sie den Maßstab also beispielsweise als 1:20000 kennen, ist =SCALE= gleich 20000.

Bei den Beschriftungen für Maßstäbe im MapServer beachten Sie bitte, dass MapServer bisher noch keinen Gebrauch von TrueType-Schriften an dieser Stelle macht.

Die Sektion für Maßstäbe im Mapfile wird mit =SCALEBAR= eingeleitet. Sie darf nicht innerhalb einer anderen Sektion stehen und muss nach dem Header stehen. Die folgenden Parameter sind für diese Sektion bekannt:

*=BACKGROUNDCOLOR <red> <green> <blue>= Die Hintergrundfarbe für den Scalebar, ''nicht'' für das komplette Bild, das den Scalebar ausmacht.
*=TRANSPARENT <ON|OFF>= Schaltet Transparenz für den Hintergrund des Scalebars ein oder aus. Voreingestellt ist der Hintergrund nicht transparent.
*=IMAGECOLOR <red> <green> <blue>= Die Hintergrundfarbe für das Bild, in dem sich der Scalebar befindet.
*=COLOR <red> <green> <blue>= Die Farbe, in der der Scalebar gemalt werden soll.
*=INTERLACE <TRUE|FALSE>= legt fest, ob der fertige Maßstab interlaced sein soll.
*=SIZE <x> <y>= Breite des Scalebars in Pixeln. Das ist nicht die Größe des fertigen Bildes, sondern nur des Maßstabs im Bild. Auch Beschriftungen werden hier noch nicht einberechnet.
*=INTERVALS= Anzahl der Intervalle auf dem Maßstab. Voreinstellung ist 4.
*=UNITS <feet|inches|kilometers|meters|miles>= Die Einheit, in der der Maßstab beschriftet sein soll. Voreinstellung ist Meilen. Gradangaben sind übrigens keine sinnvollen Einheiten für einen Maßstab. Voreinstellung ist =miles= .
*=OUTLINECOLOR <red> <green> <blue>= Umrissfarbe für die einzelnen Intervalle des Maßstabs. Soll keine Umrißfarbe verwendet werden, reicht als Wert auch =-1= .
*=STYLE <0|1>= Es gibt zwei verschiedene Styles. Style =1= ist im wesentlichen ein horizontaler, beschrifteter Strich, während Stil =0= in weiße und schwarze Sektionen unterteilt ist.
*=STATUS <ON|OFF|EMBED>= Schaltet den Maßstab an oder aus. Mit =EMBED= wird der Maßstab angeschaltet und in die fertige Karte eingebettet.
*=POSITION <ul|uc|ur|ll|lc|lr>= Bei einem in die Karte eingebetteten Maßstab wird dieser an der angegebenen Position dargestellt. In der Tabelle in der PHP MapScript-Referenz, die auf Seite~\pageref{tab:ref:mapscript:const} beginnt, finden Sie eine Erklärung der möglichen Werte.
*=POSTLABELCACHE <TRUE|FALSE>= Wird nur für Maßstäbe verwendet, die in die Karte eingebettet sind. Der Maßstab wird dann erst in die Karte eingefügt, nachdem alle Labels in der Karte gezeichnet worden sind. Voreinstellung ist =FALSE= .
*=LABEL= An dieser Stelle wird ein separates =LABEL= -Objekt eingefügt, das für die Beschriftung des Maßstabs zuständig ist. Bisher können in Maßstäben keine TrueType-Schriften verwendet werden.

==Legenden==
\index{Legende}\index{Mapfile!Legende}

Legenden erklären die in der Karte verwendeten Symbole und Zeichen. Ohne eine Legende ist eine Karte prinzipiell ohne Inhalt, da man ohne sie den Linien, Farben usw. keine Bedeutung zuordnen kann.

MapServer ist in der Lage, konfigurierbare Legenden automatisch zu generieren. Diese Legenden können dann auf die bekannte Weise über Template-Tags in das Layout der Applikation eingebunden werden.

Neben den klassischen Bitmap-Legenden (die gesamte Legende ist ein einziges Bild, das in eine HTML-Seite eingebunden wird), gibt es seit der Version~{3.6} auch HTML-Legenden, die über Templates kleine HTML-Abschnitte erzeugen.

===Die klassische MapServer-Legende===

Diese Art von Legende ist ein fertiges Bild, das vom MapServer generiert wird. Auf die Gestaltung dieser Legende hat man nicht so viel Einfluss wie bei der HTML-Legende (siehe weiter unten).

Die Sektion für Legenden im Mapfile wird mit =LEGEND= eingeleitet. Sie darf nicht innerhalb einer anderen Sektion vorkommen und muß nach dem Header stehen. Die folgenden Parameter sind für diese Sektion bekannt:

\begin{figure}
\begin{center}
\mmfig{0.35}{legende}{Die drei Vektorlayertypen in einer klassischen MapServer-Legende: Punkte, Linien und Polygone}
\end{center}
\end{figure}

*=IMAGECOLOR <red> <green> <blue>= Hintergrundfarbe für die fertige Legende
*=TRANSPARENT <ON|OFF>= Schaltet Transparenz für den Hintergrund der Legende ein oder aus. Voreingestellt ist der Hintergrund nicht transparent.
*=OUTLINECOLOR <red> <green> <blue>= Umrissfarbe für die Kästchen, die die Symbole in der Legende umranden.
*=KEYSIZE <x> <y>= Breite und Höhe der Symbole in der Legende in Pixeln. Vorgabe ist 20x10.
*=KEYSPACING <x> <y>= Horizontaler und vertikaler Abstand der Symbole bzw. der Beschriftungen zueinander. Vorgabe ist 5 und 5.
*=STATUS <ON|OFF|EMBED>= Schaltet die Legende an oder aus. Mit =EMBED= wird die Legende angeschaltet und in die fertige Karte eingebettet.
*=POSITION <ul|uc|ur|ll|lc|lr>= Bei einer in die Karte eingebetteten Legende wird diese an der angegebenen Position dargestellt. In der Tabelle in der PHP MapScript-Referenz, die auf Seite~\pageref{tab:ref:mapscript:const} beginnt, finden Sie eine Erklärung der möglichen Werte.
*=INTERLACE <TRUE|FALSE>= Ob das Bild interlaced sein soll.
*=POSTLABELCACHE <TRUE|FALSE>= Wird nur für Legenden verwendet, die in die Karte eingebettet sind. Die Legende wird dann erst in die Karte eingefügt, nachdem alle Labels in der Karte gezeichnet worden sind. Voreinstellung ist =FALSE= .
*=LABEL= An dieser Stelle wird ein separates =LABEL= -Objekt eingefügt, das für die Beschriftung des Maßstabs zuständig ist. Bisher können in Maßstäben keine TrueType-Schriften verwendet werden.
*=TEMPLATE= Definiert ein Template, das für HTML-Legenden verwendet werden soll. Siehe den folgenden Abschnitt über HTML-Legenden.

In Abbildung \ref{legende} kann man sehen, wie Legenden für verschiedene Arten von Vektorlayern aussehen. Polygone werden durch ein Rechteck dargestellt, das gegebenenfalls eine Füllfarbe hat. MapServer bedient sich an dieser Stelle bei den Angaben im Mapfile. Punktlayer werden durch einen (wenig überraschend) Punkt dargestellt, während Linienlayer eine kleine gezackte Linie bekommen.

===HTML-Legenden===
\index{HTML-Legenden}

Als Alternative zu den normalen .gif- beziehungsweise .png-Bildern, die als Legenden generiert werden, gibt es für die CGI-Version des MapServers noch die Möglichkeit, eigene Legenden über HTML-Templates zu gestalten. Die fertige Legende wird dabei weiterhin an der Stelle im Haupt-Template eingefügt, an der das Schlüsselwort =[legend]= steht.

Interessant wird eine HTML-Legende dann, wenn man in die kleinen Bruchstücke von HTML auch Teile des Formulars zur Navigation in der Karte einfügt -- später mehr dazu.

Im LEGEND-Block des Mapfiles kann ein TEMPLATE definiert, etwa folgendermaßen:

 <code>
LEGEND
...
TEMPLATE "legend.html"
END
</code> 

\subsubsection*{Aufbau des Templates}

Innerhalb eines Templates können drei verschiedene Blöcke definiert werden: für Groups, Layers und Classes. Diese Begriffe folgen den Bedeutungen im Mapfile. Es kann also HTML-Code für Gruppen von Layern generiert werden, für die Layer in diesen Gruppen und dann für jede einzelne Class in diesen Layern wiederum eigener Code. Dieser Aufbau eignet sich besonders für den Aufbau in HTML-Tabellen.

Alle Inhalte der Templatedatei, die sich außerhalb der möglichen Blöcke befinden werden schlicht ignoriert und eignen sich somit dafür, Kommentare einzufügen, die später in der fertigen HTML-Seite nicht erscheinen sollen. Für Kommentare innerhalb der Blöcke müssen selbstverständlich HTML-konforme Kommentare benutzt werden, die mit == abgeschlossen werden.

Für gewöhnlich werden mit Groups- und Layerblöcken Kopfzeilen für HTML-Bereiche definiert, in denen dann die einzelnen Classes der Reihe nach aufgelistet werden.

\subsubsection*{Groups}

Mit der Verwendung eines solchen Blocks legt man die Erzeugung von Legenden fest, in denen Layer gruppiert dargestellt werden, und zwar anhand ihrer Gruppierung im Mapfile. Wird eine Groups-Sektion verwendet, werden alle Gruppierungen als solche in der Legende dargestellt. Möchte man keine Gruppierung von Layern in der Legende, verwendet man diesen Block einfach nicht.

Wird dieser Block definiert, erscheinen Layer nicht in der Legende, die zu keiner Gruppe gehören, und ebensowenig sind deren Classes zu sehen.

Mit =[leg_group_html]= wird ein solcher Block eingeleitet, und mit einem entsprechenden =[/leg_group_html]= wieder abgeschlossen.

Die folgenden Tags können in einem Group-Block erscheinen:

*=[leg_group_name]= : Gibt den Namen der Gruppe aus.
*=[leg_icon <width=X> <height=Y>]= : Steht für das erzeugte Icon. Der erzeugte Text ist der URL zu diesem Icon. Im Kontext einer Group gibt dieser Tag das Icon für den ersten Layer in der Group zurück. Die beiden Parameter =width= und =height= sind optional und verändern die Breite und die Höhe des fertigen Icons.
*=[metadata name=<feld>]= : Ist der MapServer über entsprechende Einträge im Mapfile OGC-konform ausgelegt, können an dieser Stelle entsprechende Metadaten ausgegeben werden. Mehr zu OGC-konformen Mapservern gibt es in Kapitel~\ref{text:ogc} zu erfahren. Auch andere Metadaten aus der Web-Sektion, wie Sie in Abschnitt~21 beschrieben sind, lassen sich hier einfügen.

\subsubsection*{Layers}

Analog zu Groups wird mit =[leg_layer_html]= ein Block für einen Layer in der HTML-Legende eingeleitet und mit =[/leg_layer_html]= wieder abgeschlossen. Im startenden Tag können allerdings noch einige zusätzliche Parameter übergeben werden:

*=order_metadata=<schlüssel>= In Abschnitt~21 haben Sie erfahren, dass Sie in Layern beliebige Metadaten in einem eigenen Block speichern können. Anhand solcher Einträge können Sie nun die Reihenfolge der Layer in der HTML-Legende kontrollieren. Anschaulich: <code> LAYER ... METADATA legendenposition 2 END ... END </code> Haben Sie ein jedem Layer eine solche Klassifizierung, können Sie in der HTML-Legende die Sortierung kontrollieren mit: <code> [leg_layer_html order_metadata=legendenposition] ... [\leg_layer_html] </code> 
*=opt_flag=<wert>= Dieser Wert kontrolliert die Verhaltensweise dieses Layerblocks. Es handelt sich um eine Bitmaske, d.h. für eine Kombination der folgenden Optionen addieren Sie die entsprechenden Werte aufeinander auf. Sie werden immer eine eindeutige Zahl erhalten. Die Werte sind:
*
*=1= Zeigt den Layer in der Legende an, auch wenn sich der gezeigte Ausschnitt außerhalb des Layers befindet. Dieses Verhalten ist nicht voreingestellt.
*
*=2= Zeigt den Layer in der Legende an, auch wenn sein =STATUS= auf =OFF= gesetzt ist. Dieses Verhalten ist nicht voreingestellt.
*
*=4= Zeigt den Layer in der Legende an, auch wenn sein =TYPE= auf =QUERY= gesetzt ist und daher nur befragt werden kann, aber nicht in der Karte erscheint. Dieses Verhalten ist nicht voreingestellt.
*
*=8= Zeigt den Layer in der Legende an, auch wenn sein =TYPE= auf =ANNOTATION= gesetzt ist und daher nur Beschriftungen darstellt. Dieses Verhalten ist nicht voreingestellt. Möchten Sie beispielsweise die ersten beiden Optionen zulassen, setzen Sie =opt_flag= auf <math>1+2=3</math>. Selbstverständlich können in einem Layer-Block in der Legende eigene Tags verwendet werden:
*
*=[leg_layer_name]= Fügt den Namen des Layers an dieser Stelle ein.
*
*=[leg_icon width=<breite> height=<höhe>]= Fügt den URL eines automatisch generierten Legenden-Icons ein, wie man es auch aus der klassischen MapServer-Legende kennt. Die Breiten- und Höhenangaben erfolgen in Pixeln und sind optional. Wenn ein Layer mehrere Classes aufweist, wird ein Icon für die erste Class im Layer generiert.
*
*=[metadata name=<feld>]= Fügt beliebige Metadaten aus der entsprechenden Sektion des Layers ein -- siehe auch weiter oben.

\subsubsection*{Classes}

Und natürlich kommen auch die Classes in HTML-Legenden zu ihrem Recht. Sie werden mit =[leg_class_html]= eingeleitet und am Ende mit =[/leg_class_html]= wieder abgeschlossen.

Ebenso wie die Blöcke für Layer kennen auch die Blöcke für Classes den Parameter =opt_flag= . Wenn er verwendet wird, wird er auch mit den gleichen Parametern gefüttert wie sein Pendant im Layer-Block.

Bitten beachten Sie, das Classes ohne einen =NAME= nicht in HTML-Legenden auftauchen werden.

Sie können die folgenden Tags innerhalb eines Class-Blockes in HTML-Legenden verwenden:

*=[leg_class_name]= Der Name der Klasse. Jede Klasse, die überhaupt in der Legende auftauchen soll, benötigt einen Namen.
*=leg_icon width=<breite> height=<höhe>= Das Legenden-Icon für die Class, wie im Layer beschrieben.
*=[metadata name=<feld>]= Fügt beliebige Metadaten aus der entsprechenden Sektion der Class ein; siehe auch weiter oben.

\subsection*{Konditionale in HTML-Legenden}\index{HTML-Legenden!Konditionale}

Konditionale sind Wenn-Dann-Anweisungen. Aus einer Programmiersprache wie C kennt man das unter der folgenden Notation:

 <code>
if (<bedingung> {
... hier passiert etwas ...
}
else {
... hier passiert etwas anderes ...
}
</code> 

Solche Konditionale lassen sich auch in HTML-Legenden nutzen, etwa um Dinge nur unter bestimmten Bedingungen einzublenden. Es gibt eine gemeinsame Notation, aber für jeden möglichen Block (Group, Layer und Class) eigene Eigenschaften, die abgefragt werden können.

Um es ein wenig genauer zu nehmen: es handelt sich weniger um eine Wenn-Dann-Anweisung, als vielmehr um ein reines Wenn. Ein ''else'' ist nicht implementiert.

Notiert werden Konditionale folgendermaßen:

 <code>
[if name=<feld> oper=<operator> value=<wert>] ... [/if]
</code> 

Das heißt soviel wie: Vergleiche =feld= dahingehend, ob es in der Beziehung =oper= zum Wert =wert= steht. Wenn das der Fall ist, füge den Block bis zum =[/if]= ein.

Da das reichlich abstrakt ist, hier ein Beispiel:

 <code>
[leg_layer_html]
[if name=layer_type oper=eq value=2]
[leg_layer_name]
[/if]
[/leg_layer_html]
</code> 

In diesem Layer-Block wird der Name des Layers immer dann ausgegeben, wenn sein Typ gleich 2 ist. Der Typ 2 ist nur im Kontext von Layern definiert: Sie erfahren weiter unten, welche Werte wofür stehen.

Das =eq= steht für ''equal'' und bedeutet 'gleich'. Daneben gibt es noch =neq= (ist nicht gleich), =isset= (hat überhaupt einen Wert) und =isnull= (ist leer). Die Voreinstellung ist =eq= . Wenn man diesen Operator verwenden möchte, kann man den Teil mit =oper== auch weglassen.

\subsubsection*{Groups}

Die folgenden Konditionale können als =name= in Group-Blöcken in HTML-Legenden benutzt werden:

*=group_status= Der Status einer Group ist gleich dem =STATUS= des ersten Layers in der selben. Als Werte kommen in Frage: =0= für =OFF= , =1= für =ON= und =2= für =DEFAULT= .
*=<metadata>= Jeder Metadaten-Eintrag in der Web-Sektion läßt sich als Wert für ein Konditional benutzen.

\subsubsection*{Layers}

Die folgenden Konditionale können als =name= in Layer-Blöcken in HTML-Legenden benutzt werden:

*=layer_name= Der Name des Layers.
*=layer_group= Der Name der Group, in dem sich der Layer befindet.
*=layer_status= Der Status des Layers. Als Werte kommen in Frage: =0= für =OFF= , =1= für =ON= und =2= für =DEFAULT= .
*=layer_type= Der Typ des Layers. Infrage kommen: =0= für =POINT= . =1= für =LINE= , =2= für =POLYGON= , =3= für =RASTER= . =4= für =ANNOTATION= und =5= für =QUERY= .
*=<metadata>= Jeder Metadaten-Eintrag aus der Layer- wie aus der Web.Sektion läßt sich als Wert für ein Konditional benutzen.

\subsubsection*{Classes}

Schließlich bleiben noch die Konditionale, die als =name= in Class-Blöcken in HTML-Legenden benutzt werden können. Um genau zu sein, sind die Werte hier vollständig mit denen im Layer-Block identisch, sodass sich eine Aufzählung erübrigt.

\subsection*{Hinweise}

Für HTML-Legenden benötigen Sie mindestens die Version 3.5.1 des Mapervers.

Der 'traditionelle' =[legend]= -Block liefert den URL eines Bildes zurück, wohingegen HTML-Legenden (wenig überraschend) Blöcke von HTML zurückliefern.

Wenn der HTML-Legendenmodus über die aufrufende URL für den MapServer angegeben wird, aber kein Template im Mapfile für die Legende definiert ist, wird weiterhin ein Bild erzeugt.

\subsection*{Beispiel}

Ein Beispiel soll erhellen, wie man die Macht von HTML-Legenden ausschöpfen kann. Betrachten Sie die folgenden Zeilen, die ein Ausschnitt aus einem Legenden-Template sind:

 <code>
[leg_layer_html opt_flag=3]
<tr>
<td>
<input type="checkbox" name="layer"
value="[leg_layer_name]" [[leg_layer_name]_check]>
</td>
<td><img src="[leg_icon width=18 height=12]" align="center"></td>
<td>[leg_layer_name]</td>
</tr>
[/leg_layer_html]
</code> 

Das Ergebnis ist in Abbildung~\ref{mapfile-legende-html} zu sehen.

Der Block definiert, wie Legenden für die im Mapfile vorhandenen Layer in der Legende auftauchen sollen. Der Wert 3 für =opt_flag= sagt, dass ein Layer in der Legende stehen soll, auch wenn sich alle Daten des Layers außerhalb des dargestellten Ausschnitts befinden, und dass er in der Legende stehen soll, auch wenn sein =STATUS= auf =OFF= gesetzt ist.

\begin{figure}
\begin{center}
\mmfig{0.3}{mapfile-legende-html}{HTML-Legenden im Einsatz}
\end{center}
\end{figure}

Es folgt eine Zeile in einer HTML-Tabelle, die aus drei Spalten besteht. In der letzten Spalte steht der Name des Layers. In der vorletzten Spalte wird die Quelle für das Bild vom MapServer eingefügt, hier mit einer Größe von 18 mal 12 Pixeln.

Die erste Zeile ist etwas trickreicher. Hier wird eine Checkbox für ein HTML-Formular generiert, die als ''value'' den Namen des Layers erhält. Dadurch wird dem MapServer mitgeteilt, welche Layer darzustellen sind und welche nicht -- der Benutzer klickt einfach die Checkboxen an.

Der letzte Teil ist der interessante: wenn ein Layer beim letzten Aufruf angezeigt worden ist, sucht MapServer in Templates nach Tags wie =layername_check= und ersetzt diese Tags dann durch =checked= . Dadurch wird die Checkbox im Browser markiert. Die Namen der Layer werden hier jedoch nicht hartkodiert, sondern bei der Abarbeitung des Legenden-Templates der Reihe nach ersetzt. Dadurch entsteht für jeden Layer eine passende Checkbox.

Dieses Stück HTML-Code generiert also nicht nur eine Legende, sondern auch gleich die Elemente für das Navigationsformular aus dem Inhalt des Mapfiles. Wird dem Mapfile nun ein neuer Layer hinzugefügt (oder ein Layer entfernt), wird die Legende automatisch korrekt generiert, ohne dass man am Template etwas ändern müßte.

=== GetLegendGraphics Request ===

....

==Templates==
(20)
\index{Templates}\index{Mapfile!Templates}

In der Web-Sektion des Mapfiles können diverse Templates definiert werden, die als Ergebnis eines Aufrufs ausgeliefert werden können. Bei den Templates handelt es sich um HTML-Dateien, in denen neue, MapServer-eigene Tags definiert werden, die in eckigen Klammern notiert werden.

Damit ein Template als Ergebnis ausgeliefert wird, muß der Modus =browse= im URL angegeben sein, im Gegensatz zum Modus =map= , der lediglich die Karten als Bilder zurückliefert.

Auch für die beiden Abfragemodi =query= und =nquery= werden Templates verwendet. Was es mit Queries auf sich hat, und wie man sie in seine Applikationen einbaut, ist ab Seite~\pageref{text:mapfile:queries} in Erfahrung zu bringen.

===Die verschiedenen Arten von Templates===

Templates kommen an mehreren verschiedenen Stellen im Mapfile mit unterschiedlicher Notation vor. Hier eine Aufzählung aller Möglichkeiten, ein Template für diverse Anwendungsfälle zu deklarieren.

Grundsätzlich können Templates lokal im Dateisystem liegen, wobei dann ihr Dateiname angegeben wird. Templates können aber auch als URL deklariert werden und somit von entfernten Rechnern herbeigeholt werden.

\subsubsection*{Web-Sektion}

Die Web-Sektion kennt die folgenden Template-Angaben:

*=TEMPLATE <datei|url>= Ist das Template für die Applikation, die im Modus =browse= läuft. Das einzige Template, das beim simplen Navigieren in der Karte zum Einsatz kommt.
*=HEADER <datei|url>= Ein Kopf-Template, das ausgegeben wird, bevor irgendwelche MapServer-Ergebnisse generiert werden. Findet lediglich beim Modus =nquery= zusammen mit =FOOTER= Anwendung, um die verschiedenen Abfrageergebnisse in ein beginnendes und ein abschließendes HTML einbetten zu können.
*=FOOTER <datei|url>= Das Pendant zu =HEADER= , das nach dem Einfügen aller Ergebnisse angehängt wird.
*=MINTEMPLATE <datei|url>= Ein Template, das benutzt werden soll, wenn der minimale =SCALE= für die Anwendung (gesetzt durch =MINSCALE= in der Web-Sektion) unterschritten wird. Auf diese Weise kann man MapServer-App\-li\-ka\-tionen verschiedener Detailstufen ineinander verschachteln.
*=MAXTEMPLATE <datei|url>= Ein Template, das benutzt werden soll, wenn der maximale =SCALE= für die Anwendung (gesetzt durch =MAXSCALE= in der Web-Sektion) überschritten wird.

\subsubsection*{Layer-Sektion}

In der Layer-Sektion lassen sich die folgenden Template-Angaben machen:

*=TEMPLATE <datei|url>= Präsentiert Abfrageergebnisse. Wenn mehrere Abfrageergebnisse präsentiert werden sollen, wird für jedes der Ergebnisse dieses Template einmal eingefügt und Gebrauch von =HEADER= und =FOOTER= gemacht (siehe weiter unten).
*=FOOTER <datei|url>= Kommt bei multiplen Abfragen zum Tragen und wird angehängt, nachdem alle Ergebnisse zusammengefügt worden sind.
*=HEADER <datei|url>= Das Pendant zu =FOOTER= ; wird vor allen Abfrageergebnissen eingefügt.

Das Template via =TEMPLATE= benutzt man im wesentlichen dann, wenn man nicht, wie im folgenden beschrieben, ein solches Template in jeder Class des Layers haben möchte.

\subsubsection*{Class-Sektion}

Für eine Class gibt es nur eine Template-Angabe, namentlich die folgende:

*=TEMPLATE <datei|url>= Präsentiert Abfrageergebnisse. Wenn mehrere Abfrageergebnisse präsentiert werden sollen, wird für jedes der Ergebnisse dieses Template einmal eingefügt und Gebrauch von =HEADER= und =FOOTER= gemacht, in dem sich die Class befindet.

Wenn man nicht für jede einzelne Class ein =TEMPLATE= notieren möchte, kann man eine solche Angabe auch auf der Ebene des Layers machen.

===Aufbau===

Ein einfaches Beispiel für ein HTML-Template:

 <code>
<html>
<head><title>Beispiel</title></head>
<body>
<img src="[img]">
</body>
</html>
</code> 

Wenn der MapServer über den URL aufgerufen wird, findet er in der Web-Sektion die Angabe für das Template, ersetzt die Tags in eckigen Klammern durch seine neu generierten Werte, und liefert dann die fertige HTML-Seite aus.

Im obigen Beispiel würde der MapServer eine Karte generieren, die einen URL zugewiesen bekommt. Dieser URL würde anstelle des =[img]= -Tags eingesetzt werden.

Für die Templates, die für die Ergebnisse von multiplen Abfragen generiert werden, gilt, dass es sich nicht um komplette HTML-Dateien handeln darf. Beispielsweise möchten Sie für ein Abfrageergebnis einer Class eventuell folgendes Template definieren:

 <code>
<tr>
<td>[ID]</td>
<td>[NAME]</td>
<td>[AREA]</td>
</tr>
</code> 

Die Deklaration der Tabelle und alles andere, was für eine vollständige HTML-Datei vonnöten ist, erfolgt dann durch weitere Templates in =HEADER= und =FOOTER= .

Für Templates, die das Navigationsinterface beschreiben (=TEMPLATE= in der Web-Sektion) und solche für die Präsentation von einzelnen Abfrageergebnissen (definiert durch =TEMPLATE= in Layern) sind hingegen natürlich vollständige HTML-Dateien notwendig.

Im Folgenden nun alle möglichen Tags, die vom MapServer unterstützt werden. Sie können übrigens auch eigene Tags definieren. Wenn Sie einen Parameter im URL übergeben, der dem MapServer nicht bekannt ist, wird dieser im Template ersetzt, wenn ein entsprechender Tag vorhanden ist. Wenn im URL also =meintag=17= steht, und im Template ein Tag =[meintag]= zu finden ist, wird dieser durch 17 ersetzt. Es gibt auch immer eine Fassung, bei der Sonderzeichen (Leerzeichen etc.) durch Escapesequenzen markiert sind; für diese Tags muß dann ein =_esc= angehängt werden. Für das genannte Beispiel hieße der Tag also =[meintag_esc]= .

Zuvorderst einige allgemeine Tags:

*=[version]= : Die Versionsnummer des eingesetzten MapServers.
*=[id]= : Eine (recht)\footnote{Die Einschränkung 'recht' eindeutig soll hier nur bedeuten, dass keine Eindeutigkeit im mathematischen Sinne vorliegt. Einem Kryptographen würden sich die Haare sträuben bei der Verwendung der Session-ID als Baustein für einen 'eindeutigen' Wert. Zur Vermeidung von Kollisionen bei unseren dynamisch generierten Bildern sollte sie jedoch ausreichen.} eindeutige Session-ID für den Aufruf des MapServers, zusammengesetzt aus momentanem Datum und Zeit, sowie der Prozess-ID des Aufrufs. Diese ID ist also solange eindeutig, wie man pro Sekunde nicht mehr Anfragen bekommt, als das System gleichzeitig Prozesse starten kann. Man hätte dann allerdings noch ganz andere Probleme, als dass die ID des MapServer-Aufrufes nicht mehr eindeutig sein könnte.
*=[host]= : Der Hostname des ausführenden Rechners.
*=[port]= : Der Port, auf dem der Webserver die Anfrage entgegengenommen hat. In den meisten Fällen ist dies 80.
*=[web_meta data <key>]= : Zeigt die Metadaten aus der Web-Sektion eines OGC-konformen Mapfiles an.

Tags für Verweise auf Dateien:

*=[img]= : Der URL, an dem sich das neu generierte Kartenbild befindet.
*=[ref]= : Dito für eine eventuell erzeugte Referenzkarte.
*=[legend]= : Dito für eine eventuell erzeugte Legende.
*=[scalebar]= : Dito für eine eventuell erzeugte Maßstabsleiste.
*=[queryfile]= : Pfad zu dem File, in dem eine Query abgespeichert worden ist, falls =savequery= als Parameter gesetzt wurde. Mehr zu diesem Thema im Abschnitt über Queries, siehe Seite~\pageref{text:mapfile:query:cached}.
*=[map]= : Pfad zum Mapfile.

Die folgenden Tags lassen sich für Angaben über die Bildgeometrie verwenden:

*=[center]= : Gibt das Zentrum des Bildes in Pixeln an. Beispiel: ist das fertige Bild 300x300 Pixel groß, so steht in diesem Tag 149,149. Wofür braucht man das? Wenn man in einem Navigationsformular einen Knopf zum 'Auffrischen' der Karte hat (man möchte beispielsweise Layer hinzuschalten, aber den Ausschnitt nicht ändern), so kommt kein Klick in der Karte zustande, der den MapServer auf das neue Zentrum für den anzuzeigenden Ausschnitt hinweist. Mit diesem Tag ist jedoch im Formular folgendes Konstrukt möglich: <code> <input type="hidden" name="imgext" value="[center]"> </code> Dadurch wird ein impliziter Mausklick auf das Zentrum der Karte gesetzt.
*=[center_x]= und =[center_y]= : Die x- und y-Koordinate des Bildzentrums als einzelne Werte.
*=[mapsize]= : Die momentane Größe der Karte in Breite und Höhe in Pixeln, getrennt durch ein Leerzeichen. Mit einem =_esc= am Ende auch als escaped Version vorhanden.
*=[mapwidth]= und =[mapheight]= : Breite beziehungsweise Höhe der Karte in Pixeln.
*=[scale]= : Maßstab der Karte. Zu Maßstäben siehe vor allen Dingen auch Abschnitt~19

Angaben über die Geometrie der Karte sind mit folgenden Tags möglich. Die letzten drei Punkte in dieser Aufzählung sind nur dann verfügbar, wenn der MapServer mit der Projektionsbibliothek proj.4 kompiliert worden ist und es eine Projektionsangabe im Mapfile gibt.

*=[mapx]= und =[mapy]= : x- und y-Koordinate des Mausklicks.
*=[mapext]= und =[mapext_esc]= : Die vollen Extents der Karte, separiert durch Leerzeichen.
*=[maxx]= , =[maxy]= , =[minx]= und =[miny]= : Die einzelnen Koordinaten der Karte.
*=[rawext]= und =[rawext_esc]= : Die Extents der Karte, bevor sie auf die gewünschte Pixelgröße angepaßt worden ist, getrennt durch Leerzeichen.
*=[rawmaxx]= , =[rawmaxy]= , =[rawminx]= und =[rawminy]= : Die einzelnen Koordinaten der Extents der Karte, bevor die Karte auf die gewünschte Pixelgröße angepaßt worden ist.
*=[maplon]= und =[maplat]= : Längen- und Breitengrad des letzten Mausklicks in der Karte.
*=[mapext_latlon]= und =[mapext_latlon_esc]= : Voller Extent der Karte in Längen- und Breitengrade, separiert durch Leerzeichen.
*=[minlon]= , =[minlat]= , =[maxlon]= und =[maxlat]= : Die einzelnen Koordinaten der Extents der Karte in Längen- und Breitengraden.

Die folgenden Tags geben Aufschluss über die Layer in einer Karte:

*=[get_layers]= : Eine Aufzählung aller Layer, die in der aktuellen Karte aktiv sind, sodass sie in eine URL eingebunden werden können. Zum Beispiel: <code> layer=fluesse&layer=eisenbahn&layer=seen </code> 
*=[layers]= und =[layers_esc]= : Die Namen aller aktiven Layer, voneinander durch Leerzeichen getrennt.
*=[layername_check]= und =[layername_select]= : Im Tag muß an dieser Stelle nicht 'layer' stehen, sondern der tatsächliche Name des Layers. Ist ein Layer aktiv, wird der Tag durch das Wort =checked= bzw. =selected= ersetzt. Auf diese Weise wird von Seitenaufruf zu Seitenaufruf mitgeschleift, ob ein Layer ausgewählt ist. Ein Beispiel für einen Layer namens 'fluesse': <code> <input type="checkbox" name="layer" value="fluesse" [fluesse_select]> Flüsse </code> Wenn der Layer im URL angefordert worden ist, ist diese Checkbox automatisch selektiert.
*=[layername_meta <data> <key>]= : Dieser Tag wird, genauso wie der entsprechende Tag in der Web-Sektion, durch Metadaten aus einem OGC-konformen Mapfile gefüllt.

Auch für das Zoomverhalten gibt es einige Tags für das Template:

*=[zoomdir_<-1|0|1>]=
*=[zoom_minzoom to maxzoom_<select|check>]=

Zu guter Letzt natürlich noch die Tags, die für Queries interessant sind. Dementsprechend werden diese Tags nur dann ausgefüllt, wenn sie sich in einem Template befinden, das von einer Query abgearbeitet wird.

*=[shpext]= : Die Extents des Shapes, das das Suchergebnis darstellt.
*=[shpminx]= , =[shpmaxx]= , =[shpminy]= und =[shpmaxy]= : Dito, nur in die einzelnen Punktkoordinaten aufgeschlüsselt.
*=[shpmid]= : Der Mittelpunkt eines gewähltes Shapefiles. Steht nur zur Verfügung, wenn Queries bearbeitet werden.
*=[shpmidx]= und =[shpmidy]= : X- respektive y-Koordinate des Mittelpunkts.
*=[shpidx]= : Index des aktuellen Shapefiles. Steht nur zur Verfügung, wenn Queries bearbeitet werden.
*=[tileindex]= : Index der momentanen Rasterkachel. Steht ebenfalls nur zur Verfügung, wenn Queries bearbeitet werden.
*=[DBase column name]= : Jede beliebige Spalte einer ''.dbf'' -Datei kann in Query-Templates als Tag verwendet werden. Die entsprechenden Ergebnisse werden dann eingefügt.
*=[cl]= : Name des aktuellen Layers. Sinnvoll in Layerheadern oder -footern.
*=[lrn]= : Die Nummer eines Suchergebnisses im aktuellen Layer. Sinnvoll in Querytemplates.
*=[nl]= : Anzahl der Layer, in denen es Suchergebnisse gegeben hat. Sinnvoll in Web-Headern oder -footern.
*=[nlr]= : Gesamtzahl aller Ergebnisse im aktuellen Layer. Sinnvoll in Web-Headern und -footern.
*=[nr]= : Gesamtzahl aller Suchergebnisse. Sinnvoll in Web-Headern und -footern.
*=[rn]= : Die Nummer des Suchergebnisses innerhalb aller Suchergebnisse. Sinnvoll in Web-Headern und -footern.

==Metadaten==
(21)\index{Mapfile!Metadaten}\index{Metadaten}

Die Web-Sektion (und nicht nur diese) kann zwei Arten von Metadaten aufnehmen. Zum einen sind diejenigen Daten zu nennen, die für eine OGC-konforme Interaktion mit der Außenwelt sorgen. Wie mit diesen Daten umzugehen ist, erfahren Sie in Kapitel~\ref{text:ogc}.

Des weiteren können Sie sozusagen "`freie"' Einträge vornehmen, die Sie dann -- in eckigen Klammern, siehe den nächsten Abschnitt über Templates -- als Parameter in das Template übernehmen und so in die HTML-Ausgabe einfügen können.

Ein Beispiel:

 <code>
METADATA
autor "Thorsten Fischer"
adresse "Heilbronner Strasse 10"
END
</code> 

Diese Zeilen ermöglichen Ihnen, beispielsweise das folgende im Template zu tun:

 <code>
Der Autor [autor] kann unter
der Adresse [adresse] erreicht werden
</code> 

MapServer ersetzt diese Tags dann durch die Parameter aus der =METADATA= -Sektion.

Beachten Sie, dass Sie solche Metadaten auch auf Layer-Ebene einfügen können. Diese Daten können Sie dann später beispielsweise dazu verwenden, die Layer in HTML-Legenden auf eine bestimmte Weise zu sortieren.

Eine weitere Idee zum Einsatz von Metadaten sind Links. Speichern Sie zum Layer gehörende URLs als Metadaten und fügen Sie sie später in Templates oder HTML-Legenden ein.

==Queries==
\index{Queries}\index{Mapfile!Queries}(22)

Zuweilen möchte man seine Daten nicht nur betrachten. Auch wenn es die größte Stärke des MapServer ist, schnell Karten generieren zu können und diese dann ausliefern zu lassen, ist eine minimale GIS-Funktion zuweilen wünschenswert. Die Anfragen auf die den Karten zugrundeliegenden Datenbestände werden beim MapServer ''Queries'' genannt.

===Notation 2===

Im HTML-Template, das das Benutzer-Interface für den MapServer definiert, muß natürlich zuerst die Möglichkeit geschaffen werden, neben dem Bewegen in der Karte auch Queries zuzulassen -- man muss zwischen beiden Modi wählen können. Das kann beispielsweise durch entsprechende Radio-Buttons passieren:

 <code>
...
<input type="radio" name="mode" value="browse" checked> Browsen
<input type="radio" name="mode" value="query"> Anfrage stellen
...
</code> 

Beim Absenden des Formulars übermitteln die Radio-Buttons (wie man sie beispielsweise auch im offiziellen MapServer-Demo findet) den entsprechenden Modus an das MapServer-CGI.

Möchte man mehrere Abfrageergebnisse zulassen, benötigt man den Modus =nquery= :

 <code>
<input type="radio" name="mode" value="nquery"> Mehrere Anfragen
</code> 

Alle drei Modi können natürlich im gleichen Formular vorkommen.

Desweiteren müssen Sie in allen Layern, für die Sie Abfragen zulassen möchten, ein =TEMPLATE= definieren. Dabei können Sie einzelne Templates in den Classes des Layers definieren (die dann nur für Abfrageergebnisse der jeweiligen Klasse gelten) oder aber eine Angabe für den kompletten Layer machen; das muß dann außerhalb der Classes geschehen.

Für die einfache Query wird außerdem nur der oberste sichtbare Layer der Karte befragt\footnote{Also der letzte sichtbare Layer im Mapfile}.

Wie Templates für Abfrageergebnisse notiert werden, ist bereits in der umfänglichen Sektion über Templates beschrieben worden. Beachten Sie auf alle Fälle immer, ob Sie nur einfache oder multiple Ergebnisse bei Ihren Anfragen zulassen. Ist letzteres der Fall, sollten Sie sich über die Anordnung von =HEADER= - und =FOOTER= -Templates Gedanken machen.

Ein Beispiel. Sie haben folgendes in Ihrem Layer notiert:

 <code>
LAYER
NAME "gemeinden"
...
HEADER "gemeinden_head.html"
FOOTER "gemeinden_foot.html"
...
CLASS
TEMPLATE "gemeinden.html"
END
END
</code> 

Für eine einfach Query würde lediglich einmal =gemeinden.html= mit entsprechendem Ergebnis zurückgeliefert werden. Nehmen wir aber nun an, dass der Modues auf =nquery= gesetzt ist, und mehrere Features mit einem Mausklick erwischt worden sind -- um ein Beispiel zu wählen: 3 Stück --, so wäre das Ergebnis wie folgt:

 <code>
gemeinden_header.html
gemeinden.html
gemeinden.html
gemeinden.html
gemeinden_footer.html
</code> 

Das gleiche wiederholt sich dann noch für alle anderen Layer, die darunter liegen. Außerdem können für =nquery= auch noch ein Header sowie ein Footer in der WEB-Sektion des Mapfiles definiert werden. Diese werden dann jeweils einmal dargestellt: einmal vor allen Suchergebnissen, und einmal dahinter.

===Query maps===
\index{Query map}(23)

Querymaps sind kleine Karten, die in Ergebnistemplates dazu dienen, die Resultate von Queries zu visualisieren. Sie sind als eigene Sektion im Mapfile definiert, außerhalb jeder anderen Sektion (am besten nach dem Header) und sehen beispielsweise folgendermaßen aus:

 <code>
QUERYMAP
COLOR 255 0 0
SIZE 200 200
STATUS ON
STYLE HILITE
END
</code> 

In diesem Fall wird eine 200x200 Pixel große Querymap erzeugt, in der angefragte Features rot markiert werden.

Die folgenden Optionen können in Querymap-Sektionen auftauchen:

*=COLOR <red> <green> <blue>= Gibt die Farbe an, in der die angefragten Features markiert werden. Ergibt nur Sinn, wenn der =STYLE= auf =HILITE= gesetzt ist. Voreinstellung ist gelb.
*=SIZE <x> <y>= Die Größe, in der die Querymap gezeichnet werden soll. Voreinstellung ist die Größe der Karte.
*=STATUS <ON|OFF>= Legt fest, ob die Querymap gezeichnet werden soll.
*=STYLE <NORMAL|HILITE|SELECTED>= Dieser Stil legt für den angefragten Layer fest, wie die gewählten Features gemalt werden sollen. =NORMAL= zeichnet die Karte ohne Änderung. =HILITE= zeichnet den Layer, markiert aber die gewählten Features mit der Farbe =COLOR= ; diese Art ist auch die Voreinstellung. =SELECTED= zeichnet lediglich die gewählten Features.

Wie werden Querymaps nun dargestellt? Es gibt für diese Abfragekarten kein eigenes Schlüsselwort, vielmehr ändert sich der Tag =[img]= , wenn in einen Query-Modus geschaltet wird. Es wird dann nicht mehr die Karte, sondern eben die dazugehörige Abfragekarte dargestellt.

Abgebildet wird in der Querymap der Ausschnitt der Karte, in dem man die Anfrage gestellt hat. Darin markiert sind die Abfrageergebnisse, wie man es im =QUERYMAP= -Block angegeben hat.

Sie können übrigens eine Querymap auch separat von allem anderen mit dem Modus =querymap= anfordern, genauso, wie auch eine normale =map= .

\subsubsection*{Cached Queries}(24)\index{Queries!Cached Queries}\index{Cached Queries}

Cached Queries sind eine Möglichkeit, Abfrageergebnisse abzuspeichern. Mit Cached Queries können Sie die Abfrageergebnisse in einer Karte darstellen, deren Extents Sie beliebig wählen können. Sie sind nicht auf den Ausschnitt beschränkt, an den die Anfrage gestellt wird.

Um eine Cached Query benutzen zu können, müssen Sie zuerst eine weitere Zeile in Ihr HTML-Template aufnehmen:

 <code>
<input type="hidden" name="savequery" value="true">
</code> 

Dadurch werden nun bei Query-Aufrufen temporäre Dateien angelegt, wie es etwa auch für generierte Karten geschieht. Der Name dieser Datei läßt sich in einem Template nun mit Hilfe von Template-Tags rekonstruieren:

 <code>
<img src="[program]&map=[map]&
queryfile=[map_image_path]<NAME>[id].qy
[get_layers]&mode=map&size=200+200
</code> 

Der Wert =[map]= wird sowieso immer übergeben, und =get_layers= wird bei jedem Aufruf des MapServers automatisch aus den übergebenen Layern erstellt.\\ =map_image_path= fügt der MapServer ebenfalls automatisch aus dem Mapfile ein. Der Wert von =[id]= ist eine eindeutige ID für den jeweiligen MapServer-Aufruf und wird auch vom MapServer ausgefüllt. Der String =<NAME>= ist der Wert, der im Mapfile als =NAME= im Mapfile für die Karte gesetzt ist, und muß von Ihnen von Hand eingetragen werden.

Der Trick ist nun, dieser Karte eine Bounding Box in bekannter Notation nach Ihrem Wunsch mitzugeben; man erhält somit beliebige Kartenausschnitte, in denen Abfrageergebnisse angezeigt werden.

===Weitere Arten von Queries===

Über die beiden Modi =query= und =nquery= hinaus definiert MapServer noch eine ganze Menge weiterer Typen für Datenanfragen. Auf einige dieser Modi soll hier noch im Detail eingegangen werden.

;indexquery

Eine Indexquery sucht ein Shape über seine ID im Shapefile heraus. Im Aufruf sieht das beispielsweise folgendermaßen aus:

 <code>
http://www.example.com/cgi-bin/mapserv
? map=/pfad/zum/mapfile.map
& mode=indexquery
& qlayer=bundeslaender
& shapeindex=15
</code> 

Der Aufruf dieser Art von Query erfolgt über den Modus =indexquery= . Der Layer, der das Ziel der Anfrage sein soll, wird mit =qlayer= bestimmt.

Für das Ergebnis dieses Aufrufs wird wie gewohnt das Template benutzt, das sie im entsprechenden Layer definiert haben (bzw. in den dortigen Classes). Anstatt aber nun die Koordinaten eines Mausklicks auszuwerten, wird gezielt nach einem bestimmten Shape gesucht. Das obige Beispiel zum Beispiel sucht nach dem sechszehnten Shape im Layer =bundeslaender= , und die Darstellung im Query-Template sieht dann dementsprechend aus.

Falls Sie eine Querymap definiert haben sollten, so werden bei der Darstellung der Karte beim obigen Aufruf die Extents verwendet, die im Mapfile definiert sind. Der CGI-Parameter =mapext= kann verwendet werden, um wie im Modus =browse= einen anderen Kartenausschnitt festzulegen. Falls Sie diesen Parameter nicht auf bestimmte Werte setzen, sondern stattdessen =mapext=shapes= verwenden, wird direkt auf das Ergebnisshape gezoomt.

Nur die Querymap als Bild können Sie sich übrigens mit dem Modus =indexquerymap= zurückliefern lassen.

Zusätzlich zu den Parametern im gezeigten Beispielaufruf gibt es auch noch =tileindex= , für den Fall, dass sie gekachelte Shape-Daten verwenden.

;itemquery und itemnquery

Durch eine Itemquery können Sie Features anhand von nichträumlichen Eigenschaften auswählen. Bei Daten aus Shapefiles (auf die wir uns hier konzentrieren wollen) kommen diese Eigenschaften selbstverständlich aus den =.dbf= -Dateien.

Um über den URL auf diese Eigenschaften zugreifen zu können, müssen wir sie mit einem Namen bekannt machen. Dazu benutzen wir den Parameter =FILTER= im entsprechenden Layer:

 <code>
LAYER
...
DATA "bundeslaender"
FILTERITEM "NAME"
FILTER "
...
END
</code> 

In diesem Beispiel verwenden wir die DBF-Tabellenspalte =NAME= und machen sie nach außen als =name= bekannt.

Zugriff erhalten wir nun über diesen Namen. Im URL notieren wir jetzt folgendes:

 <code>
FIXME
</code> 

FIXME:mehr

Da diese Art von Query mit Angabe einer Zeichenkette funktioniert, ist es in den meisten Fällen sinnvoll, dem Benutzer eine Auswahlliste zur Verfügung zu stellen, aus der er sich dann Features nach Namen auswählen kann.

FIXME

;featurequery und featurenquery

\begin{figure}
\begin{center}
\mmfig{0.55}{featurenquery-berlin}{Eine =featurenquery= . Hier wurde das Bundesland Berlin gewählt und nach allen Features (Postleitzahlgebieten und bestimmte Kacheln) gefragt, die von der Fläche des Bundeslandes geschnitten werden.}
\end{center}
\end{figure}

In diesem Modus wird ein Feature ausgewählt, und alle dafür eingestellten Layer werden befragt, welche Features durch dieses Feature geschnitten werden. Sie können ein Beispiel dafür in Abbildung~\ref{featurenquery-berlin} sehen: Hier wurde das Bundesland Berlin durch einen Mausklick ausgewählt, und das Ergebnis ist eine Liste aller Features, die die Fläche eben dieses Bundeslandes schneiden.

Beachten Sie bitte, dass wir an dieser Stelle nur die Fassung dieser Query mit dem =n= im Namen betrachten. =featurequery= funktioniert analog zum Paar =query= /=nquery= mit nur einem einzigen Suchergebnis.

Als erstes benötigen Sie für diese Art von Query selbstverständlich einen entsprechenden Modus:

 <code>
... & mode = featurenquery & ...
</code> 

Danach muß spezifiziert werden, anhand welchen Layers die Auswahl getroffen werden soll. Vorstellbar wäre zum Beispiel eine Auswahlbox mit einer Liste aller Layer, aus der dann ein Layer als Bezugsebene ausgewählt werden kann. Der zuständige Parameter heißt =slayer= . Heißt der Layer beispielsweise =gruenflaechen= , so notiert man:

 <code>
... & slayer = gruenflaechen & ...
</code> 

Jeder Layer, der über =layer== im URL spezifiziert wird und ein =TEMPLATE= gesetzt hat, wird nun für den Vergleich herangezogen.

Das Abarbeiten der Query-Templates läuft in der gewohnten Weise ab; für jedes Ergebnis in einer Class werden die Templates hintereinander gehangen, für den Layer dann eventuell noch Header davor und Footer dahinter, und um das ganze herum dann eventuell vorhandene Header und Footer aus der Web-Sektion.

''Hinweis'' : Zum Zeitpunkt der Drucklegung funktionierte diese Art von Query nicht mit umprojizierten Daten. Quell- und Zielprojektion mußten übereinstimmen, um Suchergebnisse zu erhalten.

;itemfeaturequery und itemfeaturenquery

FIXME

==PostgreSQL und PostGIS==
\index{PostGIS}\index{PostgreSQL}

PostGIS, ein Zusatz für die freie Datenbank PostgreSQL, ist die 'Standard'-Daten\-bank\-an\-bindung für den MapServer. PostGIS setzt einen großen Teil der Simple Features des OGC um und kann nicht nur als Datenquelle für den MapServer dienen, sondern generell raumbezogene SQL-Anfragen verarbeiten.

Die Anbindung einer PostGIS-Datenbank wird in Kapitel~\ref{text:database} ab Seite~\pageref{text:database:postgis} beschrieben.

==OGR==
\index{OGR}(25)

Die OGR-Bibliothek ist das vektor-orientierte Gegenstück zu GDAL. Obwohl es sich um eine eigenständige Bibliothek handelt, wird sie zusammen mit GDAL ausgeliefert.

Neben den Shapefiles gibt es nämlich noch eine ganze Reihe anderer Vektorformate. Shapefiles sind so ziemlich das minimalistischste, was man sich vorstellen kann, sie beinhaltet lediglich die Koordinaten von Punkten. Viele Vektorformate sind allerdings etwas komplexer, und enthalten gleich mehrere Datensätze, einen Haufen zusätzliche Metadaten oder gleich Informationen über die Gestaltung der Daten.

Besonders bei der letztgenannten Klasse von Formaten sollte man vorsichtig sein und von OGR nicht zuviel erwarten. Zwar gibt es für diese Formate die Möglichkeit, das Layout der Daten auszulesen, aber nicht immer kann diese Information auch umgesetzt werden.

Von der Notation her gibt es, ähnlich wie bei Datenanbindungen, nur eine grundlegende Änderung: Im Layer wird nun nicht mehr =DATA= als Schlüsselwort für die Datenquellen verwendet, sondern die beiden Parameter =CONNECTIONTYPE= (dieser ist dann immer =OGR= ) und =CONNECTION= . Dabei wird =CONNECTION= dann von den notwendigen Details wie dem gewünschten Layer aus dem Datensatz usw. gefolgt.

FIXME: vervollständigen!1!

==Spezifikation von Ausgabeformaten==
(26)

Mit Version 4.0 des MapServers ist man nun endlich in der Lage, mehrere verschiedene Ausgabeformate für die fertige Karte zu spezifizieren. Bisher war man auf ein einziges Rasterbild-Format festgelegt (PNG respektive GIF).

FIXME: mehr

Ein Mapfile kann eine, mehr als eine oder sogar gar keine OUTPUTFORMAT-Sektion haben. Ohne jede Angabe wird bei einkompilierter GD-Bibliothek ein PNG-Bild zurückgeliefert.

Eine OUTPUTFORMAT-Sektion sieht typischerweise so aus:

 <code>
OUTPUTFORMAT
NAME "png"
DRIVER "GD/PNG"
MIMETYPE "image/png"
IMAGEMODE RGB
EXTENSION "png"
END
</code> 

Zuerst erhält die Sektion einen Namen. Danach wird ein "Treiber" für die Erstellung des Bildes angegeben. Für die typische PNG-Ausgabe mit der Bibliothek GD steht hier ''GD/PNG'' .

Der Mimetype ist wichtig, um dem Browser, der die fertige Karte entgegennimmt, mizuteilen, welcher Art die Daten sind, die da ankommen\footnote{Für Windows-Benutzer: Nein, der Dateiname sagt nichts über die Art einer Datei aus. Er ist im Grunde nicht einmal Bestandteil einer Datei. Microsoft hat das aber schon vor einer ganzen Weile vergessen.}. Er ist für diese Sektion allerdings Optional, da MapServer auch versucht, ihn automatisch zu bestimmen.

Der IMAGEMODE gibt unter anderem die Farbtiefe des Bildes an (siehe die Sektion über Rasterbilder; ist aber auch für Flash relevant), und schließlich die Dateinamenerweiterung des Outputs.

Im folgenden sollen für die verschiedenen Anwendungsfälle alle möglichen Optionen in der OUTPUTFORMAT-Sektion angegeben werden.

===Rasterbilder===

Bisher gibt es gibt es nur zwei Treiber für Rasterbildformate im MapServer: die inzwischen klassische Ausgabe mittels GD, und ganz neu GDAL. Letzteres kann bisher nur GeoTIFF-Bilder produzieren, aber es ist ein Anfang.

FIXME: blah

Der Parameter =IMAGEMODE= sagt aus, in welcher Farbtiefe das Bild produziert werden soll, und wie Transparenzen gehandhabt werden sollen:

*=PC256= : Produziert ein Bild mit einer eigenständigen Farbpalette mit (maximal) 256 Farben. Dies ist der klassische MapServer-Modus. Der Raster-Treiber ''GD/GIF'' kennt ausschließlich diesen Modus. TRansparenz ist mit diesem Modus möglich.
*=RGB= : 24-Bit RGB-Farbbild. Ohne Transparenz.
*=RGBA= : 32-Bit RGBA-Farbbild mit Alphakanal (Transparenz).
*FIXME: mehr?

Über alle diese Optionen hinaus gibt es noch treiberabhängige Angaben, die sogenannten FORMATOPTIONs. Sie werden folgendermaßen notiert:

 <code>
OUTPUTFORMAT
NAME "jpg"
DRIVER "GD/JPEG"
MIMETYPE "image/jpeg"
IMAGEMODE RGB
EXTENSION "jpg"
FORMATOPTION "QUALITY=75"
END
</code> 

Jedes OUTPUTFORMAT kann dabei keine, eine oder mehrere (passende!) Angaben für FORMATOPTIONs haben. Im folgenden sind alle diese Optionen für die einzelnen Treiber beschrieben.

;Der GD-Treiber

Der GD-Treiber kennt die folgenden, optionalen Parameter in der OUTPUTFORMAT-Sektion:

*=QUALITY= Legt für JPEG-Bilder die Kompression fest. Liegt zwischen =0= (niedrigste Qualität, höchste Kompression) und =100= (höchste Qualität, niedrigste Komprimierung).
*=INTERLACE= Legt fest, ob PNG- bzw. GIF-Bilder interlaced sein sollen (=ON= ) oder nicht (=OFF= ).

FIXME: mehr

;Der GDAL-Treiber

Generell kann man dem GDAL-Treiber alles als Parameter mitgeben, was die Bibliothek als Optionen kennt; was alles in Frage kommt, erfahren Sie in der Dokumentation von der Website~[[http:website:gdal]].

FIXME: vervollständigen!1!

===Vektorformate===
(27)

Vektorausgabeformate sind ein neues Feature in MapServer 4.0. Die Fülle von Einstellungen, die man dabei theoretisch machen kann, wird durch die Einführung von =OUTPUTFORMAT= abgefangen.

Alle bisher unterstützten Vektorformate zeichnen sich durch die Eigenschaft aus, dass sie nicht von sich aus im Browser darstellbar sind, sondern eine zusätzliche Bearbeitung oder doch zumindest den Einsatz von separaten Plugins im Webbrowser notwendig machen.

Wachsender Beliebtheit bei den Vektorformaten im Web erfreut sich auch SVG, ein XML-basiertes Format. Folglich sind Fragen nach einer Unterstützung für dieses Format auf der Mailingliste an der Tagesordnung. Bisher hat sich aber noch niemand die Mühe gemacht, Unterstützung für dieses Format zu implementieren. Das kann sich im Laufe der Zeit selbstverständlich ändern.

==Features==
(28)

Für manche Dinge ist es nicht nötig -- oder schlicht zu aufwendig -- ein eigenes Shapefile oder eine andere Datenquelle zu haben. Sie können einfache Features auch als =FEATURE= -Block direkt im Mapfile notieren. Ein Beispiel:

 <code>
FEATURE
POINTS
1 1
10 10
10 1
1 1
END
TEXT "Dreieck"
END
</code> 

Hier definieren wir ein Dreieck in der linken oberen Ecke der fertigen Karte. Der Parameter =TEXT= definiert die Beschriftung des Features.

Beachten Sie, dass für einen geschlossenen Linienzug der letzte Punkt dem ersten Punkt entsprechen muß. Für die Einbettung eines =FEATURE= in einen Layer schauen Sie sich bitte den nächsten Abschnitt an.

===Fix positionierte Elemente===

Zuweilen möchte man in eine fertige Karte noch eine Information einfügen, die immer gleich bleibt; ein Logo, eine Urhebernotiz, was auch immer. Das Problem ist natürlich, dass bisher immer alles georeferenziert war und daher immer auf einen bestimmten Punkt fixiert.

\begin{figure}
\begin{center}
\mmfig{0.60}{transform-label}{Ein fixes Label in einer Karte, hier der URL der MapMedia-Website.}
\end{center}
\end{figure}

Mit dem Parameter =TRANSFORM= in einem Layer können Sie dieses Verhalten jedoch ein wenig manipulieren. Dieser Parameter gibt an, ob das Koordinatensystem der Datenquelle im Verhältnis zum fertigen Bild transformiert werden soll oder nicht. Die Standardeinstellung ist immer =TRUE= , was nicht weiter verwundert, denn bisher wurde immer das Koordinatensystem der Daten in das Koordinatensystem des Bildes (Angabe in Pixeln und Ursprung links oben) umgewandelt.

Setzen Sie diesen Wert jedoch auf =FALSE= , können Sie neue Dinge tun, unter anderem auch mit einer =FEATURE= -Sektion, beispielsweise wie folgt:

 <code>
LAYER
NAME "credits"
STATUS DEFAULT
TRANSFORM FALSE
TYPE ANNOTATION
FEATURE
POINTS
10 10
END
TEXT 'http://www.mapmedia.de/'
END
CLASS
LABEL
TYPE TRUETYPE
FONT "arial"
SIZE 11
ANTIALIAS TRUE
COLOR 0 0 0
END
END
END
</code> 

Dieser Layer besteht aus nur einem Feature, einem Punkt, dessen Koordinaten fest angegeben sind, und ebenso seine Beschriftung. In der dazugehörigen Class ist die Beschriftung mit Schriftart, Farbe usw. definiert. Dadurch, dass der Status auf =DEFAULT= gesetzt ist, und dass man diesen Layer als letzten Layer im Mapfile notiert, hat man einen Effekt wie in Abbildung~\ref{transform-label}: eine Beschriftung, die immer in der Karte zu sehen ist.

FIXME: raster?

==CGI-Parameter==
(29)

FIXME:aufzählung

===Parameter einschränken===
(30)

FIXME:Restriktion durch eine EXPRESSION

\subsection*{Ändern des Mapfiles}

Von außen (über den aufrufenden URL) können auch praktisch alle Inhalte des Mapfiles verändert werden. Der Aufbau dieser neuen Parameter ist recht simpel und orientiert sich an der Struktur eines Mapfiles.

Betrachten wir den Aufbau eines Mapfiles: eine Map beinhaltet (mindestens einen) Layer, dieser mindestens eine Klasse (wenn es sich um einen Vektorlayer handelt). Diese Klasse kann nun wiederum ein Label beinhalten, welches seinerseits eine Farbe hat.

Die Adressierung kann auf verschiedene Weise geschehen. Zuerst einmal über Nummern. Im folgenden Beispiel bekommt die erste Klasse im zweiten Layer die Farbe Rot zugewiesen:

 <code>
...&map_layer_1_class_0_color=255
</code> 

Das '\

Darüber hinaus lassen sich Layer auch über ihren Namen referenzieren:

 <code>
...&map_fluesse_class_0_color=255
</code> 

Wenn der Layer nur eine Klasse hat, sollte man den Index einfach weglassen.

Des weiteren lassen sich auf diesem Weg simple Features zu einem Layer hinzufügen. Der Layer muß existieren. Hier das Beispiel aus der offiziellen MapServer-Dokumentation:

 <code>
...&map_user_feature=new&map_user_feature_points=12345.6789+12345.6789
&map_user_feature_text=My+House!
</code> 

Dem Layer ''user'' wird auf diese Weise ein Punkt mit den angegebenen Koordinaten hinzugefügt, und er wird auch gleich beschriftet. Wird ein Layername mehrfach verwendet, wird das Feature einfach erweitert. Auf diese Weise lassen sich beispielweise Polygone mit 'Löchern' hinzufügen.

=== Variablensubstituion ===

...

==Logging==

Mit Mapserver 5.0 wurden die Möglichkeiten des Loggings erheblich erweitert. Zur Konfiguration sind zwei Punkte zu beachten:

* Die Variable MS_ERRORFILE muss gesetzt werden.
* Auf Map- bzw. Layer-Ebene wird ein Debuglevel gesetzt

'''''MS_ERRORFILE <Wert>'''''

Die Variable MS_ERRORFILE kann entweder mittels Umgebungsvariable oder per CONFIG-Direktive in dem Mapfile gesetzt werden. Die CONFIG-Direktive hat dabei Vorrang, falls beide Möglichkeiten genutzt werden.
Hiermit wird angegeben wohin die Logmeldungen geschrieben werden. Je nach Wert gibt es ''folgende Werte'':
; stderr : Ausgabe wird an die Standardfehlerausgabe gesandt. Bei Apache ist dies die per error_log angegebene Datei. Beim IIS wird es per Standardausgabe ausgegeben.
; stdout : Ausgabe wird an die Standardausgabe gesandt
; windowsdebug : Ausgabe wird an die Windows OutputDebugString API gesandt. Dadurch kann mit Programmen wie Debugview (Microsoft/Sysinternals) die Ausgabe verfolgt werden.
; PFAD : eine absolute Pfadangabe zum Logfile

Wird diese Variable nicht gesetzt, ist das Logging deaktiviert.

Beispiel:

CONFIG "MS_ERRORFILE" "/Pfad/zum/Logfile"

oder

CONFIG "MS_ERRORFILE" "stderr"

Dabei sollten Pfade immer als absoluter Pfad angegeben werden.

'''''DEBUG <level>'''''

Das DEBUG-Level wird entweder global oder auf Layerebene gesetzt. Zur Verfügung stehen ''folgende 6 Level'':
; Level 0 : Es werden ausschließlich Fehler geloggt. Entspricht DEBUG OFF bzw. DEBUG 0
; Level 1 : zusätzlich Warnungen zu nicht-fatalen Fehlern wie z.B. fehlende oder falsche Werte für bestimmte Parameter, fehlende Shapefiles in tileindex oder Zeitüberschreitung bei externen WMS-Diensten
; Level 2 : zusätzlich Hinweise mit Zeitinformationen
; Level 3 : zusätzlich Debugausgaben wie WMS-Verbindungs-URLs, Datenbank-Verbindungs-Informationen usw.
; Level 4 : weitere Ausgaben
; Level 5 : detaillierte Informationen die für Entwickler gedacht sind

Das Debuglevel kann global entweder per Umgebungsvariable MS_DEBUGLEVEL oder im Mapfile gesetzt werden. Werden beide Möglichkeiten genutzt, hat die Angabe im Mapfile Vorrang. Bei der Ausgabe wird für jeden Layer das gleiche Debuglevel genutzt.
Das Debuglevel auf Layerebene überschreibt ein evtl. gesetztes globales Debuglevel. Dadurch kann bis auf Layerebene die Fehlerausgabe individuell eingestellt werden.

Wird die Umgebungsvariable benutzt so werden auch Meldungen z.B. zur Initialisierung ausgegeben die außerhalb von Layer- oder Map-Context erfolgen.

==Includes==

Bei manchen Projekten kann das Mapfile sehr groß werden. Durch die INCLUDE-Direktive kann man die Übersichtlichkeit wieder erhöhen, in dem man einzelne Abschnitte in separate Dateien auslagert. Für hochperformante Mapserveranwendungen wird dieses Vorgehen nicht empfohlen, da ein gewisser Overhead entsteht. Eine Standardanwendung wird bei Verwendung von INCLUDE-Direktiven nicht spürbar verlangsamt.

Beispielaufruf:

INCLUDE "basislayer.map"

Folgende Hinweise sind bei der Verwendung zu beachten:

* Der Name der Datei '''sollte''' in Anführungszeichen stehen
* Die maximale Verschachtelungtiefe beträgt 5
* Die Pfadangabe kann absolut oder relativ zum Mapfile erfolgen
* Die Fehlerverfolgung wird erschwert da z.B. die angegebene Zeilennummer ggf. nicht mehr stimmt

==Joins==
\index{Joins}

Der Grundgedanke bei Joins entspricht dem gleichlautenden Begriff bei SQL-Da\-ten\-ban\-ken: die Inhalte zweiter Dateien mit Daten werden zu einem einzigen Datensatz zusammengefügt. Dazu benötigt man in beiden Datensätzen ein gemeinsames Datum, wie zum Beispiel eine ID, um den Inhalt den einen Datensatzes dem anderen zuordnen zu können.

In MapServer kommt das Konzept vor allen Dingen zum Einsatz, um die Inhalte zweier DBF-Dateien zu einem einzigen zusammenzufügen, der dann dazu benutzt wird, die Expressions in Classes oder auch Query-Ergebnisse zu evaluieren.

FIXME: funktioniert nicht?

----

nicht mehr verwendet

----

;PDF

Unterstützung für die Ausgabe von PDF-Dateien wird mit der Bibliothek PDFLib realisiert. Dafür wird MapServer beim Kompilieren ganz einfach gegen diese Bibliothek gelinkt.

Das Ausgabeformat wird recht simpel folgendermaßen notiert:

 <code>
OUTPUTFORMAT
NAME "pdf"
MIMETYPE "application/pdf"
DRIVER PDF
END
</code> 

Da man PDF nicht einfach über einen =<img>= -Tag in seine HTML-Seite einbinden kann, bietet sich ein anderes Vorgehen an. Man baut ein Template zum Browsen der Karte wie gewohnt, gibt dem Benutzer aber noch einen Link mit einer Beschriftung wie 'diese Karte als PDF herunterladen' mit auf den Weg. Diesen Link kann man sich für den aktuellen Kartenausschnitt mit den entsprechenden MapServer-Tags bauen, zum Beispiel wie folgt:

 <code>
<a href="/cgi-bin/mapserv?map=[map]&imgext=[mapext]&FIXME=pdf ...">
</code> 

Die Liste der Parameter ist hier nicht vollständig, aber die Idee wird klar.

Wer den Verlauf der Entwicklung von MapServer 4.0 mitverfolgt hat, hat vielleicht mitbekommen, dass zu Beginn der PDF-Unterstützung lediglich ein PNG-Bild erzeugt worden ist, das dann in ein PDF-Dokument eingebettet wurde. Das ist nicht mehr der Fall, nun liefert MapServer für Vektordaten richtiges PDF zurück.

Wenn man eine Weile mit diesem Ausgabeformat experimentiert, wird man merken, dass die reine Ausgabe einfach nur einer Karte im PDF-Format recht unbefriedigend ist. Wer gestalterisch tätig werden möchte, der muß mit einer Skriptsprache Hand anlegen.

''Hinweis'' : Beachten Sie bitte unbedingt, dass die Nutzung für die hier verwendete Bibliothek PDFLib nicht für ausnahmslos alle Nutzungen kostenlos ist. Bitte informieren Sie sich auf der Website~[[http:website:pdflib]] der Bibliothek über die Details.

Außerdem ist die Erzeugung von PDF eine recht rechenintensive Sache, deren Einsatz man demnach mit Bedacht planen sollte.

;Shockwave Flash

Flash ist ein Vektorformat, das im Web vor allen Dingen dafür verwendet wird, Animationen darzustellen. Daher spricht man bei einem Flash-Element in einer Website gewöhnlich von einem 'Movie', sogar dann, wenn es sich eigentlich um statischen Inhalt handelt. MapServer bietet mit Version 4.0 nun auch die Möglichkeit, fertige Karten als Flash-Movies auszuliefern.

Dabei stützt sich MapServer auf die Bibliothek Ming~[[http:website:ming]], die im Moment von Wolfgang Hamann weiterentwickelt wird, nachdem er diese Aufgabe im November 2002 vom ursprünglichen Entwickler übernommen hat\footnote{Leider hat sie im Laufe der Zeit keine Updates mehr erfahren.}. Die Software zeichnet sich insbesondere durch ihre vielfältigen Bindungen an andere Programmiersprachen aus.

Die Installation für Flash-Unterstützung wird für das Selberkompilieren von Binaries ab Seite~\pageref{anhang:installation:compile:flash} besprochen.

Es gibt für uns zwei Arten, Flash-Output zu generieren: einmal einen Movie für die komplette Karte, und einmal einen Movie für jede einzelnen Layer:

 <code>
OUTPUTFORMAT
NAME "swf"
MIMETYPE "application/x-shockwave-flash"
DRIVER swf
IMAGEMODE PC256
FORMATOPTION "OUTPUT_MOVIE=SINGLE"
# FORMATOPTION "OUTPUT_MOVIE=MULTIPLE"
END
</code> 

Wenn Sie mit diesem =OUTPUTFORMAT= einen Aufruf durchführen, werden Sie feststellen, dass Sie eine Datei (oder mehrere, wenn Sie =MULTIPLE= statt =SINGLE= im Beispiel gewählt haben) mit der Endung =.swf= in Ihrem temporären Verzeichnis aufgetaucht ist.

Bevor Sie diese Dateien tatsächlich benutzen können, müssen Sie sich aber noch ein wenig Arbeit machen. Was Sie benötigen, ist Kenntnis in der Sprache ActionScript, und ein Flash-SDK. Leider würde es den Rahmen dieses Buches sprengen, das eine oder das andere zu erläutern. Daher bleibt mir nur der Verweis auf das Archiv der MapServer-Mailingliste, wo Sie auf der Suche nach Beispielapplikationen und Diskussionen fündig werden können.

;Logs
(31)

Für einen Serverdienst möchte man selbstverständlich Log-Dateien angelegt bekommen. Ein Server läuft die ganze Zeit vor sich hin, sodass man, im Gegensatz zu einer Desktop-Anwendung, im Fehlerfall meistens nicht anwesend ist. Dann sind Protokolle der Serveraktivitäten natürlich notwendig für die Fehlersuche.

Aber auch für den Entwickler sind Logfiles wichtig, zeigen sie ihm doch, wo er nach Ursachen zu suchen hat, wenn sich die Anwendung, an der er arbeitet, nicht so verhält wie erwartet.

Wofür auch immer man seine Logs verwendet, definiert wird die Logdatei in MapServer in der Web-Sektion:

 <code>
WEB
...
LOG "/pfad/zur/datei.log"
END
</code> 

Es gibt nur eine einzige Logdatei pro Mapfile, in der MapServer sowohl Fehlermeldungen als auch erfolgreiche Zugriffe loggen kann.

Das Format für Logfiles ist leider nict dokumentiert, sodass man sich mit einem Blick in den Quellcode weiterhelfen muß\footnote{Siehe Funktion =writeLog= in =mapserv.c= }. Ein Eintrag in einem Logfile sieht beispielsweise folgendermaßen aus:

 <code>
Fri Mar 21 16:02:48 2003,1031,10.0.1.2,demonstration,0, \
7.848750 49.445625 19.098750 55.070625,13.473750 52.258125, \
bundeslaender,normal execution
</code> 

So ein Eintrag erstreckt sich immer über eine einzelne Zeile. Alle Bestandteile sind durch Kommata voneinander getrennt. Die vorliegende Zeile ist im einzelnen wie folgt zu verstehen:

*=Fri Mar 21 16:02:48 2003= Ist ein Zeitstempel; Datum und Uhrzeit des Aufrufs.
*=1031= Die aktuelle Prozess-ID.
*=10.0.1.2= Die IP-Adresse des aufrufenden Hosts. Wird aus der Umgebungsvariable =REMOTE_ADDR= gelesen und ist =NULL= \footnote{Hier ist die Zeichenkette ='NULL'= gemeint}, wenn diese Variable nicht gesetzt ist.
*=demonstration= Der Name des Mapfiles, wie er mit =NAME= im Header gesetzt ist.
*=0= Der Modus des Aufrufes, also z.B. =map= , =browse= und so weiter. Es gibt 26 verschiedene, die allesamt in =maptemplate.h= in einem Aufzählungstyp definiert sind.
*=7.848750 49.445625 19.098750 55.070625= sind die Extents des angezeigten Kartenausschnitts.
*=13.473750 52.258125= Ist der Punkt in der Karte, der angeklickt worden ist. Dieser Punkt hat den Aufruf des MapServers verursacht.
*=bundeslaender= Eine Liste der angeforderten Layer, durch Leerzeichen voneinander getrennt.
*=normal execution= Ist alles glatt gelaufen, findet sich dieser Eintrag am Ende einer Zeile.

Für ausführlicheres Logging gibt es den Parameter =DEBUG= , der im Header, in Layern und in Classes definiert werden kann. Mit dieser Einstellung produzieren bisher allerdings im wesentlichen nur Raster- und WMS-konforme Layer ausführlichere Fehlermeldungen. Es steht zu erwarten, dass dieser Parameter noch weiter ausgebaut wird.

\subsubsection*{Log-Dateien im Webserver}

Neben den Logs des MapServers haben Sie im Fehlerfall natürlich immer noch die Logs Ihres Webservers zur Verfügung. Im Fehlerfall finden Sie hier auch die HTTP-Fehlercodes, die dann nützlich sind, wenn es nicht MapServer-Fehler sind, die Ihnen Probleme bereiten. Insbesondere bei der Apache-Fehlermeldung ''Internal Server Error'' finden Sie normalerweise detaillierte Einträge, die Ihnen helfen können, die Ursache des Problems schnell zu lokalisieren.

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 7

2009-01-23T10:22:11Z

Wiki-Mikee63: /* Werkzeuge der GDAL-Bibliothek */

= Zusätzliche Werkzeuge =

Viele kleine Werkzeuge stehen bereit, die das Drumherum um eine (potenzielle) MapServer-Anwendung anreichern. Und einige sind sogar ziemlich nützlich. Im folgenden sollen die Kommandozeilenwerkzeuge besprochen werden, die in den Quellcodepaketen der Shapelib, des MapServers und der Bibliothek GDAL bzw. OGR zu finden sind.

=Werkzeuge der Bibliothek Shapelib=\index{Shapelib}

Diese Bibliothek wird auch vom MapServer verwendet, nämlich um -- wenig überraschend -- mit Shapefiles umzugehen. Allerdings wird dabei keine im System installierte Shapelib benutzt. Der MapServer bringt die entsprechenden Dateien in seinem eigenen Quellcodepaket mit.

Das gilt jedoch leider nicht für die ganzen Werkzeuge der Shapelib. Möchte man also die Vorteile dieser kleinen Tools genießen, muß man es auf sich nehmen und die Shapelib extra kompilieren und installieren. Das ist schnell und einfach getan, indem man das Paket auspackt, in das neu entstandene Verzeichnis wechselt und mit

 <code>
# make
# cd contrib
# make
</code> 

das Ganze hinter sich bringt.

Man hat dann sowohl im Hauptverzeichnis des Quelltextes als auch im Unterverzeichnis =contrib= jeweils einige kleine Programme, die man sich an entsprechende Stellen im System kopieren muß. Das Verzeichnis =/usr/local/bin= kommt auf Unix-Systemen gerne zum Einsatz.

==shpdump==\index{shpdump}

Das Programm =shpdump= gibt den Inhalt eines Shapefiles in Textform auf der Kommandozeile aus. Das sieht für das Shapefile =lakespy2.shp= aus dem offiziellen Itasca-Demo beispielsweise folgendermaßen aus:

 <code>
# shpdump lakespy2.shp

Shapefile Type: Polygon # of Shapes: 1379

File Bounds: ( 393234.394, 5208170.531,0,0)
to ( 495403.171, 5303964.877,0,0)

Shape:0 (Polygon) nVertices=38, nParts=1
Bounds:( 404885.933, 5292677.993, 0, 0)
to ( 405418.198, 5293262.006, 0, 0)
( 405040.809, 5292726.997, 0, 0) Ring
( 404949.931, 5292756.498, 0, 0)
...
</code> 

Besonders schön ist die Angabe der Bounding Box ganz zu Beginn, da man auf diese Weise schnell die Extents eines Shapefiles in Erfahrung bringen kann.

==shpcreate, shpadd, dbfcreate und dbfadd==\index{shpcreate}\index{shpadd}\index{dbfcreate}\index{dbfadd}

Was diese Programme tun, kann man bereits aus ihrem Namen ersehen, und der geneigte Leser mag sich fragen, wer auf die Idee kommt, auf der Kommandozeile von Hand Shapefiles zu erstellen bzw. diesen Shapfiles von Hand Shapes hinzuzufügen?

Diese Frage fußt auf einem Mißverständnis, dem viele Menschen erliegen, die es nicht gewohnt sind, auf der Kommandozeile zu arbeiten. Tatsächlich benutzt man dieses Programm eher selten von Hand. Viel häufiger werden solche Werkzeuge als Kommandos in Skripten eingesetzt, wo sie ihre ganze Macht entfalten können.

Das Programm =shpcreate= erstellt eine neue Shapedatei, etwa folgendermaßen:

 <code>
# shpcreate bla.shp polygon
</code> 

Auf diese Weise wird ein leeres Polygon-Shapefile kreiert. Beachten Sie, dass das noch nicht die dazugehörige ''.dbf'' -Datei beinhaltet! Mögliche Shapefiletypen sind =point= , =arc= , =polygon= und =multipoint= .

Das hinzufügen von Punkten zu diesem neuen Shapefile ist ganz einfach:

 <code>
# shpadd bla.shp 1000 2000 2000 3000 3000 4000
</code> 

Dadurch wird dem Shapefile ein einzelnes Shape mit drei Punkten hinzugefügt.

Natürlich möchte man seinem Shapefile auch eine ''.dbf'' -Datei an die Seite stellen. Das kann mit =dbfcreate= geschehen:

 <code>
# dbfcreate bla.dbf -s NAME 20 -n FLAECHE 10 5
</code> 

Diese ''.dbf'' -Datei erhält zwei Spalten; als erstes eine 20 Zeichen große String-Spalte, und danach eine Spalte für numerische Einträge mit 10 Stellen, von denen 5 Nachkommastellen sind. Mehr Optionen gibt es für dieses Programm auch nicht.

Sodann sollen der Datei selbstverständlich auch Daten hinzufügen:

 <code>
# dbfadd bla.dbf Mesopotamien 20.4
</code> 

Auf diese Weise kann man beispielsweise Daten, die man aus anderen Datenquellen hat, bequem in einem Skript automatisch in ein Shapefile umwandeln.

==dbfdump==\index{dbfdump}

Diese kleine Tool macht für ''.dbf'' -Dateien überraschenderweise das, was =shpdump= für Shapefiles tut. Eine kleine Beispielausgabe anhand der Datei =airports.dbf= aus dem offiziellen Itasca-Demo:

 <code>
# dbfdump -h airports.dbf
Field 0: Type=String, Title=`NAME', Width=64, Decimals=0
Field 1: Type=Double, Title=`LAT', Width=12, Decimals=4
Field 2: Type=Double, Title=`LON', Width=12, Decimals=4
Field 3: Type=Double, Title=`ELEVATION', Width=12, Decimals=4
Field 4: Type=String, Title=`QUADNAME', Width=32, Decimals=0
NAME LAT LON ELEVATION QUADNAME
Bigfork Municipal Airport 47.7789 -93.6500 1343.0000 Effie
Bolduc Seaplane Base 47.5975 -93.4106 1325.0000 Balsam Lake
...
</code> 

Der Parameter =-h= weist das Programm an, zusätzlich noch die Header-Informationen für die Datei auszugeben.

==shpinfo==\index{shpinfo}

Dieses kleine Programm gibt einige grundlegende Informationen über ein Shapefile aus. Am Beispiel der Datei ''airports.shp'' aus dem offiziellen Itasca County-Demo:

 <code>
# shpinfo airports.shp
Info for airports.shp
Point(1), 12 Records in file
File Bounds: ( 0, 0)
( 496393, 5291930)
</code> 

Wir haben also ein Punkt-Shapefile mit 12 Shapes vor uns.

Beachten Sie, dass dieses Programm als minX/minY-Koordinaten selten etwas anderes ausgibt als 0/0, und für minimale Koordinaten daher nicht wirklich geeignet ist.

==dbfinfo==\index{dbfinfo}

Was ''shpinfo'' für Shapedateien ist, ist dieses Werkzeug für die dazugehörigen ''.dbf'' -Datensätze. Eine Beispielausgabe:

 <code>
# dbfinfo airports.dbf
Info for airports.dbf
5 Columns, 12 Records in file
NAME string (64,0)
LAT float (12,4)
LON float (12,4)
ELEVATION float (12,4)
QUADNAME string (32,0)
</code> 

=Werkzeuge des MapServers=

Nach dem Kompilieren des MapServers findet man im Quellverzeichnis das eine oder andere kleine Werkzeug. Zwei sollen uns im folgenden besonders interessieren.

==shp2img==\index{shp2img}

Dieses Programm ist im wesentlichen MapServer für die Kommandozeile. Der Aufruf sieht beispielsweise folgendermaßen aus:

 <code>
# shp2img -m mapfile.map -i PNG -e 13.0 44.5 33.3 59.6
</code> 

Dadurch wird das entsprechende Mapfile dazu benutzt, ein PNG-Bild mit den angegebenen Extents zu erzeugen. Die Kartendarstellung wird dabei aus =mapfile.amp= bezogen.

Sie können dieses Programm beispielsweise dann benutzen, wenn Sie keinen Zugriff auf einen im Webserver installierten MapServer haben können oder möchten. Es eignet vor allen Dingen zum Debuggen von Mapfiles auf Systemen ohne MapServer.

Alle möglichen Kommandozeileparameter werden durch einen Aufruf von =shp2img= ohne Optionen ausgegeben.

==shptree==\index{shptree}(2)

Wenn eine Karte gezeichnet werden soll, muß theoretisch jedes einzelne Shape in einem Shapefile darauf geprüft werden, ob es tatsächlich angezeigt werden soll. Das kann offensichtlich sehr zeitaufwendig sein.

Das Werkzeug ''shptree'' schafft hier Abhilfe, indem es einen so genannten Quadtree-Index über den Inhalt des Shapfiles erzeugt. Die Idee ist, dass man das gesamte Shapfile in vier verschiedene Gebiete zerlegt, die ihrerseits wiederum zerlegt werden, und so weiter. Diese Art der Zerlegung wird in einer Indexdatei mit der Endung ''.qix'' gespeichert.

Wenn nun eine Karte generiert werden soll, werden zuallererst Vergleiche mit dem Index angestellt, um herauszufinden, auf welche Shapes man sich bei der Darstellung überhaupt konzentrieren soll. Gerade bei großen Datenmengen kann sich die Geschwindigkeit des MapServers dabei signifikant erhöhen. Beachten Sie jedoch, dass sich dieser Index ausschließlich auf die Vektordaten im Shapfile bezieht und keine Geschwindigkeitsverbesserung für zum Beispiel Attributanfragen liefert.

Das Programm wird normalerweise sehr simpel angewendet:

 <code>
# shptree shapefile.shp
</code> 

Es gibt noch zwei weitere Optionen für das Programm, der genaue Aufruf wird definiert als

 <code>
shptree [shapefile] <tiefe> <byteorder>
</code> 

Mit Tiefe ist die Tiefe des Baumes gemeint, der erzeugt werden soll. Davon hat diese Art von Index auch ihren Namen. Man kann sich die Unterteilung des Shapfiles auch als Verzweigung in verschiedene Äste vorstellen, die sich dann wieder verzweigen und so weiter.

Die Byteorder ist eine kleine informatische Spezialität. Alle Daten werden als Bits gespeichert, und 8 solcher Bits werden zu einem Byte zusammengefaßt. 'Normale' ganzzahlige Werte sind auf Intel-Computern beispielsweise 4 Byte lang. Unterschiedlich ist aber nicht nur die Menge an Platz, die Zahlen einnehmen können, sondern auch wie sie abgespeichert werden. Ohne weiter ins Detail gehen zu wollen: es gibt verschiedene Ansätze, beispielsweise zuerst das niederwertigste Bit in einem Byte zu speichern und die anderen dahinter anzuordnen -- oder aber umgekehrt. Diese Ansätze unterscheiden sich von Plattform zu Plattform.

Rufen Sie einmal das Programm ohne jeden Parameter auf, um eine Liste der möglichen Byteorders zu Gesicht zu bekommen. Generell kann man sagen, dass es am sinnvollsten ist, keine Byteorder anzugeben und das Programm shptree ganz einfach einmal für alle Daten auf dem Zielsystem aufzurufen, dass die Applikation beherbergt.

''Hinweis'' : Beachten Sie bitte, das sich das Dateiformat der Indizes mit dem Versionssprung von MapServer von 3.6 auf 4.0 geändert hat, sodass die neue Version nicht mit Ihren alten Indizes anfangen kann. Erzeugen Sie bei einer Migration auf die neue Version Ihre Indizes neu.

==shptreevis==\index{shptreevis}

Ein kleines Visualisierungswerkzeug für die Indizes, die mit =shptree= erzeugt worden sind. Es erzeugt wiederum ein Shapefile, das die Gebiete, in die die indizierten Daten eingeteilt worden sind, enhält.

 <code>
# shptreevis shapefile neu.shp
</code> 

Sie können dieses Shapefile natürlich auch wieder als eigenen Layer in ihre Karte einbinden. Die Flächen in dem Shapefile befinden sich allesamt innerhalb der Extents der Ursprungskarte.

=Werkzeuge der GDAL-Bibliothek=

Aus der Vielzahl kleiner Werkzeuge der GDAL-Bibliothek sticht vor allen Dingen =gdaltindex= hervor, mit dem sich Kataloge für Rasterdaten erstellen lassen können.

==gdaltindex==(3)\index{gdaltindex}

Der Umgang mit Katalogen für Rasterdaten ist in Abschnitt~\ref{text:mapfile:catalogs} beschrieben. Das Format dieser Kataloge ist propretär, d.\,h. Sie werden wohl keine andere Software finden, die mit dieser Art von Katalog etwas anfangen kann.

Nehmen wir an, sie haben in einem Unterverzeichnis =luftbilder= einige Bilder im ''.tif'' -Format samt Worldfiles abgelegt, die Sie in einem Katalog zusammenfassen möchten. Der Aufruf von =gdaltindex= könnte dann zum Beispiel folgendermaßen aussehen:

 <code>
# gdaltindex -tileindex IMAGE index.shp luftbilder/*.tif
</code> 

Mit dem Parameter =tileindex= wird die Spalte in der ''.dbf'' -Datei bestimmt, die den Namen der Bild-Files enthalten soll. Es folgt der Name des zu erstellenden Index, und natürlich die Namen der georeferenzierten Daten, für die der Katalog erstellt werden soll.

Beachten Sie bitte, dass Sie auch nach Erstellung des Katalogs immer noch die Worldfiles für die Daten vorhalten müssen, obwohl ja eigentlich eben diese Angaben jetzt im Katalog stehen sollten.

Ebenfalls zu beachten sind =OFFSITE= -Angaben des Layers im Mapfile, in dem der Bildkatalog eingebunden werden soll. Da für diesen Parameter der Index der Farbe in der Farbpalette der Bilder angegeben werden muß, der transparent geschaltet werden soll, muß peinlichst genau darauf geachtet werden, dass alle Bilder im Katalog die gleiche Farbpalette haben, beziehungsweise dass sie alle die transparente Farbe an der gleichen Stelle in der Palette haben müssen.

\chapter{FAQ}\index{FAQ}(1)

=fehlermeldungen=

==projection: system file not found==

=verhalten=

==kein bild im browser==

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 7

2009-01-23T10:21:47Z

Wiki-Mikee63: /* Werkzeuge des MapServers */

HBUMNMapServer ger Capter 7

2009-01-23T10:20:29Z

Wiki-Mikee63: /* Zusätzliche Werkzeuge */

HBUMNMapServer ger Capter 6

2009-01-23T10:17:59Z

Wiki-Mikee63: /* Formulareingaben in PHP verarbeiten */

= MapScript =
(1)\index{MapScript}

Bisher haben Sie den MapServer als Applikation kennengelernt, die in einem Webserver wie zum Beispiel Apache arbeitet, und direkt über Parameter des URL aufgerufen und in ihrem Verhalten beeinflußt werden kann.

Man kann sich aber natürlich auch vorstellen, die Funktionen von MapServer -- das Lesen von Mapfiles, das Rendern der Karten und so weiter -- auch aus eigenen Programmen nutzen zu wollen, natürlich auch solchen, die nicht in einem Webserver laufen sollen. Dazu müßte man diese Funktionen separat zur Verfügung stellen, beispielsweise in einer eigenen Bibliothek, auf die dann aus anderen Programmiersprachen zugegriffen werden kann. Diese Bibliothek existiert bereits und trägt den Namen MapScript.

Zu den Sprachen wie Java, Python, Perl und einigen anderen, die mit MapScript benutzt werden können, gesellt sich auch PHP. PHP MapScript soll im Folgenden als Anknüpfungspunkt für die Erklärung von MapScript dienen -- die genaue Terminologie für einzelne Programmiersprachen entnehmen Sie bitte der jeweilgen Dokumentation der Sprache bzw. den Beispielen, die dem MapServer-Quellcode beiliegen.

=PHP MapScript=(2)\index{PHP MapScript}\index{MapScript!PHP}

Ich erspare dem Leser die an dieser Stelle üblichen Hymnen auf PHP\footnote{Beziehungsweise die üblichen Flames. Die Sprache ist definitiv nichts für Puristen oder Entwickler mit eng gesteckten Vorgaben, was den Resourcenverbrauch angeht.} und seine Flexibilität als Sprache für Webanwendungen. Es ist in der Tat sehr weit verbreitet. Das ist (neben der besonderen Pflege, die gerade diese Sprachanbindung erfährt) auch der Grund, warum wir an dieser Stelle detailliert auf PHP MapScript eingehen, und nicht beispielsweise auf Perl.

An dieser Stelle gehen wir nicht darauf ein, wie Sie PHP installieren, oder wie Sie Ihren Webserver korrekt für den Einsatz von PHP konfigurieren. Wie man das tut, erfahren Sie in der Dokumentation von PHP bzw. Ihres Webservers. Die Installation von PHP MapScript wird im Anhang dieses Handbuches abgehandelt.

Beachten Sie bitte, dass PHP MapScript im Moment zwingend voraussetzt, dass Sie PHP ''nicht'' als Modul laden, sondern als CGI-Programm einsetzen. Es kann ansonsten zu nicht vorhersehbaren Komplikationen kommen.

Als erstes deutschsprachiges Einsteigerbuch zu PHP eignet sich beispielsweise~[[theis:2000:php]]; allerdings gibt es eine solche Unzahl an Büchern über diese Sprache, dass eine persönliche Auswahl im Buchladen erfolgen sollte. Die Website zur PHP [[http:website:php]] stellt ausführliche Dokumentation bereits, die interessanterweise auch vollständig ins deutsche übersetzt ist.

Des weiteren ist es eine gute Idee, sich mit der FAQ von =de.comp.lang.php= ~[[faq:dclp]] auseinanderzusetzen, der deutschsprachigen Newsgroup zu PHP, die in einem eigenen Kapitel auch auf Sicherheitsbelange eingeht.

\begin{figure}
\begin{center}
\mmfig{0.75}{mapscript-hyk}{Ein Beispiel für eine PHP MapScript Anwendung sind die Hydrogeologischen Karten Brandenburg}
\end{center}
\end{figure}

==Laden des Moduls==

Um die MapScript-Funktionen in einer PHP-Seite verwenden zu können, muss das Modul dafür geladen werden. Das geschieht ganz einfach durch ''dl'' :

 <code>
dl ("php_mapscript.so");
</code> 

Dies sollte die erste Zeile sein, die Sie in jede Seite einfügen, die MapScript-Funktionen benutzt. Sollten Sie sich unter Windows befinden, ändert sich diese Zeile leicht in:

 <code>
dl ("php_mapscript.dll");
</code> 

Falls Sie eine portable Anwendung schreiben sollen, ist es demnach angebracht, gleich zu Beginn des Skripts auf das verwendete Betriebssystem zu prüfen und dann die korrekte Datei zu laden.

==Setzen von Objekt-Eigenschaften==

Bevor Sie auch nur eine einzige Klasse aus MapScript kennenlernen, möchte ich zeigen, wie man die Eigenschaften von Objekten setzt, da diese Methode für alle Objekte (die sie unterstützen) gleich ist.

Ein Beispiel:

 <code>
<math>layer -> set ("name", "gruenflaechen");
</code> 

Mit diesem Aufruf wird der Name eines Layer-Objektes auf =gruenflaechen= gesetzt.

Der 'korrekte' objektorientierte Ansatz wäre natürlich gewesen, dafür eine eigene Routine =setName()= zu implementieren. Da einige Klassen in MapScript jedoch über eine ziemlich große Anzahl an Eigenschaften verfügen, hat man sich auf diese Methode beschränkt.

Das Setzen von Eigenschaften auf diese Weise funktioniert nur für Eigenschaften, die nicht =read-only= sind. Nicht jedes Objekt implementiert zudem die =set()= -Methode. In der Referenz im Anhang dieses Handbuchs sehen Sie, welche Klasse eine solche Methode zur Verfügung stellt.

Darüber hinaus haben einige Klassen für einige Eigenschaften doch noch eigene Methoden implementiert. Studieren Sie die Referenz im Anhang, um herauszufinden, für welche Klassen und Eigenschaften das gilt.

==Formulareingaben in PHP verarbeiten==

In älteren PHP-Versionen war es kein Problem, URL-Parameter einfach als Variable in ein PHP-Skript zu übernehmen. Wenn ein Aufruf also etwa so aussah:

 <code>
.../skript.php?name=Calli
</code> 

Dann konnte man ohne Probleme das folgende in sein Skript schreiben:

 <code>
echo </math>name;
</code> 

Das produzierte dann die Ausgabe =Calli= .

In neueren Fassungen von PHP\footnote{Und aufgrund der bekannt gewordenen Sicherheitslücken möchte man eine alte Version nicht benutzen. Verwenden Sie nichts unter 4.3.3!} geht das so nicht mehr. Weil es durch diverse Tricksereien möglich war, globale PHP-Variablen von außen zu überschreiben, und weil man die Programmierer zwingen wollte, sich mit den Werten in ihren Variablen genauer zu befassen, muß man sich jeden Wert nun explizit aus einem Array holen, das den Namen =\<math>_GET[]= trägt.

Für unser obiges Beispiel benötigen Sie dann also folgendes:

 <code>
<math>dername = </math>_GET ['name'];
echo </math>dername;
</code> 

Manchmal werden durch eine Eingabemöglichkeit in einem HTML-Formular mehrere Werte übergeben. Ein Beispiel dafür ist ein angeklicktes Bild, wie es etwa unsere Karte ist -- ein Klick produziert natürlich eine X- und eine Y-Koordinate. PHP verhält sich an dieser Stelle etwas unerwartet. Betrachten wir das folgende Bild in einem HTML-Formular:

 <code>
<input type="image" name="img" src="[img]">
</code> 

Nach einem Klick finden Sie im URL zwei Werte, namentlich =img.x= und =img.y= . Diese beiden Variablen werden Sie aber im Array =\<math>_GET[]= vergeblich suchen, denn für PHP werden die Punkte durch Unterstriche ersetzt. Sie müssen sich also =img_x= und =img_y= aus dem Array holen.

Es ist übrigens immer angezeigt, den Wert jeder Variablen, die von außen belegt wird, eingehend auf seine Sinnhaftigkeit zu prüfen.

==Die mapObj-Klasse==\index{Mapscript!mapObj}\index{mapObj}

Als nächstes möchten wir betrachten, wie MapScript ein Mapfile behandelt. Betrachten Sie das erste Beispiel:

 <code>
</math>map = ms_newMapObj ("/path/to/mapfile.map");
<math>image = </math>map -> draw ();
<math>imageurl = </math>image -> saveWebImage (MS_PNG, 1, 1, 0);
</code> 

In der ersten Zeile wird ein =mapObj= erzeugt, das auf ein bereits existentes Mapfile zugreift. Danach wird daraus ein =ImageObj= erzeugt, es wird also die Karte gezeichnet. Dabei werden die gesetzten Werte für die Extents aus dem Mapfile übernommen.

Beachten Sie bitte, dass dadurch noch keine fertige Bild''datei'' erzeugt wird. Die Karte existiert zu diesem Zeitpunkt nur als Puffer im Speicher.

In einer Datei tatsächlich gespeichert wird das Bild in der letzten Zeile, in unserem Beispiel als Bild im PNG-Format. Die Rückgabe der Funktion ist der URL für den Webserver, unter der er das Bild ausliefern kann.

Man kann daher weiter unten in der Seite folgendes HTML verwenden:

 <code>
<html>
<head><title>Beispiel</title></head>
<body>
<img src="<?php echo <math>imageurl; ?>">
</body>
</html>
</code> 

Dadurch wird der betreffende URL in den =<img>= -Tag eingefügt und an den Client ausgeliefert. Das Resultat ist natürlich ein zentriertes Bild der Karte im Webbrowser.

Auf die gleiche Weise werden übrigens auch Legenden, Maßstäbe und Referenzkarten erzeugt:

 <code>
<math>img_legend = </math>map -> drawLegend ();
<math>img_scalebar = </math>map -> drawScaleBar ();
<math>img_refmap = </math>map -> drawReferenceMap ();
</code> 

Auch diese Bildobjekte werden wieder über deren Methode =saveWebImage= abgespeichert.

\subsubsection*{Zoomen}

Das Zoomen in eine Karte kann auf drei Weisen geschehen: Zoomen in Richtung eines Punktes, Zoomen auf ein Rechteck und Zoomen auf einen Punkt in einem bestimmten Maßstab.

Betrachten wir den ersten Fall. Wir gehen davon aus, dass wir ein Bild in einem HTML-Formular eingebettet hatten, und dieses Bild wie gerade beschrieben per PHP Mapscript erzeugt hatten. Wurde das Bild angeklickt, werden die Pixelkoordinaten des Klicks über das Formular mit übergeben. Gehen wir von einem festen Zoomfaktor von 2 aus (diesen Wert legen wir für dieses Beispiel jetzt fest), können wir mit diesen Pixeln folgendes tun:

 <code>
</math>map = ms_newMapObj ("/path/to/file.map");
<math>map -> zoomPoint (2, </math>imgxy, <math>breite, </math>hoehe, <math>extent);
<math>img = </math>map -> draw ();
...
</code> 

Das Mapfile wird in seinem ursprünglichen Zustand geladen. Dann werden der Zoomfunktion die nötigen Parameter übergeben: zuerst der Zoomfaktor, den wir hier mit 2 festlegen, aber natürlich auch im Formular einstellen lassen können. Der folgende Wert ist ein pointObj, das die Bildkoordinaten des angeklickten Punktes darstellt. Falls Sie mit diesen Werten irgendwelche Berechnungen anstellen wollen, beachten Sie, dass der Ursprung der Grafik auf dem Bildschirm in der linken oberen Ecke ist.

Breite und Höhe beziehen sich auf das Bild und sind Pixel-Werte. Der Extent (als rectObj) ist schließlich die Bounding Box der Karte in ihrem jeweiligen Koordinatensystem.

Als letzten Wert könnte man übrigens noch ein weiteres rectObj angeben, dass den maximalen Extent angibt, der beim Zoomen nicht verlassen werden darf. Diesen Aufwand muß man aber nicht unbedingt treiben, da das Schlüsselwort =MAXSCALE= in der Web-Sektion das gleiche leistet.

Im Grunde machen alle Zoomfunktionen nichts anderes, als neue Extents für einen Kartenausschnitt festzulegen. Das bedeutet aber auch, dass Ihre Applikation durcheinander kommen kann, wenn sie beispielsweise gleichzeitig die Möglichkeit zum Zoomen und zum Ändern der Größe der Karte anbietet. Stellen Sie in Ihrem Code sicher, dass Sie in einem solchen Fall zuerst die Änderung des Ausschnitts vornehmen (z.B. Zoomen) und erst danach die Werte für die Kartengeometrie setzen (zum Beispiel Höhe und Breite der Karte).

Das ''Zoomen auf ein Rechteck'' gestaltet sich ähnlich. Über normale Anwendungen im Webbrowser lassen sich zwei angeklickte Punkte nicht übertragen. Diese Funktion kommt also dann zum Tragen, wenn man mit JavaScript oder wie auch immer ein Rechteck aufziehen und entsprechende Werte übergeben kann.

Der aufmerksame Leser kommt natürlich auch auf die Idee, diese Funktion zu benutzen, wenn er auf ein bestimmtes Feature zoomen möchte. Man bestimme dann die Extents des betreffendes Shapes (das geht auch mit MapScript, siehe weiter unten) und zoomt eben auf diese.

Dummerweise geht das nur, wenn man die ''Pixel'' -Koordinaten des Rechtecks kennt, denn die Funktion =zoomRectangle= wird folgendermaßen genutzt:

 <code>
</math>map = ms_newMapObj ("/path/to/mapfile.map");
<math>map -> zoomRectangle (</math>pixext, <math>breite, </math>hoehe, <math>extent);
</code> 

Der erste Parameter ist wieder ein rectObj; er gibt die Pixelkoordinaten des Rechtecks an, auf die gezoomt werden soll. Die Breite und die Höhe sind ebenfalls Pixelangaben im Bild. Die Extents schließlich sind wieder ein RectObj, das diesmal die Bounding Box der Karte im Bild im entsprechenden Koordinatensystem angibt.

Wenn Sie einfach auf bestimmte Extents zoomen wollen, ohne vorher in Besitz von Pixelkoordinaten und so weiter zu sein, dann können Sie einfach das Mapfile laden und diese neuen Extents setzen:

 <code>
</math>map = ms_newMapObj ("/path/to/mapfile.map");
<math>map -> setExtent (</math>minx, <math>miny, </math>maxx, <math>maxy);
</math>map -> draw ();
</code> 

Warum diese Methode vier einzelne Koordinaten erwartet und kein RectObj, können wir leider nicht erklären.

Die letzte Zoommethode schließlich ist =zoomScale= :

 <code>
<math>map = ms_newMapObj ("/path/to/mapfile.map");
<math>map -> zoomScale (100000, </math>imgxy, <math>breite, </math>hoehe, </math>extent);
</code> 

Der erste Wert ist ein SCALE, wie er bereits auf Seite~\pageref{text:mapfile:scale} besprochen worden ist. Beachten Sie bitte, dass so ein Maßstab nicht viel mit dem Maßstab auf einer gedruckten Karte zu tun hat.

Die restlichen Parameter sind wieder die Pixelkoordinaten des Mausklicks, Höhe und Breite des Bildes in Pixeln sowie die Extents des Kartenausschnitts. Auch bei dieser Funktion läßt sich als letzter Parameter wieder als rectObj ein Ausschnitt angeben, aus dem nicht herausgezoomt werden darf.

\subsubsection*{Weitere Eigenschaften und Methoden}

Die restlichen Eigenschaften des mapObj-Objektes dienen dazu, Informationen beziehungsweise Referenzen auf andere Objekte aus dem Mapfile zu ziehen; aber auch, Queries auszuführen. Mehr zu Queries in PHP erfahren Sie weiter unten in dem Abschnitt über Layer. Sie finden die Queries dort (und nicht hier im mapObj, wo sie ausgeführt werden), da die Resultate auf Layer-Ebene eingeholt werden.

Alle weiteren Methoden und Eigenschaften, die mapObj bietet, sind im Anhang ab Seite~\pageref{ref:phpms:mapobj} aufgelistet.

==Fehlerbehandlung==(3)

Jetzt da Sie ein Gefühl dafür haben, wie man Objekte in PHP MapScript anspricht, sollen Sie etwas über die Wege der Fehlerbehandling erfahren, die mit MapServer 4.0 dazugekommen ist.

Bisher sind Fehler einfach aufgetreten und haben meist den weiteren Ablauf des Skripts abgebrochen. Das kann eventuell nicht erwünscht sein; so wäre es zum Beispiel vorstellbar, dass eine Datenbank, die räumliche Daten für einen Layer Ihrer Applikation vorhält, nicht erreichbar ist. Anstatt nun einfach mit einem Fehler abzubrechen, wäre es natürlich angenehmer, wenn man beim Auftreten eines Fehlers dessen Ursache prüfen könnte, nd dann über das weitere Vorgehen entscheiden könnte.

Dieses Vorgehen wird in MapScript 4.0 mit dem neuen Objekt =errorObj= umgesetzt. Dabei werden Fehler bei ihrem Auftreten in eine interne Liste eingefügt. Aus dieser Liste können sie sodann zu einem Zeitpunkt nach Wahl des Programmierers entnommen und verarbeitet werden.

Schauen wir uns das Beispiel von der offiziellen MapServer-Dokumentationsseite an:

 <code>
ms_resetErrorList ();
<math>img = </math>map -> draw ();
<math>error = ms_getErrorObj ();
while (<math>error && </math>error -> code != MS_NOERR) {
printf ("Error in
<math>error -> routine, </math>error -> message);
<math>error = </math>error -> next ();
}
</code> 

Zuerst sollten Sie zu Beginn jedes Skriptes die Fehlerliste zurücksetzen; das passiert hier in der ersten Zeile.

Danach holt man sich das globale Fehlerobjekt, über welches dann iteriert wird. Für jeden erzeugten Fehler wird dessen Eigenschaft =code= abgefragt. Dieser Code ist eine aus einer Liste von Fehlerkonstanten. Falls es sich tatsächlich um einen Fehler handelt -- auch keine Fehler ist ein Fehler, allerdings einer vom Typ =MS_NOERR= wird eine entsprechende Fehlermeldung ausgegeben. Danach wird zum nächsten unbearbeiteten Fehler in der Liste gesprungen.

Beachten Sie bitte, dass Sie nach der Abfrage des nächsten Fehlers keine Möglichkeit mehr haben, zu bereits abgearbeiteten Fehlern zurückzukehren.

Sie finden alle Details zu =errorObj= in der Referenz ab Seite~\pageref{ref:phpms:errorobj}. Die möglichen Fehlercodes sind außerdem Bestandteil von Tabelle~\ref{tab:ref:mapscript:const}, die auf Seite~\pageref{tab:ref:mapscript:const} beginnt.

==Die layerObj-Klasse==\index{Mapscript!layerObj}\index{layerObj}

Dieses Objekt läßt Sie auf alle Bestandteile einer Layer-Sektion im Mapfile zugreifen.

Dafür müssen Sie natürlich erst einmal wissen, welche Layer sich in einem gegebenen Mapfile befinden. Natürlich könnte man einfach alle Namen in seinem Script hartkodieren. Allerdings kommt man dann schnell in Bedrängnis, wenn sich am Mapfile etwas ändert. Außerdem läßt sich auf diese Weise keine Software schreiben, die sich mit beliebigen Mapfiles auseinandersetzt.

Zuerst einmal können alle Layer in einem Mapfile durch einen Index angesprochen werden, der ihrer Position im Mapfile entspricht. Der erste Layer erhält dabei den Index =0= , der zweite den Index =1= und so weiter\footnote{Informatiker beginnen immer bei Null mit dem Zählen, nicht bei Eins. Das liegt daran, dass sie sich bei Listen und so weiter nicht dafür interessieren, welche Position ein Element absolut besitzt, sondern welchen Abstand vom Beginn der Liste. Und der ist für das erste Element Null, und so weiter.}. Mit einer Schleife, die über die Anzahl der Layer läuft, kann man also beispielsweise folgendes machen:

 <code>
<math>num = </math>map -> numlayers;
for (<math>i = 0; </math>i < numlayers; </math>i++) {
<math>layer = </math>map -> getlayer (<math>i);
... jetzt passieren Dinge mit </math>layer ...
}
</code> 

Man kann die Layer aber auch über Ihren Namen ansprechen. Dabei holt man sich zuerst alle Layer-Namen via =getAllLayerNames()= aus dem mapObj (man erhält ein Array aller Namen zurück), und spricht dann die Layer einzeln mit =getLayerByName()= an.

Die häufigste Aktion mit einem Layer ist, Queries auszuführen, beziehungsweise danach Query-Ergebnisse aus ihm herauszuholen.

===Queries auf Layer===

Queries liefern seit Version~{3.5} des MapServers keine Objekte vom Type resultObj mehr direkt zurück. Vielmehr werden die Ergebnisse von Queries nun in den Layer-Objekte festgehalten.

Damit Anfragen auf einen Layer gemacht werden können, muß dieser im Mapfile einen =TEMPLATE= -Eintrag besitzen. Dieser Eintrag kann durchaus leer sein. Alternativ zur Angabe auf Layer-Ebene kann =TEMPLATE= auch nur in einigen (oder allen) =CLASS= es des Mapfiles stehen. Die Queries werden dann nur auf Mitglieder dieser Klasse angewendet.

Am häufigsten werden Queries auf einem mapObj ausgeführt; alle Query-Funktionen lassen sich jedoch auch auf einzelne Layer anwenden. Werden Queries auf mapObj-Objekte angewendet, werden einfach alle in Frage kommenden Layer der Reihe nach mit der entsprechenden Funktion bedacht.

Queries können auf drei verschiedene Weisen ausgeführt werden: an bestimmten Punkten, mit Hilfe eines Rechtecks und, ganz neu, anhand beliebiger Shapes. Doch wir beginnen mit den Punkt-Queries.

Betrachten Sie folgendes Beispiel:

 <code>
<math>punkt = ms_newPointObj ();
</math>punkt -> setXY (300000, 500000);
<math>layer -> queryByPoint (</math>punkt, MS_SINGLE, -1);
</code> 

Hier wird zuerst ein Punkt-Objekt aus den Koordinaten gebaut, die abgefragt werden sollen. Für gewöhnlich kommen diese Koordinaten durch einen Mausklick auf ein Bild in einem Formular zustande. Beachten Sie bitte, dass dieser Punkt im =Koordinatensystem der Karte= vorliegen muß; die Pixelwerte eines Mausklicks auf eine Karte müssen Sie also zuerst in passende Werte umrechnen.

Danach wird auf dem gewünschten Layer eine Query durchgeführt. Dazu wird der Punkt übergeben, die Art der Anfrage (hier soll nur ein einzelnes Ergebnis erzeugt werden; mit =MS_MULTIPLE= wären mehrere Ergebnisse möglich), und schließlich ein Puffer. Dieser Puffer ist ein Radius um den Abfragepunkt herum, in den Einheiten der Karte. Ein negativer Wert führt dazu, dass der im Mapfile gesetzte Wert verwendet wird.

Bevor man sich auf eventuelle Resultate stürzt, sollte man prüfen, ob es überhaupt Resultate gab -- die Anfrage kann schließlich auch ins Leere gegangen sein. Dazu prüft man den Rückgabewert der Funktion. Ist dieser =MS_SUCCESS= , so ist alles in Ordnung und man kann fortfahren. Trifft man auf =MS_FAILURE= , so gab es keine Ergebnisse.

Etwas problematisch ist, dass alle Query-Funktionen auch Fehlernachrichten produzieren, wann immer es keine Resultate gab. Dieses Verhalten läßt sich für einzelne Funktionen jedoch mit einem vorangestellten =@= abstellen. Ein korrekterer Aufruf der obigen Funktion wäre also:

 <code>
if ((<math>layer -> @queryByPoint (</math>punkt, MS_SINGLE, -1))
== MS_SUCCESS) {
... es gab Ergebnisse ...
} else {
... Fehlerbehandlung ...
}
</code> 

Jetzt können wir uns endlich mit dem Ergebnis des Mausklicks auseinandersetzen. Oder besser: mit den Ergebnissen, denn es können ja mehre sein. Mit =getnumresult()= bringen wir die Anzahl der Resultate eines Layers in Erfahrung; haben wir nur ein Resultat, ist das nicht nötig. Dieses eine Resultat hat immer den Index =0= :

 <code>
<math>resultat = </math>layer -> getResult (0);
<math>si = </math>resultat -> shapeindex;
<math>ti = </math>resultat -> tileindex;
<math>ti = </math>resultat -> classindex;
</code> 

Das Resultat-Objekt besitzt also drei Eigenschaften: einen Shapeindex, der die Nummer des Shapes im Shapefile angibt, das dem Layer zugrunde liegt; einen Tileindex, der für gekachelte Shapefiles angibt, in welcher Kachel das Ergebnis aufgetreten ist; und schließlich einen Classindex, der die Class im Layer bezeichnet, für den das Ergebnis aufgetreten ist.

Mit diesen Angaben können Sie dann verfahren, wie Sie es für richtig halten. Sie können zum Beispiel die Daten aus dem =.dbf= -File herausfischen, die dem Shape zugrunde liegen\footnote{Beachten Sie an dieser Stelle die eigenwillige Zählweise in =.dbf= -Dateien, die auch in PHP übernommen wurde: die Zeilen in einer solche Datei sind nicht bei 0 beginnend durchnummeriert, sondern bei 1}. Sie könnten beispielsweise auch auf das gesuchte Shape heranzoomen, indem Sie anhand des gefundenen Index die Bounding Box des Shapes aus dem Shapefile auslesen (siehe auch shapefileObj weiter unten) und diese Bounding Box als neue Extents für die Karte setzen.

Von den einfachen Punkt-Queries kann man nun voranschreiten zu den Anfragen, die über ein Rechteck definiert sind:

 <code>
<math>layer -> queryByRect (</math>rechteck);
</code> 

Das Rechteck ist dabei ein rectObj, wie es weiter unten im Text besprochen wird. Die restliche Vorgehensweise entspricht exakt demjenigen bei Punktabfragen.

Hinweise: Rechtecke lassen sich in "`normalem"' HTML nicht erzeugen. Mit JavaScript oder dem ROSA-Applet sieht das schon wieder anders aus. Beachten Sie aber, dass insbesondere öffentliche Institutionen unter Umständen äußerst restriktive Bestimmungen haben, was den Einsatz von JavaScript, dynamischem HTML, Java und so weiter angeht. Auch sicherheitsbewußte Privatanwender haben JavaScript erst gar nicht aktiviert. Überdenken Sie den Einsatz dieser Technologien.

Das gilt auch für die folgende Weise, Queries zu stellen, nämlich anhand eines Shapes, also eines beliebigen Polygons:

 <code>
<math>layer -> queryByShape (</math>shape);
</code> 

Diese Art der Query entfaltet Ihren Nutzen weniger anhand von Punkten, die in einem Web-Interface ausgewählt werden können, als vielmehr beim Vergleich von Shapes mit Shapes aus einem anderen Shapefile: wenn Sie beispielsweise ein Shapefile mit Bundesländern haben und eines, indem ohne eine solche Referenzierung Angaben von Verkaufszahlen gespeichert sind, dann lassen sich durch den 'Verschnitt' beider Daten aussagekräftige Ergebnisse erzeugen.

Wie man mit MapScript einzelne Shapes aus einem Shapefile extrahiert erfahren Sie weiter unten bei der Besprechung von shapefileObj. Ein schneller Weg involviert allerdings die Methode =getShape()= , die bereits auf der Ebene des Layers vorhanden ist.

\subsubsection*{Weitere Eigenschaften und Methoden}

Die weiteren Funktionen in layerObj dienen im wesentlichen dazu, Zugriff auf die einzelnen Werte eines Layers zu erhalten, beziehungsweise auf die weiteren Objekte darin bezug nehmen zu können, insbesondere auf die Classes im Layer.

Alle weiteren Methoden und Eigenschaften, die layerObj bietet, sind im Anhang ab Seite~\ref{ref:phpms:layerobj} aufgelistet.

==Die classObj-Klasse==\index{Mapscript!classObj}\index{classObj}

Dieses Objekt entspricht einer Class innerhalb eines Layers. Mit einem classObj können Sie im wesentlichen Farben und Symbole für eine Class setzen -- insbesondere aber die Expressions für eine Class.

Ein Beispiel, wie man das verwenden kann: Nehmen wir an, Sie haben einen Datenbestand, der Ihnen die Deutschland in lauter kleine Gebiete einteilt. In der dazu gehörigen ''.dbf'' -Datei haben Sie in einer Spalte für jedes Gebiet den prozentualen Anteil an Waldfläche gespeichert. Diese Spalte trägt den Namen =WALD= .

In Ihrer Applikation haben Sie nun ein Eingabefeld, das es dem Benutzer ermöglicht, eine Anzahl von Grün-Abstufungen zu bestimmen, in die der Layer eingeteilt werden soll. Gibt der Benutzer beispielsweise =4= ein, werden dem Layer vier Klassen hinzugefügt, die von grün bis weiß vier Farbstufen annehmen.

Sie errechnen in der PHP-Seite dann die Unterteilung in vier Grünstufen und setzen vier verschiedene Classes.

==Die imageObj-Klasse==\index{Mapscript!imageObj}\index{imageObj}

Diese Objekte werden niemals 'von Hand' erzeugt, sondern immer nur durch den Aufruf von Methoden anderer MapScript-Objekte. Bei diesen Image-Objekten handelt es sich nicht um Bild-Dateien, sondern lediglich um die Bilddaten, die in einem Puffer im Speicher liegen und noch darauf warten, gespeichert zu werden.

Alle =draw= -Methoden von mapObj erzeugen ein imageObj. Am häufigsten wird danach die Methode =saveWebImage()= aufgerufen:

 <code>
<math>image = </math>map -> draw ();
<math>url = </math>image -> saveWebImage (MS_JPEG, 0, 0, 90);
</code> 

Der erste Parameter der Methode ist das gewünschte Bildformat, das meistens =MS_PNG= sein wird, ab und zu =MS_JPEG= und nur, wenn es sich nicht vermeiden läßt, =MS_GIF= .

Die beiden folgenden Parameter legen eine Transparenz der Hintergrundfarbe bzw. ein Interlacing für das Bild fest. Der letzte (optionale) Parameter legt für Bildformate, die eine Kompression zur Verfügung stellen, den Grad dieser Kompression fest. Werte zwischen 0 und 100 sind hier möglich.

Eine vollständige Aufzählung aller Methoden dieses Objektes finden Sie im Anhang ab Seite~\pageref{ref:phpms:imageobj}.

==Die labelObj-Klasse==\index{Mapscript!labelObj}\index{labelObj}

Labels befinden sich innerhalb von classObj-Objekten. Diese Klasse kennt erstaunlicherweise keine einzige Methode außer =set()= , dafür eine große Menge von Eigenschaften. In der Referenz finden Sie ab Seite~\pageref{ref:phpms:labelobj} eine ausführliche Aufzählung.

Das bedeutet übrigens auch, dass es keinen Konstruktor für diese Klasse gibt und demnach keine Möglichkeit, ein labelObj 'von Hand' zu erstellen.

==Die webObj-Klasse==\index{Mapscript!webObj}\index{webObj}

Ebenso wie beim labelObj gibt es auch für diese Klasse keinen Konstruktor und keine weiteren Methoden neben der =set()= -Methode. In der Referenz im Anhang finden Sie ab Seite~\pageref{ref:phpms:webobj} eine Liste aller Eigenschaften dieser Klasse.

webObj-Objekte finden Sie immer als Bestandteil eines mapObj.

==Die referenceMapObj-Klasse==\index{Mapscript!referenceMapObj}\index{referenceMapObj}

Auch Objekte dieser Klasse kommen nur innerhalb eines mapObj vor, es gibt keinen Konstruktor und keine Methode außerhalb von =set()= .

In der Referenz ab Seite~\pageref{ref:phpms:referencemapobj} finden Sie eine Liste aller Eigenschaften dieser Klasse.

==Die colorObj-Klasse==\index{Mapscript!colorObj}\index{colorObj}

Jede Karte verfügt über eine bestimmte Farbpalette. Diese Palette wird beim Generieren der Karte erstellt.

Neue Farben lassen sich der Palette hinzufügen, indem man Objekte der Klasse colorObj erzeugt:

 <code>
<math>weiss = ms_newColorObj ();
</math>weiss -> setRGB (255, 255, 255);
</code> 

Diese Farbe kann dann an den Stellen, wo es möglich und nötig ist, verwendet werden.

==Die pointObj-Klasse==\index{Mapscript!pointObj}\index{pointObj}

Punkte werden an diversen Stellen in MapScript für verschiedene Dinge benötigt. Wann immer eine Funktion die zwei Koordinaten eines Punktes übergeben bekommt, wird ein pointObj verlangt. Sehen Sie sich beispielsweise die Verwendung von =queryByPoint= im Abschnitt über das Objekt =layerObj= an.

Dieses Objekt besitzt aber noch einige andere Methoden in MapScript. Insbesondere kann man damit die Abstände von Punkten zu anderen Punkten, zu Linien und zu Polygonen bestimmen; außerdem lassen sich einzelne Punkte mithilfe von Objekten der Klasse projectionObj projizieren. Des weiteren kann man einzelne Punkte aus Linien-Objekten extrahieren (siehe lineObj).

pointObj gehört zu den Klassen, deren Speicher nach Gebrauch explizit freigegeben werden muß (siehe Seite~\pageref{text:mapscript:memory}).

Die Referenz zu allen Methoden von pointObj finden Sie auf Seite~\pageref{ref:phpms:pointobj}.

==Die lineObj-Klasse==\index{Mapscript!lineObj}\index{lineObj}

Linien lassen sich entweder von Hand konstruieren (indem man der Reihe nach einzelne Punkte hinzufügt), oder aber aus Shapes der Klasse shapeObj extrahieren. Außerdem lassen sich Linien natürlich ebenfalls projizieren.

lineObj gehört zu den Klassen, deren Speicher nach Gebrauch explizit freigegeben werden muß (siehe Seite~\pageref{text:mapscript:memory}).

Die Referenz zu allen Methoden von lineObj finden Sie auf Seite~\pageref{ref:phpms:lineobj}.

==Die projectionObj-Klasse==\index{Mapscript!projectionObj}\index{projectionObj}

Dieses Objekt beschreibt einen Projektions-Abschnitt in einem Mapfile. Aber es kann auch jenseits von Mapfiles verwendet werden, um einzelne Punktkoordinaten umzuprojizieren.

\subsubsection*{Beispiel}

Dieses Beispiel projiziert einen einzelnen Punkt von einer Längen-/Breitenangabe in einen Punkt im UTM 32-System:

 <code>
<math>projin = ms_newProjectionObj ("proj=latlong");
</math>projout = ms_newProjectionObj ("proj=utm,zone=32,ellps=WGS84,
datum=WGS84,no_defs");
<math>punkt = ms_newPointObj ();
</math>punkt -> setXY (32.0, 51.0);
<math>punkt = </math>punkt -> project ();
printf ("
</code> 

Die genauen Parameter, die Sie für die von Ihnen gewünschte Projektion verwenden müssen, finden Sie in der Dokumentation der Projektionsbibliothek proj.4.

==Die shapefileObj-Klasse==\index{Mapscript!shapefileObj}\index{shapefileObj}

Diese Klasse dient dazu, Shapefiles direkt manipulieren zu können. Sie können ein Shapefile als Objekt öffnen, einzelne Shapes referenzieren, die Eigenschaften des Shapefiles auslesen und sogar neue Shapes an das Shapefile anhängen und ganz neue Shapfiles erschaffen.

Beachten Sie bitte, dass Sie kein mapObj erzeugen müssen, um Shapefiles auf diese Weise zu bearbeiten. Das shapefileObj ist unabhängig von den MapServer-verwandten Klassen in MapScript, kann aber natürlich mit diesen zusammen benutzt werden.

Die Referenz für alle Eigenschaften und Methoden von shapefileObj finden Sie ab Seite~\ref{ref:phpms:shapefileobj}.

\subsubsection*{Beispiel}

Das folgende Beispiel gibt eine simple Statistik über alle Shapefiles aus, die es im aktuellen Verzeichnis finden kann.

 <code>
foreach (glob ("*.shp") as <math>shpfname) {
<math>shpf = ms_newShapefileObj (</math>shpfname, -1);
<math>noshapes = </math>shpf -> numshapes;
<math>shpftype = </math>shpf -> type;
<math>bounds = </math>shpf -> bounds;
printf ("Anzahl der Shapes:
"Typ des Shapefiles:
"Extents:
<math>noshapes, </math>shpftype,
<math>bounds -> minx, </math>bounds -> miny,
<math>bounds -> maxx, </math>bounds -> maxy);
</math>shpf -> free ();
}
</code> 

==Struktur von PHP MapScript-Seiten==

Wenn Sie mit PHP MapScript das Verhalten einer 'normalen' MapServer-Applikation nachbilden möchten, kann Ihnen das folgende Schema einige Anhaltspunkte geben, wie beim Aufbau einer solchen Applikation vorgegangen werden kann.

Weitere Optionen für Ihre Applikation müssen an sinnvollen Stellen in das Gerüst eingefügt werden.

Diese Anleitung ist natürlich kein in Stein gemeißeltes Gesetz, sondern kann von Fall zu Fall abgeändert werden. Es bietet aber eine gute Orientierungshilfe.

#Prüfen der übergebenen Parameter auf sinnvolle Werte
#Laden des Mapfiles
#Fallunterscheidung nach gewünschtem Modus:

##Simples Browsen (Pan) der Karte:
##
*Ermitteln der Koordinaten des Mausklicks ##
*Zoomen auf den Punkt mit einer Zoomtiefe von 1
##Zoomen auf/um den betreffenden Punkt
##
*Ermitteln der Koordinaten des Mausklicks ##
*Zoomen auf den Punkt mit dem übergebenen Zoomfaktor
##Zoomen auf das angeklickte Shape
##
*Ermitteln der Shapenummer mittels queryByPoint ##
*Öffnen des entsprechenden Shapefiles und Ermitteln der Extents des angeklickten Shapes ##
*Zoomen auf das Shape mittels zoomByRect
##Query auf den geklickten Punkt
##
*Ermitteln der Kartenkoordinaten des angeklickten Punktes (oder mehrerer Punkte, falls es ein queryByRect ist) ##
*Ausführen der Query ##
*Auslesen des Ergebnis' (oder der Ergebnisse) aus einem oder mehreren Layer-Objekten ##
*Präsentation der Ergebnisse

#Rendern der Karte und Abspeichern in einer Datei
#Eintragen des URL des fertigen Bildes in den entsprechenden HTML-Tag

==Speichern von Map-Objekten in PHP-Sessions==

Leider können Objekte aus PHP-MapScript (insbesondere ein mapObj) nicht in Sessions gespeichert werden. Der Grund dafür ist, dass die Objekte in PHP-MapScript keine 'reinen' PHP-Objekte sind, sondern lediglich als Wrapper um die C-Daten\-struk\-turen des MapServer-Quellcodes angelegt sind. Das führt dazu, dass beim Speichern in einer Sitzungsvariablen lediglich der Wrapper gespeichert wird, nicht aber das darunter liegende Objekt.

Man muß also entweder (um beim Beispiel eines mapObj zu beiben) die ''vorgenommenen Änderungen'' auf eine genehme Art und Weise speichern und mitschleifen, um diese dann jedesmal auf ein neu erstelltes mapObj anzuwenden; oder man speichert die fertige Karte als Datei im System ab und speichert den Dateinamen der Karte in der Sitzungsvariablen.

==Speicherverwaltung mit MapScript==(4)

Die Speicherverwaltung aller MapScript-Objekte, die im Zusammenhang mit dem Mapfile stehen, geschieht automatisch. Sie müssen also nicht für jedes Objekt Speicher anfordern und wieder freigeben.

Etwas anders verhält es sich bei Objekten zu Shapefiles und allen geometrischen Objekten wie Punkten, Linien und so weiter. Das Anfordern von Speicher entfällt zwar. Allerdings sollten alle Objekte dieser am Ende (also nachdem man Gebrauch von ihnen gemacht hat und sie nicht mehr benötigt) explizit zerstört und alle verwendeten Resourcen freigegeben werden:

 <code>
<math>punkt = ms_newPointObj ();
...
</math>punkt -> free ();
</code> 

Zwar wird jeder Speicher, der innerhalb eines PHP-Skriptes benutzt wird, nach dem Abarbeiten der Seite automatisch wieder freigegeben. Allerdings kann bei beim exzessiven Gebrauch von Objekten innerhalb einer Seite vielleicht in Speicherschwierigkeiten kommen.

Außerdem können Sie in Ihrem Programm zwar keine Probleme mit dem Speicher haben. Denken Sie aber immer daran, dass Kollegen, Freunde, Mitarbeiter und so weiter später vielleicht auf die Idee kommen können, das Programm abzuändern und zu erweitern. Wenn Sie von vornherein vernünftig mit dem Speicher umgegangen sind, so sind Sie auf der sicheren Seite. Es zeugt darüber hinaus von einem sauberen Programmierstil.

=Weitere Sprachen=

MapScript kann mit verschiedenen Sprachen genutzt werden. Neben PHP sind die populärsten Perl, Java und Python.

Die MapServer-Entwickler bedienen sich bei diesen Sprachen des Interface-Generators SWIG~[[http:website:swig]]. Die Verwendung von SWIG und die Erstellung von MapScript-Modulen für andere Programmiersprachen wird im Anhang besprochen.

==Perl==

Zu Perl gibt es unglaublich viel Literatur. Nichts falsch machen kann man wohl mit~[[wall:1996:perl5]], dem berühmten Camel Book. Es ist auch auf deutsch erschienen.

==Java==

Java ist eine Sprache, aus der ein unglaublicher Hype hervorgegangen ist. Die Literatur, die sich mit Java auseinandersetzt, ist dermaßen umfangreich, dass Sie sich von dem Buchhändler Ihres Vertrauens beraten lassen sollten.

==Python==

Python hat sich einen Namen als einfache, strukturierte und schnell zu lernende Programmiersprache gemacht. Wer des Englischen mächtig ist, ist mit der Lektüre von~[[lutz:1999:python]] recht gut beraten; das Buch ist auch auf deutsch erschienen.

\chapter{Java-Applets}\index{Applets}(1)

=Mapplet=\index{Mapplet}(2)

=ROSA=(3)\index{ROSA}

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 6

2009-01-23T10:14:20Z

Wiki-Mikee63: /* Setzen von Objekt-Eigenschaften */

= MapScript =
(1)\index{MapScript}

Bisher haben Sie den MapServer als Applikation kennengelernt, die in einem Webserver wie zum Beispiel Apache arbeitet, und direkt über Parameter des URL aufgerufen und in ihrem Verhalten beeinflußt werden kann.

Man kann sich aber natürlich auch vorstellen, die Funktionen von MapServer -- das Lesen von Mapfiles, das Rendern der Karten und so weiter -- auch aus eigenen Programmen nutzen zu wollen, natürlich auch solchen, die nicht in einem Webserver laufen sollen. Dazu müßte man diese Funktionen separat zur Verfügung stellen, beispielsweise in einer eigenen Bibliothek, auf die dann aus anderen Programmiersprachen zugegriffen werden kann. Diese Bibliothek existiert bereits und trägt den Namen MapScript.

Zu den Sprachen wie Java, Python, Perl und einigen anderen, die mit MapScript benutzt werden können, gesellt sich auch PHP. PHP MapScript soll im Folgenden als Anknüpfungspunkt für die Erklärung von MapScript dienen -- die genaue Terminologie für einzelne Programmiersprachen entnehmen Sie bitte der jeweilgen Dokumentation der Sprache bzw. den Beispielen, die dem MapServer-Quellcode beiliegen.

=PHP MapScript=(2)\index{PHP MapScript}\index{MapScript!PHP}

Ich erspare dem Leser die an dieser Stelle üblichen Hymnen auf PHP\footnote{Beziehungsweise die üblichen Flames. Die Sprache ist definitiv nichts für Puristen oder Entwickler mit eng gesteckten Vorgaben, was den Resourcenverbrauch angeht.} und seine Flexibilität als Sprache für Webanwendungen. Es ist in der Tat sehr weit verbreitet. Das ist (neben der besonderen Pflege, die gerade diese Sprachanbindung erfährt) auch der Grund, warum wir an dieser Stelle detailliert auf PHP MapScript eingehen, und nicht beispielsweise auf Perl.

An dieser Stelle gehen wir nicht darauf ein, wie Sie PHP installieren, oder wie Sie Ihren Webserver korrekt für den Einsatz von PHP konfigurieren. Wie man das tut, erfahren Sie in der Dokumentation von PHP bzw. Ihres Webservers. Die Installation von PHP MapScript wird im Anhang dieses Handbuches abgehandelt.

Beachten Sie bitte, dass PHP MapScript im Moment zwingend voraussetzt, dass Sie PHP ''nicht'' als Modul laden, sondern als CGI-Programm einsetzen. Es kann ansonsten zu nicht vorhersehbaren Komplikationen kommen.

Als erstes deutschsprachiges Einsteigerbuch zu PHP eignet sich beispielsweise~[[theis:2000:php]]; allerdings gibt es eine solche Unzahl an Büchern über diese Sprache, dass eine persönliche Auswahl im Buchladen erfolgen sollte. Die Website zur PHP [[http:website:php]] stellt ausführliche Dokumentation bereits, die interessanterweise auch vollständig ins deutsche übersetzt ist.

Des weiteren ist es eine gute Idee, sich mit der FAQ von =de.comp.lang.php= ~[[faq:dclp]] auseinanderzusetzen, der deutschsprachigen Newsgroup zu PHP, die in einem eigenen Kapitel auch auf Sicherheitsbelange eingeht.

\begin{figure}
\begin{center}
\mmfig{0.75}{mapscript-hyk}{Ein Beispiel für eine PHP MapScript Anwendung sind die Hydrogeologischen Karten Brandenburg}
\end{center}
\end{figure}

==Laden des Moduls==

Um die MapScript-Funktionen in einer PHP-Seite verwenden zu können, muss das Modul dafür geladen werden. Das geschieht ganz einfach durch ''dl'' :

 <code>
dl ("php_mapscript.so");
</code> 

Dies sollte die erste Zeile sein, die Sie in jede Seite einfügen, die MapScript-Funktionen benutzt. Sollten Sie sich unter Windows befinden, ändert sich diese Zeile leicht in:

 <code>
dl ("php_mapscript.dll");
</code> 

Falls Sie eine portable Anwendung schreiben sollen, ist es demnach angebracht, gleich zu Beginn des Skripts auf das verwendete Betriebssystem zu prüfen und dann die korrekte Datei zu laden.

==Setzen von Objekt-Eigenschaften==

Bevor Sie auch nur eine einzige Klasse aus MapScript kennenlernen, möchte ich zeigen, wie man die Eigenschaften von Objekten setzt, da diese Methode für alle Objekte (die sie unterstützen) gleich ist.

Ein Beispiel:

 <code>
<math>layer -> set ("name", "gruenflaechen");
</code> 

Mit diesem Aufruf wird der Name eines Layer-Objektes auf =gruenflaechen= gesetzt.

Der 'korrekte' objektorientierte Ansatz wäre natürlich gewesen, dafür eine eigene Routine =setName()= zu implementieren. Da einige Klassen in MapScript jedoch über eine ziemlich große Anzahl an Eigenschaften verfügen, hat man sich auf diese Methode beschränkt.

Das Setzen von Eigenschaften auf diese Weise funktioniert nur für Eigenschaften, die nicht =read-only= sind. Nicht jedes Objekt implementiert zudem die =set()= -Methode. In der Referenz im Anhang dieses Handbuchs sehen Sie, welche Klasse eine solche Methode zur Verfügung stellt.

Darüber hinaus haben einige Klassen für einige Eigenschaften doch noch eigene Methoden implementiert. Studieren Sie die Referenz im Anhang, um herauszufinden, für welche Klassen und Eigenschaften das gilt.

==Formulareingaben in PHP verarbeiten==

In älteren PHP-Versionen war es kein Problem, URL-Parameter einfach als Variable in ein PHP-Skript zu übernehmen. Wenn ein Aufruf also etwa so aussah:

 <code>
.../skript.php?name=Calli
</code> 

Dann konnte man ohne Probleme das folgende in sein Skript schreiben:

 <code>
echo </math>name;
</code> 

Das produzierte dann die Ausgabe =Calli= .

In neueren Fassungen von PHP\footnote{Und aufgrund der bekannt gewordenen Sicherheitslücken möchte man eine alte Version nicht benutzen. Verwenden Sie nichts unter 4.3.3!} geht das so nicht mehr. Weil es durch diverse Tricksereien möglich war, globale PHP-Variablen von außen zu überschreiben, und weil man die Programmierer zwingen wollte, sich mit den Werten in ihren Variablen genauer zu befassen, muß man sich jeden Wert nun explizit aus einem Array holen, das den Namen =\<math>_GET[]= trägt.

Für unser obiges Beispiel benötigen Sie dann also folgendes:

 <code>
<math>dername = </math>_GET ['name'];
echo </math>dername;
</code> 

Manchmal werden durch eine Eingabemöglichkeit in einem HTML-Formular mehrere Werte übergeben. Ein Beispiel dafür ist ein angeklicktes Bild, wie es etwa unsere Karte ist -- ein Klick produziert natürlich eine X- und eine Y-Koordinate. PHP verhält sich an dieser Stelle etwas unerwartet. Betrachten wir das folgende Bild in einem HTML-Formular:

 <code>
<input type="image" name="img" src="[img]">
</code> 

Nach einem Klick finden Sie im URL zwei Werte, namentlich =img.x= und =img.y= . Diese beiden Variablen werden Sie aber im Array =\<math>_GET[]= vergeblich suchen, denn für PHP werden die Punkte durch Unterstriche ersetzt. Sie müssen sich also =img_x= und =img_y= aus dem Array holen.

Es ist übrigens immer angezeigt, den Wert jeder Variablen, die von außen belegt wird, eingehend auf seine Sinnhaftigkeit zu prüfen.

==Die mapObj-Klasse==\index{Mapscript!mapObj}\index{mapObj}

Als nächstes möchten wir betrachten, wie MapScript ein Mapfile behandelt. Betrachten Sie das erste Beispiel:

 <code>
</math>map = ms_newMapObj ("/path/to/mapfile.map");
<math>image = </math>map -> draw ();
<math>imageurl = </math>image -> saveWebImage (MS_PNG, 1, 1, 0);
</code> 

In der ersten Zeile wird ein =mapObj= erzeugt, das auf ein bereits existentes Mapfile zugreift. Danach wird daraus ein =ImageObj= erzeugt, es wird also die Karte gezeichnet. Dabei werden die gesetzten Werte für die Extents aus dem Mapfile übernommen.

Beachten Sie bitte, dass dadurch noch keine fertige Bild''datei'' erzeugt wird. Die Karte existiert zu diesem Zeitpunkt nur als Puffer im Speicher.

In einer Datei tatsächlich gespeichert wird das Bild in der letzten Zeile, in unserem Beispiel als Bild im PNG-Format. Die Rückgabe der Funktion ist der URL für den Webserver, unter der er das Bild ausliefern kann.

Man kann daher weiter unten in der Seite folgendes HTML verwenden:

 <code>
<html>
<head><title>Beispiel</title></head>
<body>
<img src="<?php echo <math>imageurl; ?>">
</body>
</html>
</code> 

Dadurch wird der betreffende URL in den =<img>= -Tag eingefügt und an den Client ausgeliefert. Das Resultat ist natürlich ein zentriertes Bild der Karte im Webbrowser.

Auf die gleiche Weise werden übrigens auch Legenden, Maßstäbe und Referenzkarten erzeugt:

 <code>
<math>img_legend = </math>map -> drawLegend ();
<math>img_scalebar = </math>map -> drawScaleBar ();
<math>img_refmap = </math>map -> drawReferenceMap ();
</code> 

Auch diese Bildobjekte werden wieder über deren Methode =saveWebImage= abgespeichert.

\subsubsection*{Zoomen}

Das Zoomen in eine Karte kann auf drei Weisen geschehen: Zoomen in Richtung eines Punktes, Zoomen auf ein Rechteck und Zoomen auf einen Punkt in einem bestimmten Maßstab.

Betrachten wir den ersten Fall. Wir gehen davon aus, dass wir ein Bild in einem HTML-Formular eingebettet hatten, und dieses Bild wie gerade beschrieben per PHP Mapscript erzeugt hatten. Wurde das Bild angeklickt, werden die Pixelkoordinaten des Klicks über das Formular mit übergeben. Gehen wir von einem festen Zoomfaktor von 2 aus (diesen Wert legen wir für dieses Beispiel jetzt fest), können wir mit diesen Pixeln folgendes tun:

 <code>
</math>map = ms_newMapObj ("/path/to/file.map");
<math>map -> zoomPoint (2, </math>imgxy, <math>breite, </math>hoehe, <math>extent);
<math>img = </math>map -> draw ();
...
</code> 

Das Mapfile wird in seinem ursprünglichen Zustand geladen. Dann werden der Zoomfunktion die nötigen Parameter übergeben: zuerst der Zoomfaktor, den wir hier mit 2 festlegen, aber natürlich auch im Formular einstellen lassen können. Der folgende Wert ist ein pointObj, das die Bildkoordinaten des angeklickten Punktes darstellt. Falls Sie mit diesen Werten irgendwelche Berechnungen anstellen wollen, beachten Sie, dass der Ursprung der Grafik auf dem Bildschirm in der linken oberen Ecke ist.

Breite und Höhe beziehen sich auf das Bild und sind Pixel-Werte. Der Extent (als rectObj) ist schließlich die Bounding Box der Karte in ihrem jeweiligen Koordinatensystem.

Als letzten Wert könnte man übrigens noch ein weiteres rectObj angeben, dass den maximalen Extent angibt, der beim Zoomen nicht verlassen werden darf. Diesen Aufwand muß man aber nicht unbedingt treiben, da das Schlüsselwort =MAXSCALE= in der Web-Sektion das gleiche leistet.

Im Grunde machen alle Zoomfunktionen nichts anderes, als neue Extents für einen Kartenausschnitt festzulegen. Das bedeutet aber auch, dass Ihre Applikation durcheinander kommen kann, wenn sie beispielsweise gleichzeitig die Möglichkeit zum Zoomen und zum Ändern der Größe der Karte anbietet. Stellen Sie in Ihrem Code sicher, dass Sie in einem solchen Fall zuerst die Änderung des Ausschnitts vornehmen (z.B. Zoomen) und erst danach die Werte für die Kartengeometrie setzen (zum Beispiel Höhe und Breite der Karte).

Das ''Zoomen auf ein Rechteck'' gestaltet sich ähnlich. Über normale Anwendungen im Webbrowser lassen sich zwei angeklickte Punkte nicht übertragen. Diese Funktion kommt also dann zum Tragen, wenn man mit JavaScript oder wie auch immer ein Rechteck aufziehen und entsprechende Werte übergeben kann.

Der aufmerksame Leser kommt natürlich auch auf die Idee, diese Funktion zu benutzen, wenn er auf ein bestimmtes Feature zoomen möchte. Man bestimme dann die Extents des betreffendes Shapes (das geht auch mit MapScript, siehe weiter unten) und zoomt eben auf diese.

Dummerweise geht das nur, wenn man die ''Pixel'' -Koordinaten des Rechtecks kennt, denn die Funktion =zoomRectangle= wird folgendermaßen genutzt:

 <code>
</math>map = ms_newMapObj ("/path/to/mapfile.map");
<math>map -> zoomRectangle (</math>pixext, <math>breite, </math>hoehe, <math>extent);
</code> 

Der erste Parameter ist wieder ein rectObj; er gibt die Pixelkoordinaten des Rechtecks an, auf die gezoomt werden soll. Die Breite und die Höhe sind ebenfalls Pixelangaben im Bild. Die Extents schließlich sind wieder ein RectObj, das diesmal die Bounding Box der Karte im Bild im entsprechenden Koordinatensystem angibt.

Wenn Sie einfach auf bestimmte Extents zoomen wollen, ohne vorher in Besitz von Pixelkoordinaten und so weiter zu sein, dann können Sie einfach das Mapfile laden und diese neuen Extents setzen:

 <code>
</math>map = ms_newMapObj ("/path/to/mapfile.map");
<math>map -> setExtent (</math>minx, <math>miny, </math>maxx, <math>maxy);
</math>map -> draw ();
</code> 

Warum diese Methode vier einzelne Koordinaten erwartet und kein RectObj, können wir leider nicht erklären.

Die letzte Zoommethode schließlich ist =zoomScale= :

 <code>
<math>map = ms_newMapObj ("/path/to/mapfile.map");
<math>map -> zoomScale (100000, </math>imgxy, <math>breite, </math>hoehe, </math>extent);
</code> 

Der erste Wert ist ein SCALE, wie er bereits auf Seite~\pageref{text:mapfile:scale} besprochen worden ist. Beachten Sie bitte, dass so ein Maßstab nicht viel mit dem Maßstab auf einer gedruckten Karte zu tun hat.

Die restlichen Parameter sind wieder die Pixelkoordinaten des Mausklicks, Höhe und Breite des Bildes in Pixeln sowie die Extents des Kartenausschnitts. Auch bei dieser Funktion läßt sich als letzter Parameter wieder als rectObj ein Ausschnitt angeben, aus dem nicht herausgezoomt werden darf.

\subsubsection*{Weitere Eigenschaften und Methoden}

Die restlichen Eigenschaften des mapObj-Objektes dienen dazu, Informationen beziehungsweise Referenzen auf andere Objekte aus dem Mapfile zu ziehen; aber auch, Queries auszuführen. Mehr zu Queries in PHP erfahren Sie weiter unten in dem Abschnitt über Layer. Sie finden die Queries dort (und nicht hier im mapObj, wo sie ausgeführt werden), da die Resultate auf Layer-Ebene eingeholt werden.

Alle weiteren Methoden und Eigenschaften, die mapObj bietet, sind im Anhang ab Seite~\pageref{ref:phpms:mapobj} aufgelistet.

==Fehlerbehandlung==(3)

Jetzt da Sie ein Gefühl dafür haben, wie man Objekte in PHP MapScript anspricht, sollen Sie etwas über die Wege der Fehlerbehandling erfahren, die mit MapServer 4.0 dazugekommen ist.

Bisher sind Fehler einfach aufgetreten und haben meist den weiteren Ablauf des Skripts abgebrochen. Das kann eventuell nicht erwünscht sein; so wäre es zum Beispiel vorstellbar, dass eine Datenbank, die räumliche Daten für einen Layer Ihrer Applikation vorhält, nicht erreichbar ist. Anstatt nun einfach mit einem Fehler abzubrechen, wäre es natürlich angenehmer, wenn man beim Auftreten eines Fehlers dessen Ursache prüfen könnte, nd dann über das weitere Vorgehen entscheiden könnte.

Dieses Vorgehen wird in MapScript 4.0 mit dem neuen Objekt =errorObj= umgesetzt. Dabei werden Fehler bei ihrem Auftreten in eine interne Liste eingefügt. Aus dieser Liste können sie sodann zu einem Zeitpunkt nach Wahl des Programmierers entnommen und verarbeitet werden.

Schauen wir uns das Beispiel von der offiziellen MapServer-Dokumentationsseite an:

 <code>
ms_resetErrorList ();
<math>img = </math>map -> draw ();
<math>error = ms_getErrorObj ();
while (<math>error && </math>error -> code != MS_NOERR) {
printf ("Error in
<math>error -> routine, </math>error -> message);
<math>error = </math>error -> next ();
}
</code> 

Zuerst sollten Sie zu Beginn jedes Skriptes die Fehlerliste zurücksetzen; das passiert hier in der ersten Zeile.

Danach holt man sich das globale Fehlerobjekt, über welches dann iteriert wird. Für jeden erzeugten Fehler wird dessen Eigenschaft =code= abgefragt. Dieser Code ist eine aus einer Liste von Fehlerkonstanten. Falls es sich tatsächlich um einen Fehler handelt -- auch keine Fehler ist ein Fehler, allerdings einer vom Typ =MS_NOERR= wird eine entsprechende Fehlermeldung ausgegeben. Danach wird zum nächsten unbearbeiteten Fehler in der Liste gesprungen.

Beachten Sie bitte, dass Sie nach der Abfrage des nächsten Fehlers keine Möglichkeit mehr haben, zu bereits abgearbeiteten Fehlern zurückzukehren.

Sie finden alle Details zu =errorObj= in der Referenz ab Seite~\pageref{ref:phpms:errorobj}. Die möglichen Fehlercodes sind außerdem Bestandteil von Tabelle~\ref{tab:ref:mapscript:const}, die auf Seite~\pageref{tab:ref:mapscript:const} beginnt.

==Die layerObj-Klasse==\index{Mapscript!layerObj}\index{layerObj}

Dieses Objekt läßt Sie auf alle Bestandteile einer Layer-Sektion im Mapfile zugreifen.

Dafür müssen Sie natürlich erst einmal wissen, welche Layer sich in einem gegebenen Mapfile befinden. Natürlich könnte man einfach alle Namen in seinem Script hartkodieren. Allerdings kommt man dann schnell in Bedrängnis, wenn sich am Mapfile etwas ändert. Außerdem läßt sich auf diese Weise keine Software schreiben, die sich mit beliebigen Mapfiles auseinandersetzt.

Zuerst einmal können alle Layer in einem Mapfile durch einen Index angesprochen werden, der ihrer Position im Mapfile entspricht. Der erste Layer erhält dabei den Index =0= , der zweite den Index =1= und so weiter\footnote{Informatiker beginnen immer bei Null mit dem Zählen, nicht bei Eins. Das liegt daran, dass sie sich bei Listen und so weiter nicht dafür interessieren, welche Position ein Element absolut besitzt, sondern welchen Abstand vom Beginn der Liste. Und der ist für das erste Element Null, und so weiter.}. Mit einer Schleife, die über die Anzahl der Layer läuft, kann man also beispielsweise folgendes machen:

 <code>
<math>num = </math>map -> numlayers;
for (<math>i = 0; </math>i < numlayers; </math>i++) {
<math>layer = </math>map -> getlayer (<math>i);
... jetzt passieren Dinge mit </math>layer ...
}
</code> 

Man kann die Layer aber auch über Ihren Namen ansprechen. Dabei holt man sich zuerst alle Layer-Namen via =getAllLayerNames()= aus dem mapObj (man erhält ein Array aller Namen zurück), und spricht dann die Layer einzeln mit =getLayerByName()= an.

Die häufigste Aktion mit einem Layer ist, Queries auszuführen, beziehungsweise danach Query-Ergebnisse aus ihm herauszuholen.

===Queries auf Layer===

Queries liefern seit Version~{3.5} des MapServers keine Objekte vom Type resultObj mehr direkt zurück. Vielmehr werden die Ergebnisse von Queries nun in den Layer-Objekte festgehalten.

Damit Anfragen auf einen Layer gemacht werden können, muß dieser im Mapfile einen =TEMPLATE= -Eintrag besitzen. Dieser Eintrag kann durchaus leer sein. Alternativ zur Angabe auf Layer-Ebene kann =TEMPLATE= auch nur in einigen (oder allen) =CLASS= es des Mapfiles stehen. Die Queries werden dann nur auf Mitglieder dieser Klasse angewendet.

Am häufigsten werden Queries auf einem mapObj ausgeführt; alle Query-Funktionen lassen sich jedoch auch auf einzelne Layer anwenden. Werden Queries auf mapObj-Objekte angewendet, werden einfach alle in Frage kommenden Layer der Reihe nach mit der entsprechenden Funktion bedacht.

Queries können auf drei verschiedene Weisen ausgeführt werden: an bestimmten Punkten, mit Hilfe eines Rechtecks und, ganz neu, anhand beliebiger Shapes. Doch wir beginnen mit den Punkt-Queries.

Betrachten Sie folgendes Beispiel:

 <code>
<math>punkt = ms_newPointObj ();
</math>punkt -> setXY (300000, 500000);

<math>layer -> queryByPoint (</math>punkt, MS_SINGLE, -1);
</code> 

Hier wird zuerst ein Punkt-Objekt aus den Koordinaten gebaut, die abgefragt werden sollen. Für gewöhnlich kommen diese Koordinaten durch einen Mausklick auf ein Bild in einem Formular zustande. Beachten Sie bitte, dass dieser Punkt im =Koordinatensystem der Karte= vorliegen muß; die Pixelwerte eines Mausklicks auf eine Karte müssen Sie also zuerst in passende Werte umrechnen.

Danach wird auf dem gewünschten Layer eine Query durchgeführt. Dazu wird der Punkt übergeben, die Art der Anfrage (hier soll nur ein einzelnes Ergebnis erzeugt werden; mit =MS_MULTIPLE= wären mehrere Ergebnisse möglich), und schließlich ein Puffer. Dieser Puffer ist ein Radius um den Abfragepunkt herum, in den Einheiten der Karte. Ein negativer Wert führt dazu, dass der im Mapfile gesetzte Wert verwendet wird.

Bevor man sich auf eventuelle Resultate stürzt, sollte man prüfen, ob es überhaupt Resultate gab -- die Anfrage kann schließlich auch ins Leere gegangen sein. Dazu prüft man den Rückgabewert der Funktion. Ist dieser =MS_SUCCESS= , so ist alles in Ordnung und man kann fortfahren. Trifft man auf =MS_FAILURE= , so gab es keine Ergebnisse.

Etwas problematisch ist, dass alle Query-Funktionen auch Fehlernachrichten produzieren, wann immer es keine Resultate gab. Dieses Verhalten läßt sich für einzelne Funktionen jedoch mit einem vorangestellten =@= abstellen. Ein korrekterer Aufruf der obigen Funktion wäre also:

 <code>
if ((<math>layer -> @queryByPoint (</math>punkt, MS_SINGLE, -1))
== MS_SUCCESS) {
... es gab Ergebnisse ...
} else {
... Fehlerbehandlung ...
}
</code> 

Jetzt können wir uns endlich mit dem Ergebnis des Mausklicks auseinandersetzen. Oder besser: mit den Ergebnissen, denn es können ja mehre sein. Mit =getnumresult()= bringen wir die Anzahl der Resultate eines Layers in Erfahrung; haben wir nur ein Resultat, ist das nicht nötig. Dieses eine Resultat hat immer den Index =0= :

 <code>
<math>resultat = </math>layer -> getResult (0);

<math>si = </math>resultat -> shapeindex;
<math>ti = </math>resultat -> tileindex;
<math>ti = </math>resultat -> classindex;
</code> 

Das Resultat-Objekt besitzt also drei Eigenschaften: einen Shapeindex, der die Nummer des Shapes im Shapefile angibt, das dem Layer zugrunde liegt; einen Tileindex, der für gekachelte Shapefiles angibt, in welcher Kachel das Ergebnis aufgetreten ist; und schließlich einen Classindex, der die Class im Layer bezeichnet, für den das Ergebnis aufgetreten ist.

Mit diesen Angaben können Sie dann verfahren, wie Sie es für richtig halten. Sie können zum Beispiel die Daten aus dem =.dbf= -File herausfischen, die dem Shape zugrunde liegen\footnote{Beachten Sie an dieser Stelle die eigenwillige Zählweise in =.dbf= -Dateien, die auch in PHP übernommen wurde: die Zeilen in einer solche Datei sind nicht bei 0 beginnend durchnummeriert, sondern bei 1}. Sie könnten beispielsweise auch auf das gesuchte Shape heranzoomen, indem Sie anhand des gefundenen Index die Bounding Box des Shapes aus dem Shapefile auslesen (siehe auch shapefileObj weiter unten) und diese Bounding Box als neue Extents für die Karte setzen.

Von den einfachen Punkt-Queries kann man nun voranschreiten zu den Anfragen, die über ein Rechteck definiert sind:

 <code>
<math>layer -> queryByRect (</math>rechteck);
</code> 

Das Rechteck ist dabei ein rectObj, wie es weiter unten im Text besprochen wird. Die restliche Vorgehensweise entspricht exakt demjenigen bei Punktabfragen.

Hinweise: Rechtecke lassen sich in "`normalem"' HTML nicht erzeugen. Mit JavaScript oder dem ROSA-Applet sieht das schon wieder anders aus. Beachten Sie aber, dass insbesondere öffentliche Institutionen unter Umständen äußerst restriktive Bestimmungen haben, was den Einsatz von JavaScript, dynamischem HTML, Java und so weiter angeht. Auch sicherheitsbewußte Privatanwender haben JavaScript erst gar nicht aktiviert. Überdenken Sie den Einsatz dieser Technologien.

Das gilt auch für die folgende Weise, Queries zu stellen, nämlich anhand eines Shapes, also eines beliebigen Polygons:

 <code>
<math>layer -> queryByShape (</math>shape);
</code> 

Diese Art der Query entfaltet Ihren Nutzen weniger anhand von Punkten, die in einem Web-Interface ausgewählt werden können, als vielmehr beim Vergleich von Shapes mit Shapes aus einem anderen Shapefile: wenn Sie beispielsweise ein Shapefile mit Bundesländern haben und eines, indem ohne eine solche Referenzierung Angaben von Verkaufszahlen gespeichert sind, dann lassen sich durch den 'Verschnitt' beider Daten aussagekräftige Ergebnisse erzeugen.

Wie man mit MapScript einzelne Shapes aus einem Shapefile extrahiert erfahren Sie weiter unten bei der Besprechung von shapefileObj. Ein schneller Weg involviert allerdings die Methode =getShape()= , die bereits auf der Ebene des Layers vorhanden ist.

\subsubsection*{Weitere Eigenschaften und Methoden}

Die weiteren Funktionen in layerObj dienen im wesentlichen dazu, Zugriff auf die einzelnen Werte eines Layers zu erhalten, beziehungsweise auf die weiteren Objekte darin bezug nehmen zu können, insbesondere auf die Classes im Layer.

Alle weiteren Methoden und Eigenschaften, die layerObj bietet, sind im Anhang ab Seite~\ref{ref:phpms:layerobj} aufgelistet.

==Die classObj-Klasse==\index{Mapscript!classObj}\index{classObj}

Dieses Objekt entspricht einer Class innerhalb eines Layers. Mit einem classObj können Sie im wesentlichen Farben und Symbole für eine Class setzen -- insbesondere aber die Expressions für eine Class.

Ein Beispiel, wie man das verwenden kann: Nehmen wir an, Sie haben einen Datenbestand, der Ihnen die Deutschland in lauter kleine Gebiete einteilt. In der dazu gehörigen ''.dbf'' -Datei haben Sie in einer Spalte für jedes Gebiet den prozentualen Anteil an Waldfläche gespeichert. Diese Spalte trägt den Namen =WALD= .

In Ihrer Applikation haben Sie nun ein Eingabefeld, das es dem Benutzer ermöglicht, eine Anzahl von Grün-Abstufungen zu bestimmen, in die der Layer eingeteilt werden soll. Gibt der Benutzer beispielsweise =4= ein, werden dem Layer vier Klassen hinzugefügt, die von grün bis weiß vier Farbstufen annehmen.

Sie errechnen in der PHP-Seite dann die Unterteilung in vier Grünstufen und setzen vier verschiedene Classes.

==Die imageObj-Klasse==\index{Mapscript!imageObj}\index{imageObj}

Diese Objekte werden niemals 'von Hand' erzeugt, sondern immer nur durch den Aufruf von Methoden anderer MapScript-Objekte. Bei diesen Image-Objekten handelt es sich nicht um Bild-Dateien, sondern lediglich um die Bilddaten, die in einem Puffer im Speicher liegen und noch darauf warten, gespeichert zu werden.

Alle =draw= -Methoden von mapObj erzeugen ein imageObj. Am häufigsten wird danach die Methode =saveWebImage()= aufgerufen:

 <code>
<math>image = </math>map -> draw ();
<math>url = </math>image -> saveWebImage (MS_JPEG, 0, 0, 90);
</code> 

Der erste Parameter der Methode ist das gewünschte Bildformat, das meistens =MS_PNG= sein wird, ab und zu =MS_JPEG= und nur, wenn es sich nicht vermeiden läßt, =MS_GIF= .

Die beiden folgenden Parameter legen eine Transparenz der Hintergrundfarbe bzw. ein Interlacing für das Bild fest. Der letzte (optionale) Parameter legt für Bildformate, die eine Kompression zur Verfügung stellen, den Grad dieser Kompression fest. Werte zwischen 0 und 100 sind hier möglich.

Eine vollständige Aufzählung aller Methoden dieses Objektes finden Sie im Anhang ab Seite~\pageref{ref:phpms:imageobj}.

==Die labelObj-Klasse==\index{Mapscript!labelObj}\index{labelObj}

Labels befinden sich innerhalb von classObj-Objekten. Diese Klasse kennt erstaunlicherweise keine einzige Methode außer =set()= , dafür eine große Menge von Eigenschaften. In der Referenz finden Sie ab Seite~\pageref{ref:phpms:labelobj} eine ausführliche Aufzählung.

Das bedeutet übrigens auch, dass es keinen Konstruktor für diese Klasse gibt und demnach keine Möglichkeit, ein labelObj 'von Hand' zu erstellen.

==Die webObj-Klasse==\index{Mapscript!webObj}\index{webObj}

Ebenso wie beim labelObj gibt es auch für diese Klasse keinen Konstruktor und keine weiteren Methoden neben der =set()= -Methode. In der Referenz im Anhang finden Sie ab Seite~\pageref{ref:phpms:webobj} eine Liste aller Eigenschaften dieser Klasse.

webObj-Objekte finden Sie immer als Bestandteil eines mapObj.

==Die referenceMapObj-Klasse==\index{Mapscript!referenceMapObj}\index{referenceMapObj}

Auch Objekte dieser Klasse kommen nur innerhalb eines mapObj vor, es gibt keinen Konstruktor und keine Methode außerhalb von =set()= .

In der Referenz ab Seite~\pageref{ref:phpms:referencemapobj} finden Sie eine Liste aller Eigenschaften dieser Klasse.

==Die colorObj-Klasse==\index{Mapscript!colorObj}\index{colorObj}

Jede Karte verfügt über eine bestimmte Farbpalette. Diese Palette wird beim Generieren der Karte erstellt.

Neue Farben lassen sich der Palette hinzufügen, indem man Objekte der Klasse colorObj erzeugt:

 <code>
<math>weiss = ms_newColorObj ();
</math>weiss -> setRGB (255, 255, 255);
</code> 

Diese Farbe kann dann an den Stellen, wo es möglich und nötig ist, verwendet werden.

==Die pointObj-Klasse==\index{Mapscript!pointObj}\index{pointObj}

Punkte werden an diversen Stellen in MapScript für verschiedene Dinge benötigt. Wann immer eine Funktion die zwei Koordinaten eines Punktes übergeben bekommt, wird ein pointObj verlangt. Sehen Sie sich beispielsweise die Verwendung von =queryByPoint= im Abschnitt über das Objekt =layerObj= an.

Dieses Objekt besitzt aber noch einige andere Methoden in MapScript. Insbesondere kann man damit die Abstände von Punkten zu anderen Punkten, zu Linien und zu Polygonen bestimmen; außerdem lassen sich einzelne Punkte mithilfe von Objekten der Klasse projectionObj projizieren. Des weiteren kann man einzelne Punkte aus Linien-Objekten extrahieren (siehe lineObj).

pointObj gehört zu den Klassen, deren Speicher nach Gebrauch explizit freigegeben werden muß (siehe Seite~\pageref{text:mapscript:memory}).

Die Referenz zu allen Methoden von pointObj finden Sie auf Seite~\pageref{ref:phpms:pointobj}.

==Die lineObj-Klasse==\index{Mapscript!lineObj}\index{lineObj}

Linien lassen sich entweder von Hand konstruieren (indem man der Reihe nach einzelne Punkte hinzufügt), oder aber aus Shapes der Klasse shapeObj extrahieren. Außerdem lassen sich Linien natürlich ebenfalls projizieren.

lineObj gehört zu den Klassen, deren Speicher nach Gebrauch explizit freigegeben werden muß (siehe Seite~\pageref{text:mapscript:memory}).

Die Referenz zu allen Methoden von lineObj finden Sie auf Seite~\pageref{ref:phpms:lineobj}.

==Die projectionObj-Klasse==\index{Mapscript!projectionObj}\index{projectionObj}

Dieses Objekt beschreibt einen Projektions-Abschnitt in einem Mapfile. Aber es kann auch jenseits von Mapfiles verwendet werden, um einzelne Punktkoordinaten umzuprojizieren.

\subsubsection*{Beispiel}

Dieses Beispiel projiziert einen einzelnen Punkt von einer Längen-/Breitenangabe in einen Punkt im UTM 32-System:

 <code>
<math>projin = ms_newProjectionObj ("proj=latlong");
</math>projout = ms_newProjectionObj ("proj=utm,zone=32,ellps=WGS84,
datum=WGS84,no_defs");
<math>punkt = ms_newPointObj ();
</math>punkt -> setXY (32.0, 51.0);
<math>punkt = </math>punkt -> project ();
printf ("
</code> 

Die genauen Parameter, die Sie für die von Ihnen gewünschte Projektion verwenden müssen, finden Sie in der Dokumentation der Projektionsbibliothek proj.4.

==Die shapefileObj-Klasse==\index{Mapscript!shapefileObj}\index{shapefileObj}

Diese Klasse dient dazu, Shapefiles direkt manipulieren zu können. Sie können ein Shapefile als Objekt öffnen, einzelne Shapes referenzieren, die Eigenschaften des Shapefiles auslesen und sogar neue Shapes an das Shapefile anhängen und ganz neue Shapfiles erschaffen.

Beachten Sie bitte, dass Sie kein mapObj erzeugen müssen, um Shapefiles auf diese Weise zu bearbeiten. Das shapefileObj ist unabhängig von den MapServer-verwandten Klassen in MapScript, kann aber natürlich mit diesen zusammen benutzt werden.

Die Referenz für alle Eigenschaften und Methoden von shapefileObj finden Sie ab Seite~\ref{ref:phpms:shapefileobj}.

\subsubsection*{Beispiel}

Das folgende Beispiel gibt eine simple Statistik über alle Shapefiles aus, die es im aktuellen Verzeichnis finden kann.

 <code>
foreach (glob ("*.shp") as <math>shpfname) {
<math>shpf = ms_newShapefileObj (</math>shpfname, -1);
<math>noshapes = </math>shpf -> numshapes;
<math>shpftype = </math>shpf -> type;
<math>bounds = </math>shpf -> bounds;

printf ("Anzahl der Shapes:
"Typ des Shapefiles:
"Extents:
<math>noshapes, </math>shpftype,
<math>bounds -> minx, </math>bounds -> miny,
<math>bounds -> maxx, </math>bounds -> maxy);

</math>shpf -> free ();
}
</code> 

==Struktur von PHP MapScript-Seiten==

Wenn Sie mit PHP MapScript das Verhalten einer 'normalen' MapServer-Applikation nachbilden möchten, kann Ihnen das folgende Schema einige Anhaltspunkte geben, wie beim Aufbau einer solchen Applikation vorgegangen werden kann.

Weitere Optionen für Ihre Applikation müssen an sinnvollen Stellen in das Gerüst eingefügt werden.

Diese Anleitung ist natürlich kein in Stein gemeißeltes Gesetz, sondern kann von Fall zu Fall abgeändert werden. Es bietet aber eine gute Orientierungshilfe.

#Prüfen der übergebenen Parameter auf sinnvolle Werte
#Laden des Mapfiles
#Fallunterscheidung nach gewünschtem Modus:

##Simples Browsen (Pan) der Karte:
##
*Ermitteln der Koordinaten des Mausklicks ##
*Zoomen auf den Punkt mit einer Zoomtiefe von 1
##Zoomen auf/um den betreffenden Punkt
##
*Ermitteln der Koordinaten des Mausklicks ##
*Zoomen auf den Punkt mit dem übergebenen Zoomfaktor
##Zoomen auf das angeklickte Shape
##
*Ermitteln der Shapenummer mittels queryByPoint ##
*Öffnen des entsprechenden Shapefiles und Ermitteln der Extents des angeklickten Shapes ##
*Zoomen auf das Shape mittels zoomByRect
##Query auf den geklickten Punkt
##
*Ermitteln der Kartenkoordinaten des angeklickten Punktes (oder mehrerer Punkte, falls es ein queryByRect ist) ##
*Ausführen der Query ##
*Auslesen des Ergebnis' (oder der Ergebnisse) aus einem oder mehreren Layer-Objekten ##
*Präsentation der Ergebnisse

#Rendern der Karte und Abspeichern in einer Datei
#Eintragen des URL des fertigen Bildes in den entsprechenden HTML-Tag

==Speichern von Map-Objekten in PHP-Sessions==

Leider können Objekte aus PHP-MapScript (insbesondere ein mapObj) nicht in Sessions gespeichert werden. Der Grund dafür ist, dass die Objekte in PHP-MapScript keine 'reinen' PHP-Objekte sind, sondern lediglich als Wrapper um die C-Daten\-struk\-turen des MapServer-Quellcodes angelegt sind. Das führt dazu, dass beim Speichern in einer Sitzungsvariablen lediglich der Wrapper gespeichert wird, nicht aber das darunter liegende Objekt.

Man muß also entweder (um beim Beispiel eines mapObj zu beiben) die ''vorgenommenen Änderungen'' auf eine genehme Art und Weise speichern und mitschleifen, um diese dann jedesmal auf ein neu erstelltes mapObj anzuwenden; oder man speichert die fertige Karte als Datei im System ab und speichert den Dateinamen der Karte in der Sitzungsvariablen.

==Speicherverwaltung mit MapScript==(4)

Die Speicherverwaltung aller MapScript-Objekte, die im Zusammenhang mit dem Mapfile stehen, geschieht automatisch. Sie müssen also nicht für jedes Objekt Speicher anfordern und wieder freigeben.

Etwas anders verhält es sich bei Objekten zu Shapefiles und allen geometrischen Objekten wie Punkten, Linien und so weiter. Das Anfordern von Speicher entfällt zwar. Allerdings sollten alle Objekte dieser am Ende (also nachdem man Gebrauch von ihnen gemacht hat und sie nicht mehr benötigt) explizit zerstört und alle verwendeten Resourcen freigegeben werden:

 <code>
<math>punkt = ms_newPointObj ();
...
</math>punkt -> free ();
</code> 

Zwar wird jeder Speicher, der innerhalb eines PHP-Skriptes benutzt wird, nach dem Abarbeiten der Seite automatisch wieder freigegeben. Allerdings kann bei beim exzessiven Gebrauch von Objekten innerhalb einer Seite vielleicht in Speicherschwierigkeiten kommen.

Außerdem können Sie in Ihrem Programm zwar keine Probleme mit dem Speicher haben. Denken Sie aber immer daran, dass Kollegen, Freunde, Mitarbeiter und so weiter später vielleicht auf die Idee kommen können, das Programm abzuändern und zu erweitern. Wenn Sie von vornherein vernünftig mit dem Speicher umgegangen sind, so sind Sie auf der sicheren Seite. Es zeugt darüber hinaus von einem sauberen Programmierstil.

=Weitere Sprachen=

MapScript kann mit verschiedenen Sprachen genutzt werden. Neben PHP sind die populärsten Perl, Java und Python.

Die MapServer-Entwickler bedienen sich bei diesen Sprachen des Interface-Generators SWIG~[[http:website:swig]]. Die Verwendung von SWIG und die Erstellung von MapScript-Modulen für andere Programmiersprachen wird im Anhang besprochen.

==Perl==

Zu Perl gibt es unglaublich viel Literatur. Nichts falsch machen kann man wohl mit~[[wall:1996:perl5]], dem berühmten Camel Book. Es ist auch auf deutsch erschienen.

==Java==

Java ist eine Sprache, aus der ein unglaublicher Hype hervorgegangen ist. Die Literatur, die sich mit Java auseinandersetzt, ist dermaßen umfangreich, dass Sie sich von dem Buchhändler Ihres Vertrauens beraten lassen sollten.

==Python==

Python hat sich einen Namen als einfache, strukturierte und schnell zu lernende Programmiersprache gemacht. Wer des Englischen mächtig ist, ist mit der Lektüre von~[[lutz:1999:python]] recht gut beraten; das Buch ist auch auf deutsch erschienen.

\chapter{Java-Applets}\index{Applets}(1)

=Mapplet=\index{Mapplet}(2)

=ROSA=(3)\index{ROSA}

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 6

2009-01-23T10:14:05Z

Wiki-Mikee63: /* Laden des Moduls */

= MapScript =
(1)\index{MapScript}

Bisher haben Sie den MapServer als Applikation kennengelernt, die in einem Webserver wie zum Beispiel Apache arbeitet, und direkt über Parameter des URL aufgerufen und in ihrem Verhalten beeinflußt werden kann.

Man kann sich aber natürlich auch vorstellen, die Funktionen von MapServer -- das Lesen von Mapfiles, das Rendern der Karten und so weiter -- auch aus eigenen Programmen nutzen zu wollen, natürlich auch solchen, die nicht in einem Webserver laufen sollen. Dazu müßte man diese Funktionen separat zur Verfügung stellen, beispielsweise in einer eigenen Bibliothek, auf die dann aus anderen Programmiersprachen zugegriffen werden kann. Diese Bibliothek existiert bereits und trägt den Namen MapScript.

Zu den Sprachen wie Java, Python, Perl und einigen anderen, die mit MapScript benutzt werden können, gesellt sich auch PHP. PHP MapScript soll im Folgenden als Anknüpfungspunkt für die Erklärung von MapScript dienen -- die genaue Terminologie für einzelne Programmiersprachen entnehmen Sie bitte der jeweilgen Dokumentation der Sprache bzw. den Beispielen, die dem MapServer-Quellcode beiliegen.

=PHP MapScript=(2)\index{PHP MapScript}\index{MapScript!PHP}

Ich erspare dem Leser die an dieser Stelle üblichen Hymnen auf PHP\footnote{Beziehungsweise die üblichen Flames. Die Sprache ist definitiv nichts für Puristen oder Entwickler mit eng gesteckten Vorgaben, was den Resourcenverbrauch angeht.} und seine Flexibilität als Sprache für Webanwendungen. Es ist in der Tat sehr weit verbreitet. Das ist (neben der besonderen Pflege, die gerade diese Sprachanbindung erfährt) auch der Grund, warum wir an dieser Stelle detailliert auf PHP MapScript eingehen, und nicht beispielsweise auf Perl.

An dieser Stelle gehen wir nicht darauf ein, wie Sie PHP installieren, oder wie Sie Ihren Webserver korrekt für den Einsatz von PHP konfigurieren. Wie man das tut, erfahren Sie in der Dokumentation von PHP bzw. Ihres Webservers. Die Installation von PHP MapScript wird im Anhang dieses Handbuches abgehandelt.

Beachten Sie bitte, dass PHP MapScript im Moment zwingend voraussetzt, dass Sie PHP ''nicht'' als Modul laden, sondern als CGI-Programm einsetzen. Es kann ansonsten zu nicht vorhersehbaren Komplikationen kommen.

Als erstes deutschsprachiges Einsteigerbuch zu PHP eignet sich beispielsweise~[[theis:2000:php]]; allerdings gibt es eine solche Unzahl an Büchern über diese Sprache, dass eine persönliche Auswahl im Buchladen erfolgen sollte. Die Website zur PHP [[http:website:php]] stellt ausführliche Dokumentation bereits, die interessanterweise auch vollständig ins deutsche übersetzt ist.

Des weiteren ist es eine gute Idee, sich mit der FAQ von =de.comp.lang.php= ~[[faq:dclp]] auseinanderzusetzen, der deutschsprachigen Newsgroup zu PHP, die in einem eigenen Kapitel auch auf Sicherheitsbelange eingeht.

\begin{figure}
\begin{center}
\mmfig{0.75}{mapscript-hyk}{Ein Beispiel für eine PHP MapScript Anwendung sind die Hydrogeologischen Karten Brandenburg}
\end{center}
\end{figure}

==Laden des Moduls==

Um die MapScript-Funktionen in einer PHP-Seite verwenden zu können, muss das Modul dafür geladen werden. Das geschieht ganz einfach durch ''dl'' :

 <code>
dl ("php_mapscript.so");
</code> 

Dies sollte die erste Zeile sein, die Sie in jede Seite einfügen, die MapScript-Funktionen benutzt. Sollten Sie sich unter Windows befinden, ändert sich diese Zeile leicht in:

 <code>
dl ("php_mapscript.dll");
</code> 

Falls Sie eine portable Anwendung schreiben sollen, ist es demnach angebracht, gleich zu Beginn des Skripts auf das verwendete Betriebssystem zu prüfen und dann die korrekte Datei zu laden.

==Setzen von Objekt-Eigenschaften==

Bevor Sie auch nur eine einzige Klasse aus MapScript kennenlernen, möchte ich zeigen, wie man die Eigenschaften von Objekten setzt, da diese Methode für alle Objekte (die sie unterstützen) gleich ist.

Ein Beispiel:

 <code>
<math>layer -> set ("name", "gruenflaechen");
</code> 

Mit diesem Aufruf wird der Name eines Layer-Objektes auf =gruenflaechen= gesetzt.

Der 'korrekte' objektorientierte Ansatz wäre natürlich gewesen, dafür eine eigene Routine =setName()= zu implementieren. Da einige Klassen in MapScript jedoch über eine ziemlich große Anzahl an Eigenschaften verfügen, hat man sich auf diese Methode beschränkt.

Das Setzen von Eigenschaften auf diese Weise funktioniert nur für Eigenschaften, die nicht =read-only= sind. Nicht jedes Objekt implementiert zudem die =set()= -Methode. In der Referenz im Anhang dieses Handbuchs sehen Sie, welche Klasse eine solche Methode zur Verfügung stellt.

Darüber hinaus haben einige Klassen für einige Eigenschaften doch noch eigene Methoden implementiert. Studieren Sie die Referenz im Anhang, um herauszufinden, für welche Klassen und Eigenschaften das gilt.

==Formulareingaben in PHP verarbeiten==

In älteren PHP-Versionen war es kein Problem, URL-Parameter einfach als Variable in ein PHP-Skript zu übernehmen. Wenn ein Aufruf also etwa so aussah:

 <code>
.../skript.php?name=Calli
</code> 

Dann konnte man ohne Probleme das folgende in sein Skript schreiben:

 <code>
echo </math>name;
</code> 

Das produzierte dann die Ausgabe =Calli= .

In neueren Fassungen von PHP\footnote{Und aufgrund der bekannt gewordenen Sicherheitslücken möchte man eine alte Version nicht benutzen. Verwenden Sie nichts unter 4.3.3!} geht das so nicht mehr. Weil es durch diverse Tricksereien möglich war, globale PHP-Variablen von außen zu überschreiben, und weil man die Programmierer zwingen wollte, sich mit den Werten in ihren Variablen genauer zu befassen, muß man sich jeden Wert nun explizit aus einem Array holen, das den Namen =\<math>_GET[]= trägt.

Für unser obiges Beispiel benötigen Sie dann also folgendes:

 <code>
<math>dername = </math>_GET ['name'];
echo </math>dername;
</code> 

Manchmal werden durch eine Eingabemöglichkeit in einem HTML-Formular mehrere Werte übergeben. Ein Beispiel dafür ist ein angeklicktes Bild, wie es etwa unsere Karte ist -- ein Klick produziert natürlich eine X- und eine Y-Koordinate. PHP verhält sich an dieser Stelle etwas unerwartet. Betrachten wir das folgende Bild in einem HTML-Formular:

 <code>
<input type="image" name="img" src="[img]">
</code> 

Nach einem Klick finden Sie im URL zwei Werte, namentlich =img.x= und =img.y= . Diese beiden Variablen werden Sie aber im Array =\<math>_GET[]= vergeblich suchen, denn für PHP werden die Punkte durch Unterstriche ersetzt. Sie müssen sich also =img_x= und =img_y= aus dem Array holen.

Es ist übrigens immer angezeigt, den Wert jeder Variablen, die von außen belegt wird, eingehend auf seine Sinnhaftigkeit zu prüfen.

==Die mapObj-Klasse==\index{Mapscript!mapObj}\index{mapObj}

Als nächstes möchten wir betrachten, wie MapScript ein Mapfile behandelt. Betrachten Sie das erste Beispiel:

 <code>
</math>map = ms_newMapObj ("/path/to/mapfile.map");
<math>image = </math>map -> draw ();
<math>imageurl = </math>image -> saveWebImage (MS_PNG, 1, 1, 0);
</code> 

In der ersten Zeile wird ein =mapObj= erzeugt, das auf ein bereits existentes Mapfile zugreift. Danach wird daraus ein =ImageObj= erzeugt, es wird also die Karte gezeichnet. Dabei werden die gesetzten Werte für die Extents aus dem Mapfile übernommen.

Beachten Sie bitte, dass dadurch noch keine fertige Bild''datei'' erzeugt wird. Die Karte existiert zu diesem Zeitpunkt nur als Puffer im Speicher.

In einer Datei tatsächlich gespeichert wird das Bild in der letzten Zeile, in unserem Beispiel als Bild im PNG-Format. Die Rückgabe der Funktion ist der URL für den Webserver, unter der er das Bild ausliefern kann.

Man kann daher weiter unten in der Seite folgendes HTML verwenden:

 <code>
<html>
<head><title>Beispiel</title></head>
<body>
<img src="<?php echo <math>imageurl; ?>">
</body>
</html>
</code> 

Dadurch wird der betreffende URL in den =<img>= -Tag eingefügt und an den Client ausgeliefert. Das Resultat ist natürlich ein zentriertes Bild der Karte im Webbrowser.

Auf die gleiche Weise werden übrigens auch Legenden, Maßstäbe und Referenzkarten erzeugt:

 <code>
<math>img_legend = </math>map -> drawLegend ();
<math>img_scalebar = </math>map -> drawScaleBar ();
<math>img_refmap = </math>map -> drawReferenceMap ();
</code> 

Auch diese Bildobjekte werden wieder über deren Methode =saveWebImage= abgespeichert.

\subsubsection*{Zoomen}

Das Zoomen in eine Karte kann auf drei Weisen geschehen: Zoomen in Richtung eines Punktes, Zoomen auf ein Rechteck und Zoomen auf einen Punkt in einem bestimmten Maßstab.

Betrachten wir den ersten Fall. Wir gehen davon aus, dass wir ein Bild in einem HTML-Formular eingebettet hatten, und dieses Bild wie gerade beschrieben per PHP Mapscript erzeugt hatten. Wurde das Bild angeklickt, werden die Pixelkoordinaten des Klicks über das Formular mit übergeben. Gehen wir von einem festen Zoomfaktor von 2 aus (diesen Wert legen wir für dieses Beispiel jetzt fest), können wir mit diesen Pixeln folgendes tun:

 <code>
</math>map = ms_newMapObj ("/path/to/file.map");
<math>map -> zoomPoint (2, </math>imgxy, <math>breite, </math>hoehe, <math>extent);
<math>img = </math>map -> draw ();
...
</code> 

Das Mapfile wird in seinem ursprünglichen Zustand geladen. Dann werden der Zoomfunktion die nötigen Parameter übergeben: zuerst der Zoomfaktor, den wir hier mit 2 festlegen, aber natürlich auch im Formular einstellen lassen können. Der folgende Wert ist ein pointObj, das die Bildkoordinaten des angeklickten Punktes darstellt. Falls Sie mit diesen Werten irgendwelche Berechnungen anstellen wollen, beachten Sie, dass der Ursprung der Grafik auf dem Bildschirm in der linken oberen Ecke ist.

Breite und Höhe beziehen sich auf das Bild und sind Pixel-Werte. Der Extent (als rectObj) ist schließlich die Bounding Box der Karte in ihrem jeweiligen Koordinatensystem.

Als letzten Wert könnte man übrigens noch ein weiteres rectObj angeben, dass den maximalen Extent angibt, der beim Zoomen nicht verlassen werden darf. Diesen Aufwand muß man aber nicht unbedingt treiben, da das Schlüsselwort =MAXSCALE= in der Web-Sektion das gleiche leistet.

Im Grunde machen alle Zoomfunktionen nichts anderes, als neue Extents für einen Kartenausschnitt festzulegen. Das bedeutet aber auch, dass Ihre Applikation durcheinander kommen kann, wenn sie beispielsweise gleichzeitig die Möglichkeit zum Zoomen und zum Ändern der Größe der Karte anbietet. Stellen Sie in Ihrem Code sicher, dass Sie in einem solchen Fall zuerst die Änderung des Ausschnitts vornehmen (z.B. Zoomen) und erst danach die Werte für die Kartengeometrie setzen (zum Beispiel Höhe und Breite der Karte).

Das ''Zoomen auf ein Rechteck'' gestaltet sich ähnlich. Über normale Anwendungen im Webbrowser lassen sich zwei angeklickte Punkte nicht übertragen. Diese Funktion kommt also dann zum Tragen, wenn man mit JavaScript oder wie auch immer ein Rechteck aufziehen und entsprechende Werte übergeben kann.

Der aufmerksame Leser kommt natürlich auch auf die Idee, diese Funktion zu benutzen, wenn er auf ein bestimmtes Feature zoomen möchte. Man bestimme dann die Extents des betreffendes Shapes (das geht auch mit MapScript, siehe weiter unten) und zoomt eben auf diese.

Dummerweise geht das nur, wenn man die ''Pixel'' -Koordinaten des Rechtecks kennt, denn die Funktion =zoomRectangle= wird folgendermaßen genutzt:

 <code>
</math>map = ms_newMapObj ("/path/to/mapfile.map");
<math>map -> zoomRectangle (</math>pixext, <math>breite, </math>hoehe, <math>extent);
</code> 

Der erste Parameter ist wieder ein rectObj; er gibt die Pixelkoordinaten des Rechtecks an, auf die gezoomt werden soll. Die Breite und die Höhe sind ebenfalls Pixelangaben im Bild. Die Extents schließlich sind wieder ein RectObj, das diesmal die Bounding Box der Karte im Bild im entsprechenden Koordinatensystem angibt.

Wenn Sie einfach auf bestimmte Extents zoomen wollen, ohne vorher in Besitz von Pixelkoordinaten und so weiter zu sein, dann können Sie einfach das Mapfile laden und diese neuen Extents setzen:

 <code>
</math>map = ms_newMapObj ("/path/to/mapfile.map");
<math>map -> setExtent (</math>minx, <math>miny, </math>maxx, <math>maxy);
</math>map -> draw ();
</code> 

Warum diese Methode vier einzelne Koordinaten erwartet und kein RectObj, können wir leider nicht erklären.

Die letzte Zoommethode schließlich ist =zoomScale= :

 <code>
<math>map = ms_newMapObj ("/path/to/mapfile.map");
<math>map -> zoomScale (100000, </math>imgxy, <math>breite, </math>hoehe, </math>extent);
</code> 

Der erste Wert ist ein SCALE, wie er bereits auf Seite~\pageref{text:mapfile:scale} besprochen worden ist. Beachten Sie bitte, dass so ein Maßstab nicht viel mit dem Maßstab auf einer gedruckten Karte zu tun hat.

Die restlichen Parameter sind wieder die Pixelkoordinaten des Mausklicks, Höhe und Breite des Bildes in Pixeln sowie die Extents des Kartenausschnitts. Auch bei dieser Funktion läßt sich als letzter Parameter wieder als rectObj ein Ausschnitt angeben, aus dem nicht herausgezoomt werden darf.

\subsubsection*{Weitere Eigenschaften und Methoden}

Die restlichen Eigenschaften des mapObj-Objektes dienen dazu, Informationen beziehungsweise Referenzen auf andere Objekte aus dem Mapfile zu ziehen; aber auch, Queries auszuführen. Mehr zu Queries in PHP erfahren Sie weiter unten in dem Abschnitt über Layer. Sie finden die Queries dort (und nicht hier im mapObj, wo sie ausgeführt werden), da die Resultate auf Layer-Ebene eingeholt werden.

Alle weiteren Methoden und Eigenschaften, die mapObj bietet, sind im Anhang ab Seite~\pageref{ref:phpms:mapobj} aufgelistet.

==Fehlerbehandlung==(3)

Jetzt da Sie ein Gefühl dafür haben, wie man Objekte in PHP MapScript anspricht, sollen Sie etwas über die Wege der Fehlerbehandling erfahren, die mit MapServer 4.0 dazugekommen ist.

Bisher sind Fehler einfach aufgetreten und haben meist den weiteren Ablauf des Skripts abgebrochen. Das kann eventuell nicht erwünscht sein; so wäre es zum Beispiel vorstellbar, dass eine Datenbank, die räumliche Daten für einen Layer Ihrer Applikation vorhält, nicht erreichbar ist. Anstatt nun einfach mit einem Fehler abzubrechen, wäre es natürlich angenehmer, wenn man beim Auftreten eines Fehlers dessen Ursache prüfen könnte, nd dann über das weitere Vorgehen entscheiden könnte.

Dieses Vorgehen wird in MapScript 4.0 mit dem neuen Objekt =errorObj= umgesetzt. Dabei werden Fehler bei ihrem Auftreten in eine interne Liste eingefügt. Aus dieser Liste können sie sodann zu einem Zeitpunkt nach Wahl des Programmierers entnommen und verarbeitet werden.

Schauen wir uns das Beispiel von der offiziellen MapServer-Dokumentationsseite an:

 <code>
ms_resetErrorList ();
<math>img = </math>map -> draw ();
<math>error = ms_getErrorObj ();
while (<math>error && </math>error -> code != MS_NOERR) {
printf ("Error in
<math>error -> routine, </math>error -> message);
<math>error = </math>error -> next ();
}
</code> 

Zuerst sollten Sie zu Beginn jedes Skriptes die Fehlerliste zurücksetzen; das passiert hier in der ersten Zeile.

Danach holt man sich das globale Fehlerobjekt, über welches dann iteriert wird. Für jeden erzeugten Fehler wird dessen Eigenschaft =code= abgefragt. Dieser Code ist eine aus einer Liste von Fehlerkonstanten. Falls es sich tatsächlich um einen Fehler handelt -- auch keine Fehler ist ein Fehler, allerdings einer vom Typ =MS_NOERR= wird eine entsprechende Fehlermeldung ausgegeben. Danach wird zum nächsten unbearbeiteten Fehler in der Liste gesprungen.

Beachten Sie bitte, dass Sie nach der Abfrage des nächsten Fehlers keine Möglichkeit mehr haben, zu bereits abgearbeiteten Fehlern zurückzukehren.

Sie finden alle Details zu =errorObj= in der Referenz ab Seite~\pageref{ref:phpms:errorobj}. Die möglichen Fehlercodes sind außerdem Bestandteil von Tabelle~\ref{tab:ref:mapscript:const}, die auf Seite~\pageref{tab:ref:mapscript:const} beginnt.

==Die layerObj-Klasse==\index{Mapscript!layerObj}\index{layerObj}

Dieses Objekt läßt Sie auf alle Bestandteile einer Layer-Sektion im Mapfile zugreifen.

Dafür müssen Sie natürlich erst einmal wissen, welche Layer sich in einem gegebenen Mapfile befinden. Natürlich könnte man einfach alle Namen in seinem Script hartkodieren. Allerdings kommt man dann schnell in Bedrängnis, wenn sich am Mapfile etwas ändert. Außerdem läßt sich auf diese Weise keine Software schreiben, die sich mit beliebigen Mapfiles auseinandersetzt.

Zuerst einmal können alle Layer in einem Mapfile durch einen Index angesprochen werden, der ihrer Position im Mapfile entspricht. Der erste Layer erhält dabei den Index =0= , der zweite den Index =1= und so weiter\footnote{Informatiker beginnen immer bei Null mit dem Zählen, nicht bei Eins. Das liegt daran, dass sie sich bei Listen und so weiter nicht dafür interessieren, welche Position ein Element absolut besitzt, sondern welchen Abstand vom Beginn der Liste. Und der ist für das erste Element Null, und so weiter.}. Mit einer Schleife, die über die Anzahl der Layer läuft, kann man also beispielsweise folgendes machen:

 <code>
<math>num = </math>map -> numlayers;
for (<math>i = 0; </math>i < numlayers; </math>i++) {
<math>layer = </math>map -> getlayer (<math>i);
... jetzt passieren Dinge mit </math>layer ...
}
</code> 

Man kann die Layer aber auch über Ihren Namen ansprechen. Dabei holt man sich zuerst alle Layer-Namen via =getAllLayerNames()= aus dem mapObj (man erhält ein Array aller Namen zurück), und spricht dann die Layer einzeln mit =getLayerByName()= an.

Die häufigste Aktion mit einem Layer ist, Queries auszuführen, beziehungsweise danach Query-Ergebnisse aus ihm herauszuholen.

===Queries auf Layer===

Queries liefern seit Version~{3.5} des MapServers keine Objekte vom Type resultObj mehr direkt zurück. Vielmehr werden die Ergebnisse von Queries nun in den Layer-Objekte festgehalten.

Damit Anfragen auf einen Layer gemacht werden können, muß dieser im Mapfile einen =TEMPLATE= -Eintrag besitzen. Dieser Eintrag kann durchaus leer sein. Alternativ zur Angabe auf Layer-Ebene kann =TEMPLATE= auch nur in einigen (oder allen) =CLASS= es des Mapfiles stehen. Die Queries werden dann nur auf Mitglieder dieser Klasse angewendet.

Am häufigsten werden Queries auf einem mapObj ausgeführt; alle Query-Funktionen lassen sich jedoch auch auf einzelne Layer anwenden. Werden Queries auf mapObj-Objekte angewendet, werden einfach alle in Frage kommenden Layer der Reihe nach mit der entsprechenden Funktion bedacht.

Queries können auf drei verschiedene Weisen ausgeführt werden: an bestimmten Punkten, mit Hilfe eines Rechtecks und, ganz neu, anhand beliebiger Shapes. Doch wir beginnen mit den Punkt-Queries.

Betrachten Sie folgendes Beispiel:

 <code>
<math>punkt = ms_newPointObj ();
</math>punkt -> setXY (300000, 500000);

<math>layer -> queryByPoint (</math>punkt, MS_SINGLE, -1);
</code> 

Hier wird zuerst ein Punkt-Objekt aus den Koordinaten gebaut, die abgefragt werden sollen. Für gewöhnlich kommen diese Koordinaten durch einen Mausklick auf ein Bild in einem Formular zustande. Beachten Sie bitte, dass dieser Punkt im =Koordinatensystem der Karte= vorliegen muß; die Pixelwerte eines Mausklicks auf eine Karte müssen Sie also zuerst in passende Werte umrechnen.

Danach wird auf dem gewünschten Layer eine Query durchgeführt. Dazu wird der Punkt übergeben, die Art der Anfrage (hier soll nur ein einzelnes Ergebnis erzeugt werden; mit =MS_MULTIPLE= wären mehrere Ergebnisse möglich), und schließlich ein Puffer. Dieser Puffer ist ein Radius um den Abfragepunkt herum, in den Einheiten der Karte. Ein negativer Wert führt dazu, dass der im Mapfile gesetzte Wert verwendet wird.

Bevor man sich auf eventuelle Resultate stürzt, sollte man prüfen, ob es überhaupt Resultate gab -- die Anfrage kann schließlich auch ins Leere gegangen sein. Dazu prüft man den Rückgabewert der Funktion. Ist dieser =MS_SUCCESS= , so ist alles in Ordnung und man kann fortfahren. Trifft man auf =MS_FAILURE= , so gab es keine Ergebnisse.

Etwas problematisch ist, dass alle Query-Funktionen auch Fehlernachrichten produzieren, wann immer es keine Resultate gab. Dieses Verhalten läßt sich für einzelne Funktionen jedoch mit einem vorangestellten =@= abstellen. Ein korrekterer Aufruf der obigen Funktion wäre also:

 <code>
if ((<math>layer -> @queryByPoint (</math>punkt, MS_SINGLE, -1))
== MS_SUCCESS) {
... es gab Ergebnisse ...
} else {
... Fehlerbehandlung ...
}
</code> 

Jetzt können wir uns endlich mit dem Ergebnis des Mausklicks auseinandersetzen. Oder besser: mit den Ergebnissen, denn es können ja mehre sein. Mit =getnumresult()= bringen wir die Anzahl der Resultate eines Layers in Erfahrung; haben wir nur ein Resultat, ist das nicht nötig. Dieses eine Resultat hat immer den Index =0= :

 <code>
<math>resultat = </math>layer -> getResult (0);

<math>si = </math>resultat -> shapeindex;
<math>ti = </math>resultat -> tileindex;
<math>ti = </math>resultat -> classindex;
</code> 

Das Resultat-Objekt besitzt also drei Eigenschaften: einen Shapeindex, der die Nummer des Shapes im Shapefile angibt, das dem Layer zugrunde liegt; einen Tileindex, der für gekachelte Shapefiles angibt, in welcher Kachel das Ergebnis aufgetreten ist; und schließlich einen Classindex, der die Class im Layer bezeichnet, für den das Ergebnis aufgetreten ist.

Mit diesen Angaben können Sie dann verfahren, wie Sie es für richtig halten. Sie können zum Beispiel die Daten aus dem =.dbf= -File herausfischen, die dem Shape zugrunde liegen\footnote{Beachten Sie an dieser Stelle die eigenwillige Zählweise in =.dbf= -Dateien, die auch in PHP übernommen wurde: die Zeilen in einer solche Datei sind nicht bei 0 beginnend durchnummeriert, sondern bei 1}. Sie könnten beispielsweise auch auf das gesuchte Shape heranzoomen, indem Sie anhand des gefundenen Index die Bounding Box des Shapes aus dem Shapefile auslesen (siehe auch shapefileObj weiter unten) und diese Bounding Box als neue Extents für die Karte setzen.

Von den einfachen Punkt-Queries kann man nun voranschreiten zu den Anfragen, die über ein Rechteck definiert sind:

 <code>
<math>layer -> queryByRect (</math>rechteck);
</code> 

Das Rechteck ist dabei ein rectObj, wie es weiter unten im Text besprochen wird. Die restliche Vorgehensweise entspricht exakt demjenigen bei Punktabfragen.

Hinweise: Rechtecke lassen sich in "`normalem"' HTML nicht erzeugen. Mit JavaScript oder dem ROSA-Applet sieht das schon wieder anders aus. Beachten Sie aber, dass insbesondere öffentliche Institutionen unter Umständen äußerst restriktive Bestimmungen haben, was den Einsatz von JavaScript, dynamischem HTML, Java und so weiter angeht. Auch sicherheitsbewußte Privatanwender haben JavaScript erst gar nicht aktiviert. Überdenken Sie den Einsatz dieser Technologien.

Das gilt auch für die folgende Weise, Queries zu stellen, nämlich anhand eines Shapes, also eines beliebigen Polygons:

 <code>
<math>layer -> queryByShape (</math>shape);
</code> 

Diese Art der Query entfaltet Ihren Nutzen weniger anhand von Punkten, die in einem Web-Interface ausgewählt werden können, als vielmehr beim Vergleich von Shapes mit Shapes aus einem anderen Shapefile: wenn Sie beispielsweise ein Shapefile mit Bundesländern haben und eines, indem ohne eine solche Referenzierung Angaben von Verkaufszahlen gespeichert sind, dann lassen sich durch den 'Verschnitt' beider Daten aussagekräftige Ergebnisse erzeugen.

Wie man mit MapScript einzelne Shapes aus einem Shapefile extrahiert erfahren Sie weiter unten bei der Besprechung von shapefileObj. Ein schneller Weg involviert allerdings die Methode =getShape()= , die bereits auf der Ebene des Layers vorhanden ist.

\subsubsection*{Weitere Eigenschaften und Methoden}

Die weiteren Funktionen in layerObj dienen im wesentlichen dazu, Zugriff auf die einzelnen Werte eines Layers zu erhalten, beziehungsweise auf die weiteren Objekte darin bezug nehmen zu können, insbesondere auf die Classes im Layer.

Alle weiteren Methoden und Eigenschaften, die layerObj bietet, sind im Anhang ab Seite~\ref{ref:phpms:layerobj} aufgelistet.

==Die classObj-Klasse==\index{Mapscript!classObj}\index{classObj}

Dieses Objekt entspricht einer Class innerhalb eines Layers. Mit einem classObj können Sie im wesentlichen Farben und Symbole für eine Class setzen -- insbesondere aber die Expressions für eine Class.

Ein Beispiel, wie man das verwenden kann: Nehmen wir an, Sie haben einen Datenbestand, der Ihnen die Deutschland in lauter kleine Gebiete einteilt. In der dazu gehörigen ''.dbf'' -Datei haben Sie in einer Spalte für jedes Gebiet den prozentualen Anteil an Waldfläche gespeichert. Diese Spalte trägt den Namen =WALD= .

In Ihrer Applikation haben Sie nun ein Eingabefeld, das es dem Benutzer ermöglicht, eine Anzahl von Grün-Abstufungen zu bestimmen, in die der Layer eingeteilt werden soll. Gibt der Benutzer beispielsweise =4= ein, werden dem Layer vier Klassen hinzugefügt, die von grün bis weiß vier Farbstufen annehmen.

Sie errechnen in der PHP-Seite dann die Unterteilung in vier Grünstufen und setzen vier verschiedene Classes.

==Die imageObj-Klasse==\index{Mapscript!imageObj}\index{imageObj}

Diese Objekte werden niemals 'von Hand' erzeugt, sondern immer nur durch den Aufruf von Methoden anderer MapScript-Objekte. Bei diesen Image-Objekten handelt es sich nicht um Bild-Dateien, sondern lediglich um die Bilddaten, die in einem Puffer im Speicher liegen und noch darauf warten, gespeichert zu werden.

Alle =draw= -Methoden von mapObj erzeugen ein imageObj. Am häufigsten wird danach die Methode =saveWebImage()= aufgerufen:

 <code>
<math>image = </math>map -> draw ();
<math>url = </math>image -> saveWebImage (MS_JPEG, 0, 0, 90);
</code> 

Der erste Parameter der Methode ist das gewünschte Bildformat, das meistens =MS_PNG= sein wird, ab und zu =MS_JPEG= und nur, wenn es sich nicht vermeiden läßt, =MS_GIF= .

Die beiden folgenden Parameter legen eine Transparenz der Hintergrundfarbe bzw. ein Interlacing für das Bild fest. Der letzte (optionale) Parameter legt für Bildformate, die eine Kompression zur Verfügung stellen, den Grad dieser Kompression fest. Werte zwischen 0 und 100 sind hier möglich.

Eine vollständige Aufzählung aller Methoden dieses Objektes finden Sie im Anhang ab Seite~\pageref{ref:phpms:imageobj}.

==Die labelObj-Klasse==\index{Mapscript!labelObj}\index{labelObj}

Labels befinden sich innerhalb von classObj-Objekten. Diese Klasse kennt erstaunlicherweise keine einzige Methode außer =set()= , dafür eine große Menge von Eigenschaften. In der Referenz finden Sie ab Seite~\pageref{ref:phpms:labelobj} eine ausführliche Aufzählung.

Das bedeutet übrigens auch, dass es keinen Konstruktor für diese Klasse gibt und demnach keine Möglichkeit, ein labelObj 'von Hand' zu erstellen.

==Die webObj-Klasse==\index{Mapscript!webObj}\index{webObj}

Ebenso wie beim labelObj gibt es auch für diese Klasse keinen Konstruktor und keine weiteren Methoden neben der =set()= -Methode. In der Referenz im Anhang finden Sie ab Seite~\pageref{ref:phpms:webobj} eine Liste aller Eigenschaften dieser Klasse.

webObj-Objekte finden Sie immer als Bestandteil eines mapObj.

==Die referenceMapObj-Klasse==\index{Mapscript!referenceMapObj}\index{referenceMapObj}

Auch Objekte dieser Klasse kommen nur innerhalb eines mapObj vor, es gibt keinen Konstruktor und keine Methode außerhalb von =set()= .

In der Referenz ab Seite~\pageref{ref:phpms:referencemapobj} finden Sie eine Liste aller Eigenschaften dieser Klasse.

==Die colorObj-Klasse==\index{Mapscript!colorObj}\index{colorObj}

Jede Karte verfügt über eine bestimmte Farbpalette. Diese Palette wird beim Generieren der Karte erstellt.

Neue Farben lassen sich der Palette hinzufügen, indem man Objekte der Klasse colorObj erzeugt:

 <code>
<math>weiss = ms_newColorObj ();
</math>weiss -> setRGB (255, 255, 255);
</code> 

Diese Farbe kann dann an den Stellen, wo es möglich und nötig ist, verwendet werden.

==Die pointObj-Klasse==\index{Mapscript!pointObj}\index{pointObj}

Punkte werden an diversen Stellen in MapScript für verschiedene Dinge benötigt. Wann immer eine Funktion die zwei Koordinaten eines Punktes übergeben bekommt, wird ein pointObj verlangt. Sehen Sie sich beispielsweise die Verwendung von =queryByPoint= im Abschnitt über das Objekt =layerObj= an.

Dieses Objekt besitzt aber noch einige andere Methoden in MapScript. Insbesondere kann man damit die Abstände von Punkten zu anderen Punkten, zu Linien und zu Polygonen bestimmen; außerdem lassen sich einzelne Punkte mithilfe von Objekten der Klasse projectionObj projizieren. Des weiteren kann man einzelne Punkte aus Linien-Objekten extrahieren (siehe lineObj).

pointObj gehört zu den Klassen, deren Speicher nach Gebrauch explizit freigegeben werden muß (siehe Seite~\pageref{text:mapscript:memory}).

Die Referenz zu allen Methoden von pointObj finden Sie auf Seite~\pageref{ref:phpms:pointobj}.

==Die lineObj-Klasse==\index{Mapscript!lineObj}\index{lineObj}

Linien lassen sich entweder von Hand konstruieren (indem man der Reihe nach einzelne Punkte hinzufügt), oder aber aus Shapes der Klasse shapeObj extrahieren. Außerdem lassen sich Linien natürlich ebenfalls projizieren.

lineObj gehört zu den Klassen, deren Speicher nach Gebrauch explizit freigegeben werden muß (siehe Seite~\pageref{text:mapscript:memory}).

Die Referenz zu allen Methoden von lineObj finden Sie auf Seite~\pageref{ref:phpms:lineobj}.

==Die projectionObj-Klasse==\index{Mapscript!projectionObj}\index{projectionObj}

Dieses Objekt beschreibt einen Projektions-Abschnitt in einem Mapfile. Aber es kann auch jenseits von Mapfiles verwendet werden, um einzelne Punktkoordinaten umzuprojizieren.

\subsubsection*{Beispiel}

Dieses Beispiel projiziert einen einzelnen Punkt von einer Längen-/Breitenangabe in einen Punkt im UTM 32-System:

 <code>
<math>projin = ms_newProjectionObj ("proj=latlong");
</math>projout = ms_newProjectionObj ("proj=utm,zone=32,ellps=WGS84,
datum=WGS84,no_defs");
<math>punkt = ms_newPointObj ();
</math>punkt -> setXY (32.0, 51.0);
<math>punkt = </math>punkt -> project ();
printf ("
</code> 

Die genauen Parameter, die Sie für die von Ihnen gewünschte Projektion verwenden müssen, finden Sie in der Dokumentation der Projektionsbibliothek proj.4.

==Die shapefileObj-Klasse==\index{Mapscript!shapefileObj}\index{shapefileObj}

Diese Klasse dient dazu, Shapefiles direkt manipulieren zu können. Sie können ein Shapefile als Objekt öffnen, einzelne Shapes referenzieren, die Eigenschaften des Shapefiles auslesen und sogar neue Shapes an das Shapefile anhängen und ganz neue Shapfiles erschaffen.

Beachten Sie bitte, dass Sie kein mapObj erzeugen müssen, um Shapefiles auf diese Weise zu bearbeiten. Das shapefileObj ist unabhängig von den MapServer-verwandten Klassen in MapScript, kann aber natürlich mit diesen zusammen benutzt werden.

Die Referenz für alle Eigenschaften und Methoden von shapefileObj finden Sie ab Seite~\ref{ref:phpms:shapefileobj}.

\subsubsection*{Beispiel}

Das folgende Beispiel gibt eine simple Statistik über alle Shapefiles aus, die es im aktuellen Verzeichnis finden kann.

 <code>
foreach (glob ("*.shp") as <math>shpfname) {
<math>shpf = ms_newShapefileObj (</math>shpfname, -1);
<math>noshapes = </math>shpf -> numshapes;
<math>shpftype = </math>shpf -> type;
<math>bounds = </math>shpf -> bounds;

printf ("Anzahl der Shapes:
"Typ des Shapefiles:
"Extents:
<math>noshapes, </math>shpftype,
<math>bounds -> minx, </math>bounds -> miny,
<math>bounds -> maxx, </math>bounds -> maxy);

</math>shpf -> free ();
}
</code> 

==Struktur von PHP MapScript-Seiten==

Wenn Sie mit PHP MapScript das Verhalten einer 'normalen' MapServer-Applikation nachbilden möchten, kann Ihnen das folgende Schema einige Anhaltspunkte geben, wie beim Aufbau einer solchen Applikation vorgegangen werden kann.

Weitere Optionen für Ihre Applikation müssen an sinnvollen Stellen in das Gerüst eingefügt werden.

Diese Anleitung ist natürlich kein in Stein gemeißeltes Gesetz, sondern kann von Fall zu Fall abgeändert werden. Es bietet aber eine gute Orientierungshilfe.

#Prüfen der übergebenen Parameter auf sinnvolle Werte
#Laden des Mapfiles
#Fallunterscheidung nach gewünschtem Modus:

##Simples Browsen (Pan) der Karte:
##
*Ermitteln der Koordinaten des Mausklicks ##
*Zoomen auf den Punkt mit einer Zoomtiefe von 1
##Zoomen auf/um den betreffenden Punkt
##
*Ermitteln der Koordinaten des Mausklicks ##
*Zoomen auf den Punkt mit dem übergebenen Zoomfaktor
##Zoomen auf das angeklickte Shape
##
*Ermitteln der Shapenummer mittels queryByPoint ##
*Öffnen des entsprechenden Shapefiles und Ermitteln der Extents des angeklickten Shapes ##
*Zoomen auf das Shape mittels zoomByRect
##Query auf den geklickten Punkt
##
*Ermitteln der Kartenkoordinaten des angeklickten Punktes (oder mehrerer Punkte, falls es ein queryByRect ist) ##
*Ausführen der Query ##
*Auslesen des Ergebnis' (oder der Ergebnisse) aus einem oder mehreren Layer-Objekten ##
*Präsentation der Ergebnisse

#Rendern der Karte und Abspeichern in einer Datei
#Eintragen des URL des fertigen Bildes in den entsprechenden HTML-Tag

==Speichern von Map-Objekten in PHP-Sessions==

Leider können Objekte aus PHP-MapScript (insbesondere ein mapObj) nicht in Sessions gespeichert werden. Der Grund dafür ist, dass die Objekte in PHP-MapScript keine 'reinen' PHP-Objekte sind, sondern lediglich als Wrapper um die C-Daten\-struk\-turen des MapServer-Quellcodes angelegt sind. Das führt dazu, dass beim Speichern in einer Sitzungsvariablen lediglich der Wrapper gespeichert wird, nicht aber das darunter liegende Objekt.

Man muß also entweder (um beim Beispiel eines mapObj zu beiben) die ''vorgenommenen Änderungen'' auf eine genehme Art und Weise speichern und mitschleifen, um diese dann jedesmal auf ein neu erstelltes mapObj anzuwenden; oder man speichert die fertige Karte als Datei im System ab und speichert den Dateinamen der Karte in der Sitzungsvariablen.

==Speicherverwaltung mit MapScript==(4)

Die Speicherverwaltung aller MapScript-Objekte, die im Zusammenhang mit dem Mapfile stehen, geschieht automatisch. Sie müssen also nicht für jedes Objekt Speicher anfordern und wieder freigeben.

Etwas anders verhält es sich bei Objekten zu Shapefiles und allen geometrischen Objekten wie Punkten, Linien und so weiter. Das Anfordern von Speicher entfällt zwar. Allerdings sollten alle Objekte dieser am Ende (also nachdem man Gebrauch von ihnen gemacht hat und sie nicht mehr benötigt) explizit zerstört und alle verwendeten Resourcen freigegeben werden:

 <code>
<math>punkt = ms_newPointObj ();
...
</math>punkt -> free ();
</code> 

Zwar wird jeder Speicher, der innerhalb eines PHP-Skriptes benutzt wird, nach dem Abarbeiten der Seite automatisch wieder freigegeben. Allerdings kann bei beim exzessiven Gebrauch von Objekten innerhalb einer Seite vielleicht in Speicherschwierigkeiten kommen.

Außerdem können Sie in Ihrem Programm zwar keine Probleme mit dem Speicher haben. Denken Sie aber immer daran, dass Kollegen, Freunde, Mitarbeiter und so weiter später vielleicht auf die Idee kommen können, das Programm abzuändern und zu erweitern. Wenn Sie von vornherein vernünftig mit dem Speicher umgegangen sind, so sind Sie auf der sicheren Seite. Es zeugt darüber hinaus von einem sauberen Programmierstil.

=Weitere Sprachen=

MapScript kann mit verschiedenen Sprachen genutzt werden. Neben PHP sind die populärsten Perl, Java und Python.

Die MapServer-Entwickler bedienen sich bei diesen Sprachen des Interface-Generators SWIG~[[http:website:swig]]. Die Verwendung von SWIG und die Erstellung von MapScript-Modulen für andere Programmiersprachen wird im Anhang besprochen.

==Perl==

Zu Perl gibt es unglaublich viel Literatur. Nichts falsch machen kann man wohl mit~[[wall:1996:perl5]], dem berühmten Camel Book. Es ist auch auf deutsch erschienen.

==Java==

Java ist eine Sprache, aus der ein unglaublicher Hype hervorgegangen ist. Die Literatur, die sich mit Java auseinandersetzt, ist dermaßen umfangreich, dass Sie sich von dem Buchhändler Ihres Vertrauens beraten lassen sollten.

==Python==

Python hat sich einen Namen als einfache, strukturierte und schnell zu lernende Programmiersprache gemacht. Wer des Englischen mächtig ist, ist mit der Lektüre von~[[lutz:1999:python]] recht gut beraten; das Buch ist auch auf deutsch erschienen.

\chapter{Java-Applets}\index{Applets}(1)

=Mapplet=\index{Mapplet}(2)

=ROSA=(3)\index{ROSA}

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 5

2009-01-23T10:12:30Z

Wiki-Mikee63: /* Demos */

= Demos =
\index{Demos}(1)

Um einen ersten Eindruck vom MapServer zu bekommen, gibt es Demo-Applikationen. Eine nicht unerhebliche Anzahl von Anfragen auf der Mailingliste bezieht sich auf das Einrichten der Demos; es scheint also nicht ganz trivial zu sein.

Um einen reibungslosen Einstieg zu erleichtern, gebe ich hier -- soweit möglich -- eine Schritt-für-Schritt-Anleitung, damit Sie die Demos so schnell wie möglich ausprobieren können. Im wesentlichen handelt es sich um kleine Eingriffe in die Mapfiles bzw. die Templates der Anwendung, also Dinge, die sich mit einem beliebigen Texteditor schnell und einfach erledigen lassen.

Es wird aber davon ausgegangen, dass Sie bereits eine laufende MapServer-Installation haben; dass Sie also das Binary in das entsprechende =cgi-bin= -Verzeichnis im Webserver kopiert haben, und dass ein Aufruf wie in Abschnitt~\ref{text:mapfile:cgi} beschrieben, die zu erwartende Fehlermeldung produziert.

=Itasca=\index{Itasca}\index{Demos!Itasca}(2)

Itasca County ist Teil des Bundesstaates Minnesota, hat etwa 43000 Einwohner, die in 16 Städten und 42 Townships leben, und muß vor allen Dingen seit Urzeiten als typisches Demo für den MapServer herhalten. Sie können es als Paket von der MapServer-Website herunterladen. Lassen Sie sich dabei vom Dateinamen =itasca3.5.tar.gz= nicht irritieren, diese Fassung ist für MapServer 4.0 immer noch aktuell.

Die Schritte, die nun zu unternehmen sind, sind die folgenden:

#Archiv entpacken
#Temporäres Verzeichnis anlegen
#Zugriffsrechte anpassen
#Initialisierungsseite editieren
#Konvertieren der GIF-Symbole (optional)

\subsubsection*{Entpacken und Verzeichnisse setzen}

Entpacken Sie die das Archiv in das =htdocs= -Verzeichnis Ihres Webservers, unter Linux beispielsweise so:

 <code>
# tar -xzvf itasca3.5.tar.gz
</code> 

Legen Sie nun, ebenfalls im =htdocs= -Verzeichnis, ein Unterverzeichnis =ms_tmp= an. Dieses Verzeichnis wird von MapServer dazu benutzt werden, um die erzeugten Bilder zwischenzuspeichern.

Nun sollten die Zugriffs- bzw. Besitzrechte korrekt gesetzt werden. Die Demo-Dateien sollten auf den meisten Systemen dem Benutzer =root= gehören, während das Verzeichnis für die temporären Dateien von dem Benutzer beschreibbar sein muß, unter dem der Webserver läuft. Unter Debian Linux ist das beispielsweise =www-data= . Das Setzen der Rechte könnte also zum Beispiel so aussehen:

(3) <code>
# chown -R root.root itasca/
# chown www-data.root itasca/
</code> 

\subsubsection*{Dateien editieren}

Die restliche Arbeit besteht nun darin, die Startseite des Demos anzupassen. Dazu müssen Sie die Dateien jeweils in einem Texteditor Ihrer Wahl öffnen. Unter Windows könnte das beispielsweise =notepad= sein, unter Linux emacs oder vim.

Öffnen Sie zuerst die Startseite des Demos mit dem Namen =demo_init.html= . Die Zeilen, die Sie wahrscheinlich anpassen möchten, sind:

*=<form method=GET action="{= /cgi-bin/mapserv"{}>}\\ Hier setzen Sie das zu verwendende MapServer-Binary. Dieser Eintrag stimmt höchstwahrscheinlich schon.
*=<input type="{= hidden"{} name="{}map"{} value="{}..."{}>}\\ Wo hier die drei Punkte gesetzt sind, geben Sie den vollständigen Pfad zum Mapfile an. Unter Windows beinhaltet das die Angabe des Laufwerks, also zum Beispiel =c:= .
*=<input type="{= hidden"{} name="{}program"{} value="{}/cgi-bin/mapserv"{}>}\\ Hier setzen Sie noch einmal den gleichen Wert wie beim ersten Punkt in dieser Aufzählung. Ist in den meisten Fällen bereits korrekt.
*=<input type="{= hidden"{} name="map_web_imagepath"{} value="{}..."{}>}\\ Wo hier die drei Puntke gesetzt sind, geben Sie den vollständigen Pfad zum temporären Verzeichnis an, dass Sie weiter oben erzeugt haben.
*=<input type="{= hidden"{} name="{}map_web_imageurl"{} value="{}/ms_tmp/"{}>}\\ Hier geben Sie den URL des temporären Verzeichnisses an. Wenn Sie das Verzeichnis wie oben beschrieben in =htdocs= angelegt haben, reicht hier =/ms_tmp/= aus.

\subsubsection*{GIF-Symbole konvertieren}

Dieser Schritt ist optional. Er muß nur dann unternommen werden, wenn Ihr MapServer keine GIF-Unterstützung beinhaltet. Wenn Sie vorkompilierte Binaries unter Windows benutzen, haben Sie GIF-Unterstützung und können diesen Schritt auslassen. Sobald Sie aber aktuellen Quellcode beispielsweise unter Linux selber kompiliert haben, müssen Sie die GIF-Symbole konvertieren und sie in das Mapfile aufnehmen.

Am schnellsten geht die Konvertierung mit dem Werkzeug ''ImageMagick'' ~[[http:website:imagemagick]], das heutzutage jeder Linux-Distribution beiliegt und auch für Windows zu haben ist.

Wechseln Sie in das Verzeichnis =symbols= des Demos und führen dort folgendes aus:

 <code>
# mogrify -type png *.gif
</code> 

Die Referenzkarte im Unterverzeichnis =graphics= muß auf die gleiche Weise konvertiert werden.

Nun müssen im Mapfile noch alle Verweise auf GIF-Symbole geändert werden. Das können Sie natürlich von Hand machen, oder mit der Funktion 'Suchen und Ersetzen' in Ihrem Editor. Es kann unter Linux aber beispielsweise auch so geschehen:

 <code>
# sed -e 's/gif/png/' demo.map > tmp~ && mv tmp~ demo.map
</code> 

=GMap=\index{GMap}\index{Demos!GMap}(4)

\begin{figure}
\begin{center}
\mmfig{0.75}{gmap}{Das kanadische GMap-Demo}
\end{center}
\end{figure}

Dieses Demo stammt von der kanadischen Firma DM Solutions, die einen erheblichen Einfluß auf die Entwicklung des MapServers hat. Von ihrer Website~[[http:website:dmsolutions]] läßt sich ein Paket mit dem Namen =gmap-ms3.6.tar.gz= herunterladen. Stören Sie sich nicht an der Versionsnummer; das ganze funktioniert hervorragend mit MapServer 4.0.

Für GMap muß PHP MapScript installiert sein. Dieser Vorgang wird hier nicht detailliert beschrieben, das passiert allerdings im Anhang ab Seite~\pageref{anhang:compile:mapscript:php}. Einen Screenshot des funktionierenden Demos können Sie in Abbildung~\ref{gmap}.

Die folgenden Schritte müssen Sie für das korrekte Funktionieren des Demos unternehmen:

#Auspacken des Archivs
#Zugriffsrechte setzen
#Anpassen der PHP-Seite(n)
#Konvertieren der GIF-Symbole (optional)

\subsubsection*{Entpacken und Zugriffsrechte}

Begeben Sie sich in das =htdocs= -Verzeichnis Ihres Webservers und entpacken Sie das Archiv, unter Linux beispielsweise folgendermaßen:

 <code>
# tar -xzf gmap-ms3.6.tar.gz
</code> 

Passen Sie dann noch die Besitzrechte für das neue Verzeichnis an:

 <code>
# chown -R root.root gmap/
</code> 

\subsubsection*{Anpassen der PHP-Seiten}

Die folgenden Änderungen werden, wie schon beim Itasca-Demo, ganz einfach mit einem Texteditor vorgenommen.

Zu Beginn der Datei =gmap75.phtml= finden Sie Zeilen, die prüfen, auf welchen Betriebssystem es sich befindet und in Abhängigkeit davon die MapScript-Bibliothek lädt. Unter Windows ist das eine Datei mit der Endung =.dll= , unter Linux mit der Endung =.so= . Wenn Sie beim Aufruf von

 <code>
http://name.des.servers/gmap/htdocs/gmap75.phmtml
</code> 

eine Fehlermeldung erhalten, dass MapScript nicht geladen werden konnte, ändern Sie den Namen der Bibliothek in den korrekten Wert. Beispielsweise wird es auf vielen Unix-Systemen passieren, dass die Zeilen

 <code>
if (!extension_loaded("MapScript"))
dl("php_mapscript_36.so");
</code> 

geändert werden müssen in:

 <code>
if (!extension_loaded("MapScript"))
dl("php_mapscript.so");
</code> 

Das ist insbesondere der Fall, wenn Sie aus den Quellen selberkompiliert haben, da die Datei dann nicht so heißt, wie von GMap ursprünglich erwartet.

Als nächstes muß noch das Mapfile angepaßt werden. Falls Sie den Schritten für das Itasca-Demo weiter oben gefolgt sind, und das Verzeichnis für temporäre Pfade wie auf Seite~\pageref{text:demos:itasca:temp} beschrieben anglegt haben, müssen Sie in =gmap75.map= die Zeile für den =IMAGEPATH= geändert werden; dort steht dann

 <code>
IMAGEPATH "/.../ms_tmp/"
</code> 

wobei die drei Punkte für den kompletten Pfad zum temporären Verzeichnis im System stehen und dementsprechend von Ihnen ausgefüllt werden müssen.

\subsubsection*{Konvertierung der GIF-Symbole}

Falls Ihre MapServer-Installation nicht mit GIF-Dateien umgehen kann (siehe auch weiter vorne in der entsprechenden Sektion zum Itasca-Demo), müssen Sie noch die Referenzkarte =keymap.gif= im Unterverzeichnis =htdocs/images= in ein PNG-Bild konvertieren, und den Verweis auf das Bild im Mapfile abändern.

Die Konvertierung kann wieder mit ImageMagick geschehen:

 <code>
# convert keymap.gif keymap.png
</code> 

Der Verweis auf die Referenzkarte im Mapfile heißt dann:

 <code>
REFERENCE
IMAGE "images/keymap.png"
...
</code> 

\subsubsection*{Der Java-Modus}

Sollten Sie nun immer noch kein Bild in Ihrem Browser zu sehen bekommen, liegt es daran, dass GMap grundsätzlich im Java-Modus startet, Sie aber kein Java-Plugin in Ihrem Browser installiert haben. In diesem Fall können Sie mit einem Klick auf das Java-Symbol in der linken unteren Ecke in den 'reinen' HTML-Modus schalten.

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 4

2009-01-23T10:10:00Z

Wiki-Mikee63: /* Beispiel: Einspielen des Itasca-Demos */

= Datenbankanbindungen =
\index{Datenbanken}(1)

Die Verwendung von Datenbanken für die Speicherung von Vektordaten\footnote{Es gibt auch Datenbanken, die Rasterdaten in Datenbanken speichern und verarbeiten. Generell ist das jedoch etwas, was man nicht wirklich haben möchte.} birgt diverse Vorteile.

Zuerst einmal ermöglicht es eine Datenhaltung, die von der eigentlichen Applikation getrennt ist: das System, das die fertigen Karten ausliefert, kann ein anderes sein als dasjenige, das die Daten hält. Das läßt sich zwar auch beispielweise über Netzwerkdateisysteme erreichen; dann müssen aber bei einer Anfrage alle Daten übertragen werden, wohingegen eine Datenbank in der Lage ist, nur die gewünschten Ergebnisse zurückzureichen.

Das impliziert auch gleich einen zweiten Vorteil: man kann auch die Berechnungen auf ein anderes System auslagern. Wenn die Datenbank in der Lage ist, die darzustellenden Shapes für einen gegebenen Ausschnitt schnell zu finden und auszuliefern, fallen diese Berechnungen auf dem kartenproduzierenden System fort. Darüberhinaus sind Datenbanken beim Lesen ihrer Daten generell erheblich schneller als es Zugriffe auf ein Dateisystem sind, sodass auch hier ein versteckter Performancegewinn winkt.

Das überhaupt beste Einsatzgebiet für eine GIS-Datenbank sind sehr große Datensätze, aus denen kleine Ausschnitte gezeigt werden, da Datenbanken auf die Geschwindigkeit der Suche optimiert sind.

Für einen sicherheitsorientierten Personenkreis ist außerdem interessant, dass jemand, der Zugriff auf das System mit dem MapServer erlangt, nicht automatisch Zugriff auf die Daten erhält.

Ein Großteil dieser Vorteile existiert ganz offensichtlich nur dann, wenn MapServer und Datenbank tatsächlich auf verschiedenen Systemen residieren. Es hindert Sie natürlich niemand daran, beides auf dem gleichen Rechner laufen zu lassen.

=PostgreSQL und PostGIS=
(2)
\index{Datenbank!PostgreSQL}
\index{PostGIS}\index{PostgreSQL}

PostgreSQL ist eine freie SQL-Datenbank, die eine komplexe Geschichte und vor allen Dingen eine Menge Namensänderungen vorweisen kann. Insbesondere aber handelt es sich um eine schnelle, hochgradig konfigurierbare Datenbank, die dem Vergleich mit den 'Großen' des kommerziellen Geschäfts gelassen entgegen sehen kann.

PostGIS ist eine Erweiterung von PostgreSQL, deren wichtigster Beitrag wohl die Implementierung eines großen Teils der Simple Features des OGC ist. Der MapServer kann mit Unterstützung für PostGIS kompiliert werden. Das interessanteste Merkmal ist wohl, dass auf diese Weise der Datenbank die Berechnung der anzuzeigenden Punkte überlassen wird.

Die Features von PostGIS, die über die Anbindung an den MapServer hinausgehen, sollen hier nicht Gegenstand der Betrachtung sein. Für ein weiteres Studium sei auf die PostGIS-Dokumentation verwiesen.

Oft ist die Frage gestellt worden, warum ausgerechnet PostGIS benutzt wurde, und nicht etwa MySQL. Der Hauptgrund ist wohl, dass die Unterstützung für Transactions\footnote{Darunter versteht man das Zusammenfassen mehrer SQL-Anweisungen zu eben einer Transaktion, inklusive der Möglichkeit, die gesamte Transaktion später rückgängig machen zu können.} in MySQL eher, nun, dürftig ist.

Details zur Installation von PostGIS finden Sie im Anhang. Die Webseite von PostgreSQL ist [[http:website:postgresql]] (ein guter Teil der Dokumentation ist dort auf deutsch erhältlich), die Website zu PostGIS ist [[http:website:postgis]]. Ein hervorragendes deutschsprachiges Buch zu PostgreSQL ist mit~[[hartwig:2001:postgresql]] im Handel erhältlich.

Nach der Installtion von Postgresql und Postgis muss das DBMS für die Nutzeranmeldung konfiguriert werden.
Dazu wird dem Benutzer postgres ein Password vergeben.
Als Benutzer postgres folgendes ausführen:
psql
alter user postgres with password 'newpassword';
createdb -E UTF8 postgisdb
createlang plpgsql postgisdb
psql -f /usr/share/postgresql-8.3-postgis/lwpostgis.sql -d postgisdb
psql -f /usr/share/postgresql-8.3-postgis/spatial_ref_sys.sql -d postgisdb

\subsubsection*{Vorbereiten einer Datenbank für PostGIS}

Dieser Teil gehört zum Abschnitt über die Installation von PostGIS im Anhang.

==Shapefiles in PostGIS laden==(3)

Um Ihre Shapefiles in eine PostGIS-Datenbank zu laden, benutzen Sie das kleine Werkzeug =shp2pgsql= , das als Teil des PostGIS-Quellcodes kompiliert wird. Das Programm erzeugt aus einem Shapefile eine Textdatei, die SQL-Statements zum Erstellen einer Tabelle in der Datenbank enthält. Diese Datei muß dann nur noch mittels =psql= eingelesen werden.

Ein Beispiel:

 <code>
# shp2pgsql shapefile.shp tabellenname dbname > shapefile.sql
# psql -f shapefile.sql
</code> 

Für gewöhnlich werden die Shapefiles für eine Applikation in verschiedenen Tabellen in der gleichen Datenbank abgespeichert; das kann je nach Anforderung natürlich anders sein.

\subsubsection*{Erstellen von Indizes}

Sobald Sie die Daten in Ihre Datenbanken geladen haben, sollten Sie einen räumlichen Index für diese Daten erzeugen. Das Erstellen eines solchen Index ist ein einmaliger Vorgang, der einige Zeit in Anspruch nehmen kann, der den Zugriff auf die Daten im Betrieb jedoch erheblich beschleunigt.

PostGIS verwendet sogenannte GiST-Indizes, was wundersamerweise für Generalized Search Trees steht.

 <code>
CREATE INDEX [idxname] ON [tablename] USING GIST
([geofeld] GIST_GEOMETRY_OPS);
</code> 

Dieser Vorgang kann auf großen Datensätzen laut Dokumentation recht lange Zeit dauern -- ich selbst habe nie mehr als einige Sekunden warten müssen.

Danach ist es sinnvoll, ein =VACUUM= auf der Datenbank durchzuführen:

 <code>
VACUUM ANALYZE;
</code> 

PostgreSQL beginnt dann, Statistiken und andere Informationen über die einzelnen Tabellen zusammenzustellen, die im Zusammenhang mit dem Index benötigt werden. Damit ist die PostGIS-Datenbank voll einsatzbereit.

Laut Dokumentation ist es für die Layer, die auch für Queries zur Verfügung stehen sollen, ratsam, einen sogenannten =oid= -Index zu erstellen. In Anlehnung an den GiST-Index erfolgt das folgendermaßen:

 <code>
CREATE INDEX [idxname] ON [tablename] (oid);
</code> 

===Beispiel: Einspielen des Itasca-Demos===

Um mit PostGIS erste Schritte zu unternehmen, könnte man beispielweise die Shapefiles aus dem Itasca-Demo in PostGIS-Tabellen überführen. Das möchte man jedoch kaum für jedes Shapefile einzeln und von Hand machen; ein kleines Shell-Skript hilft hier weiter:

 <code>
#!/bin/sh

S2P=/usr/local/GIS/bin/shp2pgsql
PROJ=26915
DBNAME=spatialdata
rm -rf output.sql
for s in *.shp; do
SHPFBASE=`echo <math>s | sed -e s/.shp//g`
<math>{S2P} -s </math>{PROJ} -d <math>{SHPFBASE}.shp itasca_</math>{SHPFBASE} \
</math>{DBNAME} >> output.sql
echo -e "\n" >> output.sql
echo -e "CREATE INDEX idx_itasca_<math>{SHPFBASE} ON \
itasca_</math>{SHPFBASE} USING \
GIST (the_geom GIST_GEOMETRY_OPS);\n" >> output.sql
echo -e "CREATE INDEX oid_itasca_<math>{SHPFBASE} ON \
itasca_</math>{SHPFBASE} (oid);\n" >> output.sql
done
</code> 

Auch in diesem Skript sind die Backslashes an den Zeilenende dafür da, einen Zeilenumbruch anzuzeigen, der nur wegen des Drucklayouts eingefügt werden mußte.

Das Skript definiert zuerst den Pfad zum Tool =shp2pgsql= , die gewünschte Projektion als EPSG-Code und den Namen der Datenbank. Danach werden alle Shapefiles im aktuellen Verzeichnis in SQL-Befehle konvertiert und zusammen mit den Befehlen zur Indexerzeugung in die Datei =output.sql= geschrieben. Als Tabellennamen werden die Dateinamen ohne die Endung =.shp= und mit dem vorgehängten Prefix =itasca_= verwendet.

Danach kann diese Datei wie beschrieben z.B. mit

 <code>
# psgl -d spatialdata -f output.sql
</code> 

in die Datenbank übernommen werden.

==Notation in Layern==

Die Notation von PostGIS-Layern unterscheidet sich nur geringfügig von 'normalen' Vektordatenlayern. Zuerst ein Beispiel:

 <code>
LAYER
NAME "strassen"
TYPE "LINE"
STATUS ON
CONNECTIONTYPE POSTGIS
CONNECTION "user=postgisuser dbname=berlin host=192.168.27.13"
DATA "the_geom from roads"
FILTER "length >= 20"
CLASS
COLOR 255 0 0
END
END
</code> 

Der =TYPE= des Layers muß, wie für jeden Vektorlayer, gesetzt sein. Anstatt jedoch nur eine Datenquelle mit =DATA= anzugeben, wird =CONNECTIONTYPE= verwendet, um anzuzeigen, dass eine externe Verbindung hergestellt werden soll; in diesem Fall zu einer PostGIS-Datenbank.

Die Parameter, die hinter =CONNECTION= aufgelistet sind, geben die nötigen Informationen zum lesenden\footnote{Es ist beim Einsatz von Datenbanken generell eine sinnvolle Idee, für öffentlich zugängliche Applikationen einen Benutzer auf der Datenbank einzurichten, der ausschließlich lesenden Zugriff auf einen rigoros eingeschränkten Bereich besitzt.} Zugriff auf die Datenbank an: Benutzername, Paßwort und natürlich die Adresse des Datenbankservers. Hier sind noch andere Parameter möglich -- konsultieren Sie die PostgrSQL-Dokumentation, falls sie Einstellungen vorgenommen haben, die von den Defaults abweichen, beispielsweise für Ports.

Der Parameter =DATA= gibt den Namen der Spalte an, die die eigentlichen Geometrie-Daten vorhält. Bei Daten, die mit =shp2pgsql= eingespielt worden sind, ist das normalerweise =the_geom= .

=FILTER= definiert einen zusätzlichen Filter für die Anfrage, der als Zusatz zu einer SQL-Anfrage aufgefaßt werden kann, die nach einem =WHERE= folgt. Um diese Option sinnvoll nutzen zu können, muß man sich zwangsweise ein wenig mit der Abfragesprache SQL auskennen.

Danach folgen wieder die einzelnen Klassen zur Definition der Darstellung. Falls Sie an dieser Stelle =EXPRESSION= s benutzen möchten, beachten Sie bitte, dass Sie hier Feldnamen explizit angeben müssen, da es kein =CLASSITEM= in einem PostGIS-Layer gibt.

==PostGIS außerhalb des MapServers==

PostGIS ist als Erweiterung von PostgreSQL natürlich auch ohne den MapServer nutzbar. Dabei hält sich PostGIS an die OGC-Spezifikation mit dem Namen ''Simple Features for SQL'' ~[[]], sodass Sie mit jeder zu diesem Standard konformen Software Zugriff erhalten sollten.

FIXME:vervollständigen!1!

\chapter{Maplab}\index{Maplab}(1)

TODO: vervollständigen!!1!

=Mapedit=

TODO: vervollständigen!!1!

=Mapbrowser=

TODO: vervollständigen!!1!

=GMap Factory=

TODO:mehr!1!

\chapter{Chameleon}\index{Chameleon}(1)

\chapter{Mapfile-Prototyping mit vingar}

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 4

2009-01-23T10:08:57Z

Wiki-Mikee63: /* PostgreSQL und PostGIS */

= Datenbankanbindungen =
\index{Datenbanken}(1)

Die Verwendung von Datenbanken für die Speicherung von Vektordaten\footnote{Es gibt auch Datenbanken, die Rasterdaten in Datenbanken speichern und verarbeiten. Generell ist das jedoch etwas, was man nicht wirklich haben möchte.} birgt diverse Vorteile.

Zuerst einmal ermöglicht es eine Datenhaltung, die von der eigentlichen Applikation getrennt ist: das System, das die fertigen Karten ausliefert, kann ein anderes sein als dasjenige, das die Daten hält. Das läßt sich zwar auch beispielweise über Netzwerkdateisysteme erreichen; dann müssen aber bei einer Anfrage alle Daten übertragen werden, wohingegen eine Datenbank in der Lage ist, nur die gewünschten Ergebnisse zurückzureichen.

Das impliziert auch gleich einen zweiten Vorteil: man kann auch die Berechnungen auf ein anderes System auslagern. Wenn die Datenbank in der Lage ist, die darzustellenden Shapes für einen gegebenen Ausschnitt schnell zu finden und auszuliefern, fallen diese Berechnungen auf dem kartenproduzierenden System fort. Darüberhinaus sind Datenbanken beim Lesen ihrer Daten generell erheblich schneller als es Zugriffe auf ein Dateisystem sind, sodass auch hier ein versteckter Performancegewinn winkt.

Das überhaupt beste Einsatzgebiet für eine GIS-Datenbank sind sehr große Datensätze, aus denen kleine Ausschnitte gezeigt werden, da Datenbanken auf die Geschwindigkeit der Suche optimiert sind.

Für einen sicherheitsorientierten Personenkreis ist außerdem interessant, dass jemand, der Zugriff auf das System mit dem MapServer erlangt, nicht automatisch Zugriff auf die Daten erhält.

Ein Großteil dieser Vorteile existiert ganz offensichtlich nur dann, wenn MapServer und Datenbank tatsächlich auf verschiedenen Systemen residieren. Es hindert Sie natürlich niemand daran, beides auf dem gleichen Rechner laufen zu lassen.

=PostgreSQL und PostGIS=
(2)
\index{Datenbank!PostgreSQL}
\index{PostGIS}\index{PostgreSQL}

PostgreSQL ist eine freie SQL-Datenbank, die eine komplexe Geschichte und vor allen Dingen eine Menge Namensänderungen vorweisen kann. Insbesondere aber handelt es sich um eine schnelle, hochgradig konfigurierbare Datenbank, die dem Vergleich mit den 'Großen' des kommerziellen Geschäfts gelassen entgegen sehen kann.

PostGIS ist eine Erweiterung von PostgreSQL, deren wichtigster Beitrag wohl die Implementierung eines großen Teils der Simple Features des OGC ist. Der MapServer kann mit Unterstützung für PostGIS kompiliert werden. Das interessanteste Merkmal ist wohl, dass auf diese Weise der Datenbank die Berechnung der anzuzeigenden Punkte überlassen wird.

Die Features von PostGIS, die über die Anbindung an den MapServer hinausgehen, sollen hier nicht Gegenstand der Betrachtung sein. Für ein weiteres Studium sei auf die PostGIS-Dokumentation verwiesen.

Oft ist die Frage gestellt worden, warum ausgerechnet PostGIS benutzt wurde, und nicht etwa MySQL. Der Hauptgrund ist wohl, dass die Unterstützung für Transactions\footnote{Darunter versteht man das Zusammenfassen mehrer SQL-Anweisungen zu eben einer Transaktion, inklusive der Möglichkeit, die gesamte Transaktion später rückgängig machen zu können.} in MySQL eher, nun, dürftig ist.

Details zur Installation von PostGIS finden Sie im Anhang. Die Webseite von PostgreSQL ist [[http:website:postgresql]] (ein guter Teil der Dokumentation ist dort auf deutsch erhältlich), die Website zu PostGIS ist [[http:website:postgis]]. Ein hervorragendes deutschsprachiges Buch zu PostgreSQL ist mit~[[hartwig:2001:postgresql]] im Handel erhältlich.

Nach der Installtion von Postgresql und Postgis muss das DBMS für die Nutzeranmeldung konfiguriert werden.
Dazu wird dem Benutzer postgres ein Password vergeben.
Als Benutzer postgres folgendes ausführen:
psql
alter user postgres with password 'newpassword';
createdb -E UTF8 postgisdb
createlang plpgsql postgisdb
psql -f /usr/share/postgresql-8.3-postgis/lwpostgis.sql -d postgisdb
psql -f /usr/share/postgresql-8.3-postgis/spatial_ref_sys.sql -d postgisdb

\subsubsection*{Vorbereiten einer Datenbank für PostGIS}

Dieser Teil gehört zum Abschnitt über die Installation von PostGIS im Anhang.

==Shapefiles in PostGIS laden==(3)

Um Ihre Shapefiles in eine PostGIS-Datenbank zu laden, benutzen Sie das kleine Werkzeug =shp2pgsql= , das als Teil des PostGIS-Quellcodes kompiliert wird. Das Programm erzeugt aus einem Shapefile eine Textdatei, die SQL-Statements zum Erstellen einer Tabelle in der Datenbank enthält. Diese Datei muß dann nur noch mittels =psql= eingelesen werden.

Ein Beispiel:

 <code>
# shp2pgsql shapefile.shp tabellenname dbname > shapefile.sql
# psql -f shapefile.sql
</code> 

Für gewöhnlich werden die Shapefiles für eine Applikation in verschiedenen Tabellen in der gleichen Datenbank abgespeichert; das kann je nach Anforderung natürlich anders sein.

\subsubsection*{Erstellen von Indizes}

Sobald Sie die Daten in Ihre Datenbanken geladen haben, sollten Sie einen räumlichen Index für diese Daten erzeugen. Das Erstellen eines solchen Index ist ein einmaliger Vorgang, der einige Zeit in Anspruch nehmen kann, der den Zugriff auf die Daten im Betrieb jedoch erheblich beschleunigt.

PostGIS verwendet sogenannte GiST-Indizes, was wundersamerweise für Generalized Search Trees steht.

 <code>
CREATE INDEX [idxname] ON [tablename] USING GIST
([geofeld] GIST_GEOMETRY_OPS);
</code> 

Dieser Vorgang kann auf großen Datensätzen laut Dokumentation recht lange Zeit dauern -- ich selbst habe nie mehr als einige Sekunden warten müssen.

Danach ist es sinnvoll, ein =VACUUM= auf der Datenbank durchzuführen:

 <code>
VACUUM ANALYZE;
</code> 

PostgreSQL beginnt dann, Statistiken und andere Informationen über die einzelnen Tabellen zusammenzustellen, die im Zusammenhang mit dem Index benötigt werden. Damit ist die PostGIS-Datenbank voll einsatzbereit.

Laut Dokumentation ist es für die Layer, die auch für Queries zur Verfügung stehen sollen, ratsam, einen sogenannten =oid= -Index zu erstellen. In Anlehnung an den GiST-Index erfolgt das folgendermaßen:

 <code>
CREATE INDEX [idxname] ON [tablename] (oid);
</code> 

===Beispiel: Einspielen des Itasca-Demos===

Um mit PostGIS erste Schritte zu unternehmen, könnte man beispielweise die Shapefiles aus dem Itasca-Demo in PostGIS-Tabellen überführen. Das möchte man jedoch kaum für jedes Shapefile einzeln und von Hand machen; ein kleines Shell-Skript hilft hier weiter:

 <code>
#!/bin/sh

S2P=/usr/local/GIS/bin/shp2pgsql
PROJ=26915
DBNAME=spatialdata

rm -rf output.sql

for s in *.shp; do
SHPFBASE=`echo <math>s | sed -e s/.shp//g`
<math>{S2P} -s </math>{PROJ} -d <math>{SHPFBASE}.shp itasca_</math>{SHPFBASE} \
</math>{DBNAME} >> output.sql
echo -e "\n" >> output.sql
echo -e "CREATE INDEX idx_itasca_<math>{SHPFBASE} ON \
itasca_</math>{SHPFBASE} USING \
GIST (the_geom GIST_GEOMETRY_OPS);\n" >> output.sql
echo -e "CREATE INDEX oid_itasca_<math>{SHPFBASE} ON \
itasca_</math>{SHPFBASE} (oid);\n" >> output.sql
done
</code> 

Auch in diesem Skript sind die Backslashes an den Zeilenende dafür da, einen Zeilenumbruch anzuzeigen, der nur wegen des Drucklayouts eingefügt werden mußte.

Das Skript definiert zuerst den Pfad zum Tool =shp2pgsql= , die gewünschte Projektion als EPSG-Code und den Namen der Datenbank. Danach werden alle Shapefiles im aktuellen Verzeichnis in SQL-Befehle konvertiert und zusammen mit den Befehlen zur Indexerzeugung in die Datei =output.sql= geschrieben. Als Tabellennamen werden die Dateinamen ohne die Endung =.shp= und mit dem vorgehängten Prefix =itasca_= verwendet.

Danach kann diese Datei wie beschrieben z.B. mit

 <code>
# psgl -d spatialdata -f output.sql
</code> 

in die Datenbank übernommen werden.

==Notation in Layern==

Die Notation von PostGIS-Layern unterscheidet sich nur geringfügig von 'normalen' Vektordatenlayern. Zuerst ein Beispiel:

 <code>
LAYER
NAME "strassen"
TYPE "LINE"
STATUS ON
CONNECTIONTYPE POSTGIS
CONNECTION "user=postgisuser dbname=berlin host=192.168.27.13"
DATA "the_geom from roads"
FILTER "length >= 20"
CLASS
COLOR 255 0 0
END
END
</code> 

Der =TYPE= des Layers muß, wie für jeden Vektorlayer, gesetzt sein. Anstatt jedoch nur eine Datenquelle mit =DATA= anzugeben, wird =CONNECTIONTYPE= verwendet, um anzuzeigen, dass eine externe Verbindung hergestellt werden soll; in diesem Fall zu einer PostGIS-Datenbank.

Die Parameter, die hinter =CONNECTION= aufgelistet sind, geben die nötigen Informationen zum lesenden\footnote{Es ist beim Einsatz von Datenbanken generell eine sinnvolle Idee, für öffentlich zugängliche Applikationen einen Benutzer auf der Datenbank einzurichten, der ausschließlich lesenden Zugriff auf einen rigoros eingeschränkten Bereich besitzt.} Zugriff auf die Datenbank an: Benutzername, Paßwort und natürlich die Adresse des Datenbankservers. Hier sind noch andere Parameter möglich -- konsultieren Sie die PostgrSQL-Dokumentation, falls sie Einstellungen vorgenommen haben, die von den Defaults abweichen, beispielsweise für Ports.

Der Parameter =DATA= gibt den Namen der Spalte an, die die eigentlichen Geometrie-Daten vorhält. Bei Daten, die mit =shp2pgsql= eingespielt worden sind, ist das normalerweise =the_geom= .

=FILTER= definiert einen zusätzlichen Filter für die Anfrage, der als Zusatz zu einer SQL-Anfrage aufgefaßt werden kann, die nach einem =WHERE= folgt. Um diese Option sinnvoll nutzen zu können, muß man sich zwangsweise ein wenig mit der Abfragesprache SQL auskennen.

Danach folgen wieder die einzelnen Klassen zur Definition der Darstellung. Falls Sie an dieser Stelle =EXPRESSION= s benutzen möchten, beachten Sie bitte, dass Sie hier Feldnamen explizit angeben müssen, da es kein =CLASSITEM= in einem PostGIS-Layer gibt.

==PostGIS außerhalb des MapServers==

PostGIS ist als Erweiterung von PostgreSQL natürlich auch ohne den MapServer nutzbar. Dabei hält sich PostGIS an die OGC-Spezifikation mit dem Namen ''Simple Features for SQL'' ~[[]], sodass Sie mit jeder zu diesem Standard konformen Software Zugriff erhalten sollten.

FIXME:vervollständigen!1!

\chapter{Maplab}\index{Maplab}(1)

TODO: vervollständigen!!1!

=Mapedit=

TODO: vervollständigen!!1!

=Mapbrowser=

TODO: vervollständigen!!1!

=GMap Factory=

TODO:mehr!1!

\chapter{Chameleon}\index{Chameleon}(1)

\chapter{Mapfile-Prototyping mit vingar}

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 3

2009-01-23T07:33:56Z

Wiki-Mikee63: /* Den Kontext verwenden */

[[User:Astrid Emde]] (SLD, WMC, Filter Encoding, OWS Clients) 
[[User:jtmapmedia | Jörg Thomsen]] (OGC-Konformität, Warum macht man das?, Wie macht man das? )

[[HBUMNMapServer_ger | '''Inhaltsverzeichnis''']]

= OGC-Konformität =
--[[User:Jtmapmedia|Jtmapmedia]] 13:52, 10 January 2009 (UTC)
(1)\index{OGC}

Das [http://www.opengeospatial.org/ Open Geospatial Consortium]~\cite{http:website:ogc}, kurz OGC, ist ein internationaler Zusammenschluß von '368 Unternehmen, Regierungsorganisationen und Universitäten' (Eigendarstellung auf der Website, die Zahl ändert sich beinahe wöchentlich). Ziel des OGC ist es, gemeinsame Standards (Protokolle, Formate etc.) für Austausch, Verarbeitung und Speicherung von Geodaten zu erarbeiten.

Die Standards, die uns bei der Erstellung von OGC-konformen MapServern im Internet interessieren können, sind vielfältig. Für den MapServer sind die folgenden Standards relevant bzw. implementiert:

* OGC Web Map Service Specification (WMS), für den Transfer von Rasterkarten und eventuelle Anfragen auf diese Daten,
* OGC Web Feature Service Specification (WFS), was das gleiche für Vektordaten und eventuelle Anfragen auf diese Daten ist.
* OGC Web Coverage Service Specification (WCS), regelt den Zugriff auf hochaufgelöste Rasterdaten wie Luft- und Satellitenbilder und deren Bereitstellung.
* OGC Sensor Observation Service (SOS), der den Austausch von Sensordaten, wie z.B. Wasserpegel oder Temperaturmessungen spezifiziert.
* Map Context Specification, ermöglicht das Speichern und Laden von WMS-Zuständen wie Zoomstufe, sichtbare Layer usw..

Darüber hinaus werfen wir auch noch einen raschen Blick auf

* OGC Filter Encoding (FE), damit können Geodaten, beispielsweise für Klassifizierungen, gefilter werden.
* OGC Styled Layer Descriptors (SLD), eine Spezifikation, die es ermöglicht die Kartengestaltung eines entfernten WMS zu beeinflussen.

Die Website des OGC ist unter~[[http:website:ogc]] zu erreichen. Zu allen genannten Diensten, und zu vielen weiteren, finden Sie dort auch die Spezifikationen als PDF-Dateien. Sehen Sie sie sich ruhig einmal an. Nachdem Sie die ersten 20 bis 30 Seiten überblättert haben, finden Sie vor dem Anhang die interessanten Informationen auf meist wenigen Seiten zusammengefasst.

=Warum macht man das?=
--[[User:Jtmapmedia|Jtmapmedia]] 13:56, 10 January 2009 (UTC)

Eine berechtigte Frage ist natürlich, warum man diese Funktionalität überhaupt haben wollen könnte. Die Antworten sind vielfältig. Hier einige Beispiele:

\subsubsection* {'''Kein Zugang zu den Originaldaten'''}

Die wenigsten Besitzer von Geodaten rücken diese umsonst, oder überhaupt heraus. Manche sind allerdings durchaus gewillt, Karten auszuliefern; ihre Originaldaten kommen dabei nicht an die Öffentlichkeit. Durch die Bereitstellung von Karten nach den Kriterien des WMS sind darüberhinaus nicht nur Sie, sondern auch andere in der Lage, Karten aus der 'schwierigen Quelle' zu beziehen. Die Existenz eines Standards kann also schon zur Verbreitung von Kartenmaterial beitragen.

\subsubsection*{'''Lastenverteilung'''}

Ähnlich wie bei Datenbankanbindungen -- siehe auch Kapitel~\ref{text:database} -- kann beispielweise ein WMS-konformes zur Verteilung von Rechenlast beitragen, indem einzelne Layer der Karte einfach auf verschiedene Rechner verteilt werden.

\subsubsection*{'''Herstellerunabhängigkeit'''}

Durch ein standardisiertes Kommunikationsprotokoll sind Sie in der Lage, sich den Hersteller Ihrer Software auszusuchen. Umgekehrt bedeutet das auch, dass Sie nicht auf die Software eines bestimmten Herstellers angewiesen sind, wenn beispielsweise auf einen WMS-konformen Server zugegriffen werden soll. Die Wahl der Software kann also eher an anderen Kriterien (z.B. dem Preis) ausgerichtet werden. Heutzutage gibt es eine große Zahl OGC-konformer Programme, die sich nahezu beliebig miteinander verknüpfen lassen, so kann eine als WMS konfigurierter UMN MapServer seine Karte problemlos an verschiedene Klienten sowohl im Browser (z.N. Mapbender, OpanLayers) als auch auf dem Desktop (z.B. Quantum GIS, gvSIG) ausliefern und einen wichtigen Teil zur Geodateninfrastruktur beitragen.

Auf der Website des OGC finden Sie eine Liste von Herstellern und Produkten~[[http:website:ogcnetwork:impl]] und eine Beschreibung, welche Standards in welcher Version von ihnen unterstützt werden.

\subsection*{'''Existenz von Evaluationskriterien'''}

Häufig steht man vor der Frage, welches Produkt man für einen besonderen Zweck einsetzen soll. Das richtige Vorgehen ist natürlich, sich klarzumachen, welche Eigenschaften und Möglichkeiten die Software bieten soll, und anhand einer daraus hervorgehenden Liste kann man dann verschiedene Produkte evaluieren.

Solch ein Evaluationsvorgang kann zeitlich und finanziell sehr aufwändig sein. Weithin anerkannte Standards helfen dabei, Entscheidungen anhand fertig vorliegender Kriterienkataloge zu treffen.

= Wie macht man das? =
--[[User:Jtmapmedia|Jtmapmedia]] 18:00, 10 January 2009 (UTC)

Eine UMN MapServer-Anwendung OGC-konform zu gestalten ist keine Hexerei, Sie benötigen nicht einmal eine Erweiterung und müssen auch nichts neu kompilieren - es sind lediglich einige Erweiterungen im Mapfile notwendig. Bevor wir uns aber wieder dem Mapfile zuwenden, ein paar Sätze das grundsätzliche Verständnis der Funktionsweise von OGC-Diensten fördern.

Der Aufruf eines WMS-Servers erfolgt ganz ähnlich dem Aufruf des UMN MapServers, nämlich über einen URL mit den gewünschten Parametern, Sie werden im Folgenden bemerken, dass auch andere Aufrufe, wie WFS oder WCS, dem gleichen Muster folgen. Die Benennung der Parameter, ihr Verhalten und ihre Wirkung unterscheiden sich jedoch mehr oder weniger stark von dem, was Sie bisher von ihrem MapServer gewohnt sind.

Schauen Sie sich einmal einen Aufruf für eine Karte als Beispiel an. Um die Generierung solcher URLs müssen Sie sich im Detail nicht kümmern; wenn Sie einen Server betreiben, dann sowieso nicht, weil der Aufrufende die URLs kennen muss, und nicht Sie; und wenn Sie MapServer als Client betreiben, dann müssen Sie zwar einige Angaben im Mapfile zwingend machen, aber alle dynamischen Parameter werden von MapServer aufgefüllt.

\subsubsection*{'''Hinweis'''} 
In der Version 4.x war MapServer sehr tolerant, einige würden sagen nicht voll OGC-konform, weil er nicht alle Aufrufparameter verlangte, die die Spezifikation vorschreibt. Wenn Sie beim Aufruf eines WMS ab UMN Version einen laut Spezifikation erforderlichen Parameter weglassen, wird das nun mit einer Fehlermeldung quittiert.

Nun aber ein Beispiel für einen WMS-konformen URL des MapServers:

FIXME: Beispielaufruf dem aktuellen OSM/Hamburg-Beispiel anpassen. 
<code>
http://www.example.com/cgi-bin/mapserv
? SERVICE=WMS
& VERSION=1.1.1
& REQUEST=GetMap
& FORMAT=image/png
& LAYERS=gruenflaechen,fluesse,bebauung
& SRS=EPSG:4326
& BBOX=5.0,45.0,15.0,55.0
& WIDTH=500
& HEIGHT=500
& STYLES,,,
#hier enden die Pflichtparameter, Auftritt zweier optionaler Parameter:
& TRANSPARENT=TRUE
& EXCEPTIONS=application/vnd.ogc.se_inimage
</code> 

Sie werden sich jetzt fragen, wo denn der Hinweis auf das Mapfile geblieben ist, den Sie bisher immer mit angeben mussten. Ein Parameter ''map'' ist in der WMS-Spezifikation allerdings nirgends erwähnt. Wie man sich dieses Parameters entledigen kann, erfahren Sie weiter unten auf Seite~\pageref{text:wms:mapfilename}.

Der erste Parameter ''SERVICE'' gibt an, welche Spezifikation genutzt werden soll. Wir möchten eine Karte im PNG-Format abrufen, die im Browser angezeigt werden soll, also benutzen wir den Web Map Service.

Als nächstes wird mit ''VERSION'' angegeben, in welcher WMS-Version man die Kommunikation wünscht. Laut Spezifikation soll dabei im Hintergrund eine Aushandlung der Version stattfinden, falls eine Seite eine angegebene Version nicht kennt; Client und Server handeln sich dann gegenseitig herunter, bis sie auf eine Version treffen, die sie beide verstehen.

Der Parameter ''REQUEST'' gibt die Art der Anfrage an. Die in MapServer implementierten Modi sind bereits weiter oben in Abschnitt~2 genannt worden. Beachten Sie, dass die Schreibweise von ''GetMap'' bezüglich der Klein- und Großbuchstaben irrelevant sein sollte. Das gleiche gilt auch für die Namen der Parameter wie ''VERSION'', ''REQUEST'' und so weiter. Die Großschreibung erfolgt hier nur wegen der besseren Lesbarkeit. Es gibt aber auch Dienste, die diese Schreibweise ewarten.

Die Angabe ''FORMAT'' wird als sogenannter ''MIME type'' gemacht, eine standardisierte Notation für die Art von über das Netz geschickten Daten. Bildformat folgen prinzipiell dem Muster ''image/'' plus angehängtem Namen des Bildformats, also zum Beispiel ''image/jpeg'' für JPEG-Bilder. Mehr über MIME-Typen inklusive Links zu den diversen zuständigen RFCs finden Sie auf~[[http:homepage:mime]].

Es folgen die Layer, die angezeigt werden sollen. Anders als beim 'klassischen' MapServer, wo die Layernamen einzeln jeweils mit ''layer'' notiert werden, wird bei WMS-konformen Servern eine Liste der gewünschten Layer benötigt, wobei die einzelnen Layer durch Kommata voneinander getrennt werden. Dabei ist die Reihenfolge wichtig: der zuerst genannte Layer wird als erste Ebene in die Karte gezeichnet, liegt also zuunterst. Die im Mapfile festgelegte Reihenfolge spielt keine Rolle mehr.

Mit ''SRS'' wird das ''spatial reference system'' definiert, also die gewünschte Projektion angegeben. WMS verlangt EPSG-Codes für die Notierung der Projektion, wobei das Schlüsselwort ''EPSG'' und die dazugehörige Zahl durch einen Doppelpunkt voneinander getrennt werden. Mehr zu diesem Thema, das oft zu schwer identifizierbaren Fehlern führt und einige Nerven kosten kann, finden Sie im Anhang FIXME: Verweis auf den noch zu erstellenden Anhang.

''BBOX'': Ähnlich wie die anzuzeigenden Kartenebenen werden auch die gewünschten Extents durch mehrere Werte angefordert, die in einer Liste durch Kommata voneinander getrennt sind. Achten Sie immer darauf, dass die Werte der BBOX mit dem SRS korrespondieren.

''WIDTH'' und ''HEIGHT'' geben die Größe in Pixeln vor, die die fertige Karte haben soll. Beachten Sie, dass diese Werte mit der BBOX korrelieren müssen; eine quadratische BBOX in Verbindung mit ungleicher Höhe und Breite führt zu einer Verzerrung des Kartenbildes.

Der Parameter ''STYLES'' gibt für jeden Layer eine Darstellungsoption an (sofern der Provider des Service dieses mit den sog. ''Named Styles'' vorbereitet hat). Sie müssen keine Styles angeben, der Parameter im GetMap-Aufruf ist jedoch Pflicht.

Mit ''TRANSPARENT'' wird die Hintergrundfarbe der Karte transparent geschaltet. Das will man offensichtlich dann haben, wenn man unter dieser Kartenebene noch andere Layer anzeigen möchte.

Schließlich und endlich wird dem WMS im obigen Beispiel mitgeteilt in welcher Form Fehlermeldungen ausgegeben werden, in unserem Fall soll die Fehlermeldung in resultierende Rasterbild gerendert werden. Wenn Sie eine XML-formatierte Fehlermeldung bevorzugen verwenden Sie ''application/vnd.ogc.se_xml''.

Das Ergebnis dieses Aufrufes ist also eine 500 mal 500 Pixel große, auf EPSG-Code FIXME: 4326 projizierte Karte im PNG-Format mit den angegebenen Extents und transparentem Hintergrund. Der aufrufende URL dieser Karte kann entweder so bei Ihnen im Webbrowser erscheinen, oder aber von MapServer dynamisch für die Anzeige als Rasterlayer generiert worden sein.

Als nächstes schauen wir uns an, wie aus einem bestehenden Mapfile eines gemacht werden kann, das für WMS-konformes Verhalten nach außen sorgt.

=Web Map Service (WMS)=
==UMN als WMS Server==

Von besonderem Interesse ist die ''OpenGIS Web Map Server Interfaces Implementation Specification'' , im folgenden kurz WMS-Standard genannt. Diese Spezifikation liegt inzwischen in der Version 1.1.1~[[pdf:spec:ogc111]] vor. MapServer unterstützt aber auch die zurückliegenden Standards 1.0.0~[[pdf:spec:ogc100]] und 1.1.0~[[pdf:spec:ogc110]].

Sinn der WMS-Spezifikation ist es, ein offenes, definiertes Interface sowohl für Clients als auch für Server zur Verfügung zu stellen, die Karten und Daten über diese Karten miteinander austauschen wollen. Zur Kommunikation zwischen den Servern und Clients wird das HTTP-Protokoll verwendet. Über das Protokoll werden Daten im XML-Format übertragen\footnote{Für Exceptions sind auch andere Formate möglich.}. Parsen und weiterverarbeiten läßt sich XML in fast jeder bekannten Programmiersprache. Auf diese Weise ist man nicht an Webapplikationen gebunden, wenn man ein Programm entwickeln möchte, das mit einem WMS-Mapserver 'redet'. Die dazugehörige DTD\footnote{Die sogenannten ''document type definitions'' dienen der Validierung von Dokumenten. Sie können ein DTD also benutzen, um zu testen, um ein Dokument einem bestimmten Rahmen an Vorgaben genügt.} ist vom OGC zu beziehen und in der Spezifikation beschrieben. Gedruckt lernen Sie mehr über XML durch die Lektüre von~[[ray:2001:xml]], online finden Sie die Spezifikationen unter~[[http:homepage:xml]].

\subsubsection*{Hinweis}

Eine zentrale Rolle bei der Verwendung von WMS spielt die Umprojizierung von Daten. Da bei WMS Rasterdaten zum Einsatz kommen\footnote{Die Datenquelle für den Server kann natürlich ein Vektorformat haben. Produziert werden aber ausschließlich Rasterdaten, wie wir es bisher immer beim MapServer gesehen haben.}, und MapServer Rasterdaten ausschließlich unter Zuhilfenahme der Bibliothek GDAL umprojizieren kann, sollten Sie MapServer mit der Unterstützung für GDAL kompiliert haben.

==Servermodi==(2)

Die genannten Spezifikation in ihrer letzten Version verlangt: es ''müssen'' zwei Arten von Anfragen implementiert sein, zwei weitere sind optional und ''können'' implementiert sein. Die beiden folgenden Anfragen (weiterhin auch ''Requests'' genannt) müssen vorhanden sein:

*=getCapabilities= : Diese Anfrage muss ein XML-Dokument zurückliefern, das die Fähigkeiten des Mapservers beschreibt.
*=getMap= : Auf diese Anfrage wird eine Karte als Rasterbild zurückgeliefert.

Entsprechend der Anforderung sind diese beiden Anfragen auch im MapServer implementiert.

Die beiden Fähigkeiten, die implementiert sein ''können'' , sind:

*=getFeatureInfo= : auf diese Anfrage liefert der Mapserver Informationen über einen bestimmten Punkt in einer Karte zurück. Diese Informationen können entweder in einer reinen Textdarstellung oder in GML (einem XML-Format) zurückgegeben werden.
*=describeLayer= liefert ein XML-Dokument mit detaillierten Informationen über einen Layer zurück. Dieser Modus wäre für einen SLD\footnote{Styled Layer Descriptor}-konformen MapServer interessant, aber dieser Standard hat bisher noch keine Umsetzung im MapServer erfahren.

Das einzige Feature, das im MapServer zurzeit nicht implementiert ist, ist demnach =describeLayer= . Es gibt noch einige andere Modi; mehr dazu in Abschnitt~7

==WMS-Metadaten im Mapfile==\index{Metadaten}

Zuallererst benötigt ihr Mapfile einen Namen. Im Header muß also der Parameter =NAME= definiert sein.

Einen 'minimalen' WMS-Server erhalten Sie zum einen durch Metadaten in der =WEB= -Sektion des Mapfiles, zum anderen durch Metadaten in den einzelnen Layern. Einige davon sind zwingend erforderlich, andere optional. Wie die Notation von Metadaten im Mapfile generell erfolgt, haben Sie bereits in Abschnitt~\ref{text:mapfile:web:meta} erfahren.

 <code>
WEB
...
METADATA
"wms_title" "Ein WMS-Server"
"wms_onlineresource" \
"http://www.example.com/cgi-bin/mapserv?map=mapfile.map&"
"wms_srs" "EPSG:31464 EPSG:4326"
END
END
</code> 

Der =wms_title= ist der Titel für die Karte, dieser muß angegeben werden. Der zweite Parameter gibt an, unter welchem URL der Server aufzurufen ist.

Beachten Sie dabei, das =\&= anzugeben, bzw. ein Fragezeichen, wenn Sie nach dem eigentlichen CGI-Programm keinen Parameter zu stehen haben.

=wms_srs= steht für die Projektion, in der die Karten angeboten werden können. Die Spezifikation schreibt vor, dass hier immer mindestens EPSG-Code 4326 angeboten werden muß. Mehrere Projektionen werden einfach durch Leerzeichen voneinander getrennt. Mehr zu EPSG und Projektionen im allgemeinen haben Sie schon in Abschnitt~\ref{text:map:projections} erfahren.

Sie benötigen =wms_srs= nicht, wenn Sie für die Karte einen Projektionsblock mit EPSG-Angabe definiert haben; die =WEB= -Sektion 'erbt' dann diese Projektion als Vorgabe.

Was machen Sie, wenn Ihre Daten allesamt in einer Projektion vorliegen, für die es keinen EPSG-Code gibt? Dann können Sie einen =PROJECTION= -Block definieren, der Parameter für die Projektionsbibliothek ''proj.4'' enthält (das Beispiel stammt direkt aus der MapServer-Dokumentation):

 <code>
PROJECTION
"proj=lcc"
"ellps=GRS80"
"lat_0=49"
"lon_0=-95"
"lat_1=49"
"lat_2=77"
END
</code> 

Wenn Sie nun EPSG-Codes in =wms_srs= nach außen anbieten, werden die Daten automatisch umprojiziert.

\subsubsection*{Notwendige Metadaten in den Layern}

Des weiteren müssen nun in jedem Layer zusätzliche Angaben nach folgendem Muster gemacht werden:

 <code>
LAYER
NAME "einlayer"
...
METADATA
"wms_title" "Titel fuer den Layer"
"wms_srs" "EPSG:31494"
END
END
</code> 

Daneben muß auch in jedem Layer ein Name gesetzt und eine Projektion definiert sein. Als Standardvorgabe erbt jeder Layer die Projektionen aus der =WEB= -Sektion, sodass sie nicht noch einmal neu notiert werden müssen.

Sie benötigen natürlich immer noch eine Projektionsangabe im Layer in Form eines =PROJECTION= -Blocks, um zu definieren, in welcher Projektion die Datenquelle vorliegt, damit MapServer im Zweifelsfall korrekt projizieren kann. Das gilt natürlich insbesondere dann, wenn Sie mehr als nur eine Projektion anbieten wollen.

MapServer geht im übrigen davon aus, dass sie tatsächlich alle Layer im Mapfile nach außen zur Verfügung stellen wollen. Layer, die sie ''nicht'' nach außen geben wollen, haben also in diesem Mapfile nichts verloren. Es gibt bisher keinen Mechanismus, mit dem man einzelne Layer (oder alle) in einem Mapfile von der Auslieferung per WMS ausschließen kann.

\subsubsection*{Metadaten in der Web-Sektion}

Im folgenden sind alle Metadaten beschrieben, die Sie für einen WMS-konformen Server in der =WEB= -Sektion des Mapfiles notieren können. Alle Angaben sind optional, falls nicht anders angegeben.

*=wms_abstract= Eine elaborierte Zusammenfassung dessen, was der Server soll und ist.
*=wms_accessconstraints= Gibt Zugangsbeschränkungen für den MapServer an. Beachten Sie bitte, dass ein Eintrag hier lediglich eine Absichtserklärung ist. Ein Text wie 'Dieser Server darf nur im Intranet unserer Firma verwendet werden' ist natürlich schön und gut, aber die entsprechenden Zugriffsbeschränkungen sind selbtsverständlich nur durch die entsprechende Konfiguration der Systeme zu erreichen.
*=wms_addresstype= Art der Adresse. Für dieses und die folgenden fünf Felder gilt, dass bei Angabe eines der Felder auch die anderen fünf mit Inhalt gefüllt werden müssen.
*=wms_address= Die Adresse.
*=wms_city= Adressbestandteil: Stadt
*=wms_country= Adressbestandteil: Land
*=wms_postcode= Adressbestandteil: Postleitzahl
*=wms_stateorprovince= Adressbestandteil: Staat oder Provinz
*=wms_contactelectronicmailaddress= Emailadresse einer Kontaktperson für diesen Server
*=wms_contactoraganization= Organisation der Kontaktperson
*=wms_contactperson= Name der Kontaktperson für diesen Server
*=wms_contactposition= Position der Kontaktperson innerhalb ihrer Organisation
*=wms_contactvoicetelephone= Telefonnummer der Kontaktperson
*=wms_fees= Art und Umfang der Gebühren, die für die Nutzung dieses Servers fällig werden. Genau wie bei =wms_accessconstraints= ist dies lediglich eine Absichtserklärung; wenn Sie Gebühren für die Verwendung des Servers erheben möchten, müssen Sie die Zugriffskontrolle durch eine geeignete Systemkonfiguration und ein passendes Geschäftsmodell herbeiführen.
*=wms_keywordlist= Eine Liste von Schlüsselworten, die auf den Server zutreffen. Dieser Parameter ist mit dem Blick darauf geschaffen worden, dass es eines Tages in einer eigens dafür geschaffenen Datenbank eine Sammlung von Capabilities-Dokumenten geben könnte, die dann die Schlüsselwortlisten durchsuchen kann. Bisher gibt es keine solche Datenbank. Es sind auch keine Standardschlüsselwörter definiert.
*=wms_onlineresource= Der URL, mit dem der Server aufgerufen wird. Beinhaltet beim UMN MapServer meistens: <code> http://www.example.com/cgi-bin/mapserv? </code> und gegebenenfalls daran angehängt noch das Mapfile. Wenn ein Mapfile über =map== angehangen wird, darf nicht das abschließende =\&= vergessen werden! Dieser Parameter ist zwingend notwendig.
*=wms_resx= Horizontale Auflösung der Karte in Pixeln.
*=wms_resy= Vertikale Auflösung der Karte in Pixeln.
*=wms_srs= Projektion(en), in der die Karte angeboten werden kann. Dieser Parameter mit mindestens einer Projektion ist zwingend notwendig.
*=wms_title= Titel der Karte. Dieser Parameter ist zwingend notwendig.

\subsubsection*{Metadaten in den einzelnen Layern}

Im folgenden die Metadaten, die Sie für einen WMS-konformen MapServer in den einzelnen Layern im Mapfile definieren können. Alle Parameter sind optional, sofern nicht anders angegeben.

*=wms_abstract= Elaborierte Zusammenfassung dessen, was dieser Layer soll und ist.
*=wms_extent= Die Bounding Box des Layers.
*=wms_keywordlist= Eine Liste von Schlüsselworten, die auf diesen Server zutreffen. %
*=wms_opaque= FIXME: was ist das?
*=wms_srs= Projektion(en), in der die Karte angeboten werden kann.
*=wms_title= Titel des Layers. Dieser Parameter ist zwingend erforderlich.

\subsubsection*{Das Mapfile als Parameter}(4)

Der Name des Mapfiles in der URL-Zeile ist nicht Bestandteil eines OGC-konformen Aufrufs des Mapservers. Unter Sicherheitsaspekten kann es darüber hinaus eventuell nicht angebracht sein, dem Client etwas über die Verzeichnisstruktur des Server-Systems zu verraten.

Im Moment gibt es zwei verschiedene Wege, den Ort des Mapfiles vor Außenstehenden zu verbergen:

*''Verwenden eines Wrapper-Skripts'' : Anstatt des CGI-Binaries wird ein kleines Skript aufgerufen, das die Umgebungsvariable = MS_MAPFILE = setzt und dann seinerseits das CGI-Programm aufruft. Ganz primitiv könnte ein solches Skript für die Shell =bash= etwa wie folgt aussehen: <code> #!/bin/sh MS_MAPFILE=/usr/local/there/is/my.map export MS_MAPFILE /usr/local/httpd/cgi-bin/mapserv </code> Beachten Sie bitte, dass dieses Beispiel nur für Unix-Systeme funktioniert, auf denen die Shell =bash= installiert ist. Für andere Shells kann die Notation abweichen.
*''Webserver-Konfiguration'' : Der Webserver ist unter Umständen in der Lage, für bestimmte aufgerufene URLs spezifische Umgebungsvariablen zu setzen. Im Apache sähe ein Eintrag in der Datei ''httpd.conf'' dann beispielsweise folgendermaßen aus (wegen der Zeilenlänge für das Drucklayout umgebrochen, muß in der Konfigurationsdatei eine Zeile sein): <code> SetEnvIf Request_URI "/cgi-bin/mapserv" \ MS_MAPFILE=/usr/local/there/is/my.map </code> Dieser Eintrag funktioniert nur im Apache und kann für andere Webserver vollkommen anders aussehen. Konsultieren Sie Ihre Dokumentation.

\subsubsection*{getCapabilities}(5)

Nachdem man zufrieden mit seinem Setup ist, möchte man es natürlich ausprobieren. Dazu ruft man als erstes das ''Capabilities'' -Dokument ab:

 <code>
http://server/cgi-bin/mapserv?VERSION=1.1.0&REQUEST=getCapabilities \
&map=mapfile.map
</code> 

Dabei müssen Sie bei =getCapabilities= nicht auf Groß- oder Kleinbuchstaben achten. Ebensowenig bei allen anderen Parametern, die vor einem Gleichheitszeichen stehen.

Der Webserver sollte Ihnen nun eine Datei des Typs =application/vnd.ogc.wms_xml= zurückliefern. Diese Textdatei können Sie abspeichern und in einem beliebigen Texteditor öffnen. Eventuell ist Ihr Webbrowser auch von sich aus in der Lage, XML-Dateien automatisch in einem ansprechenden Layout darzustellen.

Schauen Sie sich nun den Inhalt der Datei genau an. Wo immer Sie auf Zeilen treffen, die

 <code>

</code> 

beinhalten, gilt es, etwas zu bereinigen. Beispielsweise erfahren Sie aus einer Warnung wie dieser:

 <code>

</code> 

dass Sie einen Meta-Tag für den Titel der entsprechenden Sektion vergessen haben.

Sobald Sie keine Warnungen dieser Art mehr in Ihrem Capabilities-Dokument finden, ist ihr MapServer WMS-konform und voll einsatzbereit.

\subsubsection*{getMap}

Wenn die Capabilities wie erwartet geliefert werden, ist der nächste logische Schritt natürlich, sich eine Karte von Hand abzuholen. Dafür konstruieren Sie sich in Ihrem Webbrowser einen Aufruf, der etwa so aussieht, wie das Beispiel in Abschnitt~3. Dabei machen Sie sich dann auch gleich mit der Benennung der Parameter vertraut.

Das beste was Ihnen passieren kann, ist natürlich, dass Sie gleich ihre gewünschte Karte bekommen. Dann sind Sie natürlich fertig. Sobald Sie jedoch Ihren ersten Fehler machen, müssen Sie sich mit Fehlermeldungen auseinandersetzen, den so genannten Exceptions.

==Exceptions==\index{Exceptions}\index{WMS!Exceptions}

Exceptions sind Meldungen, die von einem WMS-konformen Mapserver im Fehlerfall ausgegeben werden müssen. Das entspricht in etwa dem Expcetions-Konzept diverser Programmiersprachen wie z.B. Java. Der Sinn ist es, dem aufrufenden Client -- sei es nun eine menschliche Person, sei es eine Software -- anhand des Typs und des Inhalts der Fehlermeldung eine Entscheidung über das weitere Vorgehen treffen zu können. Eine solche Art der Fehlerbehandlung verhindert natürlich unter anderem, dass ein Programm seine Durchführung im Fehlerfall einfach beendet.

Wenn Sie bei einem WMS-konformen Aufruf einen Fehler machen, indem Sie beispielsweise einen Parameternamen wie =REQUEST= absichtlich falsch schreiben, wird Ihnen MapServer eine Datei in einem XML-Format zurückliefern:

*=application/vnd.ogc.se_xml= Ein WMS-konformer Mapserver muß mindestens diese Art der Vermittlung von Exceptions beherrschen. Solch eine Datei kann beispielsweise folgenden Inhalt haben: <code> <?xml version='1.0' encoding="ISO-8859-1" standalone="no" ?> <!DOCTYPE ServiceExceptionReport SYSTEM "http://www.digitalearth.gov/wmt/xml/exception_1_1_0.dtd"> <ServiceExceptionReport version="1.1.0"> <ServiceException> msWMSDispatch(): WMS server error. Incomplete WMS request: REQUEST parameter missing </ServiceException> </ServiceExceptionReport> </code> 

\begin{figure}
\begin{center}
\mmfig{0.6}{wms-exception-inimage}{Exception vom Typ application/vnd.ogc.se_inimage.}
\end{center}
\end{figure}

Des weiteren kann ein Mapserver Exceptions in den folgenden MIME-Typen zur Verfügung stellen:

*=application/vnd.ogc.se_inimage= Die Exception wird als Text in das auszuliefernde Bild eingefügt.
*=application/vnd.ogc.se_blank= Die Spezifikation geht von der Idee, dass ein leeres Bild etwas ist, dass man grundsätzlich nicht haben möchte, und somit nie bekommt. Daher kann ein 'leeres' Bild als Fehlermeldung angesehen werden. Als 'leeres' Bild ist ein Bild definiert, das ganz mit der Hintergrundfarbe der Karte ausgefüllt ist.

Im URL des Aufrufs wird die gewünschte Art der Exception mit dem Parameter =EXCEPTIONS= notiert. Wollen Sie Exceptions also im Bild notiert haben, schreiben Sie in Ihrem URL:

 <code>
... & EXCEPTIONS=application/vnd.ogc.se_inimage & ...
</code> 

Beachten Sie bitte, dass nur die XML-Variante implementiert sein muß. Wenn Sie von einem Server Exceptions im Bild verlangen, er aber nur XML kann, dann wird er XML liefern.

Beachten Sie außerdem, dass das Handling von Exceptions insbesondere bei Kaskaden von WMS-konformen Servern eine Rolle spielt. So kann es Ihnen passieren, dass Sie sich einen Layer von einem Server holen, der sich wiederum sein Bild von anderen entfernten Quellen heranholt, und von dort im Fehlerfall eine Exception in das Bild eingetragen bekommt. Dadurch haben Sie die Fehlermeldung dann natürlich auch im Bild zu stehen.

===Hinweis===

Viele Kartenanbieter tendieren dazu, ihre fertigen Karten mit Schriftzügen, Logos, Nordpfeilen, Wasserzeichen und so weiter auszustatten. Denken Sie immer daran, dass der Kunde, der Ihren Service wiederum als Datenquelle benutzt, eventuell auf die Idee kommt, die von Ihnen bezogene Karte umzuprojizieren! Das kann dann zu interessanten Effekten führen, wenn dann Dritte den Schriftzug mit der URL Ihrer Firmenwebsite quer über die ganze Karte gekrakelt bekommen. Entwickeln Sie im Vorhinein zusammen mit den Benutzern des Service ein Konzept, dass solche häßlichen Effekte verhindert.

==getFeatureInfo==

Sich Karten einfach nur anzusehen, ist selbstverständlich nur die Hälfte des Reizes eines WMS-konformen Servers. Man möchte selbstverständlich auch Queries auf die Daten durchführen können. Zu diesem Zweck gibt es den =REQUEST= mit dem Namen =getFeatureInfo= .

Zuerst einmal gilt es, Queries überhaupt erst einmal zuzulassen. Wie schon bei den 'klassischen' Queries (siehe Abschnitt~\ref{text:mapfile:queries}) kann man in MapServer eine Query nur auf einem Layer durchführen, der ein =TEMPLATE= definiert.

Wenn man das tut, und sich die ''capabilities'' anschaut, wird man für den Layer auf ein Attribut der folgenden Art treffen:

 <code>
<Layer queryable="1" opaque="0" cascaded="0">
</code> 

Der Wert =1= für =queryable= zeigt im Gegensatz zum Wert =0= an, dass Queries auf diesen Layer zulässig sind.

Um einen Aufruf vom Typ =getFeatureInfo= zu verstehen, betrachten wir einmal einen vollständigen URL für diesen Vorgang:

 <code>
http://www.example.com/cgi-bin/mapserv
? map=/usr/local/mapserv/mapfile.map
& VERSION=1.1.0
& REQUEST=getFeatureInfo
& QUERY_LAYERS=gruenflaechen
& SRS=EPSG:4326
& BBOX=5.0,45.0,15.0,55.0
& WIDTH=500
& HEIGHT=500
& X=250
& Y=250
& INFO_TYPE=text/plain
</code> 

Einige Bestandteile sind dem Leser bereits bekannt: Version des Standards, Angabe der Projektion durch =SRS= . Dazu kommt, wenig überraschend, die Angabe des =REQUEST= .

Da jetzt keine Darstellung mehr erfolgen sollen, werden keine =LAYERS= mehr angegeben, sondern =QUERY_LAYERS= \footnote{Diese Unterscheidung ist offensichtlich eigentlich unnötig, da man die Funktion der Layerangabe ja eigentlich serverseitig aus dem =REQUEST= schließen könnte.}. Um Ergebnisse zu liefern, muß jeder Layer in der Liste =QUERY_LAYERS= das Attribut =queryable= auf =1= gesetzt haben -- siehe oben.

Zwingend sind darüberhinaus die Angabe der Extents des Bildes, das man befragen möchte (angegeben mit =BBOX= ), Breite und Höhe des Bildes sowie die X- und die Y-Koordinate des Punktes im Bild, der sich der Aufmerksamkeit des Users erfreut, beispielsweise durch einen Mausklick. Beachten Sie, dass es sich dabei um Bildkoordinaten handelt, es handelt sich also um Pixelwerte. Der Koordinatenursprung eines Bildes ist links oben.

Am interessantesten ist natürlich der =INFO_TYPE= , der angibt, auf welche Weise die Queryergebnisse formatiert sein sollen. MapServer unterstützt die folgenden Formate:

*=text/plain= , das Standardformat, falls Sie nichts anderes angegeben haben;
*=text/html= , was ein wenig Vorbereitung erfordert, im wesentlichen aber wie Queries auf einem 'normalen' MapServer-CGI behandelt wird; und
*=application/vnd.ogc.gml= , GML, eine XML-Repräsentation für Geodaten.

Betrachten wir die Formate im Detail:

\subsubsection*{text/plain}

Dieser Ausgabetyp für getFeatureInfo ist die Voreinstellung für MapServer, falls Sie keinen anderen Ausgabentyp spezifizieren.

Für ein Mapfile mit den Voreinstellungen des Itasca-Demos und einem fiktiven Anklickpunkt mit den Koordinaten 200/200 sieht die Ausgabe folgendermaßen aus:

 <code>
GetFeatureInfo results:

Layer 'countyboundary'
Feature 26:
AREA = '7577272785.15393'
PERIMETER = '436617.07762'
CTY_NAME = 'Itasca'
COUN = '31'
CTY_ABBR = 'ITAS'
ISLAND = 'N'
CTY_FIPS = '61'
RECNO = '27'
</code> 

Es wird der Name des Layers ausgegeben, die Nummer des Layers innerhalb des Shapefiles, und dann alle Attribute aus der =.dbf= -Datei der Datei. Wenn es mehrere Suchergebnisse gegeben hat, werden diese der Reihe nach dargestellt.

\subsubsection*{text/html}

Mit diesem Ergebnistyp greift MapServer auf die HTML-Templates zurück, die Sie für Queries bereits in Kapitel~\ref{text:mapfile} kennengelernt haben. Das bedeutet, dass Sie ein HTML-Layout ganz nach Ihrem Geschmack gestalten können, und MapServer die entsprechenden Tags in eckigen Klammer wie gewohnt ersetzt.

Dieser ''MIME type'' bietet jedoch noch die Möglichkeit für zusätzliche Tricksereien. Der Standard schreibt nämlich keinen ''MIME type'' zwingend vor, und ebensowenig gibt es ein vorgeschriebenes Verhalten für den Fall, dass ein bestimmter Typ nicht unterstützt wird. Das führt dazu, dass MapServer es sich vorbehält, beliebige Arten von Daten zurückzuliefern.

Sie können ein =TEMPLATE= definieren, das nicht gezwungenermaßen eine HTML-Seite sein muß. Reiner ASCII-Text wäre ebenso möglich, oder alle anderen Formate, in denen Sie MapServer-Tags ersetzen können.

Sobald das Template beliebigen Formats von MapServer bearbeitet worden ist, kann das Resultat zurückgeliefert werden. Wenn man jetzt reinen ASCII-Text hat, würde MapServer ihn jedoch als =text/html= ausliefern, und das ist eigentlich nicht das, was man möchte. Der Client (also z.B. Webbrowser) interpretiert die Daten natürlich nur korrekt, wenn man ihm den korrekten MIME type liefert. Daher kann man im Mapfile für die zurückgegebenen Daten einen eigenen Metadatum den geeigneten Typ setzen:

 <code>
WEB
...
METADATA
...
"wms_feature_info_mime_type" "text/plain"
END
END
</code> 

Also noch einmal zusammenfassend: der Benutzer kann zwar von außen den =INFO_TYPE= auf =text/html= setzen; MapServer kann jedoch mit Daten beliebigen Typs antworten.

\subsubsection*{application/vnd.ogc.gml}

Damit ein Layer in diesem Format Anfragen beantworten kann, muß außerdem der Parameter =DUMP= in diesem Layer gesetzt sein:

 <code>
LAYER
...
DUMP TRUE
END
</code> 

Falls es keine Suchresultate gegeben hat, wird zwar eine Datei im korrekten Format zurückgegeben, die allerdings nur die korrekten Header enthält und ansonsten leer ist.

Für Suchergebnisse werden in diesem Format immer die Koordinaten des Features gleich mitgeliefert. Antworten können also bei großen Features nicht nur auf sich warten lassen, da MapServer für das Erzeugen großer Dokumente natürlich eine Weile braucht, sondern auch weil der Transfer über das Netz natürlich ein bißchen dauert.

Die Anfrage auf den Flughafen-Layer der Itasca-Demodaten beispielsweise liefert in den voreingestellten Extents und dem fiktiven Klick auf die Koordinate 224/75 das folgende Ergebnis:

 <code>
<?xml version="1.0" encoding="ISO-8859-1"?>

<msGMLOutput
xmlns:gml="http://www.opengis.net/gml"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance">
<countyboundary_layer>
<countyboundary_feature>
<AREA>7577272785.15393</AREA>
<PERIMETER>436617.07762</PERIMETER>
<CTY_NAME>Itasca</CTY_NAME>
<COUN>31</COUN>
<CTY_ABBR>ITAS</CTY_ABBR>
<ISLAND>N</ISLAND>
<CTY_FIPS>61</CTY_FIPS>
<RECNO>27</RECNO>
<gml:boundedBy>
<gml:Box srsName="EPSG:26915">
<gml:coordinates>
393234.393701,5207990.085063
495769.579719,5305374.105135
</gml:coordinates>
</gml:Box>
</gml:boundedBy>
<gml:Polygon srsName="EPSG:26915">
<gml:outerBoundaryIs>
<gml:LinearRing>
<gml:coordinates>
393865.671855,5300138.258409
393869.171975,5300138.258374
394516.694141,5300137.439369
395522.728579,5300136.241770
[...]
</code> 

Und so weiter, mit allen Punkten des Features.

==WMS Clients==\index{OGC!Client}(6)

WMS-konforme Mapserver lassen sich kaskadieren, indem einzelne Layer einfach als fertige Bilder von anderen WMS-konformen Mapservern bezogen werden. Durch die standardisierte Schnittstelle ist dafür kein UMN MapServer nötig. Sie können einzelne Layer beispielsweise auch von einem ESRI ArcIMS beziehen, wenn Sie möchten.

Neben der schönen Möglichkeit, die Standorte und somit Pflege einzelner Teile der Kartenerzeugung voneinander trennen zu können, indem man beispielsweise die Bodenproben von einem Amt und die hydrogeologischen Karten von einem anderen Amt miteinander über eine genormte Schnittstelle verbindet, ist ein weiteres offensichtliches Einsatzfeld natürlich die Lastenverteilung. Datenbestände, die erst umprojiziert werden müssen, können auf leistungsfähigere Server ausgelagert werden, während einfache Operationen wie beispielsweise die simple Darstellung von Rasterbildern von schwächeren Geräten übernommen werden kann\footnote{Beachten Sie dabei immer, dass zur Erzeugung des fertigen Bildes ''immer'' auf den langsamsten Layer gewartet werden muß, da ja das Bild ansonsten nicht komplett ist.}.

Im folgenden soll betrachtet werden, wie Sie einen Layer in einem Mapfile erstellen, damit er dynamisch Daten von einem WMS-konformen Server bezieht. Nach außen hin verhält sich dieser Layer dann wie jeder andere Rasterlayer auch.

\subsubsection*{Installation und Konfiguration}

Wie weiter hinten im Kapitel 'Installation' ab Seite~\pageref{text:installation} beschrieben, ist die Fähigkeit, als WMS-Client zu fungieren, nicht als Voreinstellung bei der Kompilierung gegeben, sondern muß explizit angefordert werden. Wie das genau gemacht wird, und welche Voraussetzungen gegeben sein müssen, ist in Abschnitt~\ref{text:installation:compile:wmsclient} erklärt.

\subsubsection*{getMap}

Der erste Schritt ist, sicherzustellen, dass der anzusprechende Server funktioniert und die gewünschten Daten ausliefert. Dafür holt man sich das Capabilites-Dokument dieses Servers. Wie das zu tun ist, ist auf Seite~\pageref{text:wms:getcapabilities} beschrieben.

Nun weiß man alles über die Fähigkeiten des Servers (welche Projektionen angeboten werden, wie seine Layer heißen und so weiter) und kann sich darum kümmern, eine erste Karte zu holen, um zu sehen, ob die Darstellung dem entspricht, was man erwartet. Dazu richtet man mit seinem Webbrowser eine =getMap= -Anfrage an den Server.

Wie so eine Anfrage aufgebaut sein muß, wurde bereits in Abschnitt~3 gezeigt. Ersetzen Sie allerdings alle Werte für die Parameter durch diejenigen, die Sie im abgerufenen Capabilities-Dokument gefunden haben, also durch korrekte Projektionen, Layernamen, Extents und so weiter. Sobald dieser Aufruf eine Karte in Ihrem Browser zaubert, wissen Sie, dass Sie gültige Werte besitzen und sie korrekt notiert haben, sodass Sie diese Angaben jetzt in einen Layer in Ihr Mapfile einbauen können.

\subsubsection*{Das Mapfile}

Zunächst benötigen Sie einen =PROJECTION= -Block für Ihre Karte. Sie können auf diesen Block verzichten, wenn alle Layer in der gleichen Projektion vorliegen und auch die von Ihnen angesprochenen WMS-Server nur diese eine Projektion unterstützen.

Beachten Sie, dass Sie in der =WEB= -Sektion Ihres Mapfiles einen =IMAGEPATH= -Parameter benötigen, da die Bilder von entfernten Servern als temporäre Dateien gespeichert werden müssen. Diese temporären Dateien werden übrigens nach Verwendung gleich wieder gelöscht, sodass Sie sie kaum bemerken werden.

Für WMS-konforme Anfragen an andere Server sind lediglich die Layerdefinitionen anzupassen. Dabei kommt ein =CONNECTIONTYPE= mit dem Namen =WMS= zum Einsatz:

 <code>
LAYER
NAME "Gewaesser"
TYPE RASTER
STATUS ON
CONNECTIONTYPE WMS
CONNECTION "http://www.example.com/cgi-bin/mapserv?"
METADATA
"wms_title" "Gewaesser"
"wms_server_version" "1.1.0"
"wms_srs" "EPSG:4326 EPSG:31464"
"wms_name" "seen,kanaele,fluesse,baeche"
"wms_format" "image/png"
END
PROJECTION
"init=epsg:31464"
END
END
</code> 

Wie Sie sehen, ist der URL selber sehr kurz gehalten. Er entspricht der ''onlineresource'' aus dem Capabilities-Dokument eines WMS-konformen Servers.

Alle weiteren Details zur Verbindung mit dem entfernten Server werden in Form von Metadaten gemacht. Wer bisher MapServer 3.6 eingesetzt hat, wird das noch anders kennen: in jener Version wurde noch der gesamte Verbindungsstring (bis auf die dynamischen Elemente) in der =CONNECTION= notiert.

Der =wms_title= ist der Titel für diesen Layer, der mit der Anfrage allerdings nichts zu schaffen hat.

Die Version der Anfrage wird mit =wms_server_version= notiert. Mit =wms_srs= geben Sie wieder Projektionen an, allerdings diejenigen, die von der Gegenstelle unterstützt werden.

=wms_name= benennt den oder die Layer, aus denen die bezogene Karte zusammengesetzt werden soll. Mehrere Layer werden durch Kommata voneinander abgetrennt. Beachten Sie, dass bei WMS die Reihenfolge der Ebenen von Belang ist: in unserem Beispiel werden zuerst der Layer =seen= gezeichnet, darauf dann =kanaele= und so weiter.

Das gewünschte Bildformat wird schließlich mit =wms_format= spezifiziert. Es gibt auch den Parameter =wms_formatlist= , der mehrere durch Kommata getrennte Angaben zuläßt.

''Wichtiger Hinweis'' : An keiner einzigen Stelle lädt sich MapServer die Capabilities des entfernten Servers herunter, um sich mit ihnen auseinanderzusetzen. Sie müssen also selber darauf achten, dass die von Ihnen gemachten Angaben stimmig sind.

==Exceptions==

Wenn Sie einen Layer haben, der sich Daten von einem WMS-konformen Server holt, drängt sich natürlich die Frage auf, wie MapServer im Fall von Exceptions reagiert. Eindeutige Antwort: das kommt drauf an.

Am einfachsten ist es offensichtlich, mit Exceptions, die direkt im Bild eingefügt sind, umzugehen, also mit denen, die vom Typ =application/vnd.ogc.se_inimage= sind. Diese werden einfach Bestandteil der fertigen Karte, die Sie im Webbrowser sehen. Im Fehlerfall bemerkt sehr schnell, was Sache ist.

Das gleiche gilt offensichtlich bei =application/vnd.ogc.se_blank= .

Liefert die Gegenstelle ein textbasiertes Format, also zum Beispiel GML zurück, dann gibt es ein Problem, da MapServer davon ausgeht, dass er Rasterdaten als Input erhält; demnach versucht er, das GML-Dokument als Text zu rendern, was natürlich schief geht und somit eine Fehlermeldung erzeugt.

Dieses Problem läßt sich bisher leider auch noch nicht umgehen. Das mindeste, was man also tun kann, ist für eine funktionierende Kommunikation mit dem Betreiber des Quellservers zu sorgen, damit dieser nicht einfach unangekündigt Layernamen ändert, die Ihnen Ihre Applikation wegbrechen lassen.

==Hinweise==(7)

FIXME: das auch noch bei WFS erwähnen

Wenn Sie mit der Administration sowohl des Mapservers, der als Client fungiert, als auch der Serverseite betraut sind, sollten Sie auf alle Fälle darauf achten, keine zirkulären Bezüge zu erzeugen, bei denen Server A einen Layer von Server B bezieht und dieser dann wieder Server A aufruft. Bei komplexen Installationen ist das durchaus eine Fehlerquelle, das Verhalten in diesem Fall ist undefiniert.

Ein weiterer wichtiger Faktor beim Einsatz von WMS-konformer Funktionalität ist die unschöne Tatsache, dass MapServer das Sammeln der Daten für einzelne Layer linear abarbeitet, und nicht mit einem einzelnen Thread oder Prozess pro Layer arbeitet. Das bedeutet, dass MapServer genau ''gar nichts'' tut, während er auf einen Layer aus dem Netzwerk wartet, um dann zum nächsten Layer überzugehen\ldots der dann vielleicht wieder ein solcher Layer ist, oder eine Datenbankquelle. Es wird also unnötig Rechenzeit vergeudet. Dieses Problem läßt sich im Moment auch leider nicht umgehen.

\subsubsection*{Weitere Modi für WMS}

Wer den Standard aufmerksam liest, wird noch vier weitere Operationsmodi finden, die in den einführenden Zeilen zu diesem Abschnitt nicht genannt worden sind. Sie umfassen:

*=describeLayer=
*=getLegendGraphic=
*=getStyles=
*=putStyles=

Diese Modi sind nur für Mapserver von Relevanz, die den OGC-Standard SLD unterstützen. Mit diesen ''styled layer descriptor'' ist es möglich, von außen Einfluß auf die ansonsten fixe Kartengestaltung eines Mapservers zu nehmen. Da dieser Standard serverseitig von MapServer bisher nicht unterstützt wird\footnote{Und clientseitig nur sehr sporadisch; konsultieren Sie hierzu bitte die Online-Dokumentation.}, findet hier keine detaillierte Beschreibung statt. Sie können sich aber selbstverständlich den Standard~[[pdf:spec:sld10]] lesen.

=Web Feature Server (WFS)=(8)

Die entsprechende Spezifikation des OGC~[[pdf:spec:wfs100]] sieht WFS im Kontext zu WMS. Nach der Formulierung in der Einführung des Dokuments ist WFS der 'nächste logische Schritt' nach WMS. Wo WMS die Möglichkeit bietet, Capabilities abzufragen Karten anzuzeigen und schließlich Anfragen bezüglich der Datengrundlage der Karten zu machen, stellt WFS ein Interface zur Verfügung, dass es dem Benutzer ermöglicht, Einfluß auf die Datengrundlage zu nehmen, indem Features in der Karte geändert und gelöscht, bzw. neue Features hinzugefügt werden können.

Das hört sich alles ziemlich gut an -- und doch muß der begeisterte Leser hier enttäuscht werden. MapServer ist bisher ausschließlich darauf ausgelegt, Daten aus Quellen wie der Festplatte oder einer Datenbank zu lesen und Karten zu produzieren. Von einer Unterstützung für Datenänderungen ist man im Moment noch sehr weit entfernt -- falls sie überhaupt kommen wird\footnote{Es besteht natürlich die Möglichkeit, dass Sie beispielsweise mit MapScript entsprechende Fähigkeiten in einer eigenen Applikation programmieren. Stellen Sie sich auf einigen Aufwand ein.}.

Was wir mit MapServer kriegen, ist allerdings zumindest die Möglichkeit, Vektorlayer über den Transportmechanismus von WFS als Server auszuliefern bzw. als Client zu beziehen. Das funktioniert nur mit Vektordaten, da sich Rasterdaten offensichtlich nicht in das XML-Format mit dem Namen GML verpacken lassen. Diese ''Geography Markup Language'' ist selbstverständlich ebenfalls in einer eigenen Implementation Specification definiert~[[pdf:spec:gml]].

Von den in der Spezifikation definierten Anfragetypen sind im MapServer die folgenden implementiert:

*=getCapabilities= , um ein Capabilities-Dokument abrufen zu können, wie man es bereits von WMS kennt.
*=describeFeature= liefert eine Beschreibung eines Features zurück.
*=getFeature= holt eine GML-Repräsentation eines Features.

==WFS Server==

Wie schon beim WMS-konformen Server, wird WFS in MapServer dadurch aktiviert, dass die notwendigen =METADATA= -Tags in das Mapfile eingefügt werden. Zuerst einmal müssen aber die folgenden Vorkehrungen getroffen werden:

*Zuerst muß MapServer natürlich mit WFS-Unterstützung kompiliert worden sein. Detaillierte Vorgaben dafür finden Sie in Anhang~\ref{anhang:compile}.
*Das Mapfile muß einen =NAME= haben, ebenso wie jeder einzelne Layer. Wie schon bei WMS geht MapServer bei WFS davon aus, dass jeder Layer, der sich im Mapfile befindet, auch über WFS zur Verfügung gestellt werden soll.

MapServer kann ausschließlich Vektorlayer in seinen WFS-Capabilites erscheinen lassen, also Shapefiles, PostGIS-Layer und so weiter; der Typ des Layers muß also =POINT= , =LINE= oder =POLYGON= sein.

Desweiteren muß die Eigenschaft =DUMP= im Layer auf =TRUE= gesetzt sein. Dies zeigt MapServer an, dass er GML-Repräsentationen für diesen Layer erzeugen darf. Das entspricht der Vorgabe, =getFeatureInfo= mit einem WMS-konformen Server nutzen zu können.

In der =WEB= -Sektion des Mapfiles müssen dann die folgenden Angaben gemacht werden.

*=wfs_onlineresource= Die Basisadresse des Servers. Hat denselben Aufbau wie der gleichnamige Parameter für WMS. Allerdings muß man einem WFS-konformen MapServer noch mitteilen, wie er WFS- von WMS- Anfragen zu unterscheiden hat. Das geschieht durch =SERVICE= , also etwa derart: <code> WEB .. METADATA ... "wfs_onlineresource" \ "http://www.example.com/cgi-bin/mapserv?SERVICE=WFS&map=..." END END </code> Diese Angabe ist auch dann nötig, wenn der MapServer nicht darauf eingerichtet oder konfiguriert ist, als WMS-Server zu fungieren.
*=wfs_title= Titel für die Karte; siehe WMS-Konformität. Zwingend notwendig.
*=wfs_abstract= Eine elaborierte Zusammenfassung über Sinn und Zweck dieses Servers. Siehe WMS-Konformität.
*=wfs_keywordlist= Eine Liste mit Schlüsselworten, die einen Bezug zu diesem WFS-Server haben. Siehe WMS-Konformität.
*=wfs_accessconstraints= Beschränkungen, die den Zugriff auf diesen Server betreffen. Siehe WMS-Konformität.
*=wfs_fees= Gebühren, die beim Zugriff auf diesen Server anfallen. Siehe WMS-Konformität.
*=wfs_encoding= Die Kodierung für die XML-Dateien, die durch den WFS-Server ausgeliefert werden. Voreingestellt ist hier ISO-8859-1.
*=ows_schema_location= Der Ort, an dem die OWS-Schemas zur Validierung der generierten XML-Dateien liegen. Siehe weiter unten auf Seite~\pageref{text:wfs:schemas}.
*=wfs_geometry_element_name= Weiter unten gibt es ein Beispiel zu sehen, wie eine Datei aussehen kann, die von einem WFS-konformen MapServer ausgeliefert wird. Das Element, dass die Liste der Koordinaten eines Features umfaßt, hat dabei keinen fixen Namen. Sie können mit diesem Parameter hier einen Namen festlegen; Voreinstellung in MapServer ist =MS_GEOMETRY= .
*=wfs_srs= Die Projektion, die für alle Layer in der Karte gelten soll. Wird als EPSG-Code angegeben und genauso wie bei WMS-konformen Servern notiert. Beachten Sie bitte die Anmerkungen zu Projektionen in WFS-konformen Servern im nächsten Abschnitt.

Beachten Sie, dass diese Parameter im Gegensatz zu den WMS-Parametern alle den Präfix =wfs_= tragen. Einzige Ausnahme ist =ows_schema_location= .

==Projektionen in WFS-Servern==

Die WFS-Spezifikation macht zu Projektionen andere Vorgaben als idie für WMS. So können einzelne Layer nicht in mehr als einer Projektion ausgeliefert werden. Es gibt auch keine Projektionsangabe, die man ein einziges Mal für alle Layer machen kann\footnote{Man kann aber, wie Sie weiter oben sehen konnten, MapServer so konfigurieren, dass er einen SRS-Eintrag in der WEB-Sektion bekommt und diesen dann auf alle Layer überträgt.}. Es ist aber sehr wohl möglich, für jeden Layer eine unterschiedliche Projektion anzubieten. Außerdem nennt der Standard keine Default-Projektion; anders als bei WMS, wo mindestens =EPSG:4326= angeboten werden muß.

MapServer entscheidet in zwei Schritten, welche Projektion für einen Layer nach außen mitgeteilt wird. Wenn es eine 'übergeordnete' Projektion gibt (also einen Projektionsblock mit EPSG-Code für die ganze Karte, bzw. ein =wfs_srs= in der WEB-Sektion), so findet diese Projektion auf alle Layer Anwendung, selbst dann, wenn die Layer selber noch einmal über =wfs_srs= eine Projektion definieren.

Gibt es keine solche 'Überprojektion', muß jeder Layer einen eigenen Wert setzen.

==Schemas==(9)

Schemas\footnote{In diesem Fall nicht Schemata, da es sich um einen feststehenden englischen Begriff handelt.} sind ein Mechanismus, XML-Dateien zu validieren, also zu prüfen, ob sie einem bestimmten Aufbau genügen. Sie können ein Paket standardkonformer Schemas von~[[http:owssamples]] herunterladen.

Das Archiv entpacken Sie an einen Ort, der für den WebServer erreichbar ist. Danach können Sie, wie oben gesehen, mit einem entsprechenden Metadatum den Pfad zu den Schemas angeben:

 <code>
WEB
...
METADATA
...
"ows_schema_location" "/pfad/zu/den/schemas"
END
END
</code> 

Geben Sie keinen Pfad an, wird =..= als Ort für die Schemas angenommen. Der Gedanke hinter dieser Entscheidung war, dass man damit im Wurzelverzeichnis des Webservers landet, wenn man sein MapServer-Binary im Verzeichnis =cgi-bin/= hat\footnote{Eine sehr Apache-zentrierte Denkweise.}.

Der Präfix =ows_= zeigt übrigens an, dass hier auf mehr als nur WFS-Schemas verwiesen wird; vielmehr handelt es sich um einen Verweis auf Schemas, die sich auf ''OGC Web Services'' beziehen.

==Aufruf \& Capabilities==

Sobald man die ganze vorbereitende Arbeit hinter sich gebracht hat, kann man prüfen, ob alles korrekt eingerichtet worden ist. Dazu richtet man, wie schon beim WMS-konformen Server, eine Anfrage vom Typ =getCapabilities= an den Server:

 <code>
http://www.example.com/cgi-bin/mapserv
?SERVICE=WFS
&REQUEST=getCapabilities
&map=...
</code> 

Die Vorgehensweise entspricht jetzt haargenau dem, was Sie auch mit einem WMS-Server tun würden: Sie durchsuchen das Capabilites-Dokument nach Warnungen und Fehlern, und wenn sich alles so verhält, wie es geplant war, dann haben Sie einen einsatzfähigen, WFS-konformen Server.

==WFS Client==

Was man mit WMS machen kann, will man selbstverständlich auch mit WFS machen: Einbinden von WFS-Layern als eigene Kartenebenen. Die Vorgehensweise ist dabei stark an eben das Einfügen von WMS-Layern angelehnt.

FIXME: blah

Die Voraussetzungen für die Kompilierung eines WFS-konformen Client sind etwas umfänglicher als für den entsprechenden Server. Sieh auch Abschnitt [FIXME] im Anhang.

Ein WFS-Client-Layer ist sieht anders aus als ein 'normaler' Layer, hat aber Ähnlichkeit mit einem WMS-konformen Layer. Hier ein Beispiel:

 <code>
LAYER
END
</code> 

FIXME: vervollständigen!1!

=Map Context=

Diese Spezifikation ist eine Ergänzung zur WMS-Spezifikation. Sie beschreibt einen Mechanismus, mit dem Informationen über eine Menge von WMS-produzierten Layern auf eine portable Weise zwischen Systemen ausgetauscht bzw. in einem definierten Format gespeichert und abgerufen werden können.

Das Dokument, das diesen Standard definiert ist in der Version 1.0 von der OGC-Website herunterladbar~[[pdf:spec:mapcontext10]].

MapServer kann Kontextdokumente in den Versionen 0.1.2, 0.1.4, 0.1.7 und 1.0 lesen, und in den Versionen 0.1.4, 0.1.7 und 1.0 exportieren.

Kontextdokumente lassen sich im MapServer darüberhinaus nur in MapScript verwenden, und selbst dort nur in der PHP-Fassung. Alles andere wird (noch?) nicht unterstützt. Darüberhinaus geht Map Context davon aus, dass die WMS-Spezifikation 1.1.1 beachtet wird.

Notwendige Bibliotheken für die Map Context-Funktionalität sind die Projektionsbibliothek proj.4, GDAL/OGR im Zusammenspiel mit Xerces sowie PHP MapScript. Genaue Installationsanleitungen für diese Komponenten finden Sie im Anhang ab Seite~\pageref{text:installation}.

==Das Context-Dokument==

Der Inhalt eines Context-Dokuments (oder schlicht: eines Contexts) besteht im wesentlichen aus Angaben über die Quelle(n) der einzelnen Layer, die verwendeten Bounding Boxes, Projektionen und eventuell diverse Metadaten.

Wie bei praktisch allem, was mit dem OGC in Zusammenhang steht, ist der Context ein XML-Dokument. Beachten Sie, dass in einem Context-Dokument tatsächlich nur WMS-Layer gespeichert werden können.

FIXME: fertig!1!

==Den Kontext verwenden==

Dieser Abschnitt sollte sinnvoller eigentlich im Kapitel über PHP MapScript erscheinen; der Konsistenz halber ist er hierher gewandert. Denn wie bereits erwähnt, kann Map Context bisher nur im Zusammenspiel mit PHP-MapScript benutzt werden.

Wenn Sie ein Mapfile nach den obigen Vorgaben erstellt haben, können Sie testen, ob Sie alles richtig gemacht haben:

 <code>
<?php
dl ("php_mapscript40.so");
<math>map = ms_newMapObj ("mapfile.map");
</math>map -> saveMapContext ("mapfile_context.xml");
</code> 

Danach geht es nach dem bewährten Muster daran, in der fertigen XML-Datei nach Warnhinweisen zu suchen, die zeigen, dass Dinge fehlen oder Fehler vorliegen. Wenn das nicht mehr passiert, kann Ihr Mapfile als Quelle für einen Map Context dienen.

FIXME: fertig!1!

= Styled Layer Descriptor (SLD)=
* http://www.mapserver.org/ogc/sld.html

=Filter Encoding =
[[User:Astrid Emde]]
* http://www.mapserver.org/ogc/filter_encoding.html

= WCS =
* http://de.wikipedia.org/wiki/Web_Coverage_Service
* Informationen siehe http://www.mapserver.org/ogc/wcs_server.html
* Informationen siehe http://www.mapserver.org/ogc/wcs_format.html

= WMS Time=

* Informationen siehe http://www.mapserver.org/ogc/wms_time.html

= SOS=

* Informationen siehe http://www.mapserver.org/ogc/sos_server.html

== OWS Clients ==
=== Desktop GIS ===
=== WebGIS ===

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 3

2009-01-23T07:33:23Z

Wiki-Mikee63: /* WFS Client */

HBUMNMapServer ger Capter 3

2009-01-23T07:32:58Z

Wiki-Mikee63: /* Aufruf \& Capabilities */

HBUMNMapServer ger Capter 3

2009-01-23T07:32:22Z

Wiki-Mikee63: /* Projektionen in WFS-Servern */

[[User:Astrid Emde]] (SLD, WMC, Filter Encoding, OWS Clients) 
[[User:jtmapmedia | Jörg Thomsen]] (OGC-Konformität, Warum macht man das?, Wie macht man das? )

[[HBUMNMapServer_ger | '''Inhaltsverzeichnis''']]

= OGC-Konformität =
--[[User:Jtmapmedia|Jtmapmedia]] 13:52, 10 January 2009 (UTC)
(1)\index{OGC}

Das [http://www.opengeospatial.org/ Open Geospatial Consortium]~\cite{http:website:ogc}, kurz OGC, ist ein internationaler Zusammenschluß von '368 Unternehmen, Regierungsorganisationen und Universitäten' (Eigendarstellung auf der Website, die Zahl ändert sich beinahe wöchentlich). Ziel des OGC ist es, gemeinsame Standards (Protokolle, Formate etc.) für Austausch, Verarbeitung und Speicherung von Geodaten zu erarbeiten.

Die Standards, die uns bei der Erstellung von OGC-konformen MapServern im Internet interessieren können, sind vielfältig. Für den MapServer sind die folgenden Standards relevant bzw. implementiert:

* OGC Web Map Service Specification (WMS), für den Transfer von Rasterkarten und eventuelle Anfragen auf diese Daten,
* OGC Web Feature Service Specification (WFS), was das gleiche für Vektordaten und eventuelle Anfragen auf diese Daten ist.
* OGC Web Coverage Service Specification (WCS), regelt den Zugriff auf hochaufgelöste Rasterdaten wie Luft- und Satellitenbilder und deren Bereitstellung.
* OGC Sensor Observation Service (SOS), der den Austausch von Sensordaten, wie z.B. Wasserpegel oder Temperaturmessungen spezifiziert.
* Map Context Specification, ermöglicht das Speichern und Laden von WMS-Zuständen wie Zoomstufe, sichtbare Layer usw..

Darüber hinaus werfen wir auch noch einen raschen Blick auf

* OGC Filter Encoding (FE), damit können Geodaten, beispielsweise für Klassifizierungen, gefilter werden.
* OGC Styled Layer Descriptors (SLD), eine Spezifikation, die es ermöglicht die Kartengestaltung eines entfernten WMS zu beeinflussen.

Die Website des OGC ist unter~[[http:website:ogc]] zu erreichen. Zu allen genannten Diensten, und zu vielen weiteren, finden Sie dort auch die Spezifikationen als PDF-Dateien. Sehen Sie sie sich ruhig einmal an. Nachdem Sie die ersten 20 bis 30 Seiten überblättert haben, finden Sie vor dem Anhang die interessanten Informationen auf meist wenigen Seiten zusammengefasst.

=Warum macht man das?=
--[[User:Jtmapmedia|Jtmapmedia]] 13:56, 10 January 2009 (UTC)

Eine berechtigte Frage ist natürlich, warum man diese Funktionalität überhaupt haben wollen könnte. Die Antworten sind vielfältig. Hier einige Beispiele:

\subsubsection* {'''Kein Zugang zu den Originaldaten'''}

Die wenigsten Besitzer von Geodaten rücken diese umsonst, oder überhaupt heraus. Manche sind allerdings durchaus gewillt, Karten auszuliefern; ihre Originaldaten kommen dabei nicht an die Öffentlichkeit. Durch die Bereitstellung von Karten nach den Kriterien des WMS sind darüberhinaus nicht nur Sie, sondern auch andere in der Lage, Karten aus der 'schwierigen Quelle' zu beziehen. Die Existenz eines Standards kann also schon zur Verbreitung von Kartenmaterial beitragen.

\subsubsection*{'''Lastenverteilung'''}

Ähnlich wie bei Datenbankanbindungen -- siehe auch Kapitel~\ref{text:database} -- kann beispielweise ein WMS-konformes zur Verteilung von Rechenlast beitragen, indem einzelne Layer der Karte einfach auf verschiedene Rechner verteilt werden.

\subsubsection*{'''Herstellerunabhängigkeit'''}

Durch ein standardisiertes Kommunikationsprotokoll sind Sie in der Lage, sich den Hersteller Ihrer Software auszusuchen. Umgekehrt bedeutet das auch, dass Sie nicht auf die Software eines bestimmten Herstellers angewiesen sind, wenn beispielsweise auf einen WMS-konformen Server zugegriffen werden soll. Die Wahl der Software kann also eher an anderen Kriterien (z.B. dem Preis) ausgerichtet werden. Heutzutage gibt es eine große Zahl OGC-konformer Programme, die sich nahezu beliebig miteinander verknüpfen lassen, so kann eine als WMS konfigurierter UMN MapServer seine Karte problemlos an verschiedene Klienten sowohl im Browser (z.N. Mapbender, OpanLayers) als auch auf dem Desktop (z.B. Quantum GIS, gvSIG) ausliefern und einen wichtigen Teil zur Geodateninfrastruktur beitragen.

Auf der Website des OGC finden Sie eine Liste von Herstellern und Produkten~[[http:website:ogcnetwork:impl]] und eine Beschreibung, welche Standards in welcher Version von ihnen unterstützt werden.

\subsection*{'''Existenz von Evaluationskriterien'''}

Häufig steht man vor der Frage, welches Produkt man für einen besonderen Zweck einsetzen soll. Das richtige Vorgehen ist natürlich, sich klarzumachen, welche Eigenschaften und Möglichkeiten die Software bieten soll, und anhand einer daraus hervorgehenden Liste kann man dann verschiedene Produkte evaluieren.

Solch ein Evaluationsvorgang kann zeitlich und finanziell sehr aufwändig sein. Weithin anerkannte Standards helfen dabei, Entscheidungen anhand fertig vorliegender Kriterienkataloge zu treffen.

= Wie macht man das? =
--[[User:Jtmapmedia|Jtmapmedia]] 18:00, 10 January 2009 (UTC)

Eine UMN MapServer-Anwendung OGC-konform zu gestalten ist keine Hexerei, Sie benötigen nicht einmal eine Erweiterung und müssen auch nichts neu kompilieren - es sind lediglich einige Erweiterungen im Mapfile notwendig. Bevor wir uns aber wieder dem Mapfile zuwenden, ein paar Sätze das grundsätzliche Verständnis der Funktionsweise von OGC-Diensten fördern.

Der Aufruf eines WMS-Servers erfolgt ganz ähnlich dem Aufruf des UMN MapServers, nämlich über einen URL mit den gewünschten Parametern, Sie werden im Folgenden bemerken, dass auch andere Aufrufe, wie WFS oder WCS, dem gleichen Muster folgen. Die Benennung der Parameter, ihr Verhalten und ihre Wirkung unterscheiden sich jedoch mehr oder weniger stark von dem, was Sie bisher von ihrem MapServer gewohnt sind.

Schauen Sie sich einmal einen Aufruf für eine Karte als Beispiel an. Um die Generierung solcher URLs müssen Sie sich im Detail nicht kümmern; wenn Sie einen Server betreiben, dann sowieso nicht, weil der Aufrufende die URLs kennen muss, und nicht Sie; und wenn Sie MapServer als Client betreiben, dann müssen Sie zwar einige Angaben im Mapfile zwingend machen, aber alle dynamischen Parameter werden von MapServer aufgefüllt.

\subsubsection*{'''Hinweis'''} 
In der Version 4.x war MapServer sehr tolerant, einige würden sagen nicht voll OGC-konform, weil er nicht alle Aufrufparameter verlangte, die die Spezifikation vorschreibt. Wenn Sie beim Aufruf eines WMS ab UMN Version einen laut Spezifikation erforderlichen Parameter weglassen, wird das nun mit einer Fehlermeldung quittiert.

Nun aber ein Beispiel für einen WMS-konformen URL des MapServers:

FIXME: Beispielaufruf dem aktuellen OSM/Hamburg-Beispiel anpassen. 
<code>
http://www.example.com/cgi-bin/mapserv
? SERVICE=WMS
& VERSION=1.1.1
& REQUEST=GetMap
& FORMAT=image/png
& LAYERS=gruenflaechen,fluesse,bebauung
& SRS=EPSG:4326
& BBOX=5.0,45.0,15.0,55.0
& WIDTH=500
& HEIGHT=500
& STYLES,,,
#hier enden die Pflichtparameter, Auftritt zweier optionaler Parameter:
& TRANSPARENT=TRUE
& EXCEPTIONS=application/vnd.ogc.se_inimage
</code> 

Sie werden sich jetzt fragen, wo denn der Hinweis auf das Mapfile geblieben ist, den Sie bisher immer mit angeben mussten. Ein Parameter ''map'' ist in der WMS-Spezifikation allerdings nirgends erwähnt. Wie man sich dieses Parameters entledigen kann, erfahren Sie weiter unten auf Seite~\pageref{text:wms:mapfilename}.

Der erste Parameter ''SERVICE'' gibt an, welche Spezifikation genutzt werden soll. Wir möchten eine Karte im PNG-Format abrufen, die im Browser angezeigt werden soll, also benutzen wir den Web Map Service.

Als nächstes wird mit ''VERSION'' angegeben, in welcher WMS-Version man die Kommunikation wünscht. Laut Spezifikation soll dabei im Hintergrund eine Aushandlung der Version stattfinden, falls eine Seite eine angegebene Version nicht kennt; Client und Server handeln sich dann gegenseitig herunter, bis sie auf eine Version treffen, die sie beide verstehen.

Der Parameter ''REQUEST'' gibt die Art der Anfrage an. Die in MapServer implementierten Modi sind bereits weiter oben in Abschnitt~2 genannt worden. Beachten Sie, dass die Schreibweise von ''GetMap'' bezüglich der Klein- und Großbuchstaben irrelevant sein sollte. Das gleiche gilt auch für die Namen der Parameter wie ''VERSION'', ''REQUEST'' und so weiter. Die Großschreibung erfolgt hier nur wegen der besseren Lesbarkeit. Es gibt aber auch Dienste, die diese Schreibweise ewarten.

Die Angabe ''FORMAT'' wird als sogenannter ''MIME type'' gemacht, eine standardisierte Notation für die Art von über das Netz geschickten Daten. Bildformat folgen prinzipiell dem Muster ''image/'' plus angehängtem Namen des Bildformats, also zum Beispiel ''image/jpeg'' für JPEG-Bilder. Mehr über MIME-Typen inklusive Links zu den diversen zuständigen RFCs finden Sie auf~[[http:homepage:mime]].

Es folgen die Layer, die angezeigt werden sollen. Anders als beim 'klassischen' MapServer, wo die Layernamen einzeln jeweils mit ''layer'' notiert werden, wird bei WMS-konformen Servern eine Liste der gewünschten Layer benötigt, wobei die einzelnen Layer durch Kommata voneinander getrennt werden. Dabei ist die Reihenfolge wichtig: der zuerst genannte Layer wird als erste Ebene in die Karte gezeichnet, liegt also zuunterst. Die im Mapfile festgelegte Reihenfolge spielt keine Rolle mehr.

Mit ''SRS'' wird das ''spatial reference system'' definiert, also die gewünschte Projektion angegeben. WMS verlangt EPSG-Codes für die Notierung der Projektion, wobei das Schlüsselwort ''EPSG'' und die dazugehörige Zahl durch einen Doppelpunkt voneinander getrennt werden. Mehr zu diesem Thema, das oft zu schwer identifizierbaren Fehlern führt und einige Nerven kosten kann, finden Sie im Anhang FIXME: Verweis auf den noch zu erstellenden Anhang.

''BBOX'': Ähnlich wie die anzuzeigenden Kartenebenen werden auch die gewünschten Extents durch mehrere Werte angefordert, die in einer Liste durch Kommata voneinander getrennt sind. Achten Sie immer darauf, dass die Werte der BBOX mit dem SRS korrespondieren.

''WIDTH'' und ''HEIGHT'' geben die Größe in Pixeln vor, die die fertige Karte haben soll. Beachten Sie, dass diese Werte mit der BBOX korrelieren müssen; eine quadratische BBOX in Verbindung mit ungleicher Höhe und Breite führt zu einer Verzerrung des Kartenbildes.

Der Parameter ''STYLES'' gibt für jeden Layer eine Darstellungsoption an (sofern der Provider des Service dieses mit den sog. ''Named Styles'' vorbereitet hat). Sie müssen keine Styles angeben, der Parameter im GetMap-Aufruf ist jedoch Pflicht.

Mit ''TRANSPARENT'' wird die Hintergrundfarbe der Karte transparent geschaltet. Das will man offensichtlich dann haben, wenn man unter dieser Kartenebene noch andere Layer anzeigen möchte.

Schließlich und endlich wird dem WMS im obigen Beispiel mitgeteilt in welcher Form Fehlermeldungen ausgegeben werden, in unserem Fall soll die Fehlermeldung in resultierende Rasterbild gerendert werden. Wenn Sie eine XML-formatierte Fehlermeldung bevorzugen verwenden Sie ''application/vnd.ogc.se_xml''.

Das Ergebnis dieses Aufrufes ist also eine 500 mal 500 Pixel große, auf EPSG-Code FIXME: 4326 projizierte Karte im PNG-Format mit den angegebenen Extents und transparentem Hintergrund. Der aufrufende URL dieser Karte kann entweder so bei Ihnen im Webbrowser erscheinen, oder aber von MapServer dynamisch für die Anzeige als Rasterlayer generiert worden sein.

Als nächstes schauen wir uns an, wie aus einem bestehenden Mapfile eines gemacht werden kann, das für WMS-konformes Verhalten nach außen sorgt.

=Web Map Service (WMS)=
==UMN als WMS Server==

Von besonderem Interesse ist die ''OpenGIS Web Map Server Interfaces Implementation Specification'' , im folgenden kurz WMS-Standard genannt. Diese Spezifikation liegt inzwischen in der Version 1.1.1~[[pdf:spec:ogc111]] vor. MapServer unterstützt aber auch die zurückliegenden Standards 1.0.0~[[pdf:spec:ogc100]] und 1.1.0~[[pdf:spec:ogc110]].

Sinn der WMS-Spezifikation ist es, ein offenes, definiertes Interface sowohl für Clients als auch für Server zur Verfügung zu stellen, die Karten und Daten über diese Karten miteinander austauschen wollen. Zur Kommunikation zwischen den Servern und Clients wird das HTTP-Protokoll verwendet. Über das Protokoll werden Daten im XML-Format übertragen\footnote{Für Exceptions sind auch andere Formate möglich.}. Parsen und weiterverarbeiten läßt sich XML in fast jeder bekannten Programmiersprache. Auf diese Weise ist man nicht an Webapplikationen gebunden, wenn man ein Programm entwickeln möchte, das mit einem WMS-Mapserver 'redet'. Die dazugehörige DTD\footnote{Die sogenannten ''document type definitions'' dienen der Validierung von Dokumenten. Sie können ein DTD also benutzen, um zu testen, um ein Dokument einem bestimmten Rahmen an Vorgaben genügt.} ist vom OGC zu beziehen und in der Spezifikation beschrieben. Gedruckt lernen Sie mehr über XML durch die Lektüre von~[[ray:2001:xml]], online finden Sie die Spezifikationen unter~[[http:homepage:xml]].

\subsubsection*{Hinweis}

Eine zentrale Rolle bei der Verwendung von WMS spielt die Umprojizierung von Daten. Da bei WMS Rasterdaten zum Einsatz kommen\footnote{Die Datenquelle für den Server kann natürlich ein Vektorformat haben. Produziert werden aber ausschließlich Rasterdaten, wie wir es bisher immer beim MapServer gesehen haben.}, und MapServer Rasterdaten ausschließlich unter Zuhilfenahme der Bibliothek GDAL umprojizieren kann, sollten Sie MapServer mit der Unterstützung für GDAL kompiliert haben.

==Servermodi==(2)

Die genannten Spezifikation in ihrer letzten Version verlangt: es ''müssen'' zwei Arten von Anfragen implementiert sein, zwei weitere sind optional und ''können'' implementiert sein. Die beiden folgenden Anfragen (weiterhin auch ''Requests'' genannt) müssen vorhanden sein:

*=getCapabilities= : Diese Anfrage muss ein XML-Dokument zurückliefern, das die Fähigkeiten des Mapservers beschreibt.
*=getMap= : Auf diese Anfrage wird eine Karte als Rasterbild zurückgeliefert.

Entsprechend der Anforderung sind diese beiden Anfragen auch im MapServer implementiert.

Die beiden Fähigkeiten, die implementiert sein ''können'' , sind:

*=getFeatureInfo= : auf diese Anfrage liefert der Mapserver Informationen über einen bestimmten Punkt in einer Karte zurück. Diese Informationen können entweder in einer reinen Textdarstellung oder in GML (einem XML-Format) zurückgegeben werden.
*=describeLayer= liefert ein XML-Dokument mit detaillierten Informationen über einen Layer zurück. Dieser Modus wäre für einen SLD\footnote{Styled Layer Descriptor}-konformen MapServer interessant, aber dieser Standard hat bisher noch keine Umsetzung im MapServer erfahren.

Das einzige Feature, das im MapServer zurzeit nicht implementiert ist, ist demnach =describeLayer= . Es gibt noch einige andere Modi; mehr dazu in Abschnitt~7

==WMS-Metadaten im Mapfile==\index{Metadaten}

Zuallererst benötigt ihr Mapfile einen Namen. Im Header muß also der Parameter =NAME= definiert sein.

Einen 'minimalen' WMS-Server erhalten Sie zum einen durch Metadaten in der =WEB= -Sektion des Mapfiles, zum anderen durch Metadaten in den einzelnen Layern. Einige davon sind zwingend erforderlich, andere optional. Wie die Notation von Metadaten im Mapfile generell erfolgt, haben Sie bereits in Abschnitt~\ref{text:mapfile:web:meta} erfahren.

 <code>
WEB
...
METADATA
"wms_title" "Ein WMS-Server"
"wms_onlineresource" \
"http://www.example.com/cgi-bin/mapserv?map=mapfile.map&"
"wms_srs" "EPSG:31464 EPSG:4326"
END
END
</code> 

Der =wms_title= ist der Titel für die Karte, dieser muß angegeben werden. Der zweite Parameter gibt an, unter welchem URL der Server aufzurufen ist.

Beachten Sie dabei, das =\&= anzugeben, bzw. ein Fragezeichen, wenn Sie nach dem eigentlichen CGI-Programm keinen Parameter zu stehen haben.

=wms_srs= steht für die Projektion, in der die Karten angeboten werden können. Die Spezifikation schreibt vor, dass hier immer mindestens EPSG-Code 4326 angeboten werden muß. Mehrere Projektionen werden einfach durch Leerzeichen voneinander getrennt. Mehr zu EPSG und Projektionen im allgemeinen haben Sie schon in Abschnitt~\ref{text:map:projections} erfahren.

Sie benötigen =wms_srs= nicht, wenn Sie für die Karte einen Projektionsblock mit EPSG-Angabe definiert haben; die =WEB= -Sektion 'erbt' dann diese Projektion als Vorgabe.

Was machen Sie, wenn Ihre Daten allesamt in einer Projektion vorliegen, für die es keinen EPSG-Code gibt? Dann können Sie einen =PROJECTION= -Block definieren, der Parameter für die Projektionsbibliothek ''proj.4'' enthält (das Beispiel stammt direkt aus der MapServer-Dokumentation):

 <code>
PROJECTION
"proj=lcc"
"ellps=GRS80"
"lat_0=49"
"lon_0=-95"
"lat_1=49"
"lat_2=77"
END
</code> 

Wenn Sie nun EPSG-Codes in =wms_srs= nach außen anbieten, werden die Daten automatisch umprojiziert.

\subsubsection*{Notwendige Metadaten in den Layern}

Des weiteren müssen nun in jedem Layer zusätzliche Angaben nach folgendem Muster gemacht werden:

 <code>
LAYER
NAME "einlayer"
...
METADATA
"wms_title" "Titel fuer den Layer"
"wms_srs" "EPSG:31494"
END
END
</code> 

Daneben muß auch in jedem Layer ein Name gesetzt und eine Projektion definiert sein. Als Standardvorgabe erbt jeder Layer die Projektionen aus der =WEB= -Sektion, sodass sie nicht noch einmal neu notiert werden müssen.

Sie benötigen natürlich immer noch eine Projektionsangabe im Layer in Form eines =PROJECTION= -Blocks, um zu definieren, in welcher Projektion die Datenquelle vorliegt, damit MapServer im Zweifelsfall korrekt projizieren kann. Das gilt natürlich insbesondere dann, wenn Sie mehr als nur eine Projektion anbieten wollen.

MapServer geht im übrigen davon aus, dass sie tatsächlich alle Layer im Mapfile nach außen zur Verfügung stellen wollen. Layer, die sie ''nicht'' nach außen geben wollen, haben also in diesem Mapfile nichts verloren. Es gibt bisher keinen Mechanismus, mit dem man einzelne Layer (oder alle) in einem Mapfile von der Auslieferung per WMS ausschließen kann.

\subsubsection*{Metadaten in der Web-Sektion}

Im folgenden sind alle Metadaten beschrieben, die Sie für einen WMS-konformen Server in der =WEB= -Sektion des Mapfiles notieren können. Alle Angaben sind optional, falls nicht anders angegeben.

*=wms_abstract= Eine elaborierte Zusammenfassung dessen, was der Server soll und ist.
*=wms_accessconstraints= Gibt Zugangsbeschränkungen für den MapServer an. Beachten Sie bitte, dass ein Eintrag hier lediglich eine Absichtserklärung ist. Ein Text wie 'Dieser Server darf nur im Intranet unserer Firma verwendet werden' ist natürlich schön und gut, aber die entsprechenden Zugriffsbeschränkungen sind selbtsverständlich nur durch die entsprechende Konfiguration der Systeme zu erreichen.
*=wms_addresstype= Art der Adresse. Für dieses und die folgenden fünf Felder gilt, dass bei Angabe eines der Felder auch die anderen fünf mit Inhalt gefüllt werden müssen.
*=wms_address= Die Adresse.
*=wms_city= Adressbestandteil: Stadt
*=wms_country= Adressbestandteil: Land
*=wms_postcode= Adressbestandteil: Postleitzahl
*=wms_stateorprovince= Adressbestandteil: Staat oder Provinz
*=wms_contactelectronicmailaddress= Emailadresse einer Kontaktperson für diesen Server
*=wms_contactoraganization= Organisation der Kontaktperson
*=wms_contactperson= Name der Kontaktperson für diesen Server
*=wms_contactposition= Position der Kontaktperson innerhalb ihrer Organisation
*=wms_contactvoicetelephone= Telefonnummer der Kontaktperson
*=wms_fees= Art und Umfang der Gebühren, die für die Nutzung dieses Servers fällig werden. Genau wie bei =wms_accessconstraints= ist dies lediglich eine Absichtserklärung; wenn Sie Gebühren für die Verwendung des Servers erheben möchten, müssen Sie die Zugriffskontrolle durch eine geeignete Systemkonfiguration und ein passendes Geschäftsmodell herbeiführen.
*=wms_keywordlist= Eine Liste von Schlüsselworten, die auf den Server zutreffen. Dieser Parameter ist mit dem Blick darauf geschaffen worden, dass es eines Tages in einer eigens dafür geschaffenen Datenbank eine Sammlung von Capabilities-Dokumenten geben könnte, die dann die Schlüsselwortlisten durchsuchen kann. Bisher gibt es keine solche Datenbank. Es sind auch keine Standardschlüsselwörter definiert.
*=wms_onlineresource= Der URL, mit dem der Server aufgerufen wird. Beinhaltet beim UMN MapServer meistens: <code> http://www.example.com/cgi-bin/mapserv? </code> und gegebenenfalls daran angehängt noch das Mapfile. Wenn ein Mapfile über =map== angehangen wird, darf nicht das abschließende =\&= vergessen werden! Dieser Parameter ist zwingend notwendig.
*=wms_resx= Horizontale Auflösung der Karte in Pixeln.
*=wms_resy= Vertikale Auflösung der Karte in Pixeln.
*=wms_srs= Projektion(en), in der die Karte angeboten werden kann. Dieser Parameter mit mindestens einer Projektion ist zwingend notwendig.
*=wms_title= Titel der Karte. Dieser Parameter ist zwingend notwendig.

\subsubsection*{Metadaten in den einzelnen Layern}

Im folgenden die Metadaten, die Sie für einen WMS-konformen MapServer in den einzelnen Layern im Mapfile definieren können. Alle Parameter sind optional, sofern nicht anders angegeben.

*=wms_abstract= Elaborierte Zusammenfassung dessen, was dieser Layer soll und ist.
*=wms_extent= Die Bounding Box des Layers.
*=wms_keywordlist= Eine Liste von Schlüsselworten, die auf diesen Server zutreffen. %
*=wms_opaque= FIXME: was ist das?
*=wms_srs= Projektion(en), in der die Karte angeboten werden kann.
*=wms_title= Titel des Layers. Dieser Parameter ist zwingend erforderlich.

\subsubsection*{Das Mapfile als Parameter}(4)

Der Name des Mapfiles in der URL-Zeile ist nicht Bestandteil eines OGC-konformen Aufrufs des Mapservers. Unter Sicherheitsaspekten kann es darüber hinaus eventuell nicht angebracht sein, dem Client etwas über die Verzeichnisstruktur des Server-Systems zu verraten.

Im Moment gibt es zwei verschiedene Wege, den Ort des Mapfiles vor Außenstehenden zu verbergen:

*''Verwenden eines Wrapper-Skripts'' : Anstatt des CGI-Binaries wird ein kleines Skript aufgerufen, das die Umgebungsvariable = MS_MAPFILE = setzt und dann seinerseits das CGI-Programm aufruft. Ganz primitiv könnte ein solches Skript für die Shell =bash= etwa wie folgt aussehen: <code> #!/bin/sh MS_MAPFILE=/usr/local/there/is/my.map export MS_MAPFILE /usr/local/httpd/cgi-bin/mapserv </code> Beachten Sie bitte, dass dieses Beispiel nur für Unix-Systeme funktioniert, auf denen die Shell =bash= installiert ist. Für andere Shells kann die Notation abweichen.
*''Webserver-Konfiguration'' : Der Webserver ist unter Umständen in der Lage, für bestimmte aufgerufene URLs spezifische Umgebungsvariablen zu setzen. Im Apache sähe ein Eintrag in der Datei ''httpd.conf'' dann beispielsweise folgendermaßen aus (wegen der Zeilenlänge für das Drucklayout umgebrochen, muß in der Konfigurationsdatei eine Zeile sein): <code> SetEnvIf Request_URI "/cgi-bin/mapserv" \ MS_MAPFILE=/usr/local/there/is/my.map </code> Dieser Eintrag funktioniert nur im Apache und kann für andere Webserver vollkommen anders aussehen. Konsultieren Sie Ihre Dokumentation.

\subsubsection*{getCapabilities}(5)

Nachdem man zufrieden mit seinem Setup ist, möchte man es natürlich ausprobieren. Dazu ruft man als erstes das ''Capabilities'' -Dokument ab:

 <code>
http://server/cgi-bin/mapserv?VERSION=1.1.0&REQUEST=getCapabilities \
&map=mapfile.map
</code> 

Dabei müssen Sie bei =getCapabilities= nicht auf Groß- oder Kleinbuchstaben achten. Ebensowenig bei allen anderen Parametern, die vor einem Gleichheitszeichen stehen.

Der Webserver sollte Ihnen nun eine Datei des Typs =application/vnd.ogc.wms_xml= zurückliefern. Diese Textdatei können Sie abspeichern und in einem beliebigen Texteditor öffnen. Eventuell ist Ihr Webbrowser auch von sich aus in der Lage, XML-Dateien automatisch in einem ansprechenden Layout darzustellen.

Schauen Sie sich nun den Inhalt der Datei genau an. Wo immer Sie auf Zeilen treffen, die

 <code>

</code> 

beinhalten, gilt es, etwas zu bereinigen. Beispielsweise erfahren Sie aus einer Warnung wie dieser:

 <code>

</code> 

dass Sie einen Meta-Tag für den Titel der entsprechenden Sektion vergessen haben.

Sobald Sie keine Warnungen dieser Art mehr in Ihrem Capabilities-Dokument finden, ist ihr MapServer WMS-konform und voll einsatzbereit.

\subsubsection*{getMap}

Wenn die Capabilities wie erwartet geliefert werden, ist der nächste logische Schritt natürlich, sich eine Karte von Hand abzuholen. Dafür konstruieren Sie sich in Ihrem Webbrowser einen Aufruf, der etwa so aussieht, wie das Beispiel in Abschnitt~3. Dabei machen Sie sich dann auch gleich mit der Benennung der Parameter vertraut.

Das beste was Ihnen passieren kann, ist natürlich, dass Sie gleich ihre gewünschte Karte bekommen. Dann sind Sie natürlich fertig. Sobald Sie jedoch Ihren ersten Fehler machen, müssen Sie sich mit Fehlermeldungen auseinandersetzen, den so genannten Exceptions.

==Exceptions==\index{Exceptions}\index{WMS!Exceptions}

Exceptions sind Meldungen, die von einem WMS-konformen Mapserver im Fehlerfall ausgegeben werden müssen. Das entspricht in etwa dem Expcetions-Konzept diverser Programmiersprachen wie z.B. Java. Der Sinn ist es, dem aufrufenden Client -- sei es nun eine menschliche Person, sei es eine Software -- anhand des Typs und des Inhalts der Fehlermeldung eine Entscheidung über das weitere Vorgehen treffen zu können. Eine solche Art der Fehlerbehandlung verhindert natürlich unter anderem, dass ein Programm seine Durchführung im Fehlerfall einfach beendet.

Wenn Sie bei einem WMS-konformen Aufruf einen Fehler machen, indem Sie beispielsweise einen Parameternamen wie =REQUEST= absichtlich falsch schreiben, wird Ihnen MapServer eine Datei in einem XML-Format zurückliefern:

*=application/vnd.ogc.se_xml= Ein WMS-konformer Mapserver muß mindestens diese Art der Vermittlung von Exceptions beherrschen. Solch eine Datei kann beispielsweise folgenden Inhalt haben: <code> <?xml version='1.0' encoding="ISO-8859-1" standalone="no" ?> <!DOCTYPE ServiceExceptionReport SYSTEM "http://www.digitalearth.gov/wmt/xml/exception_1_1_0.dtd"> <ServiceExceptionReport version="1.1.0"> <ServiceException> msWMSDispatch(): WMS server error. Incomplete WMS request: REQUEST parameter missing </ServiceException> </ServiceExceptionReport> </code> 

\begin{figure}
\begin{center}
\mmfig{0.6}{wms-exception-inimage}{Exception vom Typ application/vnd.ogc.se_inimage.}
\end{center}
\end{figure}

Des weiteren kann ein Mapserver Exceptions in den folgenden MIME-Typen zur Verfügung stellen:

*=application/vnd.ogc.se_inimage= Die Exception wird als Text in das auszuliefernde Bild eingefügt.
*=application/vnd.ogc.se_blank= Die Spezifikation geht von der Idee, dass ein leeres Bild etwas ist, dass man grundsätzlich nicht haben möchte, und somit nie bekommt. Daher kann ein 'leeres' Bild als Fehlermeldung angesehen werden. Als 'leeres' Bild ist ein Bild definiert, das ganz mit der Hintergrundfarbe der Karte ausgefüllt ist.

Im URL des Aufrufs wird die gewünschte Art der Exception mit dem Parameter =EXCEPTIONS= notiert. Wollen Sie Exceptions also im Bild notiert haben, schreiben Sie in Ihrem URL:

 <code>
... & EXCEPTIONS=application/vnd.ogc.se_inimage & ...
</code> 

Beachten Sie bitte, dass nur die XML-Variante implementiert sein muß. Wenn Sie von einem Server Exceptions im Bild verlangen, er aber nur XML kann, dann wird er XML liefern.

Beachten Sie außerdem, dass das Handling von Exceptions insbesondere bei Kaskaden von WMS-konformen Servern eine Rolle spielt. So kann es Ihnen passieren, dass Sie sich einen Layer von einem Server holen, der sich wiederum sein Bild von anderen entfernten Quellen heranholt, und von dort im Fehlerfall eine Exception in das Bild eingetragen bekommt. Dadurch haben Sie die Fehlermeldung dann natürlich auch im Bild zu stehen.

===Hinweis===

Viele Kartenanbieter tendieren dazu, ihre fertigen Karten mit Schriftzügen, Logos, Nordpfeilen, Wasserzeichen und so weiter auszustatten. Denken Sie immer daran, dass der Kunde, der Ihren Service wiederum als Datenquelle benutzt, eventuell auf die Idee kommt, die von Ihnen bezogene Karte umzuprojizieren! Das kann dann zu interessanten Effekten führen, wenn dann Dritte den Schriftzug mit der URL Ihrer Firmenwebsite quer über die ganze Karte gekrakelt bekommen. Entwickeln Sie im Vorhinein zusammen mit den Benutzern des Service ein Konzept, dass solche häßlichen Effekte verhindert.

==getFeatureInfo==

Sich Karten einfach nur anzusehen, ist selbstverständlich nur die Hälfte des Reizes eines WMS-konformen Servers. Man möchte selbstverständlich auch Queries auf die Daten durchführen können. Zu diesem Zweck gibt es den =REQUEST= mit dem Namen =getFeatureInfo= .

Zuerst einmal gilt es, Queries überhaupt erst einmal zuzulassen. Wie schon bei den 'klassischen' Queries (siehe Abschnitt~\ref{text:mapfile:queries}) kann man in MapServer eine Query nur auf einem Layer durchführen, der ein =TEMPLATE= definiert.

Wenn man das tut, und sich die ''capabilities'' anschaut, wird man für den Layer auf ein Attribut der folgenden Art treffen:

 <code>
<Layer queryable="1" opaque="0" cascaded="0">
</code> 

Der Wert =1= für =queryable= zeigt im Gegensatz zum Wert =0= an, dass Queries auf diesen Layer zulässig sind.

Um einen Aufruf vom Typ =getFeatureInfo= zu verstehen, betrachten wir einmal einen vollständigen URL für diesen Vorgang:

 <code>
http://www.example.com/cgi-bin/mapserv
? map=/usr/local/mapserv/mapfile.map
& VERSION=1.1.0
& REQUEST=getFeatureInfo
& QUERY_LAYERS=gruenflaechen
& SRS=EPSG:4326
& BBOX=5.0,45.0,15.0,55.0
& WIDTH=500
& HEIGHT=500
& X=250
& Y=250
& INFO_TYPE=text/plain
</code> 

Einige Bestandteile sind dem Leser bereits bekannt: Version des Standards, Angabe der Projektion durch =SRS= . Dazu kommt, wenig überraschend, die Angabe des =REQUEST= .

Da jetzt keine Darstellung mehr erfolgen sollen, werden keine =LAYERS= mehr angegeben, sondern =QUERY_LAYERS= \footnote{Diese Unterscheidung ist offensichtlich eigentlich unnötig, da man die Funktion der Layerangabe ja eigentlich serverseitig aus dem =REQUEST= schließen könnte.}. Um Ergebnisse zu liefern, muß jeder Layer in der Liste =QUERY_LAYERS= das Attribut =queryable= auf =1= gesetzt haben -- siehe oben.

Zwingend sind darüberhinaus die Angabe der Extents des Bildes, das man befragen möchte (angegeben mit =BBOX= ), Breite und Höhe des Bildes sowie die X- und die Y-Koordinate des Punktes im Bild, der sich der Aufmerksamkeit des Users erfreut, beispielsweise durch einen Mausklick. Beachten Sie, dass es sich dabei um Bildkoordinaten handelt, es handelt sich also um Pixelwerte. Der Koordinatenursprung eines Bildes ist links oben.

Am interessantesten ist natürlich der =INFO_TYPE= , der angibt, auf welche Weise die Queryergebnisse formatiert sein sollen. MapServer unterstützt die folgenden Formate:

*=text/plain= , das Standardformat, falls Sie nichts anderes angegeben haben;
*=text/html= , was ein wenig Vorbereitung erfordert, im wesentlichen aber wie Queries auf einem 'normalen' MapServer-CGI behandelt wird; und
*=application/vnd.ogc.gml= , GML, eine XML-Repräsentation für Geodaten.

Betrachten wir die Formate im Detail:

\subsubsection*{text/plain}

Dieser Ausgabetyp für getFeatureInfo ist die Voreinstellung für MapServer, falls Sie keinen anderen Ausgabentyp spezifizieren.

Für ein Mapfile mit den Voreinstellungen des Itasca-Demos und einem fiktiven Anklickpunkt mit den Koordinaten 200/200 sieht die Ausgabe folgendermaßen aus:

 <code>
GetFeatureInfo results:

Layer 'countyboundary'
Feature 26:
AREA = '7577272785.15393'
PERIMETER = '436617.07762'
CTY_NAME = 'Itasca'
COUN = '31'
CTY_ABBR = 'ITAS'
ISLAND = 'N'
CTY_FIPS = '61'
RECNO = '27'
</code> 

Es wird der Name des Layers ausgegeben, die Nummer des Layers innerhalb des Shapefiles, und dann alle Attribute aus der =.dbf= -Datei der Datei. Wenn es mehrere Suchergebnisse gegeben hat, werden diese der Reihe nach dargestellt.

\subsubsection*{text/html}

Mit diesem Ergebnistyp greift MapServer auf die HTML-Templates zurück, die Sie für Queries bereits in Kapitel~\ref{text:mapfile} kennengelernt haben. Das bedeutet, dass Sie ein HTML-Layout ganz nach Ihrem Geschmack gestalten können, und MapServer die entsprechenden Tags in eckigen Klammer wie gewohnt ersetzt.

Dieser ''MIME type'' bietet jedoch noch die Möglichkeit für zusätzliche Tricksereien. Der Standard schreibt nämlich keinen ''MIME type'' zwingend vor, und ebensowenig gibt es ein vorgeschriebenes Verhalten für den Fall, dass ein bestimmter Typ nicht unterstützt wird. Das führt dazu, dass MapServer es sich vorbehält, beliebige Arten von Daten zurückzuliefern.

Sie können ein =TEMPLATE= definieren, das nicht gezwungenermaßen eine HTML-Seite sein muß. Reiner ASCII-Text wäre ebenso möglich, oder alle anderen Formate, in denen Sie MapServer-Tags ersetzen können.

Sobald das Template beliebigen Formats von MapServer bearbeitet worden ist, kann das Resultat zurückgeliefert werden. Wenn man jetzt reinen ASCII-Text hat, würde MapServer ihn jedoch als =text/html= ausliefern, und das ist eigentlich nicht das, was man möchte. Der Client (also z.B. Webbrowser) interpretiert die Daten natürlich nur korrekt, wenn man ihm den korrekten MIME type liefert. Daher kann man im Mapfile für die zurückgegebenen Daten einen eigenen Metadatum den geeigneten Typ setzen:

 <code>
WEB
...
METADATA
...
"wms_feature_info_mime_type" "text/plain"
END
END
</code> 

Also noch einmal zusammenfassend: der Benutzer kann zwar von außen den =INFO_TYPE= auf =text/html= setzen; MapServer kann jedoch mit Daten beliebigen Typs antworten.

\subsubsection*{application/vnd.ogc.gml}

Damit ein Layer in diesem Format Anfragen beantworten kann, muß außerdem der Parameter =DUMP= in diesem Layer gesetzt sein:

 <code>
LAYER
...
DUMP TRUE
END
</code> 

Falls es keine Suchresultate gegeben hat, wird zwar eine Datei im korrekten Format zurückgegeben, die allerdings nur die korrekten Header enthält und ansonsten leer ist.

Für Suchergebnisse werden in diesem Format immer die Koordinaten des Features gleich mitgeliefert. Antworten können also bei großen Features nicht nur auf sich warten lassen, da MapServer für das Erzeugen großer Dokumente natürlich eine Weile braucht, sondern auch weil der Transfer über das Netz natürlich ein bißchen dauert.

Die Anfrage auf den Flughafen-Layer der Itasca-Demodaten beispielsweise liefert in den voreingestellten Extents und dem fiktiven Klick auf die Koordinate 224/75 das folgende Ergebnis:

 <code>
<?xml version="1.0" encoding="ISO-8859-1"?>

<msGMLOutput
xmlns:gml="http://www.opengis.net/gml"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance">
<countyboundary_layer>
<countyboundary_feature>
<AREA>7577272785.15393</AREA>
<PERIMETER>436617.07762</PERIMETER>
<CTY_NAME>Itasca</CTY_NAME>
<COUN>31</COUN>
<CTY_ABBR>ITAS</CTY_ABBR>
<ISLAND>N</ISLAND>
<CTY_FIPS>61</CTY_FIPS>
<RECNO>27</RECNO>
<gml:boundedBy>
<gml:Box srsName="EPSG:26915">
<gml:coordinates>
393234.393701,5207990.085063
495769.579719,5305374.105135
</gml:coordinates>
</gml:Box>
</gml:boundedBy>
<gml:Polygon srsName="EPSG:26915">
<gml:outerBoundaryIs>
<gml:LinearRing>
<gml:coordinates>
393865.671855,5300138.258409
393869.171975,5300138.258374
394516.694141,5300137.439369
395522.728579,5300136.241770
[...]
</code> 

Und so weiter, mit allen Punkten des Features.

==WMS Clients==\index{OGC!Client}(6)

WMS-konforme Mapserver lassen sich kaskadieren, indem einzelne Layer einfach als fertige Bilder von anderen WMS-konformen Mapservern bezogen werden. Durch die standardisierte Schnittstelle ist dafür kein UMN MapServer nötig. Sie können einzelne Layer beispielsweise auch von einem ESRI ArcIMS beziehen, wenn Sie möchten.

Neben der schönen Möglichkeit, die Standorte und somit Pflege einzelner Teile der Kartenerzeugung voneinander trennen zu können, indem man beispielsweise die Bodenproben von einem Amt und die hydrogeologischen Karten von einem anderen Amt miteinander über eine genormte Schnittstelle verbindet, ist ein weiteres offensichtliches Einsatzfeld natürlich die Lastenverteilung. Datenbestände, die erst umprojiziert werden müssen, können auf leistungsfähigere Server ausgelagert werden, während einfache Operationen wie beispielsweise die simple Darstellung von Rasterbildern von schwächeren Geräten übernommen werden kann\footnote{Beachten Sie dabei immer, dass zur Erzeugung des fertigen Bildes ''immer'' auf den langsamsten Layer gewartet werden muß, da ja das Bild ansonsten nicht komplett ist.}.

Im folgenden soll betrachtet werden, wie Sie einen Layer in einem Mapfile erstellen, damit er dynamisch Daten von einem WMS-konformen Server bezieht. Nach außen hin verhält sich dieser Layer dann wie jeder andere Rasterlayer auch.

\subsubsection*{Installation und Konfiguration}

Wie weiter hinten im Kapitel 'Installation' ab Seite~\pageref{text:installation} beschrieben, ist die Fähigkeit, als WMS-Client zu fungieren, nicht als Voreinstellung bei der Kompilierung gegeben, sondern muß explizit angefordert werden. Wie das genau gemacht wird, und welche Voraussetzungen gegeben sein müssen, ist in Abschnitt~\ref{text:installation:compile:wmsclient} erklärt.

\subsubsection*{getMap}

Der erste Schritt ist, sicherzustellen, dass der anzusprechende Server funktioniert und die gewünschten Daten ausliefert. Dafür holt man sich das Capabilites-Dokument dieses Servers. Wie das zu tun ist, ist auf Seite~\pageref{text:wms:getcapabilities} beschrieben.

Nun weiß man alles über die Fähigkeiten des Servers (welche Projektionen angeboten werden, wie seine Layer heißen und so weiter) und kann sich darum kümmern, eine erste Karte zu holen, um zu sehen, ob die Darstellung dem entspricht, was man erwartet. Dazu richtet man mit seinem Webbrowser eine =getMap= -Anfrage an den Server.

Wie so eine Anfrage aufgebaut sein muß, wurde bereits in Abschnitt~3 gezeigt. Ersetzen Sie allerdings alle Werte für die Parameter durch diejenigen, die Sie im abgerufenen Capabilities-Dokument gefunden haben, also durch korrekte Projektionen, Layernamen, Extents und so weiter. Sobald dieser Aufruf eine Karte in Ihrem Browser zaubert, wissen Sie, dass Sie gültige Werte besitzen und sie korrekt notiert haben, sodass Sie diese Angaben jetzt in einen Layer in Ihr Mapfile einbauen können.

\subsubsection*{Das Mapfile}

Zunächst benötigen Sie einen =PROJECTION= -Block für Ihre Karte. Sie können auf diesen Block verzichten, wenn alle Layer in der gleichen Projektion vorliegen und auch die von Ihnen angesprochenen WMS-Server nur diese eine Projektion unterstützen.

Beachten Sie, dass Sie in der =WEB= -Sektion Ihres Mapfiles einen =IMAGEPATH= -Parameter benötigen, da die Bilder von entfernten Servern als temporäre Dateien gespeichert werden müssen. Diese temporären Dateien werden übrigens nach Verwendung gleich wieder gelöscht, sodass Sie sie kaum bemerken werden.

Für WMS-konforme Anfragen an andere Server sind lediglich die Layerdefinitionen anzupassen. Dabei kommt ein =CONNECTIONTYPE= mit dem Namen =WMS= zum Einsatz:

 <code>
LAYER
NAME "Gewaesser"
TYPE RASTER
STATUS ON
CONNECTIONTYPE WMS
CONNECTION "http://www.example.com/cgi-bin/mapserv?"
METADATA
"wms_title" "Gewaesser"
"wms_server_version" "1.1.0"
"wms_srs" "EPSG:4326 EPSG:31464"
"wms_name" "seen,kanaele,fluesse,baeche"
"wms_format" "image/png"
END
PROJECTION
"init=epsg:31464"
END
END
</code> 

Wie Sie sehen, ist der URL selber sehr kurz gehalten. Er entspricht der ''onlineresource'' aus dem Capabilities-Dokument eines WMS-konformen Servers.

Alle weiteren Details zur Verbindung mit dem entfernten Server werden in Form von Metadaten gemacht. Wer bisher MapServer 3.6 eingesetzt hat, wird das noch anders kennen: in jener Version wurde noch der gesamte Verbindungsstring (bis auf die dynamischen Elemente) in der =CONNECTION= notiert.

Der =wms_title= ist der Titel für diesen Layer, der mit der Anfrage allerdings nichts zu schaffen hat.

Die Version der Anfrage wird mit =wms_server_version= notiert. Mit =wms_srs= geben Sie wieder Projektionen an, allerdings diejenigen, die von der Gegenstelle unterstützt werden.

=wms_name= benennt den oder die Layer, aus denen die bezogene Karte zusammengesetzt werden soll. Mehrere Layer werden durch Kommata voneinander abgetrennt. Beachten Sie, dass bei WMS die Reihenfolge der Ebenen von Belang ist: in unserem Beispiel werden zuerst der Layer =seen= gezeichnet, darauf dann =kanaele= und so weiter.

Das gewünschte Bildformat wird schließlich mit =wms_format= spezifiziert. Es gibt auch den Parameter =wms_formatlist= , der mehrere durch Kommata getrennte Angaben zuläßt.

''Wichtiger Hinweis'' : An keiner einzigen Stelle lädt sich MapServer die Capabilities des entfernten Servers herunter, um sich mit ihnen auseinanderzusetzen. Sie müssen also selber darauf achten, dass die von Ihnen gemachten Angaben stimmig sind.

==Exceptions==

Wenn Sie einen Layer haben, der sich Daten von einem WMS-konformen Server holt, drängt sich natürlich die Frage auf, wie MapServer im Fall von Exceptions reagiert. Eindeutige Antwort: das kommt drauf an.

Am einfachsten ist es offensichtlich, mit Exceptions, die direkt im Bild eingefügt sind, umzugehen, also mit denen, die vom Typ =application/vnd.ogc.se_inimage= sind. Diese werden einfach Bestandteil der fertigen Karte, die Sie im Webbrowser sehen. Im Fehlerfall bemerkt sehr schnell, was Sache ist.

Das gleiche gilt offensichtlich bei =application/vnd.ogc.se_blank= .

Liefert die Gegenstelle ein textbasiertes Format, also zum Beispiel GML zurück, dann gibt es ein Problem, da MapServer davon ausgeht, dass er Rasterdaten als Input erhält; demnach versucht er, das GML-Dokument als Text zu rendern, was natürlich schief geht und somit eine Fehlermeldung erzeugt.

Dieses Problem läßt sich bisher leider auch noch nicht umgehen. Das mindeste, was man also tun kann, ist für eine funktionierende Kommunikation mit dem Betreiber des Quellservers zu sorgen, damit dieser nicht einfach unangekündigt Layernamen ändert, die Ihnen Ihre Applikation wegbrechen lassen.

==Hinweise==(7)

FIXME: das auch noch bei WFS erwähnen

Wenn Sie mit der Administration sowohl des Mapservers, der als Client fungiert, als auch der Serverseite betraut sind, sollten Sie auf alle Fälle darauf achten, keine zirkulären Bezüge zu erzeugen, bei denen Server A einen Layer von Server B bezieht und dieser dann wieder Server A aufruft. Bei komplexen Installationen ist das durchaus eine Fehlerquelle, das Verhalten in diesem Fall ist undefiniert.

Ein weiterer wichtiger Faktor beim Einsatz von WMS-konformer Funktionalität ist die unschöne Tatsache, dass MapServer das Sammeln der Daten für einzelne Layer linear abarbeitet, und nicht mit einem einzelnen Thread oder Prozess pro Layer arbeitet. Das bedeutet, dass MapServer genau ''gar nichts'' tut, während er auf einen Layer aus dem Netzwerk wartet, um dann zum nächsten Layer überzugehen\ldots der dann vielleicht wieder ein solcher Layer ist, oder eine Datenbankquelle. Es wird also unnötig Rechenzeit vergeudet. Dieses Problem läßt sich im Moment auch leider nicht umgehen.

\subsubsection*{Weitere Modi für WMS}

Wer den Standard aufmerksam liest, wird noch vier weitere Operationsmodi finden, die in den einführenden Zeilen zu diesem Abschnitt nicht genannt worden sind. Sie umfassen:

*=describeLayer=
*=getLegendGraphic=
*=getStyles=
*=putStyles=

Diese Modi sind nur für Mapserver von Relevanz, die den OGC-Standard SLD unterstützen. Mit diesen ''styled layer descriptor'' ist es möglich, von außen Einfluß auf die ansonsten fixe Kartengestaltung eines Mapservers zu nehmen. Da dieser Standard serverseitig von MapServer bisher nicht unterstützt wird\footnote{Und clientseitig nur sehr sporadisch; konsultieren Sie hierzu bitte die Online-Dokumentation.}, findet hier keine detaillierte Beschreibung statt. Sie können sich aber selbstverständlich den Standard~[[pdf:spec:sld10]] lesen.

=Web Feature Server (WFS)=(8)

Die entsprechende Spezifikation des OGC~[[pdf:spec:wfs100]] sieht WFS im Kontext zu WMS. Nach der Formulierung in der Einführung des Dokuments ist WFS der 'nächste logische Schritt' nach WMS. Wo WMS die Möglichkeit bietet, Capabilities abzufragen Karten anzuzeigen und schließlich Anfragen bezüglich der Datengrundlage der Karten zu machen, stellt WFS ein Interface zur Verfügung, dass es dem Benutzer ermöglicht, Einfluß auf die Datengrundlage zu nehmen, indem Features in der Karte geändert und gelöscht, bzw. neue Features hinzugefügt werden können.

Das hört sich alles ziemlich gut an -- und doch muß der begeisterte Leser hier enttäuscht werden. MapServer ist bisher ausschließlich darauf ausgelegt, Daten aus Quellen wie der Festplatte oder einer Datenbank zu lesen und Karten zu produzieren. Von einer Unterstützung für Datenänderungen ist man im Moment noch sehr weit entfernt -- falls sie überhaupt kommen wird\footnote{Es besteht natürlich die Möglichkeit, dass Sie beispielsweise mit MapScript entsprechende Fähigkeiten in einer eigenen Applikation programmieren. Stellen Sie sich auf einigen Aufwand ein.}.

Was wir mit MapServer kriegen, ist allerdings zumindest die Möglichkeit, Vektorlayer über den Transportmechanismus von WFS als Server auszuliefern bzw. als Client zu beziehen. Das funktioniert nur mit Vektordaten, da sich Rasterdaten offensichtlich nicht in das XML-Format mit dem Namen GML verpacken lassen. Diese ''Geography Markup Language'' ist selbstverständlich ebenfalls in einer eigenen Implementation Specification definiert~[[pdf:spec:gml]].

Von den in der Spezifikation definierten Anfragetypen sind im MapServer die folgenden implementiert:

*=getCapabilities= , um ein Capabilities-Dokument abrufen zu können, wie man es bereits von WMS kennt.
*=describeFeature= liefert eine Beschreibung eines Features zurück.
*=getFeature= holt eine GML-Repräsentation eines Features.

==WFS Server==

Wie schon beim WMS-konformen Server, wird WFS in MapServer dadurch aktiviert, dass die notwendigen =METADATA= -Tags in das Mapfile eingefügt werden. Zuerst einmal müssen aber die folgenden Vorkehrungen getroffen werden:

*Zuerst muß MapServer natürlich mit WFS-Unterstützung kompiliert worden sein. Detaillierte Vorgaben dafür finden Sie in Anhang~\ref{anhang:compile}.
*Das Mapfile muß einen =NAME= haben, ebenso wie jeder einzelne Layer. Wie schon bei WMS geht MapServer bei WFS davon aus, dass jeder Layer, der sich im Mapfile befindet, auch über WFS zur Verfügung gestellt werden soll.

MapServer kann ausschließlich Vektorlayer in seinen WFS-Capabilites erscheinen lassen, also Shapefiles, PostGIS-Layer und so weiter; der Typ des Layers muß also =POINT= , =LINE= oder =POLYGON= sein.

Desweiteren muß die Eigenschaft =DUMP= im Layer auf =TRUE= gesetzt sein. Dies zeigt MapServer an, dass er GML-Repräsentationen für diesen Layer erzeugen darf. Das entspricht der Vorgabe, =getFeatureInfo= mit einem WMS-konformen Server nutzen zu können.

In der =WEB= -Sektion des Mapfiles müssen dann die folgenden Angaben gemacht werden.

*=wfs_onlineresource= Die Basisadresse des Servers. Hat denselben Aufbau wie der gleichnamige Parameter für WMS. Allerdings muß man einem WFS-konformen MapServer noch mitteilen, wie er WFS- von WMS- Anfragen zu unterscheiden hat. Das geschieht durch =SERVICE= , also etwa derart: <code> WEB .. METADATA ... "wfs_onlineresource" \ "http://www.example.com/cgi-bin/mapserv?SERVICE=WFS&map=..." END END </code> Diese Angabe ist auch dann nötig, wenn der MapServer nicht darauf eingerichtet oder konfiguriert ist, als WMS-Server zu fungieren.
*=wfs_title= Titel für die Karte; siehe WMS-Konformität. Zwingend notwendig.
*=wfs_abstract= Eine elaborierte Zusammenfassung über Sinn und Zweck dieses Servers. Siehe WMS-Konformität.
*=wfs_keywordlist= Eine Liste mit Schlüsselworten, die einen Bezug zu diesem WFS-Server haben. Siehe WMS-Konformität.
*=wfs_accessconstraints= Beschränkungen, die den Zugriff auf diesen Server betreffen. Siehe WMS-Konformität.
*=wfs_fees= Gebühren, die beim Zugriff auf diesen Server anfallen. Siehe WMS-Konformität.
*=wfs_encoding= Die Kodierung für die XML-Dateien, die durch den WFS-Server ausgeliefert werden. Voreingestellt ist hier ISO-8859-1.
*=ows_schema_location= Der Ort, an dem die OWS-Schemas zur Validierung der generierten XML-Dateien liegen. Siehe weiter unten auf Seite~\pageref{text:wfs:schemas}.
*=wfs_geometry_element_name= Weiter unten gibt es ein Beispiel zu sehen, wie eine Datei aussehen kann, die von einem WFS-konformen MapServer ausgeliefert wird. Das Element, dass die Liste der Koordinaten eines Features umfaßt, hat dabei keinen fixen Namen. Sie können mit diesem Parameter hier einen Namen festlegen; Voreinstellung in MapServer ist =MS_GEOMETRY= .
*=wfs_srs= Die Projektion, die für alle Layer in der Karte gelten soll. Wird als EPSG-Code angegeben und genauso wie bei WMS-konformen Servern notiert. Beachten Sie bitte die Anmerkungen zu Projektionen in WFS-konformen Servern im nächsten Abschnitt.

Beachten Sie, dass diese Parameter im Gegensatz zu den WMS-Parametern alle den Präfix =wfs_= tragen. Einzige Ausnahme ist =ows_schema_location= .

==Projektionen in WFS-Servern==

Die WFS-Spezifikation macht zu Projektionen andere Vorgaben als idie für WMS. So können einzelne Layer nicht in mehr als einer Projektion ausgeliefert werden. Es gibt auch keine Projektionsangabe, die man ein einziges Mal für alle Layer machen kann\footnote{Man kann aber, wie Sie weiter oben sehen konnten, MapServer so konfigurieren, dass er einen SRS-Eintrag in der WEB-Sektion bekommt und diesen dann auf alle Layer überträgt.}. Es ist aber sehr wohl möglich, für jeden Layer eine unterschiedliche Projektion anzubieten. Außerdem nennt der Standard keine Default-Projektion; anders als bei WMS, wo mindestens =EPSG:4326= angeboten werden muß.

MapServer entscheidet in zwei Schritten, welche Projektion für einen Layer nach außen mitgeteilt wird. Wenn es eine 'übergeordnete' Projektion gibt (also einen Projektionsblock mit EPSG-Code für die ganze Karte, bzw. ein =wfs_srs= in der WEB-Sektion), so findet diese Projektion auf alle Layer Anwendung, selbst dann, wenn die Layer selber noch einmal über =wfs_srs= eine Projektion definieren.

Gibt es keine solche 'Überprojektion', muß jeder Layer einen eigenen Wert setzen.

==Schemas==(9)

Schemas\footnote{In diesem Fall nicht Schemata, da es sich um einen feststehenden englischen Begriff handelt.} sind ein Mechanismus, XML-Dateien zu validieren, also zu prüfen, ob sie einem bestimmten Aufbau genügen. Sie können ein Paket standardkonformer Schemas von~[[http:owssamples]] herunterladen.

Das Archiv entpacken Sie an einen Ort, der für den WebServer erreichbar ist. Danach können Sie, wie oben gesehen, mit einem entsprechenden Metadatum den Pfad zu den Schemas angeben:

 <code>
WEB
...
METADATA
...
"ows_schema_location" "/pfad/zu/den/schemas"
END
END
</code> 

Geben Sie keinen Pfad an, wird =..= als Ort für die Schemas angenommen. Der Gedanke hinter dieser Entscheidung war, dass man damit im Wurzelverzeichnis des Webservers landet, wenn man sein MapServer-Binary im Verzeichnis =cgi-bin/= hat\footnote{Eine sehr Apache-zentrierte Denkweise.}.

Der Präfix =ows_= zeigt übrigens an, dass hier auf mehr als nur WFS-Schemas verwiesen wird; vielmehr handelt es sich um einen Verweis auf Schemas, die sich auf ''OGC Web Services'' beziehen.

==Aufruf \& Capabilities==

Sobald man die ganze vorbereitende Arbeit hinter sich gebracht hat, kann man prüfen, ob alles korrekt eingerichtet worden ist. Dazu richtet man, wie schon beim WMS-konformen Server, eine Anfrage vom Typ =getCapabilities= an den Server:

 <code>
http://www.example.com/cgi-bin/mapserv
? SERVICE=WFS
& REQUEST=getCapabilities
& map=...
</code> 

Die Vorgehensweise entspricht jetzt haargenau dem, was Sie auch mit einem WMS-Server tun würden: Sie durchsuchen das Capabilites-Dokument nach Warnungen und Fehlern, und wenn sich alles so verhält, wie es geplant war, dann haben Sie einen einsatzfähigen, WFS-konformen Server.

==WFS Client==

Was man mit WMS machen kann, will man selbstverständlich auch mit WFS machen: Einbinden von WFS-Layern als eigene Kartenebenen. Die Vorgehensweise ist dabei stark an eben das Einfügen von WMS-Layern angelehnt.

FIXME: blah

Die Voraussetzungen für die Kompilierung eines WFS-konformen Client sind etwas umfänglicher als für den entsprechenden Server. Sieh auch Abschnitt [FIXME] im Anhang.

Ein WFS-Client-Layer ist sieht anders aus als ein 'normaler' Layer, hat aber Ähnlichkeit mit einem WMS-konformen Layer. Hier ein Beispiel:

 <code>
LAYER
END
</code> 

FIXME: vervollständigen!1!

=Map Context=

Diese Spezifikation ist eine Ergänzung zur WMS-Spezifikation. Sie beschreibt einen Mechanismus, mit dem Informationen über eine Menge von WMS-produzierten Layern auf eine portable Weise zwischen Systemen ausgetauscht bzw. in einem definierten Format gespeichert und abgerufen werden können.

Das Dokument, das diesen Standard definiert ist in der Version 1.0 von der OGC-Website herunterladbar~[[pdf:spec:mapcontext10]].

MapServer kann Kontextdokumente in den Versionen 0.1.2, 0.1.4, 0.1.7 und 1.0 lesen, und in den Versionen 0.1.4, 0.1.7 und 1.0 exportieren.

Kontextdokumente lassen sich im MapServer darüberhinaus nur in MapScript verwenden, und selbst dort nur in der PHP-Fassung. Alles andere wird (noch?) nicht unterstützt. Darüberhinaus geht Map Context davon aus, dass die WMS-Spezifikation 1.1.1 beachtet wird.

Notwendige Bibliotheken für die Map Context-Funktionalität sind die Projektionsbibliothek proj.4, GDAL/OGR im Zusammenspiel mit Xerces sowie PHP MapScript. Genaue Installationsanleitungen für diese Komponenten finden Sie im Anhang ab Seite~\pageref{text:installation}.

==Das Context-Dokument==

Der Inhalt eines Context-Dokuments (oder schlicht: eines Contexts) besteht im wesentlichen aus Angaben über die Quelle(n) der einzelnen Layer, die verwendeten Bounding Boxes, Projektionen und eventuell diverse Metadaten.

Wie bei praktisch allem, was mit dem OGC in Zusammenhang steht, ist der Context ein XML-Dokument. Beachten Sie, dass in einem Context-Dokument tatsächlich nur WMS-Layer gespeichert werden können.

FIXME: fertig!1!

==Den Kontext verwenden==

Dieser Abschnitt sollte sinnvoller eigentlich im Kapitel über PHP MapScript erscheinen; der Konsistenz halber ist er hierher gewandert. Denn wie bereits erwähnt, kann Map Context bisher nur im Zusammenspiel mit PHP-MapScript benutzt werden.

Wenn Sie ein Mapfile nach den obigen Vorgaben erstellt haben, können Sie testen, ob Sie alles richtig gemacht haben:

 <code>
<?php
dl ("php_mapscript40.so");
<math>map = ms_newMapObj ("mapfile.map");
</math>map -> saveMapContext ("mapfile_context.xml");
</code> 

Danach geht es nach dem bewährten Muster daran, in der fertigen XML-Datei nach Warnhinweisen zu suchen, die zeigen, dass Dinge fehlen oder Fehler vorliegen. Wenn das nicht mehr passiert, kann Ihr Mapfile als Quelle für einen Map Context dienen.

FIXME: fertig!1!

= Styled Layer Descriptor (SLD)=
* http://www.mapserver.org/ogc/sld.html

=Filter Encoding =
[[User:Astrid Emde]]
* http://www.mapserver.org/ogc/filter_encoding.html

= WCS =
* http://de.wikipedia.org/wiki/Web_Coverage_Service
* Informationen siehe http://www.mapserver.org/ogc/wcs_server.html
* Informationen siehe http://www.mapserver.org/ogc/wcs_format.html

= WMS Time=

* Informationen siehe http://www.mapserver.org/ogc/wms_time.html

= SOS=

* Informationen siehe http://www.mapserver.org/ogc/sos_server.html

== OWS Clients ==
=== Desktop GIS ===
=== WebGIS ===

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 3

2009-01-23T07:29:22Z

Wiki-Mikee63: /* getFeatureInfo */

[[User:Astrid Emde]] (SLD, WMC, Filter Encoding, OWS Clients) 
[[User:jtmapmedia | Jörg Thomsen]] (OGC-Konformität, Warum macht man das?, Wie macht man das? )

[[HBUMNMapServer_ger | '''Inhaltsverzeichnis''']]

= OGC-Konformität =
--[[User:Jtmapmedia|Jtmapmedia]] 13:52, 10 January 2009 (UTC)
(1)\index{OGC}

Das [http://www.opengeospatial.org/ Open Geospatial Consortium]~\cite{http:website:ogc}, kurz OGC, ist ein internationaler Zusammenschluß von '368 Unternehmen, Regierungsorganisationen und Universitäten' (Eigendarstellung auf der Website, die Zahl ändert sich beinahe wöchentlich). Ziel des OGC ist es, gemeinsame Standards (Protokolle, Formate etc.) für Austausch, Verarbeitung und Speicherung von Geodaten zu erarbeiten.

Die Standards, die uns bei der Erstellung von OGC-konformen MapServern im Internet interessieren können, sind vielfältig. Für den MapServer sind die folgenden Standards relevant bzw. implementiert:

* OGC Web Map Service Specification (WMS), für den Transfer von Rasterkarten und eventuelle Anfragen auf diese Daten,
* OGC Web Feature Service Specification (WFS), was das gleiche für Vektordaten und eventuelle Anfragen auf diese Daten ist.
* OGC Web Coverage Service Specification (WCS), regelt den Zugriff auf hochaufgelöste Rasterdaten wie Luft- und Satellitenbilder und deren Bereitstellung.
* OGC Sensor Observation Service (SOS), der den Austausch von Sensordaten, wie z.B. Wasserpegel oder Temperaturmessungen spezifiziert.
* Map Context Specification, ermöglicht das Speichern und Laden von WMS-Zuständen wie Zoomstufe, sichtbare Layer usw..

Darüber hinaus werfen wir auch noch einen raschen Blick auf

* OGC Filter Encoding (FE), damit können Geodaten, beispielsweise für Klassifizierungen, gefilter werden.
* OGC Styled Layer Descriptors (SLD), eine Spezifikation, die es ermöglicht die Kartengestaltung eines entfernten WMS zu beeinflussen.

Die Website des OGC ist unter~[[http:website:ogc]] zu erreichen. Zu allen genannten Diensten, und zu vielen weiteren, finden Sie dort auch die Spezifikationen als PDF-Dateien. Sehen Sie sie sich ruhig einmal an. Nachdem Sie die ersten 20 bis 30 Seiten überblättert haben, finden Sie vor dem Anhang die interessanten Informationen auf meist wenigen Seiten zusammengefasst.

=Warum macht man das?=
--[[User:Jtmapmedia|Jtmapmedia]] 13:56, 10 January 2009 (UTC)

Eine berechtigte Frage ist natürlich, warum man diese Funktionalität überhaupt haben wollen könnte. Die Antworten sind vielfältig. Hier einige Beispiele:

\subsubsection* {'''Kein Zugang zu den Originaldaten'''}

Die wenigsten Besitzer von Geodaten rücken diese umsonst, oder überhaupt heraus. Manche sind allerdings durchaus gewillt, Karten auszuliefern; ihre Originaldaten kommen dabei nicht an die Öffentlichkeit. Durch die Bereitstellung von Karten nach den Kriterien des WMS sind darüberhinaus nicht nur Sie, sondern auch andere in der Lage, Karten aus der 'schwierigen Quelle' zu beziehen. Die Existenz eines Standards kann also schon zur Verbreitung von Kartenmaterial beitragen.

\subsubsection*{'''Lastenverteilung'''}

Ähnlich wie bei Datenbankanbindungen -- siehe auch Kapitel~\ref{text:database} -- kann beispielweise ein WMS-konformes zur Verteilung von Rechenlast beitragen, indem einzelne Layer der Karte einfach auf verschiedene Rechner verteilt werden.

\subsubsection*{'''Herstellerunabhängigkeit'''}

Durch ein standardisiertes Kommunikationsprotokoll sind Sie in der Lage, sich den Hersteller Ihrer Software auszusuchen. Umgekehrt bedeutet das auch, dass Sie nicht auf die Software eines bestimmten Herstellers angewiesen sind, wenn beispielsweise auf einen WMS-konformen Server zugegriffen werden soll. Die Wahl der Software kann also eher an anderen Kriterien (z.B. dem Preis) ausgerichtet werden. Heutzutage gibt es eine große Zahl OGC-konformer Programme, die sich nahezu beliebig miteinander verknüpfen lassen, so kann eine als WMS konfigurierter UMN MapServer seine Karte problemlos an verschiedene Klienten sowohl im Browser (z.N. Mapbender, OpanLayers) als auch auf dem Desktop (z.B. Quantum GIS, gvSIG) ausliefern und einen wichtigen Teil zur Geodateninfrastruktur beitragen.

Auf der Website des OGC finden Sie eine Liste von Herstellern und Produkten~[[http:website:ogcnetwork:impl]] und eine Beschreibung, welche Standards in welcher Version von ihnen unterstützt werden.

\subsection*{'''Existenz von Evaluationskriterien'''}

Häufig steht man vor der Frage, welches Produkt man für einen besonderen Zweck einsetzen soll. Das richtige Vorgehen ist natürlich, sich klarzumachen, welche Eigenschaften und Möglichkeiten die Software bieten soll, und anhand einer daraus hervorgehenden Liste kann man dann verschiedene Produkte evaluieren.

Solch ein Evaluationsvorgang kann zeitlich und finanziell sehr aufwändig sein. Weithin anerkannte Standards helfen dabei, Entscheidungen anhand fertig vorliegender Kriterienkataloge zu treffen.

= Wie macht man das? =
--[[User:Jtmapmedia|Jtmapmedia]] 18:00, 10 January 2009 (UTC)

Eine UMN MapServer-Anwendung OGC-konform zu gestalten ist keine Hexerei, Sie benötigen nicht einmal eine Erweiterung und müssen auch nichts neu kompilieren - es sind lediglich einige Erweiterungen im Mapfile notwendig. Bevor wir uns aber wieder dem Mapfile zuwenden, ein paar Sätze das grundsätzliche Verständnis der Funktionsweise von OGC-Diensten fördern.

Der Aufruf eines WMS-Servers erfolgt ganz ähnlich dem Aufruf des UMN MapServers, nämlich über einen URL mit den gewünschten Parametern, Sie werden im Folgenden bemerken, dass auch andere Aufrufe, wie WFS oder WCS, dem gleichen Muster folgen. Die Benennung der Parameter, ihr Verhalten und ihre Wirkung unterscheiden sich jedoch mehr oder weniger stark von dem, was Sie bisher von ihrem MapServer gewohnt sind.

Schauen Sie sich einmal einen Aufruf für eine Karte als Beispiel an. Um die Generierung solcher URLs müssen Sie sich im Detail nicht kümmern; wenn Sie einen Server betreiben, dann sowieso nicht, weil der Aufrufende die URLs kennen muss, und nicht Sie; und wenn Sie MapServer als Client betreiben, dann müssen Sie zwar einige Angaben im Mapfile zwingend machen, aber alle dynamischen Parameter werden von MapServer aufgefüllt.

\subsubsection*{'''Hinweis'''} 
In der Version 4.x war MapServer sehr tolerant, einige würden sagen nicht voll OGC-konform, weil er nicht alle Aufrufparameter verlangte, die die Spezifikation vorschreibt. Wenn Sie beim Aufruf eines WMS ab UMN Version einen laut Spezifikation erforderlichen Parameter weglassen, wird das nun mit einer Fehlermeldung quittiert.

Nun aber ein Beispiel für einen WMS-konformen URL des MapServers:

FIXME: Beispielaufruf dem aktuellen OSM/Hamburg-Beispiel anpassen. 
<code>
http://www.example.com/cgi-bin/mapserv
? SERVICE=WMS
& VERSION=1.1.1
& REQUEST=GetMap
& FORMAT=image/png
& LAYERS=gruenflaechen,fluesse,bebauung
& SRS=EPSG:4326
& BBOX=5.0,45.0,15.0,55.0
& WIDTH=500
& HEIGHT=500
& STYLES,,,
#hier enden die Pflichtparameter, Auftritt zweier optionaler Parameter:
& TRANSPARENT=TRUE
& EXCEPTIONS=application/vnd.ogc.se_inimage
</code> 

Sie werden sich jetzt fragen, wo denn der Hinweis auf das Mapfile geblieben ist, den Sie bisher immer mit angeben mussten. Ein Parameter ''map'' ist in der WMS-Spezifikation allerdings nirgends erwähnt. Wie man sich dieses Parameters entledigen kann, erfahren Sie weiter unten auf Seite~\pageref{text:wms:mapfilename}.

Der erste Parameter ''SERVICE'' gibt an, welche Spezifikation genutzt werden soll. Wir möchten eine Karte im PNG-Format abrufen, die im Browser angezeigt werden soll, also benutzen wir den Web Map Service.

Als nächstes wird mit ''VERSION'' angegeben, in welcher WMS-Version man die Kommunikation wünscht. Laut Spezifikation soll dabei im Hintergrund eine Aushandlung der Version stattfinden, falls eine Seite eine angegebene Version nicht kennt; Client und Server handeln sich dann gegenseitig herunter, bis sie auf eine Version treffen, die sie beide verstehen.

Der Parameter ''REQUEST'' gibt die Art der Anfrage an. Die in MapServer implementierten Modi sind bereits weiter oben in Abschnitt~2 genannt worden. Beachten Sie, dass die Schreibweise von ''GetMap'' bezüglich der Klein- und Großbuchstaben irrelevant sein sollte. Das gleiche gilt auch für die Namen der Parameter wie ''VERSION'', ''REQUEST'' und so weiter. Die Großschreibung erfolgt hier nur wegen der besseren Lesbarkeit. Es gibt aber auch Dienste, die diese Schreibweise ewarten.

Die Angabe ''FORMAT'' wird als sogenannter ''MIME type'' gemacht, eine standardisierte Notation für die Art von über das Netz geschickten Daten. Bildformat folgen prinzipiell dem Muster ''image/'' plus angehängtem Namen des Bildformats, also zum Beispiel ''image/jpeg'' für JPEG-Bilder. Mehr über MIME-Typen inklusive Links zu den diversen zuständigen RFCs finden Sie auf~[[http:homepage:mime]].

Es folgen die Layer, die angezeigt werden sollen. Anders als beim 'klassischen' MapServer, wo die Layernamen einzeln jeweils mit ''layer'' notiert werden, wird bei WMS-konformen Servern eine Liste der gewünschten Layer benötigt, wobei die einzelnen Layer durch Kommata voneinander getrennt werden. Dabei ist die Reihenfolge wichtig: der zuerst genannte Layer wird als erste Ebene in die Karte gezeichnet, liegt also zuunterst. Die im Mapfile festgelegte Reihenfolge spielt keine Rolle mehr.

Mit ''SRS'' wird das ''spatial reference system'' definiert, also die gewünschte Projektion angegeben. WMS verlangt EPSG-Codes für die Notierung der Projektion, wobei das Schlüsselwort ''EPSG'' und die dazugehörige Zahl durch einen Doppelpunkt voneinander getrennt werden. Mehr zu diesem Thema, das oft zu schwer identifizierbaren Fehlern führt und einige Nerven kosten kann, finden Sie im Anhang FIXME: Verweis auf den noch zu erstellenden Anhang.

''BBOX'': Ähnlich wie die anzuzeigenden Kartenebenen werden auch die gewünschten Extents durch mehrere Werte angefordert, die in einer Liste durch Kommata voneinander getrennt sind. Achten Sie immer darauf, dass die Werte der BBOX mit dem SRS korrespondieren.

''WIDTH'' und ''HEIGHT'' geben die Größe in Pixeln vor, die die fertige Karte haben soll. Beachten Sie, dass diese Werte mit der BBOX korrelieren müssen; eine quadratische BBOX in Verbindung mit ungleicher Höhe und Breite führt zu einer Verzerrung des Kartenbildes.

Der Parameter ''STYLES'' gibt für jeden Layer eine Darstellungsoption an (sofern der Provider des Service dieses mit den sog. ''Named Styles'' vorbereitet hat). Sie müssen keine Styles angeben, der Parameter im GetMap-Aufruf ist jedoch Pflicht.

Mit ''TRANSPARENT'' wird die Hintergrundfarbe der Karte transparent geschaltet. Das will man offensichtlich dann haben, wenn man unter dieser Kartenebene noch andere Layer anzeigen möchte.

Schließlich und endlich wird dem WMS im obigen Beispiel mitgeteilt in welcher Form Fehlermeldungen ausgegeben werden, in unserem Fall soll die Fehlermeldung in resultierende Rasterbild gerendert werden. Wenn Sie eine XML-formatierte Fehlermeldung bevorzugen verwenden Sie ''application/vnd.ogc.se_xml''.

Das Ergebnis dieses Aufrufes ist also eine 500 mal 500 Pixel große, auf EPSG-Code FIXME: 4326 projizierte Karte im PNG-Format mit den angegebenen Extents und transparentem Hintergrund. Der aufrufende URL dieser Karte kann entweder so bei Ihnen im Webbrowser erscheinen, oder aber von MapServer dynamisch für die Anzeige als Rasterlayer generiert worden sein.

Als nächstes schauen wir uns an, wie aus einem bestehenden Mapfile eines gemacht werden kann, das für WMS-konformes Verhalten nach außen sorgt.

=Web Map Service (WMS)=
==UMN als WMS Server==

Von besonderem Interesse ist die ''OpenGIS Web Map Server Interfaces Implementation Specification'' , im folgenden kurz WMS-Standard genannt. Diese Spezifikation liegt inzwischen in der Version 1.1.1~[[pdf:spec:ogc111]] vor. MapServer unterstützt aber auch die zurückliegenden Standards 1.0.0~[[pdf:spec:ogc100]] und 1.1.0~[[pdf:spec:ogc110]].

Sinn der WMS-Spezifikation ist es, ein offenes, definiertes Interface sowohl für Clients als auch für Server zur Verfügung zu stellen, die Karten und Daten über diese Karten miteinander austauschen wollen. Zur Kommunikation zwischen den Servern und Clients wird das HTTP-Protokoll verwendet. Über das Protokoll werden Daten im XML-Format übertragen\footnote{Für Exceptions sind auch andere Formate möglich.}. Parsen und weiterverarbeiten läßt sich XML in fast jeder bekannten Programmiersprache. Auf diese Weise ist man nicht an Webapplikationen gebunden, wenn man ein Programm entwickeln möchte, das mit einem WMS-Mapserver 'redet'. Die dazugehörige DTD\footnote{Die sogenannten ''document type definitions'' dienen der Validierung von Dokumenten. Sie können ein DTD also benutzen, um zu testen, um ein Dokument einem bestimmten Rahmen an Vorgaben genügt.} ist vom OGC zu beziehen und in der Spezifikation beschrieben. Gedruckt lernen Sie mehr über XML durch die Lektüre von~[[ray:2001:xml]], online finden Sie die Spezifikationen unter~[[http:homepage:xml]].

\subsubsection*{Hinweis}

Eine zentrale Rolle bei der Verwendung von WMS spielt die Umprojizierung von Daten. Da bei WMS Rasterdaten zum Einsatz kommen\footnote{Die Datenquelle für den Server kann natürlich ein Vektorformat haben. Produziert werden aber ausschließlich Rasterdaten, wie wir es bisher immer beim MapServer gesehen haben.}, und MapServer Rasterdaten ausschließlich unter Zuhilfenahme der Bibliothek GDAL umprojizieren kann, sollten Sie MapServer mit der Unterstützung für GDAL kompiliert haben.

==Servermodi==(2)

Die genannten Spezifikation in ihrer letzten Version verlangt: es ''müssen'' zwei Arten von Anfragen implementiert sein, zwei weitere sind optional und ''können'' implementiert sein. Die beiden folgenden Anfragen (weiterhin auch ''Requests'' genannt) müssen vorhanden sein:

*=getCapabilities= : Diese Anfrage muss ein XML-Dokument zurückliefern, das die Fähigkeiten des Mapservers beschreibt.
*=getMap= : Auf diese Anfrage wird eine Karte als Rasterbild zurückgeliefert.

Entsprechend der Anforderung sind diese beiden Anfragen auch im MapServer implementiert.

Die beiden Fähigkeiten, die implementiert sein ''können'' , sind:

*=getFeatureInfo= : auf diese Anfrage liefert der Mapserver Informationen über einen bestimmten Punkt in einer Karte zurück. Diese Informationen können entweder in einer reinen Textdarstellung oder in GML (einem XML-Format) zurückgegeben werden.
*=describeLayer= liefert ein XML-Dokument mit detaillierten Informationen über einen Layer zurück. Dieser Modus wäre für einen SLD\footnote{Styled Layer Descriptor}-konformen MapServer interessant, aber dieser Standard hat bisher noch keine Umsetzung im MapServer erfahren.

Das einzige Feature, das im MapServer zurzeit nicht implementiert ist, ist demnach =describeLayer= . Es gibt noch einige andere Modi; mehr dazu in Abschnitt~7

==WMS-Metadaten im Mapfile==\index{Metadaten}

Zuallererst benötigt ihr Mapfile einen Namen. Im Header muß also der Parameter =NAME= definiert sein.

Einen 'minimalen' WMS-Server erhalten Sie zum einen durch Metadaten in der =WEB= -Sektion des Mapfiles, zum anderen durch Metadaten in den einzelnen Layern. Einige davon sind zwingend erforderlich, andere optional. Wie die Notation von Metadaten im Mapfile generell erfolgt, haben Sie bereits in Abschnitt~\ref{text:mapfile:web:meta} erfahren.

 <code>
WEB
...
METADATA
"wms_title" "Ein WMS-Server"
"wms_onlineresource" \
"http://www.example.com/cgi-bin/mapserv?map=mapfile.map&"
"wms_srs" "EPSG:31464 EPSG:4326"
END
END
</code> 

Der =wms_title= ist der Titel für die Karte, dieser muß angegeben werden. Der zweite Parameter gibt an, unter welchem URL der Server aufzurufen ist.

Beachten Sie dabei, das =\&= anzugeben, bzw. ein Fragezeichen, wenn Sie nach dem eigentlichen CGI-Programm keinen Parameter zu stehen haben.

=wms_srs= steht für die Projektion, in der die Karten angeboten werden können. Die Spezifikation schreibt vor, dass hier immer mindestens EPSG-Code 4326 angeboten werden muß. Mehrere Projektionen werden einfach durch Leerzeichen voneinander getrennt. Mehr zu EPSG und Projektionen im allgemeinen haben Sie schon in Abschnitt~\ref{text:map:projections} erfahren.

Sie benötigen =wms_srs= nicht, wenn Sie für die Karte einen Projektionsblock mit EPSG-Angabe definiert haben; die =WEB= -Sektion 'erbt' dann diese Projektion als Vorgabe.

Was machen Sie, wenn Ihre Daten allesamt in einer Projektion vorliegen, für die es keinen EPSG-Code gibt? Dann können Sie einen =PROJECTION= -Block definieren, der Parameter für die Projektionsbibliothek ''proj.4'' enthält (das Beispiel stammt direkt aus der MapServer-Dokumentation):

 <code>
PROJECTION
"proj=lcc"
"ellps=GRS80"
"lat_0=49"
"lon_0=-95"
"lat_1=49"
"lat_2=77"
END
</code> 

Wenn Sie nun EPSG-Codes in =wms_srs= nach außen anbieten, werden die Daten automatisch umprojiziert.

\subsubsection*{Notwendige Metadaten in den Layern}

Des weiteren müssen nun in jedem Layer zusätzliche Angaben nach folgendem Muster gemacht werden:

 <code>
LAYER
NAME "einlayer"
...
METADATA
"wms_title" "Titel fuer den Layer"
"wms_srs" "EPSG:31494"
END
END
</code> 

Daneben muß auch in jedem Layer ein Name gesetzt und eine Projektion definiert sein. Als Standardvorgabe erbt jeder Layer die Projektionen aus der =WEB= -Sektion, sodass sie nicht noch einmal neu notiert werden müssen.

Sie benötigen natürlich immer noch eine Projektionsangabe im Layer in Form eines =PROJECTION= -Blocks, um zu definieren, in welcher Projektion die Datenquelle vorliegt, damit MapServer im Zweifelsfall korrekt projizieren kann. Das gilt natürlich insbesondere dann, wenn Sie mehr als nur eine Projektion anbieten wollen.

MapServer geht im übrigen davon aus, dass sie tatsächlich alle Layer im Mapfile nach außen zur Verfügung stellen wollen. Layer, die sie ''nicht'' nach außen geben wollen, haben also in diesem Mapfile nichts verloren. Es gibt bisher keinen Mechanismus, mit dem man einzelne Layer (oder alle) in einem Mapfile von der Auslieferung per WMS ausschließen kann.

\subsubsection*{Metadaten in der Web-Sektion}

Im folgenden sind alle Metadaten beschrieben, die Sie für einen WMS-konformen Server in der =WEB= -Sektion des Mapfiles notieren können. Alle Angaben sind optional, falls nicht anders angegeben.

*=wms_abstract= Eine elaborierte Zusammenfassung dessen, was der Server soll und ist.
*=wms_accessconstraints= Gibt Zugangsbeschränkungen für den MapServer an. Beachten Sie bitte, dass ein Eintrag hier lediglich eine Absichtserklärung ist. Ein Text wie 'Dieser Server darf nur im Intranet unserer Firma verwendet werden' ist natürlich schön und gut, aber die entsprechenden Zugriffsbeschränkungen sind selbtsverständlich nur durch die entsprechende Konfiguration der Systeme zu erreichen.
*=wms_addresstype= Art der Adresse. Für dieses und die folgenden fünf Felder gilt, dass bei Angabe eines der Felder auch die anderen fünf mit Inhalt gefüllt werden müssen.
*=wms_address= Die Adresse.
*=wms_city= Adressbestandteil: Stadt
*=wms_country= Adressbestandteil: Land
*=wms_postcode= Adressbestandteil: Postleitzahl
*=wms_stateorprovince= Adressbestandteil: Staat oder Provinz
*=wms_contactelectronicmailaddress= Emailadresse einer Kontaktperson für diesen Server
*=wms_contactoraganization= Organisation der Kontaktperson
*=wms_contactperson= Name der Kontaktperson für diesen Server
*=wms_contactposition= Position der Kontaktperson innerhalb ihrer Organisation
*=wms_contactvoicetelephone= Telefonnummer der Kontaktperson
*=wms_fees= Art und Umfang der Gebühren, die für die Nutzung dieses Servers fällig werden. Genau wie bei =wms_accessconstraints= ist dies lediglich eine Absichtserklärung; wenn Sie Gebühren für die Verwendung des Servers erheben möchten, müssen Sie die Zugriffskontrolle durch eine geeignete Systemkonfiguration und ein passendes Geschäftsmodell herbeiführen.
*=wms_keywordlist= Eine Liste von Schlüsselworten, die auf den Server zutreffen. Dieser Parameter ist mit dem Blick darauf geschaffen worden, dass es eines Tages in einer eigens dafür geschaffenen Datenbank eine Sammlung von Capabilities-Dokumenten geben könnte, die dann die Schlüsselwortlisten durchsuchen kann. Bisher gibt es keine solche Datenbank. Es sind auch keine Standardschlüsselwörter definiert.
*=wms_onlineresource= Der URL, mit dem der Server aufgerufen wird. Beinhaltet beim UMN MapServer meistens: <code> http://www.example.com/cgi-bin/mapserv? </code> und gegebenenfalls daran angehängt noch das Mapfile. Wenn ein Mapfile über =map== angehangen wird, darf nicht das abschließende =\&= vergessen werden! Dieser Parameter ist zwingend notwendig.
*=wms_resx= Horizontale Auflösung der Karte in Pixeln.
*=wms_resy= Vertikale Auflösung der Karte in Pixeln.
*=wms_srs= Projektion(en), in der die Karte angeboten werden kann. Dieser Parameter mit mindestens einer Projektion ist zwingend notwendig.
*=wms_title= Titel der Karte. Dieser Parameter ist zwingend notwendig.

\subsubsection*{Metadaten in den einzelnen Layern}

Im folgenden die Metadaten, die Sie für einen WMS-konformen MapServer in den einzelnen Layern im Mapfile definieren können. Alle Parameter sind optional, sofern nicht anders angegeben.

*=wms_abstract= Elaborierte Zusammenfassung dessen, was dieser Layer soll und ist.
*=wms_extent= Die Bounding Box des Layers.
*=wms_keywordlist= Eine Liste von Schlüsselworten, die auf diesen Server zutreffen. %
*=wms_opaque= FIXME: was ist das?
*=wms_srs= Projektion(en), in der die Karte angeboten werden kann.
*=wms_title= Titel des Layers. Dieser Parameter ist zwingend erforderlich.

\subsubsection*{Das Mapfile als Parameter}(4)

Der Name des Mapfiles in der URL-Zeile ist nicht Bestandteil eines OGC-konformen Aufrufs des Mapservers. Unter Sicherheitsaspekten kann es darüber hinaus eventuell nicht angebracht sein, dem Client etwas über die Verzeichnisstruktur des Server-Systems zu verraten.

Im Moment gibt es zwei verschiedene Wege, den Ort des Mapfiles vor Außenstehenden zu verbergen:

*''Verwenden eines Wrapper-Skripts'' : Anstatt des CGI-Binaries wird ein kleines Skript aufgerufen, das die Umgebungsvariable = MS_MAPFILE = setzt und dann seinerseits das CGI-Programm aufruft. Ganz primitiv könnte ein solches Skript für die Shell =bash= etwa wie folgt aussehen: <code> #!/bin/sh MS_MAPFILE=/usr/local/there/is/my.map export MS_MAPFILE /usr/local/httpd/cgi-bin/mapserv </code> Beachten Sie bitte, dass dieses Beispiel nur für Unix-Systeme funktioniert, auf denen die Shell =bash= installiert ist. Für andere Shells kann die Notation abweichen.
*''Webserver-Konfiguration'' : Der Webserver ist unter Umständen in der Lage, für bestimmte aufgerufene URLs spezifische Umgebungsvariablen zu setzen. Im Apache sähe ein Eintrag in der Datei ''httpd.conf'' dann beispielsweise folgendermaßen aus (wegen der Zeilenlänge für das Drucklayout umgebrochen, muß in der Konfigurationsdatei eine Zeile sein): <code> SetEnvIf Request_URI "/cgi-bin/mapserv" \ MS_MAPFILE=/usr/local/there/is/my.map </code> Dieser Eintrag funktioniert nur im Apache und kann für andere Webserver vollkommen anders aussehen. Konsultieren Sie Ihre Dokumentation.

\subsubsection*{getCapabilities}(5)

Nachdem man zufrieden mit seinem Setup ist, möchte man es natürlich ausprobieren. Dazu ruft man als erstes das ''Capabilities'' -Dokument ab:

 <code>
http://server/cgi-bin/mapserv?VERSION=1.1.0&REQUEST=getCapabilities \
&map=mapfile.map
</code> 

Dabei müssen Sie bei =getCapabilities= nicht auf Groß- oder Kleinbuchstaben achten. Ebensowenig bei allen anderen Parametern, die vor einem Gleichheitszeichen stehen.

Der Webserver sollte Ihnen nun eine Datei des Typs =application/vnd.ogc.wms_xml= zurückliefern. Diese Textdatei können Sie abspeichern und in einem beliebigen Texteditor öffnen. Eventuell ist Ihr Webbrowser auch von sich aus in der Lage, XML-Dateien automatisch in einem ansprechenden Layout darzustellen.

Schauen Sie sich nun den Inhalt der Datei genau an. Wo immer Sie auf Zeilen treffen, die

 <code>

</code> 

beinhalten, gilt es, etwas zu bereinigen. Beispielsweise erfahren Sie aus einer Warnung wie dieser:

 <code>

</code> 

dass Sie einen Meta-Tag für den Titel der entsprechenden Sektion vergessen haben.

Sobald Sie keine Warnungen dieser Art mehr in Ihrem Capabilities-Dokument finden, ist ihr MapServer WMS-konform und voll einsatzbereit.

\subsubsection*{getMap}

Wenn die Capabilities wie erwartet geliefert werden, ist der nächste logische Schritt natürlich, sich eine Karte von Hand abzuholen. Dafür konstruieren Sie sich in Ihrem Webbrowser einen Aufruf, der etwa so aussieht, wie das Beispiel in Abschnitt~3. Dabei machen Sie sich dann auch gleich mit der Benennung der Parameter vertraut.

Das beste was Ihnen passieren kann, ist natürlich, dass Sie gleich ihre gewünschte Karte bekommen. Dann sind Sie natürlich fertig. Sobald Sie jedoch Ihren ersten Fehler machen, müssen Sie sich mit Fehlermeldungen auseinandersetzen, den so genannten Exceptions.

==Exceptions==\index{Exceptions}\index{WMS!Exceptions}

Exceptions sind Meldungen, die von einem WMS-konformen Mapserver im Fehlerfall ausgegeben werden müssen. Das entspricht in etwa dem Expcetions-Konzept diverser Programmiersprachen wie z.B. Java. Der Sinn ist es, dem aufrufenden Client -- sei es nun eine menschliche Person, sei es eine Software -- anhand des Typs und des Inhalts der Fehlermeldung eine Entscheidung über das weitere Vorgehen treffen zu können. Eine solche Art der Fehlerbehandlung verhindert natürlich unter anderem, dass ein Programm seine Durchführung im Fehlerfall einfach beendet.

Wenn Sie bei einem WMS-konformen Aufruf einen Fehler machen, indem Sie beispielsweise einen Parameternamen wie =REQUEST= absichtlich falsch schreiben, wird Ihnen MapServer eine Datei in einem XML-Format zurückliefern:

*=application/vnd.ogc.se_xml= Ein WMS-konformer Mapserver muß mindestens diese Art der Vermittlung von Exceptions beherrschen. Solch eine Datei kann beispielsweise folgenden Inhalt haben: <code> <?xml version='1.0' encoding="ISO-8859-1" standalone="no" ?> <!DOCTYPE ServiceExceptionReport SYSTEM "http://www.digitalearth.gov/wmt/xml/exception_1_1_0.dtd"> <ServiceExceptionReport version="1.1.0"> <ServiceException> msWMSDispatch(): WMS server error. Incomplete WMS request: REQUEST parameter missing </ServiceException> </ServiceExceptionReport> </code> 

\begin{figure}
\begin{center}
\mmfig{0.6}{wms-exception-inimage}{Exception vom Typ application/vnd.ogc.se_inimage.}
\end{center}
\end{figure}

Des weiteren kann ein Mapserver Exceptions in den folgenden MIME-Typen zur Verfügung stellen:

*=application/vnd.ogc.se_inimage= Die Exception wird als Text in das auszuliefernde Bild eingefügt.
*=application/vnd.ogc.se_blank= Die Spezifikation geht von der Idee, dass ein leeres Bild etwas ist, dass man grundsätzlich nicht haben möchte, und somit nie bekommt. Daher kann ein 'leeres' Bild als Fehlermeldung angesehen werden. Als 'leeres' Bild ist ein Bild definiert, das ganz mit der Hintergrundfarbe der Karte ausgefüllt ist.

Im URL des Aufrufs wird die gewünschte Art der Exception mit dem Parameter =EXCEPTIONS= notiert. Wollen Sie Exceptions also im Bild notiert haben, schreiben Sie in Ihrem URL:

 <code>
... & EXCEPTIONS=application/vnd.ogc.se_inimage & ...
</code> 

Beachten Sie bitte, dass nur die XML-Variante implementiert sein muß. Wenn Sie von einem Server Exceptions im Bild verlangen, er aber nur XML kann, dann wird er XML liefern.

Beachten Sie außerdem, dass das Handling von Exceptions insbesondere bei Kaskaden von WMS-konformen Servern eine Rolle spielt. So kann es Ihnen passieren, dass Sie sich einen Layer von einem Server holen, der sich wiederum sein Bild von anderen entfernten Quellen heranholt, und von dort im Fehlerfall eine Exception in das Bild eingetragen bekommt. Dadurch haben Sie die Fehlermeldung dann natürlich auch im Bild zu stehen.

===Hinweis===

Viele Kartenanbieter tendieren dazu, ihre fertigen Karten mit Schriftzügen, Logos, Nordpfeilen, Wasserzeichen und so weiter auszustatten. Denken Sie immer daran, dass der Kunde, der Ihren Service wiederum als Datenquelle benutzt, eventuell auf die Idee kommt, die von Ihnen bezogene Karte umzuprojizieren! Das kann dann zu interessanten Effekten führen, wenn dann Dritte den Schriftzug mit der URL Ihrer Firmenwebsite quer über die ganze Karte gekrakelt bekommen. Entwickeln Sie im Vorhinein zusammen mit den Benutzern des Service ein Konzept, dass solche häßlichen Effekte verhindert.

==getFeatureInfo==

Sich Karten einfach nur anzusehen, ist selbstverständlich nur die Hälfte des Reizes eines WMS-konformen Servers. Man möchte selbstverständlich auch Queries auf die Daten durchführen können. Zu diesem Zweck gibt es den =REQUEST= mit dem Namen =getFeatureInfo= .

Zuerst einmal gilt es, Queries überhaupt erst einmal zuzulassen. Wie schon bei den 'klassischen' Queries (siehe Abschnitt~\ref{text:mapfile:queries}) kann man in MapServer eine Query nur auf einem Layer durchführen, der ein =TEMPLATE= definiert.

Wenn man das tut, und sich die ''capabilities'' anschaut, wird man für den Layer auf ein Attribut der folgenden Art treffen:

 <code>
<Layer queryable="1" opaque="0" cascaded="0">
</code> 

Der Wert =1= für =queryable= zeigt im Gegensatz zum Wert =0= an, dass Queries auf diesen Layer zulässig sind.

Um einen Aufruf vom Typ =getFeatureInfo= zu verstehen, betrachten wir einmal einen vollständigen URL für diesen Vorgang:

 <code>
http://www.example.com/cgi-bin/mapserv
? map=/usr/local/mapserv/mapfile.map
& VERSION=1.1.0
& REQUEST=getFeatureInfo
& QUERY_LAYERS=gruenflaechen
& SRS=EPSG:4326
& BBOX=5.0,45.0,15.0,55.0
& WIDTH=500
& HEIGHT=500
& X=250
& Y=250
& INFO_TYPE=text/plain
</code> 

Einige Bestandteile sind dem Leser bereits bekannt: Version des Standards, Angabe der Projektion durch =SRS= . Dazu kommt, wenig überraschend, die Angabe des =REQUEST= .

Da jetzt keine Darstellung mehr erfolgen sollen, werden keine =LAYERS= mehr angegeben, sondern =QUERY_LAYERS= \footnote{Diese Unterscheidung ist offensichtlich eigentlich unnötig, da man die Funktion der Layerangabe ja eigentlich serverseitig aus dem =REQUEST= schließen könnte.}. Um Ergebnisse zu liefern, muß jeder Layer in der Liste =QUERY_LAYERS= das Attribut =queryable= auf =1= gesetzt haben -- siehe oben.

Zwingend sind darüberhinaus die Angabe der Extents des Bildes, das man befragen möchte (angegeben mit =BBOX= ), Breite und Höhe des Bildes sowie die X- und die Y-Koordinate des Punktes im Bild, der sich der Aufmerksamkeit des Users erfreut, beispielsweise durch einen Mausklick. Beachten Sie, dass es sich dabei um Bildkoordinaten handelt, es handelt sich also um Pixelwerte. Der Koordinatenursprung eines Bildes ist links oben.

Am interessantesten ist natürlich der =INFO_TYPE= , der angibt, auf welche Weise die Queryergebnisse formatiert sein sollen. MapServer unterstützt die folgenden Formate:

*=text/plain= , das Standardformat, falls Sie nichts anderes angegeben haben;
*=text/html= , was ein wenig Vorbereitung erfordert, im wesentlichen aber wie Queries auf einem 'normalen' MapServer-CGI behandelt wird; und
*=application/vnd.ogc.gml= , GML, eine XML-Repräsentation für Geodaten.

Betrachten wir die Formate im Detail:

\subsubsection*{text/plain}

Dieser Ausgabetyp für getFeatureInfo ist die Voreinstellung für MapServer, falls Sie keinen anderen Ausgabentyp spezifizieren.

Für ein Mapfile mit den Voreinstellungen des Itasca-Demos und einem fiktiven Anklickpunkt mit den Koordinaten 200/200 sieht die Ausgabe folgendermaßen aus:

 <code>
GetFeatureInfo results:

Layer 'countyboundary'
Feature 26:
AREA = '7577272785.15393'
PERIMETER = '436617.07762'
CTY_NAME = 'Itasca'
COUN = '31'
CTY_ABBR = 'ITAS'
ISLAND = 'N'
CTY_FIPS = '61'
RECNO = '27'
</code> 

Es wird der Name des Layers ausgegeben, die Nummer des Layers innerhalb des Shapefiles, und dann alle Attribute aus der =.dbf= -Datei der Datei. Wenn es mehrere Suchergebnisse gegeben hat, werden diese der Reihe nach dargestellt.

\subsubsection*{text/html}

Mit diesem Ergebnistyp greift MapServer auf die HTML-Templates zurück, die Sie für Queries bereits in Kapitel~\ref{text:mapfile} kennengelernt haben. Das bedeutet, dass Sie ein HTML-Layout ganz nach Ihrem Geschmack gestalten können, und MapServer die entsprechenden Tags in eckigen Klammer wie gewohnt ersetzt.

Dieser ''MIME type'' bietet jedoch noch die Möglichkeit für zusätzliche Tricksereien. Der Standard schreibt nämlich keinen ''MIME type'' zwingend vor, und ebensowenig gibt es ein vorgeschriebenes Verhalten für den Fall, dass ein bestimmter Typ nicht unterstützt wird. Das führt dazu, dass MapServer es sich vorbehält, beliebige Arten von Daten zurückzuliefern.

Sie können ein =TEMPLATE= definieren, das nicht gezwungenermaßen eine HTML-Seite sein muß. Reiner ASCII-Text wäre ebenso möglich, oder alle anderen Formate, in denen Sie MapServer-Tags ersetzen können.

Sobald das Template beliebigen Formats von MapServer bearbeitet worden ist, kann das Resultat zurückgeliefert werden. Wenn man jetzt reinen ASCII-Text hat, würde MapServer ihn jedoch als =text/html= ausliefern, und das ist eigentlich nicht das, was man möchte. Der Client (also z.B. Webbrowser) interpretiert die Daten natürlich nur korrekt, wenn man ihm den korrekten MIME type liefert. Daher kann man im Mapfile für die zurückgegebenen Daten einen eigenen Metadatum den geeigneten Typ setzen:

 <code>
WEB
...
METADATA
...
"wms_feature_info_mime_type" "text/plain"
END
END
</code> 

Also noch einmal zusammenfassend: der Benutzer kann zwar von außen den =INFO_TYPE= auf =text/html= setzen; MapServer kann jedoch mit Daten beliebigen Typs antworten.

\subsubsection*{application/vnd.ogc.gml}

Damit ein Layer in diesem Format Anfragen beantworten kann, muß außerdem der Parameter =DUMP= in diesem Layer gesetzt sein:

 <code>
LAYER
...
DUMP TRUE
END
</code> 

Falls es keine Suchresultate gegeben hat, wird zwar eine Datei im korrekten Format zurückgegeben, die allerdings nur die korrekten Header enthält und ansonsten leer ist.

Für Suchergebnisse werden in diesem Format immer die Koordinaten des Features gleich mitgeliefert. Antworten können also bei großen Features nicht nur auf sich warten lassen, da MapServer für das Erzeugen großer Dokumente natürlich eine Weile braucht, sondern auch weil der Transfer über das Netz natürlich ein bißchen dauert.

Die Anfrage auf den Flughafen-Layer der Itasca-Demodaten beispielsweise liefert in den voreingestellten Extents und dem fiktiven Klick auf die Koordinate 224/75 das folgende Ergebnis:

 <code>
<?xml version="1.0" encoding="ISO-8859-1"?>

<msGMLOutput
xmlns:gml="http://www.opengis.net/gml"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance">
<countyboundary_layer>
<countyboundary_feature>
<AREA>7577272785.15393</AREA>
<PERIMETER>436617.07762</PERIMETER>
<CTY_NAME>Itasca</CTY_NAME>
<COUN>31</COUN>
<CTY_ABBR>ITAS</CTY_ABBR>
<ISLAND>N</ISLAND>
<CTY_FIPS>61</CTY_FIPS>
<RECNO>27</RECNO>
<gml:boundedBy>
<gml:Box srsName="EPSG:26915">
<gml:coordinates>
393234.393701,5207990.085063
495769.579719,5305374.105135
</gml:coordinates>
</gml:Box>
</gml:boundedBy>
<gml:Polygon srsName="EPSG:26915">
<gml:outerBoundaryIs>
<gml:LinearRing>
<gml:coordinates>
393865.671855,5300138.258409
393869.171975,5300138.258374
394516.694141,5300137.439369
395522.728579,5300136.241770
[...]
</code> 

Und so weiter, mit allen Punkten des Features.

==WMS Clients==\index{OGC!Client}(6)

WMS-konforme Mapserver lassen sich kaskadieren, indem einzelne Layer einfach als fertige Bilder von anderen WMS-konformen Mapservern bezogen werden. Durch die standardisierte Schnittstelle ist dafür kein UMN MapServer nötig. Sie können einzelne Layer beispielsweise auch von einem ESRI ArcIMS beziehen, wenn Sie möchten.

Neben der schönen Möglichkeit, die Standorte und somit Pflege einzelner Teile der Kartenerzeugung voneinander trennen zu können, indem man beispielsweise die Bodenproben von einem Amt und die hydrogeologischen Karten von einem anderen Amt miteinander über eine genormte Schnittstelle verbindet, ist ein weiteres offensichtliches Einsatzfeld natürlich die Lastenverteilung. Datenbestände, die erst umprojiziert werden müssen, können auf leistungsfähigere Server ausgelagert werden, während einfache Operationen wie beispielsweise die simple Darstellung von Rasterbildern von schwächeren Geräten übernommen werden kann\footnote{Beachten Sie dabei immer, dass zur Erzeugung des fertigen Bildes ''immer'' auf den langsamsten Layer gewartet werden muß, da ja das Bild ansonsten nicht komplett ist.}.

Im folgenden soll betrachtet werden, wie Sie einen Layer in einem Mapfile erstellen, damit er dynamisch Daten von einem WMS-konformen Server bezieht. Nach außen hin verhält sich dieser Layer dann wie jeder andere Rasterlayer auch.

\subsubsection*{Installation und Konfiguration}

Wie weiter hinten im Kapitel 'Installation' ab Seite~\pageref{text:installation} beschrieben, ist die Fähigkeit, als WMS-Client zu fungieren, nicht als Voreinstellung bei der Kompilierung gegeben, sondern muß explizit angefordert werden. Wie das genau gemacht wird, und welche Voraussetzungen gegeben sein müssen, ist in Abschnitt~\ref{text:installation:compile:wmsclient} erklärt.

\subsubsection*{getMap}

Der erste Schritt ist, sicherzustellen, dass der anzusprechende Server funktioniert und die gewünschten Daten ausliefert. Dafür holt man sich das Capabilites-Dokument dieses Servers. Wie das zu tun ist, ist auf Seite~\pageref{text:wms:getcapabilities} beschrieben.

Nun weiß man alles über die Fähigkeiten des Servers (welche Projektionen angeboten werden, wie seine Layer heißen und so weiter) und kann sich darum kümmern, eine erste Karte zu holen, um zu sehen, ob die Darstellung dem entspricht, was man erwartet. Dazu richtet man mit seinem Webbrowser eine =getMap= -Anfrage an den Server.

Wie so eine Anfrage aufgebaut sein muß, wurde bereits in Abschnitt~3 gezeigt. Ersetzen Sie allerdings alle Werte für die Parameter durch diejenigen, die Sie im abgerufenen Capabilities-Dokument gefunden haben, also durch korrekte Projektionen, Layernamen, Extents und so weiter. Sobald dieser Aufruf eine Karte in Ihrem Browser zaubert, wissen Sie, dass Sie gültige Werte besitzen und sie korrekt notiert haben, sodass Sie diese Angaben jetzt in einen Layer in Ihr Mapfile einbauen können.

\subsubsection*{Das Mapfile}

Zunächst benötigen Sie einen =PROJECTION= -Block für Ihre Karte. Sie können auf diesen Block verzichten, wenn alle Layer in der gleichen Projektion vorliegen und auch die von Ihnen angesprochenen WMS-Server nur diese eine Projektion unterstützen.

Beachten Sie, dass Sie in der =WEB= -Sektion Ihres Mapfiles einen =IMAGEPATH= -Parameter benötigen, da die Bilder von entfernten Servern als temporäre Dateien gespeichert werden müssen. Diese temporären Dateien werden übrigens nach Verwendung gleich wieder gelöscht, sodass Sie sie kaum bemerken werden.

Für WMS-konforme Anfragen an andere Server sind lediglich die Layerdefinitionen anzupassen. Dabei kommt ein =CONNECTIONTYPE= mit dem Namen =WMS= zum Einsatz:

 <code>
LAYER
NAME "Gewaesser"
TYPE RASTER
STATUS ON
CONNECTIONTYPE WMS
CONNECTION "http://www.example.com/cgi-bin/mapserv?"
METADATA
"wms_title" "Gewaesser"
"wms_server_version" "1.1.0"
"wms_srs" "EPSG:4326 EPSG:31464"
"wms_name" "seen,kanaele,fluesse,baeche"
"wms_format" "image/png"
END
PROJECTION
"init=epsg:31464"
END
END
</code> 

Wie Sie sehen, ist der URL selber sehr kurz gehalten. Er entspricht der ''onlineresource'' aus dem Capabilities-Dokument eines WMS-konformen Servers.

Alle weiteren Details zur Verbindung mit dem entfernten Server werden in Form von Metadaten gemacht. Wer bisher MapServer 3.6 eingesetzt hat, wird das noch anders kennen: in jener Version wurde noch der gesamte Verbindungsstring (bis auf die dynamischen Elemente) in der =CONNECTION= notiert.

Der =wms_title= ist der Titel für diesen Layer, der mit der Anfrage allerdings nichts zu schaffen hat.

Die Version der Anfrage wird mit =wms_server_version= notiert. Mit =wms_srs= geben Sie wieder Projektionen an, allerdings diejenigen, die von der Gegenstelle unterstützt werden.

=wms_name= benennt den oder die Layer, aus denen die bezogene Karte zusammengesetzt werden soll. Mehrere Layer werden durch Kommata voneinander abgetrennt. Beachten Sie, dass bei WMS die Reihenfolge der Ebenen von Belang ist: in unserem Beispiel werden zuerst der Layer =seen= gezeichnet, darauf dann =kanaele= und so weiter.

Das gewünschte Bildformat wird schließlich mit =wms_format= spezifiziert. Es gibt auch den Parameter =wms_formatlist= , der mehrere durch Kommata getrennte Angaben zuläßt.

''Wichtiger Hinweis'' : An keiner einzigen Stelle lädt sich MapServer die Capabilities des entfernten Servers herunter, um sich mit ihnen auseinanderzusetzen. Sie müssen also selber darauf achten, dass die von Ihnen gemachten Angaben stimmig sind.

==Exceptions==

Wenn Sie einen Layer haben, der sich Daten von einem WMS-konformen Server holt, drängt sich natürlich die Frage auf, wie MapServer im Fall von Exceptions reagiert. Eindeutige Antwort: das kommt drauf an.

Am einfachsten ist es offensichtlich, mit Exceptions, die direkt im Bild eingefügt sind, umzugehen, also mit denen, die vom Typ =application/vnd.ogc.se_inimage= sind. Diese werden einfach Bestandteil der fertigen Karte, die Sie im Webbrowser sehen. Im Fehlerfall bemerkt sehr schnell, was Sache ist.

Das gleiche gilt offensichtlich bei =application/vnd.ogc.se_blank= .

Liefert die Gegenstelle ein textbasiertes Format, also zum Beispiel GML zurück, dann gibt es ein Problem, da MapServer davon ausgeht, dass er Rasterdaten als Input erhält; demnach versucht er, das GML-Dokument als Text zu rendern, was natürlich schief geht und somit eine Fehlermeldung erzeugt.

Dieses Problem läßt sich bisher leider auch noch nicht umgehen. Das mindeste, was man also tun kann, ist für eine funktionierende Kommunikation mit dem Betreiber des Quellservers zu sorgen, damit dieser nicht einfach unangekündigt Layernamen ändert, die Ihnen Ihre Applikation wegbrechen lassen.

==Hinweise==(7)

FIXME: das auch noch bei WFS erwähnen

Wenn Sie mit der Administration sowohl des Mapservers, der als Client fungiert, als auch der Serverseite betraut sind, sollten Sie auf alle Fälle darauf achten, keine zirkulären Bezüge zu erzeugen, bei denen Server A einen Layer von Server B bezieht und dieser dann wieder Server A aufruft. Bei komplexen Installationen ist das durchaus eine Fehlerquelle, das Verhalten in diesem Fall ist undefiniert.

Ein weiterer wichtiger Faktor beim Einsatz von WMS-konformer Funktionalität ist die unschöne Tatsache, dass MapServer das Sammeln der Daten für einzelne Layer linear abarbeitet, und nicht mit einem einzelnen Thread oder Prozess pro Layer arbeitet. Das bedeutet, dass MapServer genau ''gar nichts'' tut, während er auf einen Layer aus dem Netzwerk wartet, um dann zum nächsten Layer überzugehen\ldots der dann vielleicht wieder ein solcher Layer ist, oder eine Datenbankquelle. Es wird also unnötig Rechenzeit vergeudet. Dieses Problem läßt sich im Moment auch leider nicht umgehen.

\subsubsection*{Weitere Modi für WMS}

Wer den Standard aufmerksam liest, wird noch vier weitere Operationsmodi finden, die in den einführenden Zeilen zu diesem Abschnitt nicht genannt worden sind. Sie umfassen:

*=describeLayer=
*=getLegendGraphic=
*=getStyles=
*=putStyles=

Diese Modi sind nur für Mapserver von Relevanz, die den OGC-Standard SLD unterstützen. Mit diesen ''styled layer descriptor'' ist es möglich, von außen Einfluß auf die ansonsten fixe Kartengestaltung eines Mapservers zu nehmen. Da dieser Standard serverseitig von MapServer bisher nicht unterstützt wird\footnote{Und clientseitig nur sehr sporadisch; konsultieren Sie hierzu bitte die Online-Dokumentation.}, findet hier keine detaillierte Beschreibung statt. Sie können sich aber selbstverständlich den Standard~[[pdf:spec:sld10]] lesen.

=Web Feature Server (WFS)=(8)

Die entsprechende Spezifikation des OGC~[[pdf:spec:wfs100]] sieht WFS im Kontext zu WMS. Nach der Formulierung in der Einführung des Dokuments ist WFS der 'nächste logische Schritt' nach WMS. Wo WMS die Möglichkeit bietet, Capabilities abzufragen Karten anzuzeigen und schließlich Anfragen bezüglich der Datengrundlage der Karten zu machen, stellt WFS ein Interface zur Verfügung, dass es dem Benutzer ermöglicht, Einfluß auf die Datengrundlage zu nehmen, indem Features in der Karte geändert und gelöscht, bzw. neue Features hinzugefügt werden können.

Das hört sich alles ziemlich gut an -- und doch muß der begeisterte Leser hier enttäuscht werden. MapServer ist bisher ausschließlich darauf ausgelegt, Daten aus Quellen wie der Festplatte oder einer Datenbank zu lesen und Karten zu produzieren. Von einer Unterstützung für Datenänderungen ist man im Moment noch sehr weit entfernt -- falls sie überhaupt kommen wird\footnote{Es besteht natürlich die Möglichkeit, dass Sie beispielsweise mit MapScript entsprechende Fähigkeiten in einer eigenen Applikation programmieren. Stellen Sie sich auf einigen Aufwand ein.}.

Was wir mit MapServer kriegen, ist allerdings zumindest die Möglichkeit, Vektorlayer über den Transportmechanismus von WFS als Server auszuliefern bzw. als Client zu beziehen. Das funktioniert nur mit Vektordaten, da sich Rasterdaten offensichtlich nicht in das XML-Format mit dem Namen GML verpacken lassen. Diese ''Geography Markup Language'' ist selbstverständlich ebenfalls in einer eigenen Implementation Specification definiert~[[pdf:spec:gml]].

Von den in der Spezifikation definierten Anfragetypen sind im MapServer die folgenden implementiert:

*=getCapabilities= , um ein Capabilities-Dokument abrufen zu können, wie man es bereits von WMS kennt.
*=describeFeature= liefert eine Beschreibung eines Features zurück.
*=getFeature= holt eine GML-Repräsentation eines Features.

==WFS Server==

Wie schon beim WMS-konformen Server, wird WFS in MapServer dadurch aktiviert, dass die notwendigen =METADATA= -Tags in das Mapfile eingefügt werden. Zuerst einmal müssen aber die folgenden Vorkehrungen getroffen werden:

*Zuerst muß MapServer natürlich mit WFS-Unterstützung kompiliert worden sein. Detaillierte Vorgaben dafür finden Sie in Anhang~\ref{anhang:compile}.
*Das Mapfile muß einen =NAME= haben, ebenso wie jeder einzelne Layer. Wie schon bei WMS geht MapServer bei WFS davon aus, dass jeder Layer, der sich im Mapfile befindet, auch über WFS zur Verfügung gestellt werden soll.

MapServer kann ausschließlich Vektorlayer in seinen WFS-Capabilites erscheinen lassen, also Shapefiles, PostGIS-Layer und so weiter; der Typ des Layers muß also =POINT= , =LINE= oder =POLYGON= sein.

Desweiteren muß die Eigenschaft =DUMP= im Layer auf =TRUE= gesetzt sein. Dies zeigt MapServer an, dass er GML-Repräsentationen für diesen Layer erzeugen darf. Das entspricht der Vorgabe, =getFeatureInfo= mit einem WMS-konformen Server nutzen zu können.

In der =WEB= -Sektion des Mapfiles müssen dann die folgenden Angaben gemacht werden.

*=wfs_onlineresource= Die Basisadresse des Servers. Hat denselben Aufbau wie der gleichnamige Parameter für WMS. Allerdings muß man einem WFS-konformen MapServer noch mitteilen, wie er WFS- von WMS- Anfragen zu unterscheiden hat. Das geschieht durch =SERVICE= , also etwa derart: <code> WEB .. METADATA ... "wfs_onlineresource" \ "http://www.example.com/cgi-bin/mapserv?SERVICE=WFS&map=..." END END </code> Diese Angabe ist auch dann nötig, wenn der MapServer nicht darauf eingerichtet oder konfiguriert ist, als WMS-Server zu fungieren.
*=wfs_title= Titel für die Karte; siehe WMS-Konformität. Zwingend notwendig.
*=wfs_abstract= Eine elaborierte Zusammenfassung über Sinn und Zweck dieses Servers. Siehe WMS-Konformität.
*=wfs_keywordlist= Eine Liste mit Schlüsselworten, die einen Bezug zu diesem WFS-Server haben. Siehe WMS-Konformität.
*=wfs_accessconstraints= Beschränkungen, die den Zugriff auf diesen Server betreffen. Siehe WMS-Konformität.
*=wfs_fees= Gebühren, die beim Zugriff auf diesen Server anfallen. Siehe WMS-Konformität.
*=wfs_encoding= Die Kodierung für die XML-Dateien, die durch den WFS-Server ausgeliefert werden. Voreingestellt ist hier ISO-8859-1.
*=ows_schema_location= Der Ort, an dem die OWS-Schemas zur Validierung der generierten XML-Dateien liegen. Siehe weiter unten auf Seite~\pageref{text:wfs:schemas}.
*=wfs_geometry_element_name= Weiter unten gibt es ein Beispiel zu sehen, wie eine Datei aussehen kann, die von einem WFS-konformen MapServer ausgeliefert wird. Das Element, dass die Liste der Koordinaten eines Features umfaßt, hat dabei keinen fixen Namen. Sie können mit diesem Parameter hier einen Namen festlegen; Voreinstellung in MapServer ist =MS_GEOMETRY= .
*=wfs_srs= Die Projektion, die für alle Layer in der Karte gelten soll. Wird als EPSG-Code angegeben und genauso wie bei WMS-konformen Servern notiert. Beachten Sie bitte die Anmerkungen zu Projektionen in WFS-konformen Servern im nächsten Abschnitt.

Beachten Sie, dass diese Parameter im Gegensatz zu den WMS-Parametern alle den Präfix =wfs_= tragen. Einzige Ausnahme ist =ows_schema_location= .

==Projektionen in WFS-Servern==

Die WFS-Spezifikation macht zu Projektionen andere Vorgaben als idie für WMS. So können einzelne Layer nicht in mehr als einer Projektion ausgeliefert werden. Es gibt auch keine Projektionsangabe, die man ein einziges Mal für alle Layer machen kann\footnote{Man kann aber, wie Sie weiter oben sehen konnten, MapServer so konfigurieren, dass er einen SRS-Eintrag in der WEB-Sektion bekommt und diesen dann auf alle Layer überträgt.}. Es ist aber sehr wohl möglich, für jeden Layer eine unterschiedliche Projektion anzubieten. Außerdem nennt der Standard keine Default-Projektion; anders als bei WMS, wo mindestens =EPSG:4326= angeboten werden muß.

MapServer entscheidet in zwei Schritten, welche Projektion für einen Layer nach außen mitgeteilt wird. Wenn es eine 'übergeordnete' Projektion gibt (also einen Projektionsblock mit EPSG-Code für die ganze Karte, bzw. ein =wfs_srs= in der WEB-Sektion), so findet diese Projektion auf alle Layer Anwendung, selbst dann, wenn die Layer selber noch einmal über =wfs_srs= eine Projektion definieren.

Gibt es keine solche 'Überprojektion', muß jeder Layer einen eigenen Wert setzen.

==Schemas==(9)

Schemas\footnote{In diesem Fall nicht Schemata, da es sich um einen feststehenden englischen Begriff handelt.} sind ein Mechanismus, XML-Dateien zu validieren, also zu prüfen, ob sie einem bestimmten Aufbau genügen. Sie können ein Paket standardkonformer Schemas von~[[http:owssamples]] herunterladen.

Das Archiv entpacken Sie an einen Ort, der für den WebServer erreichbar ist. Danach können Sie, wie oben gesehen, mit einem entsprechenden Metadatum den Pfad zu den Schemas angeben:

 <code>
WEB
...
METADATA
...
"ows_schema_location" "/pfad/zu/den/schemas"
END
END
</code> 

Geben Sie keinen Pfad an, wird =..= als Ort für die Schemas angenommen. Der Gedanke hinter dieser Entscheidung war, dass man damit im Wurzelverzeichnis des Webservers landet, wenn man sein MapServer-Binary im Verzeichnis =cgi-bin/= hat\footnote{Eine sehr Apache-zentrierte Denkweise.}.

Der Präfix =ows_= zeigt übrigens an, dass hier auf mehr als nur WFS-Schemas verwiesen wird; vielmehr handelt es sich um einen Verweis auf Schemas, die sich auf ''OGC Web Services'' beziehen.

==Aufruf \& Capabilities==

Sobald man die ganze vorbereitende Arbeit hinter sich gebracht hat, kann man prüfen, ob alles korrekt eingerichtet worden ist. Dazu richtet man, wie schon beim WMS-konformen Server, eine Anfrage vom Typ =getCapabilities= an den Server:

 <code>
http://www.example.com/cgi-bin/mapserv
? SERVICE=WFS
& REQUEST=getCapabilities
& map=...
</code> 

Die Vorgehensweise entspricht jetzt haargenau dem, was Sie auch mit einem WMS-Server tun würden: Sie durchsuchen das Capabilites-Dokument nach Warnungen und Fehlern, und wenn sich alles so verhält, wie es geplant war, dann haben Sie einen einsatzfähigen, WFS-konformen Server.

==WFS Client==

Was man mit WMS machen kann, will man selbstverständlich auch mit WFS machen: Einbinden von WFS-Layern als eigene Kartenebenen. Die Vorgehensweise ist dabei stark an eben das Einfügen von WMS-Layern angelehnt.

FIXME: blah

Die Voraussetzungen für die Kompilierung eines WFS-konformen Client sind etwas umfänglicher als für den entsprechenden Server. Sieh auch Abschnitt [FIXME] im Anhang.

Ein WFS-Client-Layer ist sieht anders aus als ein 'normaler' Layer, hat aber Ähnlichkeit mit einem WMS-konformen Layer. Hier ein Beispiel:

 <code>
LAYER
END
</code> 

FIXME: vervollständigen!1!

=Map Context=

Diese Spezifikation ist eine Ergänzung zur WMS-Spezifikation. Sie beschreibt einen Mechanismus, mit dem Informationen über eine Menge von WMS-produzierten Layern auf eine portable Weise zwischen Systemen ausgetauscht bzw. in einem definierten Format gespeichert und abgerufen werden können.

Das Dokument, das diesen Standard definiert ist in der Version 1.0 von der OGC-Website herunterladbar~[[pdf:spec:mapcontext10]].

MapServer kann Kontextdokumente in den Versionen 0.1.2, 0.1.4, 0.1.7 und 1.0 lesen, und in den Versionen 0.1.4, 0.1.7 und 1.0 exportieren.

Kontextdokumente lassen sich im MapServer darüberhinaus nur in MapScript verwenden, und selbst dort nur in der PHP-Fassung. Alles andere wird (noch?) nicht unterstützt. Darüberhinaus geht Map Context davon aus, dass die WMS-Spezifikation 1.1.1 beachtet wird.

Notwendige Bibliotheken für die Map Context-Funktionalität sind die Projektionsbibliothek proj.4, GDAL/OGR im Zusammenspiel mit Xerces sowie PHP MapScript. Genaue Installationsanleitungen für diese Komponenten finden Sie im Anhang ab Seite~\pageref{text:installation}.

==Das Context-Dokument==

Der Inhalt eines Context-Dokuments (oder schlicht: eines Contexts) besteht im wesentlichen aus Angaben über die Quelle(n) der einzelnen Layer, die verwendeten Bounding Boxes, Projektionen und eventuell diverse Metadaten.

Wie bei praktisch allem, was mit dem OGC in Zusammenhang steht, ist der Context ein XML-Dokument. Beachten Sie, dass in einem Context-Dokument tatsächlich nur WMS-Layer gespeichert werden können.

FIXME: fertig!1!

==Den Kontext verwenden==

Dieser Abschnitt sollte sinnvoller eigentlich im Kapitel über PHP MapScript erscheinen; der Konsistenz halber ist er hierher gewandert. Denn wie bereits erwähnt, kann Map Context bisher nur im Zusammenspiel mit PHP-MapScript benutzt werden.

Wenn Sie ein Mapfile nach den obigen Vorgaben erstellt haben, können Sie testen, ob Sie alles richtig gemacht haben:

 <code>
<?php
dl ("php_mapscript40.so");
<math>map = ms_newMapObj ("mapfile.map");
</math>map -> saveMapContext ("mapfile_context.xml");
</code> 

Danach geht es nach dem bewährten Muster daran, in der fertigen XML-Datei nach Warnhinweisen zu suchen, die zeigen, dass Dinge fehlen oder Fehler vorliegen. Wenn das nicht mehr passiert, kann Ihr Mapfile als Quelle für einen Map Context dienen.

FIXME: fertig!1!

= Styled Layer Descriptor (SLD)=
* http://www.mapserver.org/ogc/sld.html

=Filter Encoding =
[[User:Astrid Emde]]
* http://www.mapserver.org/ogc/filter_encoding.html

= WCS =
* http://de.wikipedia.org/wiki/Web_Coverage_Service
* Informationen siehe http://www.mapserver.org/ogc/wcs_server.html
* Informationen siehe http://www.mapserver.org/ogc/wcs_format.html

= WMS Time=

* Informationen siehe http://www.mapserver.org/ogc/wms_time.html

= SOS=

* Informationen siehe http://www.mapserver.org/ogc/sos_server.html

== OWS Clients ==
=== Desktop GIS ===
=== WebGIS ===

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 3

2009-01-23T07:28:07Z

Wiki-Mikee63: /* getFeatureInfo */

[[User:Astrid Emde]] (SLD, WMC, Filter Encoding, OWS Clients) 
[[User:jtmapmedia | Jörg Thomsen]] (OGC-Konformität, Warum macht man das?, Wie macht man das? )

[[HBUMNMapServer_ger | '''Inhaltsverzeichnis''']]

= OGC-Konformität =
--[[User:Jtmapmedia|Jtmapmedia]] 13:52, 10 January 2009 (UTC)
(1)\index{OGC}

Das [http://www.opengeospatial.org/ Open Geospatial Consortium]~\cite{http:website:ogc}, kurz OGC, ist ein internationaler Zusammenschluß von '368 Unternehmen, Regierungsorganisationen und Universitäten' (Eigendarstellung auf der Website, die Zahl ändert sich beinahe wöchentlich). Ziel des OGC ist es, gemeinsame Standards (Protokolle, Formate etc.) für Austausch, Verarbeitung und Speicherung von Geodaten zu erarbeiten.

Die Standards, die uns bei der Erstellung von OGC-konformen MapServern im Internet interessieren können, sind vielfältig. Für den MapServer sind die folgenden Standards relevant bzw. implementiert:

* OGC Web Map Service Specification (WMS), für den Transfer von Rasterkarten und eventuelle Anfragen auf diese Daten,
* OGC Web Feature Service Specification (WFS), was das gleiche für Vektordaten und eventuelle Anfragen auf diese Daten ist.
* OGC Web Coverage Service Specification (WCS), regelt den Zugriff auf hochaufgelöste Rasterdaten wie Luft- und Satellitenbilder und deren Bereitstellung.
* OGC Sensor Observation Service (SOS), der den Austausch von Sensordaten, wie z.B. Wasserpegel oder Temperaturmessungen spezifiziert.
* Map Context Specification, ermöglicht das Speichern und Laden von WMS-Zuständen wie Zoomstufe, sichtbare Layer usw..

Darüber hinaus werfen wir auch noch einen raschen Blick auf

* OGC Filter Encoding (FE), damit können Geodaten, beispielsweise für Klassifizierungen, gefilter werden.
* OGC Styled Layer Descriptors (SLD), eine Spezifikation, die es ermöglicht die Kartengestaltung eines entfernten WMS zu beeinflussen.

Die Website des OGC ist unter~[[http:website:ogc]] zu erreichen. Zu allen genannten Diensten, und zu vielen weiteren, finden Sie dort auch die Spezifikationen als PDF-Dateien. Sehen Sie sie sich ruhig einmal an. Nachdem Sie die ersten 20 bis 30 Seiten überblättert haben, finden Sie vor dem Anhang die interessanten Informationen auf meist wenigen Seiten zusammengefasst.

=Warum macht man das?=
--[[User:Jtmapmedia|Jtmapmedia]] 13:56, 10 January 2009 (UTC)

Eine berechtigte Frage ist natürlich, warum man diese Funktionalität überhaupt haben wollen könnte. Die Antworten sind vielfältig. Hier einige Beispiele:

\subsubsection* {'''Kein Zugang zu den Originaldaten'''}

Die wenigsten Besitzer von Geodaten rücken diese umsonst, oder überhaupt heraus. Manche sind allerdings durchaus gewillt, Karten auszuliefern; ihre Originaldaten kommen dabei nicht an die Öffentlichkeit. Durch die Bereitstellung von Karten nach den Kriterien des WMS sind darüberhinaus nicht nur Sie, sondern auch andere in der Lage, Karten aus der 'schwierigen Quelle' zu beziehen. Die Existenz eines Standards kann also schon zur Verbreitung von Kartenmaterial beitragen.

\subsubsection*{'''Lastenverteilung'''}

Ähnlich wie bei Datenbankanbindungen -- siehe auch Kapitel~\ref{text:database} -- kann beispielweise ein WMS-konformes zur Verteilung von Rechenlast beitragen, indem einzelne Layer der Karte einfach auf verschiedene Rechner verteilt werden.

\subsubsection*{'''Herstellerunabhängigkeit'''}

Durch ein standardisiertes Kommunikationsprotokoll sind Sie in der Lage, sich den Hersteller Ihrer Software auszusuchen. Umgekehrt bedeutet das auch, dass Sie nicht auf die Software eines bestimmten Herstellers angewiesen sind, wenn beispielsweise auf einen WMS-konformen Server zugegriffen werden soll. Die Wahl der Software kann also eher an anderen Kriterien (z.B. dem Preis) ausgerichtet werden. Heutzutage gibt es eine große Zahl OGC-konformer Programme, die sich nahezu beliebig miteinander verknüpfen lassen, so kann eine als WMS konfigurierter UMN MapServer seine Karte problemlos an verschiedene Klienten sowohl im Browser (z.N. Mapbender, OpanLayers) als auch auf dem Desktop (z.B. Quantum GIS, gvSIG) ausliefern und einen wichtigen Teil zur Geodateninfrastruktur beitragen.

Auf der Website des OGC finden Sie eine Liste von Herstellern und Produkten~[[http:website:ogcnetwork:impl]] und eine Beschreibung, welche Standards in welcher Version von ihnen unterstützt werden.

\subsection*{'''Existenz von Evaluationskriterien'''}

Häufig steht man vor der Frage, welches Produkt man für einen besonderen Zweck einsetzen soll. Das richtige Vorgehen ist natürlich, sich klarzumachen, welche Eigenschaften und Möglichkeiten die Software bieten soll, und anhand einer daraus hervorgehenden Liste kann man dann verschiedene Produkte evaluieren.

Solch ein Evaluationsvorgang kann zeitlich und finanziell sehr aufwändig sein. Weithin anerkannte Standards helfen dabei, Entscheidungen anhand fertig vorliegender Kriterienkataloge zu treffen.

= Wie macht man das? =
--[[User:Jtmapmedia|Jtmapmedia]] 18:00, 10 January 2009 (UTC)

Eine UMN MapServer-Anwendung OGC-konform zu gestalten ist keine Hexerei, Sie benötigen nicht einmal eine Erweiterung und müssen auch nichts neu kompilieren - es sind lediglich einige Erweiterungen im Mapfile notwendig. Bevor wir uns aber wieder dem Mapfile zuwenden, ein paar Sätze das grundsätzliche Verständnis der Funktionsweise von OGC-Diensten fördern.

Der Aufruf eines WMS-Servers erfolgt ganz ähnlich dem Aufruf des UMN MapServers, nämlich über einen URL mit den gewünschten Parametern, Sie werden im Folgenden bemerken, dass auch andere Aufrufe, wie WFS oder WCS, dem gleichen Muster folgen. Die Benennung der Parameter, ihr Verhalten und ihre Wirkung unterscheiden sich jedoch mehr oder weniger stark von dem, was Sie bisher von ihrem MapServer gewohnt sind.

Schauen Sie sich einmal einen Aufruf für eine Karte als Beispiel an. Um die Generierung solcher URLs müssen Sie sich im Detail nicht kümmern; wenn Sie einen Server betreiben, dann sowieso nicht, weil der Aufrufende die URLs kennen muss, und nicht Sie; und wenn Sie MapServer als Client betreiben, dann müssen Sie zwar einige Angaben im Mapfile zwingend machen, aber alle dynamischen Parameter werden von MapServer aufgefüllt.

\subsubsection*{'''Hinweis'''} 
In der Version 4.x war MapServer sehr tolerant, einige würden sagen nicht voll OGC-konform, weil er nicht alle Aufrufparameter verlangte, die die Spezifikation vorschreibt. Wenn Sie beim Aufruf eines WMS ab UMN Version einen laut Spezifikation erforderlichen Parameter weglassen, wird das nun mit einer Fehlermeldung quittiert.

Nun aber ein Beispiel für einen WMS-konformen URL des MapServers:

FIXME: Beispielaufruf dem aktuellen OSM/Hamburg-Beispiel anpassen. 
<code>
http://www.example.com/cgi-bin/mapserv
? SERVICE=WMS
& VERSION=1.1.1
& REQUEST=GetMap
& FORMAT=image/png
& LAYERS=gruenflaechen,fluesse,bebauung
& SRS=EPSG:4326
& BBOX=5.0,45.0,15.0,55.0
& WIDTH=500
& HEIGHT=500
& STYLES,,,
#hier enden die Pflichtparameter, Auftritt zweier optionaler Parameter:
& TRANSPARENT=TRUE
& EXCEPTIONS=application/vnd.ogc.se_inimage
</code> 

Sie werden sich jetzt fragen, wo denn der Hinweis auf das Mapfile geblieben ist, den Sie bisher immer mit angeben mussten. Ein Parameter ''map'' ist in der WMS-Spezifikation allerdings nirgends erwähnt. Wie man sich dieses Parameters entledigen kann, erfahren Sie weiter unten auf Seite~\pageref{text:wms:mapfilename}.

Der erste Parameter ''SERVICE'' gibt an, welche Spezifikation genutzt werden soll. Wir möchten eine Karte im PNG-Format abrufen, die im Browser angezeigt werden soll, also benutzen wir den Web Map Service.

Als nächstes wird mit ''VERSION'' angegeben, in welcher WMS-Version man die Kommunikation wünscht. Laut Spezifikation soll dabei im Hintergrund eine Aushandlung der Version stattfinden, falls eine Seite eine angegebene Version nicht kennt; Client und Server handeln sich dann gegenseitig herunter, bis sie auf eine Version treffen, die sie beide verstehen.

Der Parameter ''REQUEST'' gibt die Art der Anfrage an. Die in MapServer implementierten Modi sind bereits weiter oben in Abschnitt~2 genannt worden. Beachten Sie, dass die Schreibweise von ''GetMap'' bezüglich der Klein- und Großbuchstaben irrelevant sein sollte. Das gleiche gilt auch für die Namen der Parameter wie ''VERSION'', ''REQUEST'' und so weiter. Die Großschreibung erfolgt hier nur wegen der besseren Lesbarkeit. Es gibt aber auch Dienste, die diese Schreibweise ewarten.

Die Angabe ''FORMAT'' wird als sogenannter ''MIME type'' gemacht, eine standardisierte Notation für die Art von über das Netz geschickten Daten. Bildformat folgen prinzipiell dem Muster ''image/'' plus angehängtem Namen des Bildformats, also zum Beispiel ''image/jpeg'' für JPEG-Bilder. Mehr über MIME-Typen inklusive Links zu den diversen zuständigen RFCs finden Sie auf~[[http:homepage:mime]].

Es folgen die Layer, die angezeigt werden sollen. Anders als beim 'klassischen' MapServer, wo die Layernamen einzeln jeweils mit ''layer'' notiert werden, wird bei WMS-konformen Servern eine Liste der gewünschten Layer benötigt, wobei die einzelnen Layer durch Kommata voneinander getrennt werden. Dabei ist die Reihenfolge wichtig: der zuerst genannte Layer wird als erste Ebene in die Karte gezeichnet, liegt also zuunterst. Die im Mapfile festgelegte Reihenfolge spielt keine Rolle mehr.

Mit ''SRS'' wird das ''spatial reference system'' definiert, also die gewünschte Projektion angegeben. WMS verlangt EPSG-Codes für die Notierung der Projektion, wobei das Schlüsselwort ''EPSG'' und die dazugehörige Zahl durch einen Doppelpunkt voneinander getrennt werden. Mehr zu diesem Thema, das oft zu schwer identifizierbaren Fehlern führt und einige Nerven kosten kann, finden Sie im Anhang FIXME: Verweis auf den noch zu erstellenden Anhang.

''BBOX'': Ähnlich wie die anzuzeigenden Kartenebenen werden auch die gewünschten Extents durch mehrere Werte angefordert, die in einer Liste durch Kommata voneinander getrennt sind. Achten Sie immer darauf, dass die Werte der BBOX mit dem SRS korrespondieren.

''WIDTH'' und ''HEIGHT'' geben die Größe in Pixeln vor, die die fertige Karte haben soll. Beachten Sie, dass diese Werte mit der BBOX korrelieren müssen; eine quadratische BBOX in Verbindung mit ungleicher Höhe und Breite führt zu einer Verzerrung des Kartenbildes.

Der Parameter ''STYLES'' gibt für jeden Layer eine Darstellungsoption an (sofern der Provider des Service dieses mit den sog. ''Named Styles'' vorbereitet hat). Sie müssen keine Styles angeben, der Parameter im GetMap-Aufruf ist jedoch Pflicht.

Mit ''TRANSPARENT'' wird die Hintergrundfarbe der Karte transparent geschaltet. Das will man offensichtlich dann haben, wenn man unter dieser Kartenebene noch andere Layer anzeigen möchte.

Schließlich und endlich wird dem WMS im obigen Beispiel mitgeteilt in welcher Form Fehlermeldungen ausgegeben werden, in unserem Fall soll die Fehlermeldung in resultierende Rasterbild gerendert werden. Wenn Sie eine XML-formatierte Fehlermeldung bevorzugen verwenden Sie ''application/vnd.ogc.se_xml''.

Das Ergebnis dieses Aufrufes ist also eine 500 mal 500 Pixel große, auf EPSG-Code FIXME: 4326 projizierte Karte im PNG-Format mit den angegebenen Extents und transparentem Hintergrund. Der aufrufende URL dieser Karte kann entweder so bei Ihnen im Webbrowser erscheinen, oder aber von MapServer dynamisch für die Anzeige als Rasterlayer generiert worden sein.

Als nächstes schauen wir uns an, wie aus einem bestehenden Mapfile eines gemacht werden kann, das für WMS-konformes Verhalten nach außen sorgt.

=Web Map Service (WMS)=
==UMN als WMS Server==

Von besonderem Interesse ist die ''OpenGIS Web Map Server Interfaces Implementation Specification'' , im folgenden kurz WMS-Standard genannt. Diese Spezifikation liegt inzwischen in der Version 1.1.1~[[pdf:spec:ogc111]] vor. MapServer unterstützt aber auch die zurückliegenden Standards 1.0.0~[[pdf:spec:ogc100]] und 1.1.0~[[pdf:spec:ogc110]].

Sinn der WMS-Spezifikation ist es, ein offenes, definiertes Interface sowohl für Clients als auch für Server zur Verfügung zu stellen, die Karten und Daten über diese Karten miteinander austauschen wollen. Zur Kommunikation zwischen den Servern und Clients wird das HTTP-Protokoll verwendet. Über das Protokoll werden Daten im XML-Format übertragen\footnote{Für Exceptions sind auch andere Formate möglich.}. Parsen und weiterverarbeiten läßt sich XML in fast jeder bekannten Programmiersprache. Auf diese Weise ist man nicht an Webapplikationen gebunden, wenn man ein Programm entwickeln möchte, das mit einem WMS-Mapserver 'redet'. Die dazugehörige DTD\footnote{Die sogenannten ''document type definitions'' dienen der Validierung von Dokumenten. Sie können ein DTD also benutzen, um zu testen, um ein Dokument einem bestimmten Rahmen an Vorgaben genügt.} ist vom OGC zu beziehen und in der Spezifikation beschrieben. Gedruckt lernen Sie mehr über XML durch die Lektüre von~[[ray:2001:xml]], online finden Sie die Spezifikationen unter~[[http:homepage:xml]].

\subsubsection*{Hinweis}

Eine zentrale Rolle bei der Verwendung von WMS spielt die Umprojizierung von Daten. Da bei WMS Rasterdaten zum Einsatz kommen\footnote{Die Datenquelle für den Server kann natürlich ein Vektorformat haben. Produziert werden aber ausschließlich Rasterdaten, wie wir es bisher immer beim MapServer gesehen haben.}, und MapServer Rasterdaten ausschließlich unter Zuhilfenahme der Bibliothek GDAL umprojizieren kann, sollten Sie MapServer mit der Unterstützung für GDAL kompiliert haben.

==Servermodi==(2)

Die genannten Spezifikation in ihrer letzten Version verlangt: es ''müssen'' zwei Arten von Anfragen implementiert sein, zwei weitere sind optional und ''können'' implementiert sein. Die beiden folgenden Anfragen (weiterhin auch ''Requests'' genannt) müssen vorhanden sein:

*=getCapabilities= : Diese Anfrage muss ein XML-Dokument zurückliefern, das die Fähigkeiten des Mapservers beschreibt.
*=getMap= : Auf diese Anfrage wird eine Karte als Rasterbild zurückgeliefert.

Entsprechend der Anforderung sind diese beiden Anfragen auch im MapServer implementiert.

Die beiden Fähigkeiten, die implementiert sein ''können'' , sind:

*=getFeatureInfo= : auf diese Anfrage liefert der Mapserver Informationen über einen bestimmten Punkt in einer Karte zurück. Diese Informationen können entweder in einer reinen Textdarstellung oder in GML (einem XML-Format) zurückgegeben werden.
*=describeLayer= liefert ein XML-Dokument mit detaillierten Informationen über einen Layer zurück. Dieser Modus wäre für einen SLD\footnote{Styled Layer Descriptor}-konformen MapServer interessant, aber dieser Standard hat bisher noch keine Umsetzung im MapServer erfahren.

Das einzige Feature, das im MapServer zurzeit nicht implementiert ist, ist demnach =describeLayer= . Es gibt noch einige andere Modi; mehr dazu in Abschnitt~7

==WMS-Metadaten im Mapfile==\index{Metadaten}

Zuallererst benötigt ihr Mapfile einen Namen. Im Header muß also der Parameter =NAME= definiert sein.

Einen 'minimalen' WMS-Server erhalten Sie zum einen durch Metadaten in der =WEB= -Sektion des Mapfiles, zum anderen durch Metadaten in den einzelnen Layern. Einige davon sind zwingend erforderlich, andere optional. Wie die Notation von Metadaten im Mapfile generell erfolgt, haben Sie bereits in Abschnitt~\ref{text:mapfile:web:meta} erfahren.

 <code>
WEB
...
METADATA
"wms_title" "Ein WMS-Server"
"wms_onlineresource" \
"http://www.example.com/cgi-bin/mapserv?map=mapfile.map&"
"wms_srs" "EPSG:31464 EPSG:4326"
END
END
</code> 

Der =wms_title= ist der Titel für die Karte, dieser muß angegeben werden. Der zweite Parameter gibt an, unter welchem URL der Server aufzurufen ist.

Beachten Sie dabei, das =\&= anzugeben, bzw. ein Fragezeichen, wenn Sie nach dem eigentlichen CGI-Programm keinen Parameter zu stehen haben.

=wms_srs= steht für die Projektion, in der die Karten angeboten werden können. Die Spezifikation schreibt vor, dass hier immer mindestens EPSG-Code 4326 angeboten werden muß. Mehrere Projektionen werden einfach durch Leerzeichen voneinander getrennt. Mehr zu EPSG und Projektionen im allgemeinen haben Sie schon in Abschnitt~\ref{text:map:projections} erfahren.

Sie benötigen =wms_srs= nicht, wenn Sie für die Karte einen Projektionsblock mit EPSG-Angabe definiert haben; die =WEB= -Sektion 'erbt' dann diese Projektion als Vorgabe.

Was machen Sie, wenn Ihre Daten allesamt in einer Projektion vorliegen, für die es keinen EPSG-Code gibt? Dann können Sie einen =PROJECTION= -Block definieren, der Parameter für die Projektionsbibliothek ''proj.4'' enthält (das Beispiel stammt direkt aus der MapServer-Dokumentation):

 <code>
PROJECTION
"proj=lcc"
"ellps=GRS80"
"lat_0=49"
"lon_0=-95"
"lat_1=49"
"lat_2=77"
END
</code> 

Wenn Sie nun EPSG-Codes in =wms_srs= nach außen anbieten, werden die Daten automatisch umprojiziert.

\subsubsection*{Notwendige Metadaten in den Layern}

Des weiteren müssen nun in jedem Layer zusätzliche Angaben nach folgendem Muster gemacht werden:

 <code>
LAYER
NAME "einlayer"
...
METADATA
"wms_title" "Titel fuer den Layer"
"wms_srs" "EPSG:31494"
END
END
</code> 

Daneben muß auch in jedem Layer ein Name gesetzt und eine Projektion definiert sein. Als Standardvorgabe erbt jeder Layer die Projektionen aus der =WEB= -Sektion, sodass sie nicht noch einmal neu notiert werden müssen.

Sie benötigen natürlich immer noch eine Projektionsangabe im Layer in Form eines =PROJECTION= -Blocks, um zu definieren, in welcher Projektion die Datenquelle vorliegt, damit MapServer im Zweifelsfall korrekt projizieren kann. Das gilt natürlich insbesondere dann, wenn Sie mehr als nur eine Projektion anbieten wollen.

MapServer geht im übrigen davon aus, dass sie tatsächlich alle Layer im Mapfile nach außen zur Verfügung stellen wollen. Layer, die sie ''nicht'' nach außen geben wollen, haben also in diesem Mapfile nichts verloren. Es gibt bisher keinen Mechanismus, mit dem man einzelne Layer (oder alle) in einem Mapfile von der Auslieferung per WMS ausschließen kann.

\subsubsection*{Metadaten in der Web-Sektion}

Im folgenden sind alle Metadaten beschrieben, die Sie für einen WMS-konformen Server in der =WEB= -Sektion des Mapfiles notieren können. Alle Angaben sind optional, falls nicht anders angegeben.

*=wms_abstract= Eine elaborierte Zusammenfassung dessen, was der Server soll und ist.
*=wms_accessconstraints= Gibt Zugangsbeschränkungen für den MapServer an. Beachten Sie bitte, dass ein Eintrag hier lediglich eine Absichtserklärung ist. Ein Text wie 'Dieser Server darf nur im Intranet unserer Firma verwendet werden' ist natürlich schön und gut, aber die entsprechenden Zugriffsbeschränkungen sind selbtsverständlich nur durch die entsprechende Konfiguration der Systeme zu erreichen.
*=wms_addresstype= Art der Adresse. Für dieses und die folgenden fünf Felder gilt, dass bei Angabe eines der Felder auch die anderen fünf mit Inhalt gefüllt werden müssen.
*=wms_address= Die Adresse.
*=wms_city= Adressbestandteil: Stadt
*=wms_country= Adressbestandteil: Land
*=wms_postcode= Adressbestandteil: Postleitzahl
*=wms_stateorprovince= Adressbestandteil: Staat oder Provinz
*=wms_contactelectronicmailaddress= Emailadresse einer Kontaktperson für diesen Server
*=wms_contactoraganization= Organisation der Kontaktperson
*=wms_contactperson= Name der Kontaktperson für diesen Server
*=wms_contactposition= Position der Kontaktperson innerhalb ihrer Organisation
*=wms_contactvoicetelephone= Telefonnummer der Kontaktperson
*=wms_fees= Art und Umfang der Gebühren, die für die Nutzung dieses Servers fällig werden. Genau wie bei =wms_accessconstraints= ist dies lediglich eine Absichtserklärung; wenn Sie Gebühren für die Verwendung des Servers erheben möchten, müssen Sie die Zugriffskontrolle durch eine geeignete Systemkonfiguration und ein passendes Geschäftsmodell herbeiführen.
*=wms_keywordlist= Eine Liste von Schlüsselworten, die auf den Server zutreffen. Dieser Parameter ist mit dem Blick darauf geschaffen worden, dass es eines Tages in einer eigens dafür geschaffenen Datenbank eine Sammlung von Capabilities-Dokumenten geben könnte, die dann die Schlüsselwortlisten durchsuchen kann. Bisher gibt es keine solche Datenbank. Es sind auch keine Standardschlüsselwörter definiert.
*=wms_onlineresource= Der URL, mit dem der Server aufgerufen wird. Beinhaltet beim UMN MapServer meistens: <code> http://www.example.com/cgi-bin/mapserv? </code> und gegebenenfalls daran angehängt noch das Mapfile. Wenn ein Mapfile über =map== angehangen wird, darf nicht das abschließende =\&= vergessen werden! Dieser Parameter ist zwingend notwendig.
*=wms_resx= Horizontale Auflösung der Karte in Pixeln.
*=wms_resy= Vertikale Auflösung der Karte in Pixeln.
*=wms_srs= Projektion(en), in der die Karte angeboten werden kann. Dieser Parameter mit mindestens einer Projektion ist zwingend notwendig.
*=wms_title= Titel der Karte. Dieser Parameter ist zwingend notwendig.

\subsubsection*{Metadaten in den einzelnen Layern}

Im folgenden die Metadaten, die Sie für einen WMS-konformen MapServer in den einzelnen Layern im Mapfile definieren können. Alle Parameter sind optional, sofern nicht anders angegeben.

*=wms_abstract= Elaborierte Zusammenfassung dessen, was dieser Layer soll und ist.
*=wms_extent= Die Bounding Box des Layers.
*=wms_keywordlist= Eine Liste von Schlüsselworten, die auf diesen Server zutreffen. %
*=wms_opaque= FIXME: was ist das?
*=wms_srs= Projektion(en), in der die Karte angeboten werden kann.
*=wms_title= Titel des Layers. Dieser Parameter ist zwingend erforderlich.

\subsubsection*{Das Mapfile als Parameter}(4)

Der Name des Mapfiles in der URL-Zeile ist nicht Bestandteil eines OGC-konformen Aufrufs des Mapservers. Unter Sicherheitsaspekten kann es darüber hinaus eventuell nicht angebracht sein, dem Client etwas über die Verzeichnisstruktur des Server-Systems zu verraten.

Im Moment gibt es zwei verschiedene Wege, den Ort des Mapfiles vor Außenstehenden zu verbergen:

*''Verwenden eines Wrapper-Skripts'' : Anstatt des CGI-Binaries wird ein kleines Skript aufgerufen, das die Umgebungsvariable = MS_MAPFILE = setzt und dann seinerseits das CGI-Programm aufruft. Ganz primitiv könnte ein solches Skript für die Shell =bash= etwa wie folgt aussehen: <code> #!/bin/sh MS_MAPFILE=/usr/local/there/is/my.map export MS_MAPFILE /usr/local/httpd/cgi-bin/mapserv </code> Beachten Sie bitte, dass dieses Beispiel nur für Unix-Systeme funktioniert, auf denen die Shell =bash= installiert ist. Für andere Shells kann die Notation abweichen.
*''Webserver-Konfiguration'' : Der Webserver ist unter Umständen in der Lage, für bestimmte aufgerufene URLs spezifische Umgebungsvariablen zu setzen. Im Apache sähe ein Eintrag in der Datei ''httpd.conf'' dann beispielsweise folgendermaßen aus (wegen der Zeilenlänge für das Drucklayout umgebrochen, muß in der Konfigurationsdatei eine Zeile sein): <code> SetEnvIf Request_URI "/cgi-bin/mapserv" \ MS_MAPFILE=/usr/local/there/is/my.map </code> Dieser Eintrag funktioniert nur im Apache und kann für andere Webserver vollkommen anders aussehen. Konsultieren Sie Ihre Dokumentation.

\subsubsection*{getCapabilities}(5)

Nachdem man zufrieden mit seinem Setup ist, möchte man es natürlich ausprobieren. Dazu ruft man als erstes das ''Capabilities'' -Dokument ab:

 <code>
http://server/cgi-bin/mapserv?VERSION=1.1.0&REQUEST=getCapabilities \
&map=mapfile.map
</code> 

Dabei müssen Sie bei =getCapabilities= nicht auf Groß- oder Kleinbuchstaben achten. Ebensowenig bei allen anderen Parametern, die vor einem Gleichheitszeichen stehen.

Der Webserver sollte Ihnen nun eine Datei des Typs =application/vnd.ogc.wms_xml= zurückliefern. Diese Textdatei können Sie abspeichern und in einem beliebigen Texteditor öffnen. Eventuell ist Ihr Webbrowser auch von sich aus in der Lage, XML-Dateien automatisch in einem ansprechenden Layout darzustellen.

Schauen Sie sich nun den Inhalt der Datei genau an. Wo immer Sie auf Zeilen treffen, die

 <code>

</code> 

beinhalten, gilt es, etwas zu bereinigen. Beispielsweise erfahren Sie aus einer Warnung wie dieser:

 <code>

</code> 

dass Sie einen Meta-Tag für den Titel der entsprechenden Sektion vergessen haben.

Sobald Sie keine Warnungen dieser Art mehr in Ihrem Capabilities-Dokument finden, ist ihr MapServer WMS-konform und voll einsatzbereit.

\subsubsection*{getMap}

Wenn die Capabilities wie erwartet geliefert werden, ist der nächste logische Schritt natürlich, sich eine Karte von Hand abzuholen. Dafür konstruieren Sie sich in Ihrem Webbrowser einen Aufruf, der etwa so aussieht, wie das Beispiel in Abschnitt~3. Dabei machen Sie sich dann auch gleich mit der Benennung der Parameter vertraut.

Das beste was Ihnen passieren kann, ist natürlich, dass Sie gleich ihre gewünschte Karte bekommen. Dann sind Sie natürlich fertig. Sobald Sie jedoch Ihren ersten Fehler machen, müssen Sie sich mit Fehlermeldungen auseinandersetzen, den so genannten Exceptions.

==Exceptions==\index{Exceptions}\index{WMS!Exceptions}

Exceptions sind Meldungen, die von einem WMS-konformen Mapserver im Fehlerfall ausgegeben werden müssen. Das entspricht in etwa dem Expcetions-Konzept diverser Programmiersprachen wie z.B. Java. Der Sinn ist es, dem aufrufenden Client -- sei es nun eine menschliche Person, sei es eine Software -- anhand des Typs und des Inhalts der Fehlermeldung eine Entscheidung über das weitere Vorgehen treffen zu können. Eine solche Art der Fehlerbehandlung verhindert natürlich unter anderem, dass ein Programm seine Durchführung im Fehlerfall einfach beendet.

Wenn Sie bei einem WMS-konformen Aufruf einen Fehler machen, indem Sie beispielsweise einen Parameternamen wie =REQUEST= absichtlich falsch schreiben, wird Ihnen MapServer eine Datei in einem XML-Format zurückliefern:

*=application/vnd.ogc.se_xml= Ein WMS-konformer Mapserver muß mindestens diese Art der Vermittlung von Exceptions beherrschen. Solch eine Datei kann beispielsweise folgenden Inhalt haben: <code> <?xml version='1.0' encoding="ISO-8859-1" standalone="no" ?> <!DOCTYPE ServiceExceptionReport SYSTEM "http://www.digitalearth.gov/wmt/xml/exception_1_1_0.dtd"> <ServiceExceptionReport version="1.1.0"> <ServiceException> msWMSDispatch(): WMS server error. Incomplete WMS request: REQUEST parameter missing </ServiceException> </ServiceExceptionReport> </code> 

\begin{figure}
\begin{center}
\mmfig{0.6}{wms-exception-inimage}{Exception vom Typ application/vnd.ogc.se_inimage.}
\end{center}
\end{figure}

Des weiteren kann ein Mapserver Exceptions in den folgenden MIME-Typen zur Verfügung stellen:

*=application/vnd.ogc.se_inimage= Die Exception wird als Text in das auszuliefernde Bild eingefügt.
*=application/vnd.ogc.se_blank= Die Spezifikation geht von der Idee, dass ein leeres Bild etwas ist, dass man grundsätzlich nicht haben möchte, und somit nie bekommt. Daher kann ein 'leeres' Bild als Fehlermeldung angesehen werden. Als 'leeres' Bild ist ein Bild definiert, das ganz mit der Hintergrundfarbe der Karte ausgefüllt ist.

Im URL des Aufrufs wird die gewünschte Art der Exception mit dem Parameter =EXCEPTIONS= notiert. Wollen Sie Exceptions also im Bild notiert haben, schreiben Sie in Ihrem URL:

 <code>
... & EXCEPTIONS=application/vnd.ogc.se_inimage & ...
</code> 

Beachten Sie bitte, dass nur die XML-Variante implementiert sein muß. Wenn Sie von einem Server Exceptions im Bild verlangen, er aber nur XML kann, dann wird er XML liefern.

Beachten Sie außerdem, dass das Handling von Exceptions insbesondere bei Kaskaden von WMS-konformen Servern eine Rolle spielt. So kann es Ihnen passieren, dass Sie sich einen Layer von einem Server holen, der sich wiederum sein Bild von anderen entfernten Quellen heranholt, und von dort im Fehlerfall eine Exception in das Bild eingetragen bekommt. Dadurch haben Sie die Fehlermeldung dann natürlich auch im Bild zu stehen.

===Hinweis===

Viele Kartenanbieter tendieren dazu, ihre fertigen Karten mit Schriftzügen, Logos, Nordpfeilen, Wasserzeichen und so weiter auszustatten. Denken Sie immer daran, dass der Kunde, der Ihren Service wiederum als Datenquelle benutzt, eventuell auf die Idee kommt, die von Ihnen bezogene Karte umzuprojizieren! Das kann dann zu interessanten Effekten führen, wenn dann Dritte den Schriftzug mit der URL Ihrer Firmenwebsite quer über die ganze Karte gekrakelt bekommen. Entwickeln Sie im Vorhinein zusammen mit den Benutzern des Service ein Konzept, dass solche häßlichen Effekte verhindert.

==getFeatureInfo==

Sich Karten einfach nur anzusehen, ist selbstverständlich nur die Hälfte des Reizes eines WMS-konformen Servers. Man möchte selbstverständlich auch Queries auf die Daten durchführen können. Zu diesem Zweck gibt es den =REQUEST= mit dem Namen =getFeatureInfo= .

Zuerst einmal gilt es, Queries überhaupt erst einmal zuzulassen. Wie schon bei den 'klassischen' Queries (siehe Abschnitt~\ref{text:mapfile:queries}) kann man in MapServer eine Query nur auf einem Layer durchführen, der ein =TEMPLATE= definiert.

Wenn man das tut, und sich die ''capabilities'' anschaut, wird man für den Layer auf ein Attribut der folgenden Art treffen:

 <code>
<Layer queryable="1" opaque="0" cascaded="0">
</code> 

Der Wert =1= für =queryable= zeigt im Gegensatz zum Wert =0= an, dass Queries auf diesen Layer zulässig sind.

Um einen Aufruf vom Typ =getFeatureInfo= zu verstehen, betrachten wir einmal einen vollständigen URL für diesen Vorgang:

 <code>
http://www.example.com/cgi-bin/mapserv
? map=/usr/local/mapserv/mapfile.map
& VERSION=1.1.0
& REQUEST=getFeatureInfo
& QUERY_LAYERS=gruenflaechen
& SRS=EPSG:4326
& BBOX=5.0,45.0,15.0,55.0
& WIDTH=500
& HEIGHT=500
& X=250
& Y=250
& INFO_TYPE=text/plain
</code> 

Einige Bestandteile sind dem Leser bereits bekannt: Version des Standards, Angabe der Projektion durch =SRS= . Dazu kommt, wenig überraschend, die Angabe des =REQUEST= .

Da jetzt keine Darstellung mehr erfolgen sollen, werden keine =LAYERS= mehr angegeben, sondern =QUERY_LAYERS= \footnote{Diese Unterscheidung ist offensichtlich eigentlich unnötig, da man die Funktion der Layerangabe ja eigentlich serverseitig aus dem =REQUEST= schließen könnte.}. Um Ergebnisse zu liefern, muß jeder Layer in der Liste =QUERY_LAYERS= das Attribut =queryable= auf =1= gesetzt haben -- siehe oben.

Zwingend sind darüberhinaus die Angabe der Extents des Bildes, das man befragen möchte (angegeben mit =BBOX= ), Breite und Höhe des Bildes sowie die X- und die Y-Koordinate des Punktes im Bild, der sich der Aufmerksamkeit des Users erfreut, beispielsweise durch einen Mausklick. Beachten Sie, dass es sich dabei um Bildkoordinaten handelt, es handelt sich also um Pixelwerte. Der Koordinatenursprung eines Bildes ist links oben.

Am interessantesten ist natürlich der =INFO_TYPE= , der angibt, auf welche Weise die Queryergebnisse formatiert sein sollen. MapServer unterstützt die folgenden Formate:

*=text/plain= , das Standardformat, falls Sie nichts anderes angegeben haben;
*=text/html= , was ein wenig Vorbereitung erfordert, im wesentlichen aber wie Queries auf einem 'normalen' MapServer-CGI behandelt wird; und
*=application/vnd.ogc.gml= , GML, eine XML-Repräsentation für Geodaten.

Betrachten wir die Formate im Detail:

\subsubsection*{text/plain}

Dieser Ausgabetyp für getFeatureInfo ist die Voreinstellung für MapServer, falls Sie keinen anderen Ausgabentyp spezifizieren.

Für ein Mapfile mit den Voreinstellungen des Itasca-Demos und einem fiktiven Anklickpunkt mit den Koordinaten 200/200 sieht die Ausgabe folgendermaßen aus:

 <code>
GetFeatureInfo results:

Layer 'countyboundary'
Feature 26:
AREA = '7577272785.15393'
PERIMETER = '436617.07762'
CTY_NAME = 'Itasca'
COUN = '31'
CTY_ABBR = 'ITAS'
ISLAND = 'N'
CTY_FIPS = '61'
RECNO = '27'
</code> 

Es wird der Name des Layers ausgegeben, die Nummer des Layers innerhalb des Shapefiles, und dann alle Attribute aus der =.dbf= -Datei der Datei. Wenn es mehrere Suchergebnisse gegeben hat, werden diese der Reihe nach dargestellt.

\subsubsection*{text/html}

Mit diesem Ergebnistyp greift MapServer auf die HTML-Templates zurück, die Sie für Queries bereits in Kapitel~\ref{text:mapfile} kennengelernt haben. Das bedeutet, dass Sie ein HTML-Layout ganz nach Ihrem Geschmack gestalten können, und MapServer die entsprechenden Tags in eckigen Klammer wie gewohnt ersetzt.

Dieser ''MIME type'' bietet jedoch noch die Möglichkeit für zusätzliche Tricksereien. Der Standard schreibt nämlich keinen ''MIME type'' zwingend vor, und ebensowenig gibt es ein vorgeschriebenes Verhalten für den Fall, dass ein bestimmter Typ nicht unterstützt wird. Das führt dazu, dass MapServer es sich vorbehält, beliebige Arten von Daten zurückzuliefern.

Sie können ein =TEMPLATE= definieren, das nicht gezwungenermaßen eine HTML-Seite sein muß. Reiner ASCII-Text wäre ebenso möglich, oder alle anderen Formate, in denen Sie MapServer-Tags ersetzen können.

Sobald das Template beliebigen Formats von MapServer bearbeitet worden ist, kann das Resultat zurückgeliefert werden. Wenn man jetzt reinen ASCII-Text hat, würde MapServer ihn jedoch als =text/html= ausliefern, und das ist eigentlich nicht das, was man möchte. Der Client (also z.B. Webbrowser) interpretiert die Daten natürlich nur korrekt, wenn man ihm den korrekten MIME type liefert. Daher kann man im Mapfile für die zurückgegebenen Daten einen eigenen Metadatum den geeigneten Typ setzen:

 <code>
WEB
...
METADATA
...
"wms_feature_info_mime_type" "text/plain"
END
END
</code> 

Also noch einmal zusammenfassend: der Benutzer kann zwar von außen den =INFO_TYPE= auf =text/html= setzen; MapServer kann jedoch mit Daten beliebigen Typs antworten.

\subsubsection*{application/vnd.ogc.gml}

Damit ein Layer in diesem Format Anfragen beantworten kann, muß außerdem der Parameter =DUMP= in diesem Layer gesetzt sein:

 <code>
LAYER
...
DUMP TRUE
END
</code> 

Falls es keine Suchresultate gegeben hat, wird zwar eine Datei im korrekten Format zurückgegeben, die allerdings nur die korrekten Header enthält und ansonsten leer ist.

Für Suchergebnisse werden in diesem Format immer die Koordinaten des Features gleich mitgeliefert. Antworten können also bei großen Features nicht nur auf sich warten lassen, da MapServer für das Erzeugen großer Dokumente natürlich eine Weile braucht, sondern auch weil der Transfer über das Netz natürlich ein bißchen dauert.

Die Anfrage auf den Flughafen-Layer der Itasca-Demodaten beispielsweise liefert in den voreingestellten Extents und dem fiktiven Klick auf die Koordinate 224/75 das folgende Ergebnis:

 <code>
<?xml version="1.0" encoding="ISO-8859-1"?>

<msGMLOutput
xmlns:gml="http://www.opengis.net/gml"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance">
<countyboundary_layer>
<countyboundary_feature>
<AREA>7577272785.15393</AREA>
<PERIMETER>436617.07762</PERIMETER>
<CTY_NAME>Itasca</CTY_NAME>
<COUN>31</COUN>
<CTY_ABBR>ITAS</CTY_ABBR>
<ISLAND>N</ISLAND>
<CTY_FIPS>61</CTY_FIPS>
<RECNO>27</RECNO>
<gml:boundedBy>
<gml:Box srsName="EPSG:26915">
<gml:coordinates>
393234.393701,5207990.085063
495769.579719,5305374.105135
</gml:coordinates>
</gml:Box>
</gml:boundedBy>
<gml:Polygon srsName="EPSG:26915">
<gml:outerBoundaryIs>
<gml:LinearRing>
<gml:coordinates>
393865.671855,5300138.258409
393869.171975,5300138.258374
394516.694141,5300137.439369
395522.728579,5300136.241770
[...]
</code> 

Und so weiter, mit allen Punkten des Features.

==WMS Clients==\index{OGC!Client}(6)

WMS-konforme Mapserver lassen sich kaskadieren, indem einzelne Layer einfach als fertige Bilder von anderen WMS-konformen Mapservern bezogen werden. Durch die standardisierte Schnittstelle ist dafür kein UMN MapServer nötig. Sie können einzelne Layer beispielsweise auch von einem ESRI ArcIMS beziehen, wenn Sie möchten.

Neben der schönen Möglichkeit, die Standorte und somit Pflege einzelner Teile der Kartenerzeugung voneinander trennen zu können, indem man beispielsweise die Bodenproben von einem Amt und die hydrogeologischen Karten von einem anderen Amt miteinander über eine genormte Schnittstelle verbindet, ist ein weiteres offensichtliches Einsatzfeld natürlich die Lastenverteilung. Datenbestände, die erst umprojiziert werden müssen, können auf leistungsfähigere Server ausgelagert werden, während einfache Operationen wie beispielsweise die simple Darstellung von Rasterbildern von schwächeren Geräten übernommen werden kann\footnote{Beachten Sie dabei immer, dass zur Erzeugung des fertigen Bildes ''immer'' auf den langsamsten Layer gewartet werden muß, da ja das Bild ansonsten nicht komplett ist.}.

Im folgenden soll betrachtet werden, wie Sie einen Layer in einem Mapfile erstellen, damit er dynamisch Daten von einem WMS-konformen Server bezieht. Nach außen hin verhält sich dieser Layer dann wie jeder andere Rasterlayer auch.

\subsubsection*{Installation und Konfiguration}

Wie weiter hinten im Kapitel 'Installation' ab Seite~\pageref{text:installation} beschrieben, ist die Fähigkeit, als WMS-Client zu fungieren, nicht als Voreinstellung bei der Kompilierung gegeben, sondern muß explizit angefordert werden. Wie das genau gemacht wird, und welche Voraussetzungen gegeben sein müssen, ist in Abschnitt~\ref{text:installation:compile:wmsclient} erklärt.

\subsubsection*{getMap}

Der erste Schritt ist, sicherzustellen, dass der anzusprechende Server funktioniert und die gewünschten Daten ausliefert. Dafür holt man sich das Capabilites-Dokument dieses Servers. Wie das zu tun ist, ist auf Seite~\pageref{text:wms:getcapabilities} beschrieben.

Nun weiß man alles über die Fähigkeiten des Servers (welche Projektionen angeboten werden, wie seine Layer heißen und so weiter) und kann sich darum kümmern, eine erste Karte zu holen, um zu sehen, ob die Darstellung dem entspricht, was man erwartet. Dazu richtet man mit seinem Webbrowser eine =getMap= -Anfrage an den Server.

Wie so eine Anfrage aufgebaut sein muß, wurde bereits in Abschnitt~3 gezeigt. Ersetzen Sie allerdings alle Werte für die Parameter durch diejenigen, die Sie im abgerufenen Capabilities-Dokument gefunden haben, also durch korrekte Projektionen, Layernamen, Extents und so weiter. Sobald dieser Aufruf eine Karte in Ihrem Browser zaubert, wissen Sie, dass Sie gültige Werte besitzen und sie korrekt notiert haben, sodass Sie diese Angaben jetzt in einen Layer in Ihr Mapfile einbauen können.

\subsubsection*{Das Mapfile}

Zunächst benötigen Sie einen =PROJECTION= -Block für Ihre Karte. Sie können auf diesen Block verzichten, wenn alle Layer in der gleichen Projektion vorliegen und auch die von Ihnen angesprochenen WMS-Server nur diese eine Projektion unterstützen.

Beachten Sie, dass Sie in der =WEB= -Sektion Ihres Mapfiles einen =IMAGEPATH= -Parameter benötigen, da die Bilder von entfernten Servern als temporäre Dateien gespeichert werden müssen. Diese temporären Dateien werden übrigens nach Verwendung gleich wieder gelöscht, sodass Sie sie kaum bemerken werden.

Für WMS-konforme Anfragen an andere Server sind lediglich die Layerdefinitionen anzupassen. Dabei kommt ein =CONNECTIONTYPE= mit dem Namen =WMS= zum Einsatz:

 <code>
LAYER
NAME "Gewaesser"
TYPE RASTER
STATUS ON
CONNECTIONTYPE WMS
CONNECTION "http://www.example.com/cgi-bin/mapserv?"
METADATA
"wms_title" "Gewaesser"
"wms_server_version" "1.1.0"
"wms_srs" "EPSG:4326 EPSG:31464"
"wms_name" "seen,kanaele,fluesse,baeche"
"wms_format" "image/png"
END
PROJECTION
"init=epsg:31464"
END
END
</code> 

Wie Sie sehen, ist der URL selber sehr kurz gehalten. Er entspricht der ''onlineresource'' aus dem Capabilities-Dokument eines WMS-konformen Servers.

Alle weiteren Details zur Verbindung mit dem entfernten Server werden in Form von Metadaten gemacht. Wer bisher MapServer 3.6 eingesetzt hat, wird das noch anders kennen: in jener Version wurde noch der gesamte Verbindungsstring (bis auf die dynamischen Elemente) in der =CONNECTION= notiert.

Der =wms_title= ist der Titel für diesen Layer, der mit der Anfrage allerdings nichts zu schaffen hat.

Die Version der Anfrage wird mit =wms_server_version= notiert. Mit =wms_srs= geben Sie wieder Projektionen an, allerdings diejenigen, die von der Gegenstelle unterstützt werden.

=wms_name= benennt den oder die Layer, aus denen die bezogene Karte zusammengesetzt werden soll. Mehrere Layer werden durch Kommata voneinander abgetrennt. Beachten Sie, dass bei WMS die Reihenfolge der Ebenen von Belang ist: in unserem Beispiel werden zuerst der Layer =seen= gezeichnet, darauf dann =kanaele= und so weiter.

Das gewünschte Bildformat wird schließlich mit =wms_format= spezifiziert. Es gibt auch den Parameter =wms_formatlist= , der mehrere durch Kommata getrennte Angaben zuläßt.

''Wichtiger Hinweis'' : An keiner einzigen Stelle lädt sich MapServer die Capabilities des entfernten Servers herunter, um sich mit ihnen auseinanderzusetzen. Sie müssen also selber darauf achten, dass die von Ihnen gemachten Angaben stimmig sind.

==Exceptions==

Wenn Sie einen Layer haben, der sich Daten von einem WMS-konformen Server holt, drängt sich natürlich die Frage auf, wie MapServer im Fall von Exceptions reagiert. Eindeutige Antwort: das kommt drauf an.

Am einfachsten ist es offensichtlich, mit Exceptions, die direkt im Bild eingefügt sind, umzugehen, also mit denen, die vom Typ =application/vnd.ogc.se_inimage= sind. Diese werden einfach Bestandteil der fertigen Karte, die Sie im Webbrowser sehen. Im Fehlerfall bemerkt sehr schnell, was Sache ist.

Das gleiche gilt offensichtlich bei =application/vnd.ogc.se_blank= .

Liefert die Gegenstelle ein textbasiertes Format, also zum Beispiel GML zurück, dann gibt es ein Problem, da MapServer davon ausgeht, dass er Rasterdaten als Input erhält; demnach versucht er, das GML-Dokument als Text zu rendern, was natürlich schief geht und somit eine Fehlermeldung erzeugt.

Dieses Problem läßt sich bisher leider auch noch nicht umgehen. Das mindeste, was man also tun kann, ist für eine funktionierende Kommunikation mit dem Betreiber des Quellservers zu sorgen, damit dieser nicht einfach unangekündigt Layernamen ändert, die Ihnen Ihre Applikation wegbrechen lassen.

==Hinweise==(7)

FIXME: das auch noch bei WFS erwähnen

Wenn Sie mit der Administration sowohl des Mapservers, der als Client fungiert, als auch der Serverseite betraut sind, sollten Sie auf alle Fälle darauf achten, keine zirkulären Bezüge zu erzeugen, bei denen Server A einen Layer von Server B bezieht und dieser dann wieder Server A aufruft. Bei komplexen Installationen ist das durchaus eine Fehlerquelle, das Verhalten in diesem Fall ist undefiniert.

Ein weiterer wichtiger Faktor beim Einsatz von WMS-konformer Funktionalität ist die unschöne Tatsache, dass MapServer das Sammeln der Daten für einzelne Layer linear abarbeitet, und nicht mit einem einzelnen Thread oder Prozess pro Layer arbeitet. Das bedeutet, dass MapServer genau ''gar nichts'' tut, während er auf einen Layer aus dem Netzwerk wartet, um dann zum nächsten Layer überzugehen\ldots der dann vielleicht wieder ein solcher Layer ist, oder eine Datenbankquelle. Es wird also unnötig Rechenzeit vergeudet. Dieses Problem läßt sich im Moment auch leider nicht umgehen.

\subsubsection*{Weitere Modi für WMS}

Wer den Standard aufmerksam liest, wird noch vier weitere Operationsmodi finden, die in den einführenden Zeilen zu diesem Abschnitt nicht genannt worden sind. Sie umfassen:

*=describeLayer=
*=getLegendGraphic=
*=getStyles=
*=putStyles=

Diese Modi sind nur für Mapserver von Relevanz, die den OGC-Standard SLD unterstützen. Mit diesen ''styled layer descriptor'' ist es möglich, von außen Einfluß auf die ansonsten fixe Kartengestaltung eines Mapservers zu nehmen. Da dieser Standard serverseitig von MapServer bisher nicht unterstützt wird\footnote{Und clientseitig nur sehr sporadisch; konsultieren Sie hierzu bitte die Online-Dokumentation.}, findet hier keine detaillierte Beschreibung statt. Sie können sich aber selbstverständlich den Standard~[[pdf:spec:sld10]] lesen.

=Web Feature Server (WFS)=(8)

Die entsprechende Spezifikation des OGC~[[pdf:spec:wfs100]] sieht WFS im Kontext zu WMS. Nach der Formulierung in der Einführung des Dokuments ist WFS der 'nächste logische Schritt' nach WMS. Wo WMS die Möglichkeit bietet, Capabilities abzufragen Karten anzuzeigen und schließlich Anfragen bezüglich der Datengrundlage der Karten zu machen, stellt WFS ein Interface zur Verfügung, dass es dem Benutzer ermöglicht, Einfluß auf die Datengrundlage zu nehmen, indem Features in der Karte geändert und gelöscht, bzw. neue Features hinzugefügt werden können.

Das hört sich alles ziemlich gut an -- und doch muß der begeisterte Leser hier enttäuscht werden. MapServer ist bisher ausschließlich darauf ausgelegt, Daten aus Quellen wie der Festplatte oder einer Datenbank zu lesen und Karten zu produzieren. Von einer Unterstützung für Datenänderungen ist man im Moment noch sehr weit entfernt -- falls sie überhaupt kommen wird\footnote{Es besteht natürlich die Möglichkeit, dass Sie beispielsweise mit MapScript entsprechende Fähigkeiten in einer eigenen Applikation programmieren. Stellen Sie sich auf einigen Aufwand ein.}.

Was wir mit MapServer kriegen, ist allerdings zumindest die Möglichkeit, Vektorlayer über den Transportmechanismus von WFS als Server auszuliefern bzw. als Client zu beziehen. Das funktioniert nur mit Vektordaten, da sich Rasterdaten offensichtlich nicht in das XML-Format mit dem Namen GML verpacken lassen. Diese ''Geography Markup Language'' ist selbstverständlich ebenfalls in einer eigenen Implementation Specification definiert~[[pdf:spec:gml]].

Von den in der Spezifikation definierten Anfragetypen sind im MapServer die folgenden implementiert:

*=getCapabilities= , um ein Capabilities-Dokument abrufen zu können, wie man es bereits von WMS kennt.
*=describeFeature= liefert eine Beschreibung eines Features zurück.
*=getFeature= holt eine GML-Repräsentation eines Features.

==WFS Server==

Wie schon beim WMS-konformen Server, wird WFS in MapServer dadurch aktiviert, dass die notwendigen =METADATA= -Tags in das Mapfile eingefügt werden. Zuerst einmal müssen aber die folgenden Vorkehrungen getroffen werden:

*Zuerst muß MapServer natürlich mit WFS-Unterstützung kompiliert worden sein. Detaillierte Vorgaben dafür finden Sie in Anhang~\ref{anhang:compile}.
*Das Mapfile muß einen =NAME= haben, ebenso wie jeder einzelne Layer. Wie schon bei WMS geht MapServer bei WFS davon aus, dass jeder Layer, der sich im Mapfile befindet, auch über WFS zur Verfügung gestellt werden soll.

MapServer kann ausschließlich Vektorlayer in seinen WFS-Capabilites erscheinen lassen, also Shapefiles, PostGIS-Layer und so weiter; der Typ des Layers muß also =POINT= , =LINE= oder =POLYGON= sein.

Desweiteren muß die Eigenschaft =DUMP= im Layer auf =TRUE= gesetzt sein. Dies zeigt MapServer an, dass er GML-Repräsentationen für diesen Layer erzeugen darf. Das entspricht der Vorgabe, =getFeatureInfo= mit einem WMS-konformen Server nutzen zu können.

In der =WEB= -Sektion des Mapfiles müssen dann die folgenden Angaben gemacht werden.

*=wfs_onlineresource= Die Basisadresse des Servers. Hat denselben Aufbau wie der gleichnamige Parameter für WMS. Allerdings muß man einem WFS-konformen MapServer noch mitteilen, wie er WFS- von WMS- Anfragen zu unterscheiden hat. Das geschieht durch =SERVICE= , also etwa derart: <code> WEB .. METADATA ... "wfs_onlineresource" \ "http://www.example.com/cgi-bin/mapserv?SERVICE=WFS&map=..." END END </code> Diese Angabe ist auch dann nötig, wenn der MapServer nicht darauf eingerichtet oder konfiguriert ist, als WMS-Server zu fungieren.
*=wfs_title= Titel für die Karte; siehe WMS-Konformität. Zwingend notwendig.
*=wfs_abstract= Eine elaborierte Zusammenfassung über Sinn und Zweck dieses Servers. Siehe WMS-Konformität.
*=wfs_keywordlist= Eine Liste mit Schlüsselworten, die einen Bezug zu diesem WFS-Server haben. Siehe WMS-Konformität.
*=wfs_accessconstraints= Beschränkungen, die den Zugriff auf diesen Server betreffen. Siehe WMS-Konformität.
*=wfs_fees= Gebühren, die beim Zugriff auf diesen Server anfallen. Siehe WMS-Konformität.
*=wfs_encoding= Die Kodierung für die XML-Dateien, die durch den WFS-Server ausgeliefert werden. Voreingestellt ist hier ISO-8859-1.
*=ows_schema_location= Der Ort, an dem die OWS-Schemas zur Validierung der generierten XML-Dateien liegen. Siehe weiter unten auf Seite~\pageref{text:wfs:schemas}.
*=wfs_geometry_element_name= Weiter unten gibt es ein Beispiel zu sehen, wie eine Datei aussehen kann, die von einem WFS-konformen MapServer ausgeliefert wird. Das Element, dass die Liste der Koordinaten eines Features umfaßt, hat dabei keinen fixen Namen. Sie können mit diesem Parameter hier einen Namen festlegen; Voreinstellung in MapServer ist =MS_GEOMETRY= .
*=wfs_srs= Die Projektion, die für alle Layer in der Karte gelten soll. Wird als EPSG-Code angegeben und genauso wie bei WMS-konformen Servern notiert. Beachten Sie bitte die Anmerkungen zu Projektionen in WFS-konformen Servern im nächsten Abschnitt.

Beachten Sie, dass diese Parameter im Gegensatz zu den WMS-Parametern alle den Präfix =wfs_= tragen. Einzige Ausnahme ist =ows_schema_location= .

==Projektionen in WFS-Servern==

Die WFS-Spezifikation macht zu Projektionen andere Vorgaben als idie für WMS. So können einzelne Layer nicht in mehr als einer Projektion ausgeliefert werden. Es gibt auch keine Projektionsangabe, die man ein einziges Mal für alle Layer machen kann\footnote{Man kann aber, wie Sie weiter oben sehen konnten, MapServer so konfigurieren, dass er einen SRS-Eintrag in der WEB-Sektion bekommt und diesen dann auf alle Layer überträgt.}. Es ist aber sehr wohl möglich, für jeden Layer eine unterschiedliche Projektion anzubieten. Außerdem nennt der Standard keine Default-Projektion; anders als bei WMS, wo mindestens =EPSG:4326= angeboten werden muß.

MapServer entscheidet in zwei Schritten, welche Projektion für einen Layer nach außen mitgeteilt wird. Wenn es eine 'übergeordnete' Projektion gibt (also einen Projektionsblock mit EPSG-Code für die ganze Karte, bzw. ein =wfs_srs= in der WEB-Sektion), so findet diese Projektion auf alle Layer Anwendung, selbst dann, wenn die Layer selber noch einmal über =wfs_srs= eine Projektion definieren.

Gibt es keine solche 'Überprojektion', muß jeder Layer einen eigenen Wert setzen.

==Schemas==(9)

Schemas\footnote{In diesem Fall nicht Schemata, da es sich um einen feststehenden englischen Begriff handelt.} sind ein Mechanismus, XML-Dateien zu validieren, also zu prüfen, ob sie einem bestimmten Aufbau genügen. Sie können ein Paket standardkonformer Schemas von~[[http:owssamples]] herunterladen.

Das Archiv entpacken Sie an einen Ort, der für den WebServer erreichbar ist. Danach können Sie, wie oben gesehen, mit einem entsprechenden Metadatum den Pfad zu den Schemas angeben:

 <code>
WEB
...
METADATA
...
"ows_schema_location" "/pfad/zu/den/schemas"
END
END
</code> 

Geben Sie keinen Pfad an, wird =..= als Ort für die Schemas angenommen. Der Gedanke hinter dieser Entscheidung war, dass man damit im Wurzelverzeichnis des Webservers landet, wenn man sein MapServer-Binary im Verzeichnis =cgi-bin/= hat\footnote{Eine sehr Apache-zentrierte Denkweise.}.

Der Präfix =ows_= zeigt übrigens an, dass hier auf mehr als nur WFS-Schemas verwiesen wird; vielmehr handelt es sich um einen Verweis auf Schemas, die sich auf ''OGC Web Services'' beziehen.

==Aufruf \& Capabilities==

Sobald man die ganze vorbereitende Arbeit hinter sich gebracht hat, kann man prüfen, ob alles korrekt eingerichtet worden ist. Dazu richtet man, wie schon beim WMS-konformen Server, eine Anfrage vom Typ =getCapabilities= an den Server:

 <code>
http://www.example.com/cgi-bin/mapserv
? SERVICE=WFS
& REQUEST=getCapabilities
& map=...
</code> 

Die Vorgehensweise entspricht jetzt haargenau dem, was Sie auch mit einem WMS-Server tun würden: Sie durchsuchen das Capabilites-Dokument nach Warnungen und Fehlern, und wenn sich alles so verhält, wie es geplant war, dann haben Sie einen einsatzfähigen, WFS-konformen Server.

==WFS Client==

Was man mit WMS machen kann, will man selbstverständlich auch mit WFS machen: Einbinden von WFS-Layern als eigene Kartenebenen. Die Vorgehensweise ist dabei stark an eben das Einfügen von WMS-Layern angelehnt.

FIXME: blah

Die Voraussetzungen für die Kompilierung eines WFS-konformen Client sind etwas umfänglicher als für den entsprechenden Server. Sieh auch Abschnitt [FIXME] im Anhang.

Ein WFS-Client-Layer ist sieht anders aus als ein 'normaler' Layer, hat aber Ähnlichkeit mit einem WMS-konformen Layer. Hier ein Beispiel:

 <code>
LAYER
END
</code> 

FIXME: vervollständigen!1!

=Map Context=

Diese Spezifikation ist eine Ergänzung zur WMS-Spezifikation. Sie beschreibt einen Mechanismus, mit dem Informationen über eine Menge von WMS-produzierten Layern auf eine portable Weise zwischen Systemen ausgetauscht bzw. in einem definierten Format gespeichert und abgerufen werden können.

Das Dokument, das diesen Standard definiert ist in der Version 1.0 von der OGC-Website herunterladbar~[[pdf:spec:mapcontext10]].

MapServer kann Kontextdokumente in den Versionen 0.1.2, 0.1.4, 0.1.7 und 1.0 lesen, und in den Versionen 0.1.4, 0.1.7 und 1.0 exportieren.

Kontextdokumente lassen sich im MapServer darüberhinaus nur in MapScript verwenden, und selbst dort nur in der PHP-Fassung. Alles andere wird (noch?) nicht unterstützt. Darüberhinaus geht Map Context davon aus, dass die WMS-Spezifikation 1.1.1 beachtet wird.

Notwendige Bibliotheken für die Map Context-Funktionalität sind die Projektionsbibliothek proj.4, GDAL/OGR im Zusammenspiel mit Xerces sowie PHP MapScript. Genaue Installationsanleitungen für diese Komponenten finden Sie im Anhang ab Seite~\pageref{text:installation}.

==Das Context-Dokument==

Der Inhalt eines Context-Dokuments (oder schlicht: eines Contexts) besteht im wesentlichen aus Angaben über die Quelle(n) der einzelnen Layer, die verwendeten Bounding Boxes, Projektionen und eventuell diverse Metadaten.

Wie bei praktisch allem, was mit dem OGC in Zusammenhang steht, ist der Context ein XML-Dokument. Beachten Sie, dass in einem Context-Dokument tatsächlich nur WMS-Layer gespeichert werden können.

FIXME: fertig!1!

==Den Kontext verwenden==

Dieser Abschnitt sollte sinnvoller eigentlich im Kapitel über PHP MapScript erscheinen; der Konsistenz halber ist er hierher gewandert. Denn wie bereits erwähnt, kann Map Context bisher nur im Zusammenspiel mit PHP-MapScript benutzt werden.

Wenn Sie ein Mapfile nach den obigen Vorgaben erstellt haben, können Sie testen, ob Sie alles richtig gemacht haben:

 <code>
<?php
dl ("php_mapscript40.so");
<math>map = ms_newMapObj ("mapfile.map");
</math>map -> saveMapContext ("mapfile_context.xml");
</code> 

Danach geht es nach dem bewährten Muster daran, in der fertigen XML-Datei nach Warnhinweisen zu suchen, die zeigen, dass Dinge fehlen oder Fehler vorliegen. Wenn das nicht mehr passiert, kann Ihr Mapfile als Quelle für einen Map Context dienen.

FIXME: fertig!1!

= Styled Layer Descriptor (SLD)=
* http://www.mapserver.org/ogc/sld.html

=Filter Encoding =
[[User:Astrid Emde]]
* http://www.mapserver.org/ogc/filter_encoding.html

= WCS =
* http://de.wikipedia.org/wiki/Web_Coverage_Service
* Informationen siehe http://www.mapserver.org/ogc/wcs_server.html
* Informationen siehe http://www.mapserver.org/ogc/wcs_format.html

= WMS Time=

* Informationen siehe http://www.mapserver.org/ogc/wms_time.html

= SOS=

* Informationen siehe http://www.mapserver.org/ogc/sos_server.html

== OWS Clients ==
=== Desktop GIS ===
=== WebGIS ===

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 3

2009-01-23T07:24:50Z

Wiki-Mikee63: /* UMN als WMS Server */

[[User:Astrid Emde]] (SLD, WMC, Filter Encoding, OWS Clients) 
[[User:jtmapmedia | Jörg Thomsen]] (OGC-Konformität, Warum macht man das?, Wie macht man das? )

[[HBUMNMapServer_ger | '''Inhaltsverzeichnis''']]

= OGC-Konformität =
--[[User:Jtmapmedia|Jtmapmedia]] 13:52, 10 January 2009 (UTC)
(1)\index{OGC}

Das [http://www.opengeospatial.org/ Open Geospatial Consortium]~\cite{http:website:ogc}, kurz OGC, ist ein internationaler Zusammenschluß von '368 Unternehmen, Regierungsorganisationen und Universitäten' (Eigendarstellung auf der Website, die Zahl ändert sich beinahe wöchentlich). Ziel des OGC ist es, gemeinsame Standards (Protokolle, Formate etc.) für Austausch, Verarbeitung und Speicherung von Geodaten zu erarbeiten.

Die Standards, die uns bei der Erstellung von OGC-konformen MapServern im Internet interessieren können, sind vielfältig. Für den MapServer sind die folgenden Standards relevant bzw. implementiert:

* OGC Web Map Service Specification (WMS), für den Transfer von Rasterkarten und eventuelle Anfragen auf diese Daten,
* OGC Web Feature Service Specification (WFS), was das gleiche für Vektordaten und eventuelle Anfragen auf diese Daten ist.
* OGC Web Coverage Service Specification (WCS), regelt den Zugriff auf hochaufgelöste Rasterdaten wie Luft- und Satellitenbilder und deren Bereitstellung.
* OGC Sensor Observation Service (SOS), der den Austausch von Sensordaten, wie z.B. Wasserpegel oder Temperaturmessungen spezifiziert.
* Map Context Specification, ermöglicht das Speichern und Laden von WMS-Zuständen wie Zoomstufe, sichtbare Layer usw..

Darüber hinaus werfen wir auch noch einen raschen Blick auf

* OGC Filter Encoding (FE), damit können Geodaten, beispielsweise für Klassifizierungen, gefilter werden.
* OGC Styled Layer Descriptors (SLD), eine Spezifikation, die es ermöglicht die Kartengestaltung eines entfernten WMS zu beeinflussen.

Die Website des OGC ist unter~[[http:website:ogc]] zu erreichen. Zu allen genannten Diensten, und zu vielen weiteren, finden Sie dort auch die Spezifikationen als PDF-Dateien. Sehen Sie sie sich ruhig einmal an. Nachdem Sie die ersten 20 bis 30 Seiten überblättert haben, finden Sie vor dem Anhang die interessanten Informationen auf meist wenigen Seiten zusammengefasst.

=Warum macht man das?=
--[[User:Jtmapmedia|Jtmapmedia]] 13:56, 10 January 2009 (UTC)

Eine berechtigte Frage ist natürlich, warum man diese Funktionalität überhaupt haben wollen könnte. Die Antworten sind vielfältig. Hier einige Beispiele:

\subsubsection* {'''Kein Zugang zu den Originaldaten'''}

Die wenigsten Besitzer von Geodaten rücken diese umsonst, oder überhaupt heraus. Manche sind allerdings durchaus gewillt, Karten auszuliefern; ihre Originaldaten kommen dabei nicht an die Öffentlichkeit. Durch die Bereitstellung von Karten nach den Kriterien des WMS sind darüberhinaus nicht nur Sie, sondern auch andere in der Lage, Karten aus der 'schwierigen Quelle' zu beziehen. Die Existenz eines Standards kann also schon zur Verbreitung von Kartenmaterial beitragen.

\subsubsection*{'''Lastenverteilung'''}

Ähnlich wie bei Datenbankanbindungen -- siehe auch Kapitel~\ref{text:database} -- kann beispielweise ein WMS-konformes zur Verteilung von Rechenlast beitragen, indem einzelne Layer der Karte einfach auf verschiedene Rechner verteilt werden.

\subsubsection*{'''Herstellerunabhängigkeit'''}

Durch ein standardisiertes Kommunikationsprotokoll sind Sie in der Lage, sich den Hersteller Ihrer Software auszusuchen. Umgekehrt bedeutet das auch, dass Sie nicht auf die Software eines bestimmten Herstellers angewiesen sind, wenn beispielsweise auf einen WMS-konformen Server zugegriffen werden soll. Die Wahl der Software kann also eher an anderen Kriterien (z.B. dem Preis) ausgerichtet werden. Heutzutage gibt es eine große Zahl OGC-konformer Programme, die sich nahezu beliebig miteinander verknüpfen lassen, so kann eine als WMS konfigurierter UMN MapServer seine Karte problemlos an verschiedene Klienten sowohl im Browser (z.N. Mapbender, OpanLayers) als auch auf dem Desktop (z.B. Quantum GIS, gvSIG) ausliefern und einen wichtigen Teil zur Geodateninfrastruktur beitragen.

Auf der Website des OGC finden Sie eine Liste von Herstellern und Produkten~[[http:website:ogcnetwork:impl]] und eine Beschreibung, welche Standards in welcher Version von ihnen unterstützt werden.

\subsection*{'''Existenz von Evaluationskriterien'''}

Häufig steht man vor der Frage, welches Produkt man für einen besonderen Zweck einsetzen soll. Das richtige Vorgehen ist natürlich, sich klarzumachen, welche Eigenschaften und Möglichkeiten die Software bieten soll, und anhand einer daraus hervorgehenden Liste kann man dann verschiedene Produkte evaluieren.

Solch ein Evaluationsvorgang kann zeitlich und finanziell sehr aufwändig sein. Weithin anerkannte Standards helfen dabei, Entscheidungen anhand fertig vorliegender Kriterienkataloge zu treffen.

= Wie macht man das? =
--[[User:Jtmapmedia|Jtmapmedia]] 18:00, 10 January 2009 (UTC)

Eine UMN MapServer-Anwendung OGC-konform zu gestalten ist keine Hexerei, Sie benötigen nicht einmal eine Erweiterung und müssen auch nichts neu kompilieren - es sind lediglich einige Erweiterungen im Mapfile notwendig. Bevor wir uns aber wieder dem Mapfile zuwenden, ein paar Sätze das grundsätzliche Verständnis der Funktionsweise von OGC-Diensten fördern.

Der Aufruf eines WMS-Servers erfolgt ganz ähnlich dem Aufruf des UMN MapServers, nämlich über einen URL mit den gewünschten Parametern, Sie werden im Folgenden bemerken, dass auch andere Aufrufe, wie WFS oder WCS, dem gleichen Muster folgen. Die Benennung der Parameter, ihr Verhalten und ihre Wirkung unterscheiden sich jedoch mehr oder weniger stark von dem, was Sie bisher von ihrem MapServer gewohnt sind.

Schauen Sie sich einmal einen Aufruf für eine Karte als Beispiel an. Um die Generierung solcher URLs müssen Sie sich im Detail nicht kümmern; wenn Sie einen Server betreiben, dann sowieso nicht, weil der Aufrufende die URLs kennen muss, und nicht Sie; und wenn Sie MapServer als Client betreiben, dann müssen Sie zwar einige Angaben im Mapfile zwingend machen, aber alle dynamischen Parameter werden von MapServer aufgefüllt.

\subsubsection*{'''Hinweis'''} 
In der Version 4.x war MapServer sehr tolerant, einige würden sagen nicht voll OGC-konform, weil er nicht alle Aufrufparameter verlangte, die die Spezifikation vorschreibt. Wenn Sie beim Aufruf eines WMS ab UMN Version einen laut Spezifikation erforderlichen Parameter weglassen, wird das nun mit einer Fehlermeldung quittiert.

Nun aber ein Beispiel für einen WMS-konformen URL des MapServers:

FIXME: Beispielaufruf dem aktuellen OSM/Hamburg-Beispiel anpassen. 
<code>
http://www.example.com/cgi-bin/mapserv
? SERVICE=WMS
& VERSION=1.1.1
& REQUEST=GetMap
& FORMAT=image/png
& LAYERS=gruenflaechen,fluesse,bebauung
& SRS=EPSG:4326
& BBOX=5.0,45.0,15.0,55.0
& WIDTH=500
& HEIGHT=500
& STYLES,,,
#hier enden die Pflichtparameter, Auftritt zweier optionaler Parameter:
& TRANSPARENT=TRUE
& EXCEPTIONS=application/vnd.ogc.se_inimage
</code> 

Sie werden sich jetzt fragen, wo denn der Hinweis auf das Mapfile geblieben ist, den Sie bisher immer mit angeben mussten. Ein Parameter ''map'' ist in der WMS-Spezifikation allerdings nirgends erwähnt. Wie man sich dieses Parameters entledigen kann, erfahren Sie weiter unten auf Seite~\pageref{text:wms:mapfilename}.

Der erste Parameter ''SERVICE'' gibt an, welche Spezifikation genutzt werden soll. Wir möchten eine Karte im PNG-Format abrufen, die im Browser angezeigt werden soll, also benutzen wir den Web Map Service.

Als nächstes wird mit ''VERSION'' angegeben, in welcher WMS-Version man die Kommunikation wünscht. Laut Spezifikation soll dabei im Hintergrund eine Aushandlung der Version stattfinden, falls eine Seite eine angegebene Version nicht kennt; Client und Server handeln sich dann gegenseitig herunter, bis sie auf eine Version treffen, die sie beide verstehen.

Der Parameter ''REQUEST'' gibt die Art der Anfrage an. Die in MapServer implementierten Modi sind bereits weiter oben in Abschnitt~2 genannt worden. Beachten Sie, dass die Schreibweise von ''GetMap'' bezüglich der Klein- und Großbuchstaben irrelevant sein sollte. Das gleiche gilt auch für die Namen der Parameter wie ''VERSION'', ''REQUEST'' und so weiter. Die Großschreibung erfolgt hier nur wegen der besseren Lesbarkeit. Es gibt aber auch Dienste, die diese Schreibweise ewarten.

Die Angabe ''FORMAT'' wird als sogenannter ''MIME type'' gemacht, eine standardisierte Notation für die Art von über das Netz geschickten Daten. Bildformat folgen prinzipiell dem Muster ''image/'' plus angehängtem Namen des Bildformats, also zum Beispiel ''image/jpeg'' für JPEG-Bilder. Mehr über MIME-Typen inklusive Links zu den diversen zuständigen RFCs finden Sie auf~[[http:homepage:mime]].

Es folgen die Layer, die angezeigt werden sollen. Anders als beim 'klassischen' MapServer, wo die Layernamen einzeln jeweils mit ''layer'' notiert werden, wird bei WMS-konformen Servern eine Liste der gewünschten Layer benötigt, wobei die einzelnen Layer durch Kommata voneinander getrennt werden. Dabei ist die Reihenfolge wichtig: der zuerst genannte Layer wird als erste Ebene in die Karte gezeichnet, liegt also zuunterst. Die im Mapfile festgelegte Reihenfolge spielt keine Rolle mehr.

Mit ''SRS'' wird das ''spatial reference system'' definiert, also die gewünschte Projektion angegeben. WMS verlangt EPSG-Codes für die Notierung der Projektion, wobei das Schlüsselwort ''EPSG'' und die dazugehörige Zahl durch einen Doppelpunkt voneinander getrennt werden. Mehr zu diesem Thema, das oft zu schwer identifizierbaren Fehlern führt und einige Nerven kosten kann, finden Sie im Anhang FIXME: Verweis auf den noch zu erstellenden Anhang.

''BBOX'': Ähnlich wie die anzuzeigenden Kartenebenen werden auch die gewünschten Extents durch mehrere Werte angefordert, die in einer Liste durch Kommata voneinander getrennt sind. Achten Sie immer darauf, dass die Werte der BBOX mit dem SRS korrespondieren.

''WIDTH'' und ''HEIGHT'' geben die Größe in Pixeln vor, die die fertige Karte haben soll. Beachten Sie, dass diese Werte mit der BBOX korrelieren müssen; eine quadratische BBOX in Verbindung mit ungleicher Höhe und Breite führt zu einer Verzerrung des Kartenbildes.

Der Parameter ''STYLES'' gibt für jeden Layer eine Darstellungsoption an (sofern der Provider des Service dieses mit den sog. ''Named Styles'' vorbereitet hat). Sie müssen keine Styles angeben, der Parameter im GetMap-Aufruf ist jedoch Pflicht.

Mit ''TRANSPARENT'' wird die Hintergrundfarbe der Karte transparent geschaltet. Das will man offensichtlich dann haben, wenn man unter dieser Kartenebene noch andere Layer anzeigen möchte.

Schließlich und endlich wird dem WMS im obigen Beispiel mitgeteilt in welcher Form Fehlermeldungen ausgegeben werden, in unserem Fall soll die Fehlermeldung in resultierende Rasterbild gerendert werden. Wenn Sie eine XML-formatierte Fehlermeldung bevorzugen verwenden Sie ''application/vnd.ogc.se_xml''.

Das Ergebnis dieses Aufrufes ist also eine 500 mal 500 Pixel große, auf EPSG-Code FIXME: 4326 projizierte Karte im PNG-Format mit den angegebenen Extents und transparentem Hintergrund. Der aufrufende URL dieser Karte kann entweder so bei Ihnen im Webbrowser erscheinen, oder aber von MapServer dynamisch für die Anzeige als Rasterlayer generiert worden sein.

Als nächstes schauen wir uns an, wie aus einem bestehenden Mapfile eines gemacht werden kann, das für WMS-konformes Verhalten nach außen sorgt.

=Web Map Service (WMS)=
==UMN als WMS Server==

Von besonderem Interesse ist die ''OpenGIS Web Map Server Interfaces Implementation Specification'' , im folgenden kurz WMS-Standard genannt. Diese Spezifikation liegt inzwischen in der Version 1.1.1~[[pdf:spec:ogc111]] vor. MapServer unterstützt aber auch die zurückliegenden Standards 1.0.0~[[pdf:spec:ogc100]] und 1.1.0~[[pdf:spec:ogc110]].

Sinn der WMS-Spezifikation ist es, ein offenes, definiertes Interface sowohl für Clients als auch für Server zur Verfügung zu stellen, die Karten und Daten über diese Karten miteinander austauschen wollen. Zur Kommunikation zwischen den Servern und Clients wird das HTTP-Protokoll verwendet. Über das Protokoll werden Daten im XML-Format übertragen\footnote{Für Exceptions sind auch andere Formate möglich.}. Parsen und weiterverarbeiten läßt sich XML in fast jeder bekannten Programmiersprache. Auf diese Weise ist man nicht an Webapplikationen gebunden, wenn man ein Programm entwickeln möchte, das mit einem WMS-Mapserver 'redet'. Die dazugehörige DTD\footnote{Die sogenannten ''document type definitions'' dienen der Validierung von Dokumenten. Sie können ein DTD also benutzen, um zu testen, um ein Dokument einem bestimmten Rahmen an Vorgaben genügt.} ist vom OGC zu beziehen und in der Spezifikation beschrieben. Gedruckt lernen Sie mehr über XML durch die Lektüre von~[[ray:2001:xml]], online finden Sie die Spezifikationen unter~[[http:homepage:xml]].

\subsubsection*{Hinweis}

Eine zentrale Rolle bei der Verwendung von WMS spielt die Umprojizierung von Daten. Da bei WMS Rasterdaten zum Einsatz kommen\footnote{Die Datenquelle für den Server kann natürlich ein Vektorformat haben. Produziert werden aber ausschließlich Rasterdaten, wie wir es bisher immer beim MapServer gesehen haben.}, und MapServer Rasterdaten ausschließlich unter Zuhilfenahme der Bibliothek GDAL umprojizieren kann, sollten Sie MapServer mit der Unterstützung für GDAL kompiliert haben.

==Servermodi==(2)

Die genannten Spezifikation in ihrer letzten Version verlangt: es ''müssen'' zwei Arten von Anfragen implementiert sein, zwei weitere sind optional und ''können'' implementiert sein. Die beiden folgenden Anfragen (weiterhin auch ''Requests'' genannt) müssen vorhanden sein:

*=getCapabilities= : Diese Anfrage muss ein XML-Dokument zurückliefern, das die Fähigkeiten des Mapservers beschreibt.
*=getMap= : Auf diese Anfrage wird eine Karte als Rasterbild zurückgeliefert.

Entsprechend der Anforderung sind diese beiden Anfragen auch im MapServer implementiert.

Die beiden Fähigkeiten, die implementiert sein ''können'' , sind:

*=getFeatureInfo= : auf diese Anfrage liefert der Mapserver Informationen über einen bestimmten Punkt in einer Karte zurück. Diese Informationen können entweder in einer reinen Textdarstellung oder in GML (einem XML-Format) zurückgegeben werden.
*=describeLayer= liefert ein XML-Dokument mit detaillierten Informationen über einen Layer zurück. Dieser Modus wäre für einen SLD\footnote{Styled Layer Descriptor}-konformen MapServer interessant, aber dieser Standard hat bisher noch keine Umsetzung im MapServer erfahren.

Das einzige Feature, das im MapServer zurzeit nicht implementiert ist, ist demnach =describeLayer= . Es gibt noch einige andere Modi; mehr dazu in Abschnitt~7

==WMS-Metadaten im Mapfile==\index{Metadaten}

Zuallererst benötigt ihr Mapfile einen Namen. Im Header muß also der Parameter =NAME= definiert sein.

Einen 'minimalen' WMS-Server erhalten Sie zum einen durch Metadaten in der =WEB= -Sektion des Mapfiles, zum anderen durch Metadaten in den einzelnen Layern. Einige davon sind zwingend erforderlich, andere optional. Wie die Notation von Metadaten im Mapfile generell erfolgt, haben Sie bereits in Abschnitt~\ref{text:mapfile:web:meta} erfahren.

 <code>
WEB
...
METADATA
"wms_title" "Ein WMS-Server"
"wms_onlineresource" \
"http://www.example.com/cgi-bin/mapserv?map=mapfile.map&"
"wms_srs" "EPSG:31464 EPSG:4326"
END
END
</code> 

Der =wms_title= ist der Titel für die Karte, dieser muß angegeben werden. Der zweite Parameter gibt an, unter welchem URL der Server aufzurufen ist.

Beachten Sie dabei, das =\&= anzugeben, bzw. ein Fragezeichen, wenn Sie nach dem eigentlichen CGI-Programm keinen Parameter zu stehen haben.

=wms_srs= steht für die Projektion, in der die Karten angeboten werden können. Die Spezifikation schreibt vor, dass hier immer mindestens EPSG-Code 4326 angeboten werden muß. Mehrere Projektionen werden einfach durch Leerzeichen voneinander getrennt. Mehr zu EPSG und Projektionen im allgemeinen haben Sie schon in Abschnitt~\ref{text:map:projections} erfahren.

Sie benötigen =wms_srs= nicht, wenn Sie für die Karte einen Projektionsblock mit EPSG-Angabe definiert haben; die =WEB= -Sektion 'erbt' dann diese Projektion als Vorgabe.

Was machen Sie, wenn Ihre Daten allesamt in einer Projektion vorliegen, für die es keinen EPSG-Code gibt? Dann können Sie einen =PROJECTION= -Block definieren, der Parameter für die Projektionsbibliothek ''proj.4'' enthält (das Beispiel stammt direkt aus der MapServer-Dokumentation):

 <code>
PROJECTION
"proj=lcc"
"ellps=GRS80"
"lat_0=49"
"lon_0=-95"
"lat_1=49"
"lat_2=77"
END
</code> 

Wenn Sie nun EPSG-Codes in =wms_srs= nach außen anbieten, werden die Daten automatisch umprojiziert.

\subsubsection*{Notwendige Metadaten in den Layern}

Des weiteren müssen nun in jedem Layer zusätzliche Angaben nach folgendem Muster gemacht werden:

 <code>
LAYER
NAME "einlayer"
...
METADATA
"wms_title" "Titel fuer den Layer"
"wms_srs" "EPSG:31494"
END
END
</code> 

Daneben muß auch in jedem Layer ein Name gesetzt und eine Projektion definiert sein. Als Standardvorgabe erbt jeder Layer die Projektionen aus der =WEB= -Sektion, sodass sie nicht noch einmal neu notiert werden müssen.

Sie benötigen natürlich immer noch eine Projektionsangabe im Layer in Form eines =PROJECTION= -Blocks, um zu definieren, in welcher Projektion die Datenquelle vorliegt, damit MapServer im Zweifelsfall korrekt projizieren kann. Das gilt natürlich insbesondere dann, wenn Sie mehr als nur eine Projektion anbieten wollen.

MapServer geht im übrigen davon aus, dass sie tatsächlich alle Layer im Mapfile nach außen zur Verfügung stellen wollen. Layer, die sie ''nicht'' nach außen geben wollen, haben also in diesem Mapfile nichts verloren. Es gibt bisher keinen Mechanismus, mit dem man einzelne Layer (oder alle) in einem Mapfile von der Auslieferung per WMS ausschließen kann.

\subsubsection*{Metadaten in der Web-Sektion}

Im folgenden sind alle Metadaten beschrieben, die Sie für einen WMS-konformen Server in der =WEB= -Sektion des Mapfiles notieren können. Alle Angaben sind optional, falls nicht anders angegeben.

*=wms_abstract= Eine elaborierte Zusammenfassung dessen, was der Server soll und ist.
*=wms_accessconstraints= Gibt Zugangsbeschränkungen für den MapServer an. Beachten Sie bitte, dass ein Eintrag hier lediglich eine Absichtserklärung ist. Ein Text wie 'Dieser Server darf nur im Intranet unserer Firma verwendet werden' ist natürlich schön und gut, aber die entsprechenden Zugriffsbeschränkungen sind selbtsverständlich nur durch die entsprechende Konfiguration der Systeme zu erreichen.
*=wms_addresstype= Art der Adresse. Für dieses und die folgenden fünf Felder gilt, dass bei Angabe eines der Felder auch die anderen fünf mit Inhalt gefüllt werden müssen.
*=wms_address= Die Adresse.
*=wms_city= Adressbestandteil: Stadt
*=wms_country= Adressbestandteil: Land
*=wms_postcode= Adressbestandteil: Postleitzahl
*=wms_stateorprovince= Adressbestandteil: Staat oder Provinz
*=wms_contactelectronicmailaddress= Emailadresse einer Kontaktperson für diesen Server
*=wms_contactoraganization= Organisation der Kontaktperson
*=wms_contactperson= Name der Kontaktperson für diesen Server
*=wms_contactposition= Position der Kontaktperson innerhalb ihrer Organisation
*=wms_contactvoicetelephone= Telefonnummer der Kontaktperson
*=wms_fees= Art und Umfang der Gebühren, die für die Nutzung dieses Servers fällig werden. Genau wie bei =wms_accessconstraints= ist dies lediglich eine Absichtserklärung; wenn Sie Gebühren für die Verwendung des Servers erheben möchten, müssen Sie die Zugriffskontrolle durch eine geeignete Systemkonfiguration und ein passendes Geschäftsmodell herbeiführen.
*=wms_keywordlist= Eine Liste von Schlüsselworten, die auf den Server zutreffen. Dieser Parameter ist mit dem Blick darauf geschaffen worden, dass es eines Tages in einer eigens dafür geschaffenen Datenbank eine Sammlung von Capabilities-Dokumenten geben könnte, die dann die Schlüsselwortlisten durchsuchen kann. Bisher gibt es keine solche Datenbank. Es sind auch keine Standardschlüsselwörter definiert.
*=wms_onlineresource= Der URL, mit dem der Server aufgerufen wird. Beinhaltet beim UMN MapServer meistens: <code> http://www.example.com/cgi-bin/mapserv? </code> und gegebenenfalls daran angehängt noch das Mapfile. Wenn ein Mapfile über =map== angehangen wird, darf nicht das abschließende =\&= vergessen werden! Dieser Parameter ist zwingend notwendig.
*=wms_resx= Horizontale Auflösung der Karte in Pixeln.
*=wms_resy= Vertikale Auflösung der Karte in Pixeln.
*=wms_srs= Projektion(en), in der die Karte angeboten werden kann. Dieser Parameter mit mindestens einer Projektion ist zwingend notwendig.
*=wms_title= Titel der Karte. Dieser Parameter ist zwingend notwendig.

\subsubsection*{Metadaten in den einzelnen Layern}

Im folgenden die Metadaten, die Sie für einen WMS-konformen MapServer in den einzelnen Layern im Mapfile definieren können. Alle Parameter sind optional, sofern nicht anders angegeben.

*=wms_abstract= Elaborierte Zusammenfassung dessen, was dieser Layer soll und ist.
*=wms_extent= Die Bounding Box des Layers.
*=wms_keywordlist= Eine Liste von Schlüsselworten, die auf diesen Server zutreffen. %
*=wms_opaque= FIXME: was ist das?
*=wms_srs= Projektion(en), in der die Karte angeboten werden kann.
*=wms_title= Titel des Layers. Dieser Parameter ist zwingend erforderlich.

\subsubsection*{Das Mapfile als Parameter}(4)

Der Name des Mapfiles in der URL-Zeile ist nicht Bestandteil eines OGC-konformen Aufrufs des Mapservers. Unter Sicherheitsaspekten kann es darüber hinaus eventuell nicht angebracht sein, dem Client etwas über die Verzeichnisstruktur des Server-Systems zu verraten.

Im Moment gibt es zwei verschiedene Wege, den Ort des Mapfiles vor Außenstehenden zu verbergen:

*''Verwenden eines Wrapper-Skripts'' : Anstatt des CGI-Binaries wird ein kleines Skript aufgerufen, das die Umgebungsvariable = MS_MAPFILE = setzt und dann seinerseits das CGI-Programm aufruft. Ganz primitiv könnte ein solches Skript für die Shell =bash= etwa wie folgt aussehen: <code> #!/bin/sh MS_MAPFILE=/usr/local/there/is/my.map export MS_MAPFILE /usr/local/httpd/cgi-bin/mapserv </code> Beachten Sie bitte, dass dieses Beispiel nur für Unix-Systeme funktioniert, auf denen die Shell =bash= installiert ist. Für andere Shells kann die Notation abweichen.
*''Webserver-Konfiguration'' : Der Webserver ist unter Umständen in der Lage, für bestimmte aufgerufene URLs spezifische Umgebungsvariablen zu setzen. Im Apache sähe ein Eintrag in der Datei ''httpd.conf'' dann beispielsweise folgendermaßen aus (wegen der Zeilenlänge für das Drucklayout umgebrochen, muß in der Konfigurationsdatei eine Zeile sein): <code> SetEnvIf Request_URI "/cgi-bin/mapserv" \ MS_MAPFILE=/usr/local/there/is/my.map </code> Dieser Eintrag funktioniert nur im Apache und kann für andere Webserver vollkommen anders aussehen. Konsultieren Sie Ihre Dokumentation.

\subsubsection*{getCapabilities}(5)

Nachdem man zufrieden mit seinem Setup ist, möchte man es natürlich ausprobieren. Dazu ruft man als erstes das ''Capabilities'' -Dokument ab:

 <code>
http://server/cgi-bin/mapserv?VERSION=1.1.0&REQUEST=getCapabilities \
&map=mapfile.map
</code> 

Dabei müssen Sie bei =getCapabilities= nicht auf Groß- oder Kleinbuchstaben achten. Ebensowenig bei allen anderen Parametern, die vor einem Gleichheitszeichen stehen.

Der Webserver sollte Ihnen nun eine Datei des Typs =application/vnd.ogc.wms_xml= zurückliefern. Diese Textdatei können Sie abspeichern und in einem beliebigen Texteditor öffnen. Eventuell ist Ihr Webbrowser auch von sich aus in der Lage, XML-Dateien automatisch in einem ansprechenden Layout darzustellen.

Schauen Sie sich nun den Inhalt der Datei genau an. Wo immer Sie auf Zeilen treffen, die

 <code>

</code> 

beinhalten, gilt es, etwas zu bereinigen. Beispielsweise erfahren Sie aus einer Warnung wie dieser:

 <code>

</code> 

dass Sie einen Meta-Tag für den Titel der entsprechenden Sektion vergessen haben.

Sobald Sie keine Warnungen dieser Art mehr in Ihrem Capabilities-Dokument finden, ist ihr MapServer WMS-konform und voll einsatzbereit.

\subsubsection*{getMap}

Wenn die Capabilities wie erwartet geliefert werden, ist der nächste logische Schritt natürlich, sich eine Karte von Hand abzuholen. Dafür konstruieren Sie sich in Ihrem Webbrowser einen Aufruf, der etwa so aussieht, wie das Beispiel in Abschnitt~3. Dabei machen Sie sich dann auch gleich mit der Benennung der Parameter vertraut.

Das beste was Ihnen passieren kann, ist natürlich, dass Sie gleich ihre gewünschte Karte bekommen. Dann sind Sie natürlich fertig. Sobald Sie jedoch Ihren ersten Fehler machen, müssen Sie sich mit Fehlermeldungen auseinandersetzen, den so genannten Exceptions.

==Exceptions==\index{Exceptions}\index{WMS!Exceptions}

Exceptions sind Meldungen, die von einem WMS-konformen Mapserver im Fehlerfall ausgegeben werden müssen. Das entspricht in etwa dem Expcetions-Konzept diverser Programmiersprachen wie z.B. Java. Der Sinn ist es, dem aufrufenden Client -- sei es nun eine menschliche Person, sei es eine Software -- anhand des Typs und des Inhalts der Fehlermeldung eine Entscheidung über das weitere Vorgehen treffen zu können. Eine solche Art der Fehlerbehandlung verhindert natürlich unter anderem, dass ein Programm seine Durchführung im Fehlerfall einfach beendet.

Wenn Sie bei einem WMS-konformen Aufruf einen Fehler machen, indem Sie beispielsweise einen Parameternamen wie =REQUEST= absichtlich falsch schreiben, wird Ihnen MapServer eine Datei in einem XML-Format zurückliefern:

*=application/vnd.ogc.se_xml= Ein WMS-konformer Mapserver muß mindestens diese Art der Vermittlung von Exceptions beherrschen. Solch eine Datei kann beispielsweise folgenden Inhalt haben: <code> <?xml version='1.0' encoding="ISO-8859-1" standalone="no" ?> <!DOCTYPE ServiceExceptionReport SYSTEM "http://www.digitalearth.gov/wmt/xml/exception_1_1_0.dtd"> <ServiceExceptionReport version="1.1.0"> <ServiceException> msWMSDispatch(): WMS server error. Incomplete WMS request: REQUEST parameter missing </ServiceException> </ServiceExceptionReport> </code> 

\begin{figure}
\begin{center}
\mmfig{0.6}{wms-exception-inimage}{Exception vom Typ application/vnd.ogc.se_inimage.}
\end{center}
\end{figure}

Des weiteren kann ein Mapserver Exceptions in den folgenden MIME-Typen zur Verfügung stellen:

*=application/vnd.ogc.se_inimage= Die Exception wird als Text in das auszuliefernde Bild eingefügt.
*=application/vnd.ogc.se_blank= Die Spezifikation geht von der Idee, dass ein leeres Bild etwas ist, dass man grundsätzlich nicht haben möchte, und somit nie bekommt. Daher kann ein 'leeres' Bild als Fehlermeldung angesehen werden. Als 'leeres' Bild ist ein Bild definiert, das ganz mit der Hintergrundfarbe der Karte ausgefüllt ist.

Im URL des Aufrufs wird die gewünschte Art der Exception mit dem Parameter =EXCEPTIONS= notiert. Wollen Sie Exceptions also im Bild notiert haben, schreiben Sie in Ihrem URL:

 <code>
... & EXCEPTIONS=application/vnd.ogc.se_inimage & ...
</code> 

Beachten Sie bitte, dass nur die XML-Variante implementiert sein muß. Wenn Sie von einem Server Exceptions im Bild verlangen, er aber nur XML kann, dann wird er XML liefern.

Beachten Sie außerdem, dass das Handling von Exceptions insbesondere bei Kaskaden von WMS-konformen Servern eine Rolle spielt. So kann es Ihnen passieren, dass Sie sich einen Layer von einem Server holen, der sich wiederum sein Bild von anderen entfernten Quellen heranholt, und von dort im Fehlerfall eine Exception in das Bild eingetragen bekommt. Dadurch haben Sie die Fehlermeldung dann natürlich auch im Bild zu stehen.

===Hinweis===

Viele Kartenanbieter tendieren dazu, ihre fertigen Karten mit Schriftzügen, Logos, Nordpfeilen, Wasserzeichen und so weiter auszustatten. Denken Sie immer daran, dass der Kunde, der Ihren Service wiederum als Datenquelle benutzt, eventuell auf die Idee kommt, die von Ihnen bezogene Karte umzuprojizieren! Das kann dann zu interessanten Effekten führen, wenn dann Dritte den Schriftzug mit der URL Ihrer Firmenwebsite quer über die ganze Karte gekrakelt bekommen. Entwickeln Sie im Vorhinein zusammen mit den Benutzern des Service ein Konzept, dass solche häßlichen Effekte verhindert.

==getFeatureInfo==

Sich Karten einfach nur anzusehen, ist selbstverständlich nur die Hälfte des Reizes eines WMS-konformen Servers. Man möchte selbstverständlich auch Queries auf die Daten durchführen können. Zu diesem Zweck gibt es den =REQUEST= mit dem Namen =getFeatureInfo= .

Zuerst einmal gilt es, Queries überhaupt erst einmal zuzulassen. Wie schon bei den 'klassischen' Queries (siehe Abschnitt~\ref{text:mapfile:queries}) kann man in MapServer eine Query nur auf einem Layer durchführen, der ein =TEMPLATE= definiert.

Wenn man das tut, und sich die ''capabilities'' anschaut, wird man für den Layer auf ein Attribut der folgenden Art treffen:

 <code>
<Layer queryable="1" opaque="0" cascaded="0">
</code> 

Der Wert =1= für =queryable= zeigt im Gegensatz zum Wert =0= an, dass Queries auf diesen Layer zulässig sind.

Um einen Aufruf vom Typ =getFeatureInfo= zu verstehen, betrachten wir einmal einen vollständigen URL für diesen Vorgang:

 <code>
http://www.example.com/cgi-bin/mapserv
? map=/usr/local/mapserv/mapfile.map
& VERSION=1.1.0
& REQUEST=getFeatureInfo
& QUERY_LAYERS=gruenflaechen
& SRS=EPSG:4326
& BBOX=5.0,45.0,15.0,55.0
& WIDTH=500
& HEIGHT=500
& X=250
& Y=250
& INFO_TYPE=text/plain
</code> 

Einige Bestandteile sind dem Leser bereits bekannt: Version des Standards, Angabe der Projektion durch =SRS= . Dazu kommt, wenig überraschend, die Angabe des =REQUEST= .

Da jetzt keine Darstellung mehr erfolgen sollen, werden keine =LAYERS= mehr angegeben, sondern =QUERY_LAYERS= \footnote{Diese Unterscheidung ist offensichtlich eigentlich unnötig, da man die Funktion der Layerangabe ja eigentlich serverseitig aus dem =REQUEST= schließen könnte.}. Um Ergebnisse zu liefern, muß jeder Layer in der Liste =QUERY_LAYERS= das Attribut =queryable= auf =1= gesetzt haben -- siehe oben.

Zwingend sind darüberhinaus die Angabe der Extents des Bildes, das man befragen möchte (angegeben mit =BBOX= ), Breite und Höhe des Bildes sowie die X- und die Y-Koordinate des Punktes im Bild, der sich der Aufmerksamkeit des Users erfreut, beispielsweise durch einen Mausklick. Beachten Sie, dass es sich dabei um Bildkoordinaten handelt, es handelt sich also um Pixelwerte. Der Koordinatenursprung eines Bildes ist links oben.

Am interessantesten ist natürlich der =INFO_TYPE= , der angibt, auf welche Weise die Queryergebnisse formatiert sein sollen. MapServer unterstützt die folgenden Formate:

*=text/plain= , das Standardformat, falls Sie nichts anderes angegeben haben;
*=text/html= , was ein wenig Vorbereitung erfordert, im wesentlichen aber wie Queries auf einem 'normalen' MapServer-CGI behandelt wird; und
*=application/vnd.ogc.gml= , GML, eine XML-Repräsentation für Geodaten.

Betrachten wir die Formate im Detail:

\subsubsection*{text/plain}

Dieser Ausgabetyp für getFeatureInfo ist die Voreinstellung für MapServer, falls Sie keinen anderen Ausgabentyp spezifizieren.

Für ein Mapfile mit den Voreinstellungen des Itasca-Demos und einem fiktiven Anklickpunkt mit den Koordinaten 200/200 sieht die Ausgabe folgendermaßen aus:

 <code>
GetFeatureInfo results:

Layer 'countyboundary'
Feature 26:
AREA = '7577272785.15393'
PERIMETER = '436617.07762'
CTY_NAME = 'Itasca'
COUN = '31'
CTY_ABBR = 'ITAS'
ISLAND = 'N'
CTY_FIPS = '61'
RECNO = '27'
</code> 

Es wird der Name des Layers ausgegeben, die Nummer des Layers innerhalb des Shapefiles, und dann alle Attribute aus der =.dbf= -Datei der Datei. Wenn es mehrere Suchergebnisse gegeben hat, werden diese der Reihe nach dargestellt.

\subsubsection*{text/html}

Mit diesem Ergebnistyp greift MapServer auf die HTML-Templates zurück, die Sie für Queries bereits in Kapitel~\ref{text:mapfile} kennengelernt haben. Das bedeutet, dass Sie ein HTML-Layout ganz nach Ihrem Geschmack gestalten können, und MapServer die entsprechenden Tags in eckigen Klammer wie gewohnt ersetzt.

Dieser ''MIME type'' bietet jedoch noch die Möglichkeit für zusätzliche Tricksereien. Der Standard schreibt nämlich keinen ''MIME type'' zwingend vor, und ebensowenig gibt es ein vorgeschriebenes Verhalten für den Fall, dass ein bestimmter Typ nicht unterstützt wird. Das führt dazu, dass MapServer es sich vorbehält, beliebige Arten von Daten zurückzuliefern.

Sie können ein =TEMPLATE= definieren, das nicht gezwungenermaßen eine HTML-Seite sein muß. Reiner ASCII-Text wäre ebenso möglich, oder alle anderen Formate, in denen Sie MapServer-Tags ersetzen können.

Sobald das Template beliebigen Formats von MapServer bearbeitet worden ist, kann das Resultat zurückgeliefert werden. Wenn man jetzt reinen ASCII-Text hat, würde MapServer ihn jedoch als =text/html= ausliefern, und das ist eigentlich nicht das, was man möchte. Der Client (also z.B. Webbrowser) interpretiert die Daten natürlich nur korrekt, wenn man ihm den korrekten MIME type liefert. Daher kann man im Mapfile für die zurückgegebenen Daten einen eigenen Metadatum den geeigneten Typ setzen:

 <code>
WEB
...
METADATA
...
"wms_feature_info_mime_type" "text/plain"
END
END
</code> 

Also noch einmal zusammenfassend: der Benutzer kann zwar von außen den =INFO_TYPE= auf =text/html= setzen; MapServer kann jedoch mit Daten beliebigen Typs antworten.

\subsubsection*{application/vnd.ogc.gml}

Damit ein Layer in diesem Format Anfragen beantworten kann, muß außerdem der Parameter =DUMP= in diesem Layer gesetzt sein:

 <code>
LAYER
...
DUMP TRUE
END
</code> 

Falls es keine Suchresultate gegeben hat, wird zwar eine Datei im korrekten Format zurückgegeben, die allerdings nur die korrekten Header enthält und ansonsten leer ist.

Für Suchergebnisse werden in diesem Format immer die Koordinaten des Features gleich mitgeliefert. Antworten können also bei großen Features nicht nur auf sich warten lassen, da MapServer für das Erzeugen großer Dokumente natürlich eine Weile braucht, sondern auch weil der Transfer über das Netz natürlich ein bißchen dauert.

Die Anfrage auf den Flughafen-Layer der Itasca-Demodaten beispielsweise liefert in den voreingestellten Extents und dem fiktiven Klick auf die Koordinate 224/75 das folgende Ergebnis:

 <code>
<?xml version="1.0" encoding="ISO-8859-1"?>

<msGMLOutput
xmlns:gml="http://www.opengis.net/gml"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance">
<countyboundary_layer>
<countyboundary_feature>
<AREA>7577272785.15393</AREA>
<PERIMETER>436617.07762</PERIMETER>
<CTY_NAME>Itasca</CTY_NAME>
<COUN>31</COUN>
<CTY_ABBR>ITAS</CTY_ABBR>
<ISLAND>N</ISLAND>
<CTY_FIPS>61</CTY_FIPS>
<RECNO>27</RECNO>
<gml:boundedBy>
<gml:Box srsName="EPSG:26915">
<gml:coordinates>
393234.393701,5207990.085063
495769.579719,5305374.105135
</gml:coordinates>
</gml:Box>
</gml:boundedBy>
<gml:Polygon srsName="EPSG:26915">
<gml:outerBoundaryIs>
<gml:LinearRing>
<gml:coordinates>
393865.671855,5300138.258409
393869.171975,5300138.258374
394516.694141,5300137.439369
395522.728579,5300136.241770
[...]
</code> 

Und so weiter, mit allen Punkten des Features.

==WMS Clients==\index{OGC!Client}(6)

WMS-konforme Mapserver lassen sich kaskadieren, indem einzelne Layer einfach als fertige Bilder von anderen WMS-konformen Mapservern bezogen werden. Durch die standardisierte Schnittstelle ist dafür kein UMN MapServer nötig. Sie können einzelne Layer beispielsweise auch von einem ESRI ArcIMS beziehen, wenn Sie möchten.

Neben der schönen Möglichkeit, die Standorte und somit Pflege einzelner Teile der Kartenerzeugung voneinander trennen zu können, indem man beispielsweise die Bodenproben von einem Amt und die hydrogeologischen Karten von einem anderen Amt miteinander über eine genormte Schnittstelle verbindet, ist ein weiteres offensichtliches Einsatzfeld natürlich die Lastenverteilung. Datenbestände, die erst umprojiziert werden müssen, können auf leistungsfähigere Server ausgelagert werden, während einfache Operationen wie beispielsweise die simple Darstellung von Rasterbildern von schwächeren Geräten übernommen werden kann\footnote{Beachten Sie dabei immer, dass zur Erzeugung des fertigen Bildes ''immer'' auf den langsamsten Layer gewartet werden muß, da ja das Bild ansonsten nicht komplett ist.}.

Im folgenden soll betrachtet werden, wie Sie einen Layer in einem Mapfile erstellen, damit er dynamisch Daten von einem WMS-konformen Server bezieht. Nach außen hin verhält sich dieser Layer dann wie jeder andere Rasterlayer auch.

\subsubsection*{Installation und Konfiguration}

Wie weiter hinten im Kapitel 'Installation' ab Seite~\pageref{text:installation} beschrieben, ist die Fähigkeit, als WMS-Client zu fungieren, nicht als Voreinstellung bei der Kompilierung gegeben, sondern muß explizit angefordert werden. Wie das genau gemacht wird, und welche Voraussetzungen gegeben sein müssen, ist in Abschnitt~\ref{text:installation:compile:wmsclient} erklärt.

\subsubsection*{getMap}

Der erste Schritt ist, sicherzustellen, dass der anzusprechende Server funktioniert und die gewünschten Daten ausliefert. Dafür holt man sich das Capabilites-Dokument dieses Servers. Wie das zu tun ist, ist auf Seite~\pageref{text:wms:getcapabilities} beschrieben.

Nun weiß man alles über die Fähigkeiten des Servers (welche Projektionen angeboten werden, wie seine Layer heißen und so weiter) und kann sich darum kümmern, eine erste Karte zu holen, um zu sehen, ob die Darstellung dem entspricht, was man erwartet. Dazu richtet man mit seinem Webbrowser eine =getMap= -Anfrage an den Server.

Wie so eine Anfrage aufgebaut sein muß, wurde bereits in Abschnitt~3 gezeigt. Ersetzen Sie allerdings alle Werte für die Parameter durch diejenigen, die Sie im abgerufenen Capabilities-Dokument gefunden haben, also durch korrekte Projektionen, Layernamen, Extents und so weiter. Sobald dieser Aufruf eine Karte in Ihrem Browser zaubert, wissen Sie, dass Sie gültige Werte besitzen und sie korrekt notiert haben, sodass Sie diese Angaben jetzt in einen Layer in Ihr Mapfile einbauen können.

\subsubsection*{Das Mapfile}

Zunächst benötigen Sie einen =PROJECTION= -Block für Ihre Karte. Sie können auf diesen Block verzichten, wenn alle Layer in der gleichen Projektion vorliegen und auch die von Ihnen angesprochenen WMS-Server nur diese eine Projektion unterstützen.

Beachten Sie, dass Sie in der =WEB= -Sektion Ihres Mapfiles einen =IMAGEPATH= -Parameter benötigen, da die Bilder von entfernten Servern als temporäre Dateien gespeichert werden müssen. Diese temporären Dateien werden übrigens nach Verwendung gleich wieder gelöscht, sodass Sie sie kaum bemerken werden.

Für WMS-konforme Anfragen an andere Server sind lediglich die Layerdefinitionen anzupassen. Dabei kommt ein =CONNECTIONTYPE= mit dem Namen =WMS= zum Einsatz:

 <code>
LAYER
NAME "Gewaesser"
TYPE RASTER
STATUS ON
CONNECTIONTYPE WMS
CONNECTION "http://www.example.com/cgi-bin/mapserv?"
METADATA
"wms_title" "Gewaesser"
"wms_server_version" "1.1.0"
"wms_srs" "EPSG:4326 EPSG:31464"
"wms_name" "seen,kanaele,fluesse,baeche"
"wms_format" "image/png"
END
PROJECTION
"init=epsg:31464"
END
END
</code> 

Wie Sie sehen, ist der URL selber sehr kurz gehalten. Er entspricht der ''onlineresource'' aus dem Capabilities-Dokument eines WMS-konformen Servers.

Alle weiteren Details zur Verbindung mit dem entfernten Server werden in Form von Metadaten gemacht. Wer bisher MapServer 3.6 eingesetzt hat, wird das noch anders kennen: in jener Version wurde noch der gesamte Verbindungsstring (bis auf die dynamischen Elemente) in der =CONNECTION= notiert.

Der =wms_title= ist der Titel für diesen Layer, der mit der Anfrage allerdings nichts zu schaffen hat.

Die Version der Anfrage wird mit =wms_server_version= notiert. Mit =wms_srs= geben Sie wieder Projektionen an, allerdings diejenigen, die von der Gegenstelle unterstützt werden.

=wms_name= benennt den oder die Layer, aus denen die bezogene Karte zusammengesetzt werden soll. Mehrere Layer werden durch Kommata voneinander abgetrennt. Beachten Sie, dass bei WMS die Reihenfolge der Ebenen von Belang ist: in unserem Beispiel werden zuerst der Layer =seen= gezeichnet, darauf dann =kanaele= und so weiter.

Das gewünschte Bildformat wird schließlich mit =wms_format= spezifiziert. Es gibt auch den Parameter =wms_formatlist= , der mehrere durch Kommata getrennte Angaben zuläßt.

''Wichtiger Hinweis'' : An keiner einzigen Stelle lädt sich MapServer die Capabilities des entfernten Servers herunter, um sich mit ihnen auseinanderzusetzen. Sie müssen also selber darauf achten, dass die von Ihnen gemachten Angaben stimmig sind.

==Exceptions==

Wenn Sie einen Layer haben, der sich Daten von einem WMS-konformen Server holt, drängt sich natürlich die Frage auf, wie MapServer im Fall von Exceptions reagiert. Eindeutige Antwort: das kommt drauf an.

Am einfachsten ist es offensichtlich, mit Exceptions, die direkt im Bild eingefügt sind, umzugehen, also mit denen, die vom Typ =application/vnd.ogc.se_inimage= sind. Diese werden einfach Bestandteil der fertigen Karte, die Sie im Webbrowser sehen. Im Fehlerfall bemerkt sehr schnell, was Sache ist.

Das gleiche gilt offensichtlich bei =application/vnd.ogc.se_blank= .

Liefert die Gegenstelle ein textbasiertes Format, also zum Beispiel GML zurück, dann gibt es ein Problem, da MapServer davon ausgeht, dass er Rasterdaten als Input erhält; demnach versucht er, das GML-Dokument als Text zu rendern, was natürlich schief geht und somit eine Fehlermeldung erzeugt.

Dieses Problem läßt sich bisher leider auch noch nicht umgehen. Das mindeste, was man also tun kann, ist für eine funktionierende Kommunikation mit dem Betreiber des Quellservers zu sorgen, damit dieser nicht einfach unangekündigt Layernamen ändert, die Ihnen Ihre Applikation wegbrechen lassen.

==Hinweise==(7)

FIXME: das auch noch bei WFS erwähnen

Wenn Sie mit der Administration sowohl des Mapservers, der als Client fungiert, als auch der Serverseite betraut sind, sollten Sie auf alle Fälle darauf achten, keine zirkulären Bezüge zu erzeugen, bei denen Server A einen Layer von Server B bezieht und dieser dann wieder Server A aufruft. Bei komplexen Installationen ist das durchaus eine Fehlerquelle, das Verhalten in diesem Fall ist undefiniert.

Ein weiterer wichtiger Faktor beim Einsatz von WMS-konformer Funktionalität ist die unschöne Tatsache, dass MapServer das Sammeln der Daten für einzelne Layer linear abarbeitet, und nicht mit einem einzelnen Thread oder Prozess pro Layer arbeitet. Das bedeutet, dass MapServer genau ''gar nichts'' tut, während er auf einen Layer aus dem Netzwerk wartet, um dann zum nächsten Layer überzugehen\ldots der dann vielleicht wieder ein solcher Layer ist, oder eine Datenbankquelle. Es wird also unnötig Rechenzeit vergeudet. Dieses Problem läßt sich im Moment auch leider nicht umgehen.

\subsubsection*{Weitere Modi für WMS}

Wer den Standard aufmerksam liest, wird noch vier weitere Operationsmodi finden, die in den einführenden Zeilen zu diesem Abschnitt nicht genannt worden sind. Sie umfassen:

*=describeLayer=
*=getLegendGraphic=
*=getStyles=
*=putStyles=

Diese Modi sind nur für Mapserver von Relevanz, die den OGC-Standard SLD unterstützen. Mit diesen ''styled layer descriptor'' ist es möglich, von außen Einfluß auf die ansonsten fixe Kartengestaltung eines Mapservers zu nehmen. Da dieser Standard serverseitig von MapServer bisher nicht unterstützt wird\footnote{Und clientseitig nur sehr sporadisch; konsultieren Sie hierzu bitte die Online-Dokumentation.}, findet hier keine detaillierte Beschreibung statt. Sie können sich aber selbstverständlich den Standard~[[pdf:spec:sld10]] lesen.

=Web Feature Server (WFS)=(8)

Die entsprechende Spezifikation des OGC~[[pdf:spec:wfs100]] sieht WFS im Kontext zu WMS. Nach der Formulierung in der Einführung des Dokuments ist WFS der 'nächste logische Schritt' nach WMS. Wo WMS die Möglichkeit bietet, Capabilities abzufragen Karten anzuzeigen und schließlich Anfragen bezüglich der Datengrundlage der Karten zu machen, stellt WFS ein Interface zur Verfügung, dass es dem Benutzer ermöglicht, Einfluß auf die Datengrundlage zu nehmen, indem Features in der Karte geändert und gelöscht, bzw. neue Features hinzugefügt werden können.

Das hört sich alles ziemlich gut an -- und doch muß der begeisterte Leser hier enttäuscht werden. MapServer ist bisher ausschließlich darauf ausgelegt, Daten aus Quellen wie der Festplatte oder einer Datenbank zu lesen und Karten zu produzieren. Von einer Unterstützung für Datenänderungen ist man im Moment noch sehr weit entfernt -- falls sie überhaupt kommen wird\footnote{Es besteht natürlich die Möglichkeit, dass Sie beispielsweise mit MapScript entsprechende Fähigkeiten in einer eigenen Applikation programmieren. Stellen Sie sich auf einigen Aufwand ein.}.

Was wir mit MapServer kriegen, ist allerdings zumindest die Möglichkeit, Vektorlayer über den Transportmechanismus von WFS als Server auszuliefern bzw. als Client zu beziehen. Das funktioniert nur mit Vektordaten, da sich Rasterdaten offensichtlich nicht in das XML-Format mit dem Namen GML verpacken lassen. Diese ''Geography Markup Language'' ist selbstverständlich ebenfalls in einer eigenen Implementation Specification definiert~[[pdf:spec:gml]].

Von den in der Spezifikation definierten Anfragetypen sind im MapServer die folgenden implementiert:

*=getCapabilities= , um ein Capabilities-Dokument abrufen zu können, wie man es bereits von WMS kennt.
*=describeFeature= liefert eine Beschreibung eines Features zurück.
*=getFeature= holt eine GML-Repräsentation eines Features.

==WFS Server==

Wie schon beim WMS-konformen Server, wird WFS in MapServer dadurch aktiviert, dass die notwendigen =METADATA= -Tags in das Mapfile eingefügt werden. Zuerst einmal müssen aber die folgenden Vorkehrungen getroffen werden:

*Zuerst muß MapServer natürlich mit WFS-Unterstützung kompiliert worden sein. Detaillierte Vorgaben dafür finden Sie in Anhang~\ref{anhang:compile}.
*Das Mapfile muß einen =NAME= haben, ebenso wie jeder einzelne Layer. Wie schon bei WMS geht MapServer bei WFS davon aus, dass jeder Layer, der sich im Mapfile befindet, auch über WFS zur Verfügung gestellt werden soll.

MapServer kann ausschließlich Vektorlayer in seinen WFS-Capabilites erscheinen lassen, also Shapefiles, PostGIS-Layer und so weiter; der Typ des Layers muß also =POINT= , =LINE= oder =POLYGON= sein.

Desweiteren muß die Eigenschaft =DUMP= im Layer auf =TRUE= gesetzt sein. Dies zeigt MapServer an, dass er GML-Repräsentationen für diesen Layer erzeugen darf. Das entspricht der Vorgabe, =getFeatureInfo= mit einem WMS-konformen Server nutzen zu können.

In der =WEB= -Sektion des Mapfiles müssen dann die folgenden Angaben gemacht werden.

*=wfs_onlineresource= Die Basisadresse des Servers. Hat denselben Aufbau wie der gleichnamige Parameter für WMS. Allerdings muß man einem WFS-konformen MapServer noch mitteilen, wie er WFS- von WMS- Anfragen zu unterscheiden hat. Das geschieht durch =SERVICE= , also etwa derart: <code> WEB .. METADATA ... "wfs_onlineresource" \ "http://www.example.com/cgi-bin/mapserv?SERVICE=WFS&map=..." END END </code> Diese Angabe ist auch dann nötig, wenn der MapServer nicht darauf eingerichtet oder konfiguriert ist, als WMS-Server zu fungieren.
*=wfs_title= Titel für die Karte; siehe WMS-Konformität. Zwingend notwendig.
*=wfs_abstract= Eine elaborierte Zusammenfassung über Sinn und Zweck dieses Servers. Siehe WMS-Konformität.
*=wfs_keywordlist= Eine Liste mit Schlüsselworten, die einen Bezug zu diesem WFS-Server haben. Siehe WMS-Konformität.
*=wfs_accessconstraints= Beschränkungen, die den Zugriff auf diesen Server betreffen. Siehe WMS-Konformität.
*=wfs_fees= Gebühren, die beim Zugriff auf diesen Server anfallen. Siehe WMS-Konformität.
*=wfs_encoding= Die Kodierung für die XML-Dateien, die durch den WFS-Server ausgeliefert werden. Voreingestellt ist hier ISO-8859-1.
*=ows_schema_location= Der Ort, an dem die OWS-Schemas zur Validierung der generierten XML-Dateien liegen. Siehe weiter unten auf Seite~\pageref{text:wfs:schemas}.
*=wfs_geometry_element_name= Weiter unten gibt es ein Beispiel zu sehen, wie eine Datei aussehen kann, die von einem WFS-konformen MapServer ausgeliefert wird. Das Element, dass die Liste der Koordinaten eines Features umfaßt, hat dabei keinen fixen Namen. Sie können mit diesem Parameter hier einen Namen festlegen; Voreinstellung in MapServer ist =MS_GEOMETRY= .
*=wfs_srs= Die Projektion, die für alle Layer in der Karte gelten soll. Wird als EPSG-Code angegeben und genauso wie bei WMS-konformen Servern notiert. Beachten Sie bitte die Anmerkungen zu Projektionen in WFS-konformen Servern im nächsten Abschnitt.

Beachten Sie, dass diese Parameter im Gegensatz zu den WMS-Parametern alle den Präfix =wfs_= tragen. Einzige Ausnahme ist =ows_schema_location= .

==Projektionen in WFS-Servern==

Die WFS-Spezifikation macht zu Projektionen andere Vorgaben als idie für WMS. So können einzelne Layer nicht in mehr als einer Projektion ausgeliefert werden. Es gibt auch keine Projektionsangabe, die man ein einziges Mal für alle Layer machen kann\footnote{Man kann aber, wie Sie weiter oben sehen konnten, MapServer so konfigurieren, dass er einen SRS-Eintrag in der WEB-Sektion bekommt und diesen dann auf alle Layer überträgt.}. Es ist aber sehr wohl möglich, für jeden Layer eine unterschiedliche Projektion anzubieten. Außerdem nennt der Standard keine Default-Projektion; anders als bei WMS, wo mindestens =EPSG:4326= angeboten werden muß.

MapServer entscheidet in zwei Schritten, welche Projektion für einen Layer nach außen mitgeteilt wird. Wenn es eine 'übergeordnete' Projektion gibt (also einen Projektionsblock mit EPSG-Code für die ganze Karte, bzw. ein =wfs_srs= in der WEB-Sektion), so findet diese Projektion auf alle Layer Anwendung, selbst dann, wenn die Layer selber noch einmal über =wfs_srs= eine Projektion definieren.

Gibt es keine solche 'Überprojektion', muß jeder Layer einen eigenen Wert setzen.

==Schemas==(9)

Schemas\footnote{In diesem Fall nicht Schemata, da es sich um einen feststehenden englischen Begriff handelt.} sind ein Mechanismus, XML-Dateien zu validieren, also zu prüfen, ob sie einem bestimmten Aufbau genügen. Sie können ein Paket standardkonformer Schemas von~[[http:owssamples]] herunterladen.

Das Archiv entpacken Sie an einen Ort, der für den WebServer erreichbar ist. Danach können Sie, wie oben gesehen, mit einem entsprechenden Metadatum den Pfad zu den Schemas angeben:

 <code>
WEB
...
METADATA
...
"ows_schema_location" "/pfad/zu/den/schemas"
END
END
</code> 

Geben Sie keinen Pfad an, wird =..= als Ort für die Schemas angenommen. Der Gedanke hinter dieser Entscheidung war, dass man damit im Wurzelverzeichnis des Webservers landet, wenn man sein MapServer-Binary im Verzeichnis =cgi-bin/= hat\footnote{Eine sehr Apache-zentrierte Denkweise.}.

Der Präfix =ows_= zeigt übrigens an, dass hier auf mehr als nur WFS-Schemas verwiesen wird; vielmehr handelt es sich um einen Verweis auf Schemas, die sich auf ''OGC Web Services'' beziehen.

==Aufruf \& Capabilities==

Sobald man die ganze vorbereitende Arbeit hinter sich gebracht hat, kann man prüfen, ob alles korrekt eingerichtet worden ist. Dazu richtet man, wie schon beim WMS-konformen Server, eine Anfrage vom Typ =getCapabilities= an den Server:

 <code>
http://www.example.com/cgi-bin/mapserv
? SERVICE=WFS
& REQUEST=getCapabilities
& map=...
</code> 

Die Vorgehensweise entspricht jetzt haargenau dem, was Sie auch mit einem WMS-Server tun würden: Sie durchsuchen das Capabilites-Dokument nach Warnungen und Fehlern, und wenn sich alles so verhält, wie es geplant war, dann haben Sie einen einsatzfähigen, WFS-konformen Server.

==WFS Client==

Was man mit WMS machen kann, will man selbstverständlich auch mit WFS machen: Einbinden von WFS-Layern als eigene Kartenebenen. Die Vorgehensweise ist dabei stark an eben das Einfügen von WMS-Layern angelehnt.

FIXME: blah

Die Voraussetzungen für die Kompilierung eines WFS-konformen Client sind etwas umfänglicher als für den entsprechenden Server. Sieh auch Abschnitt [FIXME] im Anhang.

Ein WFS-Client-Layer ist sieht anders aus als ein 'normaler' Layer, hat aber Ähnlichkeit mit einem WMS-konformen Layer. Hier ein Beispiel:

 <code>
LAYER
END
</code> 

FIXME: vervollständigen!1!

=Map Context=

Diese Spezifikation ist eine Ergänzung zur WMS-Spezifikation. Sie beschreibt einen Mechanismus, mit dem Informationen über eine Menge von WMS-produzierten Layern auf eine portable Weise zwischen Systemen ausgetauscht bzw. in einem definierten Format gespeichert und abgerufen werden können.

Das Dokument, das diesen Standard definiert ist in der Version 1.0 von der OGC-Website herunterladbar~[[pdf:spec:mapcontext10]].

MapServer kann Kontextdokumente in den Versionen 0.1.2, 0.1.4, 0.1.7 und 1.0 lesen, und in den Versionen 0.1.4, 0.1.7 und 1.0 exportieren.

Kontextdokumente lassen sich im MapServer darüberhinaus nur in MapScript verwenden, und selbst dort nur in der PHP-Fassung. Alles andere wird (noch?) nicht unterstützt. Darüberhinaus geht Map Context davon aus, dass die WMS-Spezifikation 1.1.1 beachtet wird.

Notwendige Bibliotheken für die Map Context-Funktionalität sind die Projektionsbibliothek proj.4, GDAL/OGR im Zusammenspiel mit Xerces sowie PHP MapScript. Genaue Installationsanleitungen für diese Komponenten finden Sie im Anhang ab Seite~\pageref{text:installation}.

==Das Context-Dokument==

Der Inhalt eines Context-Dokuments (oder schlicht: eines Contexts) besteht im wesentlichen aus Angaben über die Quelle(n) der einzelnen Layer, die verwendeten Bounding Boxes, Projektionen und eventuell diverse Metadaten.

Wie bei praktisch allem, was mit dem OGC in Zusammenhang steht, ist der Context ein XML-Dokument. Beachten Sie, dass in einem Context-Dokument tatsächlich nur WMS-Layer gespeichert werden können.

FIXME: fertig!1!

==Den Kontext verwenden==

Dieser Abschnitt sollte sinnvoller eigentlich im Kapitel über PHP MapScript erscheinen; der Konsistenz halber ist er hierher gewandert. Denn wie bereits erwähnt, kann Map Context bisher nur im Zusammenspiel mit PHP-MapScript benutzt werden.

Wenn Sie ein Mapfile nach den obigen Vorgaben erstellt haben, können Sie testen, ob Sie alles richtig gemacht haben:

 <code>
<?php
dl ("php_mapscript40.so");
<math>map = ms_newMapObj ("mapfile.map");
</math>map -> saveMapContext ("mapfile_context.xml");
</code> 

Danach geht es nach dem bewährten Muster daran, in der fertigen XML-Datei nach Warnhinweisen zu suchen, die zeigen, dass Dinge fehlen oder Fehler vorliegen. Wenn das nicht mehr passiert, kann Ihr Mapfile als Quelle für einen Map Context dienen.

FIXME: fertig!1!

= Styled Layer Descriptor (SLD)=
* http://www.mapserver.org/ogc/sld.html

=Filter Encoding =
[[User:Astrid Emde]]
* http://www.mapserver.org/ogc/filter_encoding.html

= WCS =
* http://de.wikipedia.org/wiki/Web_Coverage_Service
* Informationen siehe http://www.mapserver.org/ogc/wcs_server.html
* Informationen siehe http://www.mapserver.org/ogc/wcs_format.html

= WMS Time=

* Informationen siehe http://www.mapserver.org/ogc/wms_time.html

= SOS=

* Informationen siehe http://www.mapserver.org/ogc/sos_server.html

== OWS Clients ==
=== Desktop GIS ===
=== WebGIS ===

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 2

2009-01-23T07:07:55Z

Wiki-Mikee63: /* PostgreSQL und PostGIS */

[[User:Lars]] (logging, includes, fastcgi) 
[[User:Simon Appelt]] (Web-Sektion, Layer, Weitere Layer-Optionen)
= Mapfile =
\index{Mapfile}

Das Mapfile wird Ihnen größte Freude bereiten. Sie werden die meisten Ihrer Fehler damit machen, und die meiste Zeit, die Sie mit dem MapServer überhaupt verbringen, wird das Editieren Ihrer Mapfiles zum Inhalt haben.

=Bedeutung des Mapfiles=

Das Mapfile ist die zentrale Layout- und Konfigurationsdatei einer MapServer-Anwendung,sozusagen das "Herz". Sie beschreibt Inhalt und Darstellung der fertigen Karte und enthält zusätzliche Informationen, um Maßstäbe, Legenden und Referenzkarten passend zur fertigen Karte zu erstellen.

Auch die Metadaten, die zur OGC-konformen Funktionsweise benötigt werden, sind im Mapfile angegeben.

Bevor wir jedoch in alle Details des Mapfiles einsteigen, werfen wir einen Blick auf die generelle Funktionsweise des MapServers.

==MapServer als CGI==\index{CGI}(2)

Dies ist der "Standard"-Weg, den MapServer zu benutzen: indem er als Programm in einem Webserver wie beispielsweise dem Apache residiert. Über den URL bekommt das Programm Parameter zugewiesen und ändert seine Ausgabe anhand dieser Parameter.

Ein Beispiel. Ein typischer URL sieht etwa folgendermaßen aus:

 <code>
http://www.example.com/cgi-bin/mapserv \
? map=/usr/local/www/mapfile.map
</code> 

Das ganze ist für den Druck umgebrochen, es handelt sich um eine einzige Zeile, und die Leestellen im URL sind ebenfalls nur für die Lesbarkeit hinzugefügt. Backslashes an den Enden zeigen an, dass die Zeile noch nicht beendet ist. Diese Unix-typische Notation wird im folgenden im ganzen Buch Verwendung finden.

Beachten Sie bitte, dass die Domain =example.com= für anschauliche Zwecke in der Literatur~[[rfc2606]] reserviert ist und Ihnen ''kein Ergebnis'' bei einem Aufruf anzeigen wird. Ersetzen Sie diesen Domainnamen durch den tatsächlichen Namen Ihres Hosts.

Der MapServer, das eigentliche Programm, das die Arbeit macht, liegt offensichtlich in einem =cgi-bin= genannten Verzeichnis des Webservers. Ruft man ihn einfach ohne Parameter auf, also etwa folgendermaßen:

 <code>
http://www.example.com/cgi-bin/mapserv
</code> 

dann sollte man als Antwort folgendes in seinem Browser sehen:

 <code>
No query information to decode. QUERY_STRING is set, but empty.
</code> 

\begin{figure}
\begin{center}
\mmfig{0.35}{motzing}{Der MapServer motzt herum; genau das, was man am Anfang sehen möchte.}
\end{center}
\end{figure}

Also wie in Abbildung~\ref{motzing}. Wie reagiert man darauf? Indem man sich freut, denn alles ist in Ordnung; hurra, er kann schon rummotzen! Dies ist die Meldung, die man sehen möchte. MapServer beschwert sich lediglich, dass er keine Parameter zur Verarbeitung genannt bekommen hat. Nach einer neuen Installation ist diese Meldung nach dem ersten Testaufruf das gewünschte Ergebnis.

Der erste Parameter wird mit einem Fragezeichen =?= eingeleitet, alle weiteren werden mit einem Kaufmanns-Und =\&= voneinander getrennt.

Zwingend notwendig ist die Angabe eines Mapfiles über den Parameter =map== \footnote{Man kann diese Preisgabe des Ortes, an dem das Mapfile liegt, auch nach außen verbergen. Mehr dazu später.}, damit dem MapServer bekannt ist, welches Layout für die Karte zur Anwendung kommen soll.

Liegt Ihr Mapfile unter Unix etwa unter =/usr/local/maps/mymap.map= , so wäre also folgender Aufruf korrekt:

 <code>
http://www.example.com/cgi-bin/mapserv?map=/usr/local/maps/mymap.map
</code> 

Pfade unter Windows werden ebenfalls so angegeben, wie Sie es gewohnt sind, also beispielweise mit =C:= am Anfang.

==Die Modi==

MapServer kennt nun verschiedene Betriebs''modi'' , die über den Parameter =mode== notiert werden. Es gibt die folgenden Modi:

*=browse= : Läßt Sie die Karte browsen. Das bedeutet im wesentlichen, dass MapServer die Templates berücksichtigt, die im Mapfile angegeben sind, und somit HTML-Dateien mit Navigationselementen ausliefert. Wenn kein Modus angegeben ist, geht MapServer immer von =browse= aus. Was es mit Templates genau auf sich hat, erfahren Sie in Abschnitt~20 ab Seite~\pageref{text:mapfile:templates}.
*=map= : Dieser Modus läßt den MapServer Template-Angaben ignorieren und nur die Karte ausliefern. Zum Testen Ihres Mapfiles ist dies wahrscheinlich genau der Modus, den Sie haben möchten.
*=query= : Dieser Modus und seine Funktion, das Abfragen von Daten, die der Karte zugrunde liegen, werden ab Seite~\pageref{text:mapfile:queries} beschrieben.
*=nquery= : Wo =query= immer nur ein Ergebnis zurückliefern kann, kann =nquery= mehrere Ergebnisse liefern, sowohl im gleichen Layer als auch aus verschiedenen Layern (und auch beides zusammen, natürlich). Die Template-Angaben für diesen Modus können recht umfangreich sein.

Wenn Sie also Ihr Mapfile =mymap.map= im Modus =map= aufrufen wollten -- wodurch lediglich eine Karte, aber kein HTML-Interface produziert würde --, würden Sie folgendes notieren:

 <code>
http://www.example.com/cgi-bin/mapserv \
? map=/usr/local/maps/mymap.map \
& mode=map
</code> 

==Die weiteren Parameter==

Alle Variablen, die das Aussehen einer Karte beeinflussen können, werden über solche Parameter übergeben. Das schließt das Mapfile und den Modus mit ein, und darüberhinaus \ldots\ nun, eben alles andere, inklusive der Kartenebenen, die Sie sehen möchten, die Eckpunkte des gewünschten Kartenausschnitts, und noch diverse andere Dinge mehr. Da kann ein URL schnell einmal wie folgt aussehen:

 <code>
http://www.example.com/cgi-bin/mapserv \
? map=/usr/local/maps/mymap.map \
& mode=map \
& layer=postleitzahlen&layer=fluesse&layer=strassen \
& imgext=18.0+9.0+30.0+15.0
</code> 

Und sie kann noch viel viel länger werden. Und Ihr erster Gedanke, wenn Sie das sehen, ist natürlich vollkommen korrekt: Das will kein Mensch jedesmal eintippen müssen.

Daher werden diese Parameter für gewöhnlich über Eingaben in einem HTML-Formular generiert. Dazu gehört dann beispielsweise auch die Karte, die Sie im Browserfenster anklicken. Diese Formulare werden aus den Templates generiert, die weiter oben schon einmal erwähnt worden sind.

Für das erste setzen wir uns ausschließlich mit der Gestaltung der Karte auseinander, wofür Sie nur den Modus =map= ohne zusätzliche Parameter benötigten. Wenn ab Seite~\pageref{text:mapfile:templates} die Templates dazukommen, wird Ihr Wissen um eine Navigation in der Karte erweitert. Ab Seite~\pageref{text:mapfile:cgiparams} finden Sie schließlich eine Aufzählung aller möglichen CGI-Parameter.

Neben der CGI-Fassung gibt es zwei weitere Wege, die Funktionalitäten des MapServers zu nutzen. Beide unterscheiden sich zum Teil radikal von der Weise, die in diesem Kapitel behandelt wird.

\subsubsection*{Der OGC-konforme MapServer}\index{OGC}

Der OGC-konforme MapServer arbeitet ebenfalls als CGI-Programm und muß vor allen Dingen mit Metadaten versorgt werden, die dann bei der Kommunikation mit anderen Servern und mit Client-Appli\-ka\-tio\-nen verwendet werden.

Leider weicht sowohl die Notation des aufrufenden URL als auch die Notation der Metadaten im Mapfile ein wenig von der des MapServers im 'Normalbetrieb' ab, was nicht zur Lesbarkeit der ganzen Datei beiträgt. Die Unterschiede in der Notation werden im entsprechenden Kapitel ab Seite~\pageref{text:ogc} natürlich erläutert.

\subsubsection*{MapScript}\index{MapScript}

MapScript muß nicht gezwungenermaßen mit einem Mapfile arbeiten, z.B. wenn man damit nur Shapefiles bearbeiten möchte. Sobald man beginnt, mit Karten arbeiten zu wollen, wird man jedoch auch mit MapScript ein Mapfile laden, das dann verwendet werden kann.

Alle Sektionen im Mapfile werden dann als Objekte in einer Programmiersprache behandelt. Grundsätzlich ist nicht einmal ein Webserver vonnöten, auch lokale Applikationen lassen sich mit MapScript realisieren.

Am häufigsten sieht man MapScript jedoch in seiner Variante für PHP im Einsatz, die dann natürlich wieder in Webservern läuft. Als Beispiel konzentrieren wir uns in diesem Handbuch auf eben diese Version von MapScript.

=Grundlegender Aufbau des Mapfiles=

Werfen wir zuerst einen ganz allgemeinen Blick darauf, wie Inhalte im Mapfile notiert werden, bevor dann näher beschrieben wird, welche Einträge es denn gibt.

Das Mapfile besteht aus einzelnen Blöcken, die mit einem Schlüsselwort beginnen und mit einem =END= abgeschlossen werden:

 <code>
WEB
...
END
</code> 

Dieses Beispiel zeigt den Beginn und das Ende eines =WEB= -Blocks. Innerhalb eines solchen Blocks folgen Deklarationen von Schlüsselworten und dazugehörigen Werten, oder wieder neue Blöcke. Beispiele für Blöcke in Blöcken sind Classes innerhalb von Layern.

Ausnahmen für diese Notation sind der Header des Mapfiles und das Mapfile selber, das zwar mit einem END abgeschlossen werden muss, aber kein einleitendes Schlüsselwort kennt.

Wann immer im folgenden drei Punkte in Beispielen zu sehen sind, sollen diese Punkte nicht tatsächlich eingegeben werden; es handelt sich vielmehr um Platzhalter, die zeigen, dass etwas weggelassen worden ist.

Es können drei verschiedene Dinge als Werte notiert werden: Schlüsselworte, Zahlen oder Zeichenketten.

 <code>
SCHLÜSSELWORT SCHLÜSSEL
STATUS ON

SCHLÜSSELWORT "ZEICHENKETTE"
DATA "myshapefile"

SCHLÜSSELWORT ZAHL [ZAHL ...]
EXTENT 0 0 4000 4000
</code> 

Im Gegensatz zu Schlüsselworten und Zeichenketten ist es bei Zahlen in den meisten Fällen nötig, mehr als nur eine zu schreiben. So benötigt man für den Extent einer Karte stets vier Zahlen, die die beiden Koordinaten jeweils eines Eckpunktes bezeichnen.

Zeichenketten sollten generell nicht mit Zahlen beginnen: =zweiterlayer= ist als Layername in Ordnung, =2terlayer= nicht.

Ausnahmen dazu bilden Angaben zu Projektionen von Karten und Layern und die Metadaten in diversen Sektionen. Deren Notation wird in den entsprechenden Abschnitten näher beschrieben.

Zwei Arten von Angaben verdienen besondere Beachtung: Pfade in das Dateisystem und Farben.

\subsubsection*{Notation von Pfaden}

Pfade können absolute oder relative Angaben sein. Absolute Angaben sehen etwa folgendermaßen aus:

 <code>
SHAPEPATH "c:\mapserver\daten"
SHAPEPATH "/usr/local/GIS/daten/"
</code> 

Absolute Pfade heißen so, weil sie den vollständigen Pfad von der Wurzel des Dateisystems bis hin zur Datei angeben.

Relative Pfade bewegen sich immer in Relation zu etwas, in unserem Fall zum Mapfile:

 <code>
SHAPEPATH "daten/"
</code> 

In diesem Fall gibt es also im Verzeichnis des Mapfiles ein Unterverzeichnis mit dem Namen =daten= .

\subsubsection*{Farbwerte}

Farben werden als RGB-Werte angegeben, also bestehend aus ihren jeweiligen Anteilen von Rot, Grün und Blau, in Werten von 0 bis 255\footnote{Dadurch lassen sich theoretisch <math>2^{24}</math> Farben, also die bekannten 16 Millionen darstellen}. Einige Beispiele:

 <code>
COLOR 0 0 0 # schwarz
COLOR 255 255 255 # weiß
COLOR 255 0 0 # rot
COLOR 0 255 0 # grün
COLOR 0 0 255 # blau
</code> 

Und so weiter. Farben, bei denen alle drei Zahlen gleich sind, ergeben Grautöne. Im Web finden sich einige Farb- und Umrechnungstabellen.

Beachten Sie bitte: Ohne weitere Angaben zum Ausgabeformat -- siehe Seite~\pageref{text:mapfile:ausgabeformate} -- produziert MapServer nur Bilder mit einer Palette von 256 Farben. Mehr über Farben in MapServer erfahren Sie in eben diesem Abschnitt.

=Der Header=
\index{Header}\index{Mapfile!Header}(3)

Der Header im Mapfile enthält globale Angaben, die sich auf alle Sektionen im
Mapfile beziehen oder das Aussehen des fertigen Bildes bestimmen, das produziert
werden soll. Der Header ist die einzige Sektion, die nicht durch ein END
abgeschlossen wird. Er besitzt auch kein einleitendes Schlüsselwort.

Ein Beispiel für einen kompletten Header\footnote{Um keinen Fehler im Modus =map= zu produzieren, reichen eigentlich schon SIZE und EXTENT, zusammen mit einem END für ein vollständiges Mapfile.}:

 <code>
NAME "brandenburg"
EXTENT 0.0 0.0 1.0 1.0
SIZE 450 450
SHAPEPATH "daten/brandenburg/"
</code> 

Sie können die folgenden Angaben im Header Ihres Mapfiles machen:

*=NAME <name>= Ein Name als Beschreibung der Karte. Dieser Name sollte einzigartig sein und im weiteren nicht als Name für Layer verwendet werden. Der Name der Karte wird für WMS-konforme Aufrufe verwendet -- siehe auch das entsprechende Kapitel --, als auch als Prefix für die Namen temporär erzeugter Dateien des MapServer.
*=STATUS <ON|OFF>= : Der Status der Karte, ob an oder aus. Da man ein Mapfile normalerweise schreibt, um eine Karte anzuzeigen, drängt sich =ON= geradezu auf.\\ Ausschalten will man das nur dann, wenn man nur die anderen Elemente benutzen will, die man im Mapfile definiert, also zum Beispiel Maßstäbe und Legenden.
*=EXTENT <minx miny maxx maxy>= : Eine Bounding Box um die Daten herum. Wird im URL für den MapServer keine Bounding Box explizit angegeben, ist diese Angabe im Mapfile eine Standardeinstellung, die automatisch verwendet wird. Dieser Wert muß zwingendermaßen vorhanden sein.\\ Sorgen Sie dafür, dass hier ein sinnvoller Wert steht. MapServer ist nicht in der Lage, aus den vorliegenden Daten einen 'Default'-Extent zu ermitteln. Auf das Problem angesprochen, meinten die Entwickler, so ein Feature auch nicht implementieren zu wollen, zumal einige Datenformate gar keinen Extent speichern und das Errechnen aus den Daten selbst viel zu aufwendig wäre.
*=SIZE <width height>= : Die Größe des zu produzierenden Bildes, anzugeben in Breite und Höhe in Pixeln. Auch dies ist eine Voreinstellung, die Verwendung findet, wenn es keine andere explizite Angabe gibt. Die Größe des zu produzierenden Bildes ist auf 2048 Pixel im Quadrat beschränkt.
*=SHAPEPATH <path>= : Der Ort im Dateisystem, an dem die Daten liegen. Kann ein relativer Pfad zum Mapfile sein, oder ein absoluter, der irgendwo anders in das lokale Dateisystem weist.
*=SYMBOLSET <filename>= : Die Datei, in der Symbole definiert werden. Was es mit Symbolen auf sich hat, und wie Symbole im Mapfile selber anstatt in einer separaten Datei notiert werden können, erfahren Sie in Abschnitt~17.
*=FONTSET <filename>= : Die Datei, die Aliase für TrueType-Schriften enthält. Zum Aufbau dieser Datei und der Verwendung von Schriften im MapServer siehe den Abschnitt ab Seite~\pageref{text:mapfile:fonts}.
*=IMAGECOLOR <red green blue>= : Hintergrundfarbe des fertigen Kartenbildes, in RGB-Werten.
*=IMAGEFORMAT <name>= : Name des Ausgabeformats, das produziert werden soll. Muß ein interner Name für ein Bildformat sein, oder der Name eines Ausgabeformates, der mit einer =OUTPUTFORMAT= -Sektion definiert worden ist. Mehr zu Ausgabeformaten finden Sie ab Seite~\pageref{text:mapfile:ausgabeformate}.

\subsubsection*{Das Wort MAP}

Sie können ein Mapfile auch mit dem Schlüsselwort =MAP= einleiten:

 <code>
MAP
NAME "brandenburg"
SIZE 400 400
...
END
</code> 

Das ist nicht notwendig. Sie können so allerdings dem abschließenden =END= am Ende des Mapfiles sozusagen einen Startparameter zur Seite stellen. Es sieht hübscher aus, hat aber keine Funktion.

=Die Web-Sektion=
\index{Web}\index{Mapfile!Web}

Der Web-Block im Mapfile definiert das Verhalten des MapServer-Interface nach außen und beinhaltet URLs für verschiedene Gelegenheiten, einige interne Informationen, die nicht nach außen weitergegeben werden, sowie eventuell Metadaten für verschiedene Anwendungsfälle, für gewöhnlich zum Beispiel für OGC-konformes Verhalten.

Der Web-Block wird mit den Schlüsselwort =WEB= eingeleitet und durch ein =END= abgeschlossen.

'Web' ist als Name eigentlich irreführend, da die Daten in diesem Abschnitt nicht notwendigerweise nur von Web-Diensten genutzt werden. Aber der MapServer wurde als Web-Applikation entwickelt, und daher ist es unwahrscheinlich, dass sich an dieser Benennung etwas ändern wird.

Die folgenden Elemente können in der Web-Sektion verwendet werden:

*=ERROR <url>= \index{ERROR}: Definiert einen URL, an den der Benutzer weitergeleitet wird, wenn ein Fehler in der MapServer-Applikation auftritt. Kann eine absolute URL sein, die mit =http://= eingeleitet wird, oder ein Pfad relativ zur Lage des Mapfiles. Wird =ERROR= nicht definiert, wird einfach nur die Fehlernachricht als Text ausgegeben.\\ Beachten Sie dabei, dass das für das Debuggen während der Entwicklung Ihrer Anwendung nicht begehrenswert ist, da keine der MapServer-Fehlermeldungen mehr ausgegeben werden. Das will man für gewöhnlich nur für das fertige System haben, sobald man seine Benutzer nicht mehr mit den Fehlermeldungen des MapServers konfrontieren möchte, sondern mit einer hübschen Fehlerseite.
*=EMPTY <url>= \index{EMPTY}: URL, an den der Benutzer weitergeleitet wird, wenn ein Query keine Resultate erbracht hat. Wenn =EMPTY= nicht definiert ist, wird dafür der Wert von =ERROR= benutzt.
*=FOOTER <filename>= \index{FOOTER}: Der Fußteil einer fertigen Ausgabe. Kommt nur bei Queries zur Anwendung, die mehrere Ergebnisse zurückliefern sollen.
*=HEADER <filename>= \index{HEADER}: Der Kopfteil einer fertigen Ausgabe. Kommt nur bei Queries zur Anwendung, die mehrere Ergebnisse zurückliefern sollen.
*=TEMPLATE <url|filename>= \index{TEMPLATE}: Das Template, das das eigentliche Interface zum Benutzer darstellt. Darstellung der Karte und die Navigation darin werden durch das Template übernommen. Der Aufbau eines Templates wird detailliert in Abschnitt~20 behandelt.
*=IMAGEPATH= \index{IMAGEPATH}: Der Pfad zu dem Verzeichnis, in dem die vom MapServer generierten Bilder abgelegt werden sollen. Dieser Pfad muß auf dem System existieren und muß vom Webserver (bzw. von dem Benutzer, mit dessen Rechten der Webserver läuft) beschreibbar sein. Diese Angabe muß mit dem Verzeichnistrenner der jeweiligen Plattform enden, also =/= auf Unix-Systemen und so weiter.
*=IMAGEURL= \index{IMAGEURL}: Der URL zum genannten =IMAGEPATH= . =IMAGEURL= wird vom Webbrowser zurückgegeben und muß daher im Webserver so konfiguriert sein, dass =IMAGEURL= auf =IMAGEPATH= abgebildet wird. Auf Unix-Systemen wird meistens der URL =/tmp= auf das lokale Verzeichnis =/tmp/= (oder auch =/var/tmp/= ) abgebildet. Damit gibt man jedoch auch sein temporäres Verzeichnis dem öffentlichen Zugriff preis. Sinnvoller ist es, ein eigenes Verzeichnis für diese Dateien anzulegen. Mehr Überlegungen zu diesem Thema finden Sie in Anhang~\ref{anhang:sicherheit}.
*=LOG <filename>= \index{LOG}: Die Logdatei für den MapServer. Diese Datei muß auf dem System existieren und muss vom Webserver (bzw. von dem Benutzer, mit dessen Rechten der Webserver läuft) beschreibbar sein. Mehr zu Log-Dateien erfahren Sie weiter unten in Abschnitt~31.
*=METADATA<filename>= \index{LOG}: Die Sektion Metadata ermöglicht es, weiterführende Informationen über den WMS-Dienst bereitzustellen, um nach aussen eine gewisse Transparents zu schaffen. So gibt es zum Beispiel den erforderlichen Parameter "wms_title", über dem das Kind einen Namen bekommt. Nähre Information zu den einzelenen Parametern, finden Sie im Kapitell 3, Sektion 3.2.3 WMS-Metadaten im Mapfile.
*=MINSCALEDENOM= \index{MINSCALE}: Der minimale =SCALE= , in dem Karten zu sehen sind. Wird eine Karte mit einem kleineren =SCALE= vom Client angefordert, liefert MapServer eine Karte in dem =SCALE= zurück, der =MINSCALE= entspricht. Mehr zur Verwendung von =SCALE= -ähnlichen Parametern im Mapfile finden Sie in Sektion~19.
*=MAXSCALEDENOM= \index{MAXSCALE}: Der maximale =SCALE= , in dem Karten zu sehen sind. Wird eine Karte mit einem größeren =SCALE= vom Client angefordert, liefert MapServer eine Karte in dem =SCALE= zurück, der =MAXSCALE= entspricht. Mehr zur Verwendung von =SCALE= -ähnlichen Parametern im Mapfile finden Sie in Sektion~19.
*=MINTEMPLATE= \index{MINTEMPLATE}: Template, das anstelle von =TEMPLATE= benutzt werden soll, wenn der Client eine Karte angefordert hat, deren =SCALE= unter =MINSCALEDENOM= liegt. Mit einem solchen Template lassen sich Applikationen ineinander verschachteln, indem ab bestimmten Zoomtiefen einfach andere Templates benutzt werden.
*=MAXTEMPLATE= \index{MAXTEMPLATE}: Template, das anstelle von =TEMPLATE= benutzt werden soll, wenn der Client eine Karte angefordert hat, deren =SCALE= über =MAXSCALEDENOM= liegt. Mit einem solchen Template lassen sich Applikationen ineinander verschachteln, indem ab bestimmten Zoomtiefen einfach andere Templates benutzt werden.

Der Parameter =IMAGEQUALITY= , mit dem sich Kompressionsraten für produzierte JPEG-Bilder setzen ließ, wird nicht mehr unterstützt. Verwenden Sie stattdessen einen entsprechenden Parameter in einer =OUTPUTFORMAT= -Sektion (siehe weiter hinten). Das gleiche gilt für =INTERLACED= .

=Layer=
\index{Layer}\index{Mapfile!Layer}

MapServer organisiert seine Daten in Schichten, die übereinander liegen -- eben den Layern. Diese Schichten werden dann zu einem fertigen Bild zusammengefügt. Einzelne Sets von Raster- oder Polygondaten müssen jeweils in einen eigenen Layer eingebunden werden. Über die Layer werden auch Queries definiert, die dazu verwendet werden, Anfragen an zusätzlich gespeicherte Daten zu stellen. Auf diese Weise können beispielsweise Flächen angeklickt und detaillierte Informationen zu diesen angezeigt werden.

Bei nicht-OGC-konformen MapServern spielt die Reihenfolge der Layer im Mapfile eine wichtige Rolle.
Dies können sie sich wie eine Art Stapelverarbeitung vorstellen. Der Layer, der oben auf dem Stapel liegt, wird als erstes abgearbeitet und gezeichnet, somit liegt dieser in der Kartendarstellung ganz unten. Rasterbilder bieten sich meist als unterster Layer an. Auf den ersten Layer wird dann der zweite Layer im Mapfile gezeichnet, und so weiter.

Wir betrachten im folgenden den Aufbau eines Vektorlayers mit Zugriff auf ein Shapfile. Rasterdaten werden in Abschnitt~7 besprochen.

*=NAME <name>= : Ein Name als Beschreibung des Layers. Mehrere Layer können identische Namen tragen und werden dann als ein einziger Layer behandelt. Diese Vorgehensweise wird manchmal für Beschriftungen (Annotationen, siehe weiter hinten) gewählt, um in einem Zug den Layer samt Beschriftung ein- oder ausblenden zu können. Ansonsten sollte der Name so gewählt werden, dass er eindeutig ist. Um mögliche Fehlerquellen bei der Wahl des Layernames von vornherein zu vermeiden,
ist es empfehlenswert den Layernamen so zu bestimmen, dass weder Sonderzeichen, noch Zahlen und Umlaute enthalten sind.

*=DATA <filename>= : Der Dateiname des Shapefiles. Dieser Name ist relativ zum =SHAPEPATH= im Header des Mapfiles. Die Zeichenkette hier wird also einfach angehangen. Der Name sollte ohne den Anhang ''.shp'' angegeben werden. Bitte beachten Sie, dass die zum Shapefile gehörige ''.dbf'' -Datei immer vorhanden sein muss, auch wenn man nicht auf ihren Inhalt zugreift. Das gleiche gilt natürlich auch für die Indexdatei mit der Endung ''.shx'' , nur wird diese ja beim Zugriff auf das Shape tatsächlich verwendet. Des weiteren können Sie hier auch einfach den absoluten Pfadnamen einer Datei angeben.
*=STATUS <ON|OFF|DEFAULT>= : Der Status des Layers. Es gilt drei verschiedene Stadien zu unterscheiden. =DEFAULT= stellt den betreffenden Layer auf jeden Fall dar, unabhängig davon, ob der Benutzer ihn über den URL anfordert. Auf diese Weise läßt sich die Darstellung beispielsweise eines Hintergrundbildes erzwingen, ohne dass man ihn von außen abschalten kann. =OFF= stellt den Layer gar nicht da, unabhängig davon, ob er von außen angefordert worden ist. =ON= hingegen macht den Layer darstellbar, und er wird angezeigt, wenn er über den entsprechenden Parameter des URL angefordert worden ist.
*=TYPE <POINT|LINE|POLYGON>= : Für Vektorlayer kommen nur diese drei verschiedenen Typen in Frage. Punktlayer sind offensichtlich nur für Punktdaten geeignet. Generell lassen sich Linien- und Vektordaten als das jeweils andere darstellen. Das wirkt sich im wesentlich auf die Art und Weise aus, mit der MapServer die Definitionen in den Klassen des Layers interpretiert. Mehr dazu im Abschnitt über Classes.

Beachten Sie bitte, dass in den Layer-Sektionen mit diesen Angaben noch keine Aussagen über das Layout der Daten gemacht werden. Diese Aussagen werden erst in den Klassen innerhalb eines Layers getroffen!

==Gruppierungen von Layern==
(4)
\index{Groups}\index{Layer!Groups}

Zuweilen möchte man mehrere Layer gleichzeitig ansprechen, indem man sie beispielsweise in einem Schwung an- und wieder ausschaltet. Wenn man für jeden dieser Layer einen eigenen Eintrag in der Navigation zuläßt, kann es schnell unübersichtlich werden.

Eine Möglichkeit ist, zusammengehörigen Layern den gleichen Namen zu geben. Wenn man also drei Layer hat, die beispielsweise Landstraßen, Autobahnen und Bundesstraßen darstellen, kann man sie alle drei =strasse= nennen und ist fertig.

Das widerspricht jedoch ein wenig der Idee, drei verschiedene Layer zu haben. Man hätte dann ebenso gut alle Daten in einem Shapefile unterbringen und die Art der Darstellung mit entsprechenden Classes über die Daten in der ''.dbf'' -Datei erledigen können.

Das Schlüsselwort =GROUP= erlaubt die Gruppierung von Layern unter Beibehaltung ihrer Namen mitsamt der Möglichkeit, sie alle auf einmal ansprechen zu können. Man schaue sich folgendes Fragment an:

 <code>
LAYER
NAME "autobahnen"
GROUP "strassen"
...
END

LAYER
NAME "bundesstrassen"
GROUP "strassen"
...
END

LAYER
NAME "landstrassen"
GROUP "strassen"
...
END
</code> 

Nun ist es möglich, im URL eines MapServer-Aufrufs weiterhin folgendes zu schreiben:

 <code>
...&layer=landstrassen&layer=autobahnen&...
</code> 

Zusätzlich gewinnt man aber auch die folgende Notation:

 <code>
...&layer=strassen&...
</code> 

==Weitere Layer-Optionen==

Im folgenden eine Liste aller weiteren Schlüsselworte, die in Layern Verwendung finden können. Falls Sie dieses Buch von vorne nach hinten durchlesen\footnote{Sowas soll's geben.}, werden Sie einige der Begriffe wahrscheinlich noch nicht kennen. Sie sollten dann später noch einmal hierher zurückkehren und sich die Bedeutung der Dinge klarmachen.

*=REQUIRES <expression>= Legt bestimmte Voraussetzungen fest, unter denen ein Layer angezeigt wird. Ein Beispiel: <code> LAYER NAME "gruenflaechen" STATUS ON REQUIRES "[parks] != 1" ... END </code> Dieser Layer würde also nur dann angezeigt, wenn ein anderer Layer mit dem Namen =parks= ''nicht'' zu sehen ist. Logische Operatoren wie =AND= und =OR= können hier Verwendung finden.
*=MAXSCALE <double>= Der maximale SCALE, bei dem der Layer noch gezeichnet werden soll. Dieser Wert ist unter Umständen nicht vertrauenswürdig -- siehe auch den Abschnitt~19 über Maßstäbe.
*=MINSCALE <double>= Das gleiche für einen minimalen SCALE.
*=LABELANGLEITEM <colname>= Gibt bei einem Shapefile die Spalte in der ''.dbf'' -Datei an, in der ein Winkel stehen soll, um den ein Label im Layer gedreht werden soll.
*=LABELMAXSCALE <integer>= Der maximale SCALE, in dem Labels in diesem Layer gezeichnet werden sollen. Anmerkungen zu diesem Wert siehe weiter oben.
*=LABELMINSCALE <integer>= Der minimale SCALE, bei dem Labels in diesem Layer noch gezeichnet werden sollen.
*=LABELREQUIRES <expression>= Siehe weiter oben das =REQUIRES= -Schlüsselwort; wirkt sich aber nur auf die Label in einem Layer aus.
*=MAXFEATURES <integer>= Die maximale Anzahl an Features, die in diesem Layer gezeichnet werden sollen.
*=OFFSITE <integer>= Kommt nur bei Rasterbildern zur Anwendung und gibt die Nummer der Farbe in der Farbpalette an, die transparent geschaltet werden soll.
*=POSTLABELCACHE <true|false>= Gibt an, ob der Layer vor oder nach allen Labels gezeichnet werden soll. Voreinstellung ist =false= .
*=SYMBOLSCALE <double>= Der SCALE, bei dem Labels (und Symbole) in ihrer vollen Größe gezeichnet werden. Auf diese Weise erreicht man Beschriftungen, die beim Herein- und Herauszoomen mitskalieren.
*=TRANSFORM <true|false>= Definiert, ob ein Layer von dem Koordinatensystem seiner Daten in ein Bildkoordinatensystem transformiert werden soll. Voreinstellung ist =true= . Eine nützliche Funktion, wenn man Bilder an festen Stellen in jeder Karte einbinden möchte, beispielsweise Nordpfeile oder Logos.
*=CLASSITEM <colname>=
*=CLASSGROUP <name>=
*=CONNECTIONTYP<local|sde|ogr|postgis|oraclespatial|wms>=
*=CONNECTION <string>=
*=DEBUG<off|on|0|1|2|3|4|5>= Der DEBUG Befehl kommt dann zum Einsatz, sobald sie ihr Mapfile speziell testen möchten. So geben die einzelnen Level detailierte Antworten,zum Beispiel über die Darstellungsdauer des einzelnen Layer. Um den DEBUG Parameter verwendeen zu können, muss im Vorfeld im oberen MAP-Teil ein MS_ERRORFILE definiert werden, über dem die Ausgabedatei bestimmt wird. Näheres dazu finden sie im Kapitel 12 Logging.
*=DUMP<true|false>= Ist default mäßig auf =false=, sollten sie später mit WMS GetFeatureInfo arbeiten empfiehlt es sich, diesen Parameter auf =true= zusetzen, damit der MapServer die Anfrage bearbeiten kann. Die Antwort liefert der MapServer als GML Datei.
*=FILTER<string>=
*=FILTERITEM<attribute>=
*=LABELCACHE<on|off>=
*=LABELITEM<colname>= Mit diesem Befehl, lassen sich ihre Vektordaten beschriften (labeln), hierfür geben sie die Spalte, aus der gewünschten Datenquelle, an in der sich der gewünschte, darzustellende Zeichensatz befindet. Zur Beschriftung mit Inhalten aus mehreren Datenspalten kann der TEXT-Eintrag in der CLASS genutzt werden in der Form: TEXT ([colname 1], [colname 2]). Möglich ist damit auch, dynamische Einträge aus den Tabellenspalten mit fixen Textbestandteilen zu mischen. In diesen Fällen kann LABELITEM entfallen.

 <code>
Bsp. 1: Mischung aus zwei Tabellenspalten
CLASS
...
TEXT ([stadtteil]-[stadtviertel])
END

oder
Bsp. 2: Mischung aus einer Tabellenspalte und fixen Text (''GK:'')

CLASS
...
TEXT (GK:[gk-zone])
END
</code> 

*=OPACITY<integer|alpha>= Definiert die Tranpsarents eines Layers, hierbei können sie mit zwei unterschiedlichen Operanten arbeiten. Die am häufigsten verwendete Methode ist die Angabe des Wertebereichs von 0 bis 100 als Integerzahl, wobei 100 den Layer komplett transparent darstellt. Die zweite Möglichkeit kommt eher selten zum Einsatz, dabei wird...
*=PROCESSING<string>=
*=REQUIRES<expression>=
*=SIZEUNITS<pixels|feet|inches|kilometers|meters|miles>=
*=STYLEITEM<attribute]>=
*=TILEINDEX<filename|layername>=
*=TILEITEM<attribute>=
*=TOLERANCE<double>=
*=TOLERANCEUNITS<pixels|feet|inches|kilometers|meters|miles|dd>=
*=UNITS<feet|inches|kilometers|meters|miles|dd|pixels|percentages>=
*=HEADER<filename>=
*=FOOTER<filename>=

=Classes=\index{Classes}\index{Klassen}\index{Mapfile!Classes}

''Hinweis'' : Beachten Sie auf alle Fälle die Hinweise in Abschnitt~6, insbesondere, wenn Sie bisher älteren MapServer-Versionen als 4.0 gearbeitet haben.

Classes residieren ausschließlich innerhalb eines Layers. Sie definieren, wie die Daten innerhalb eines Layers tatsächlich dargestellt werden.

Zur Illustration ein erstes kleines Beispiel:

 <code>
LAYER
NAME "fluesse"
DATA "shapes/fluesse"
TYPE LINE
STATUS ON
CLASS
COLOR 0 0 255
END
END
</code> 

In diesem Vektorlayer gibt es lediglich eine einzige Class, was bedeutet, dass alle Shapes aus dem Shapefile auf die gleiche Weise dargestellt werden. In diesem Fall sind sie blau eingefärbt.

Beachten Sie, dass Sie zur Einfärbung von Linien und Punkten das Attribut =COLOR= benutzen müssen, wohingegen dieser Wert bei Polygonen die Füllfarbe bezeichnet. Der Rand des Polygons wird durch =OUTLINECOLOR= angesprochen.

\subsection*{Datenabhängiges Einfärben}

Wozu aber nun Classes einführen, wenn man diese Angaben auch direkt in den Layer schreiben könnte? Weil man durch Classes themenbezogene Darstellungen erreichen kann. Sehen wir uns das folgende Beispiel an:

 <code>
LAYER
NAME "fluesse"
DATA "shapes/fluesse"
TYPE LINE
STATUS ON
CLASSITEM "NAME"
CLASS
EXPRESSION "Wolga"
COLOR 255 31 31
END
CLASS
EXPRESSION /./
COLOR 31 31 255
END
END
</code> 

Wir sehen zuerst ein neues Schlüsselwort, =CLASSITEM= . Die Zeichenkette dahinter benennt die Spalte in der ''.dbf'' -Tabelle, anhand derer wir im folgenden filtern wollen. Alle Angaben in den Classes, die sich in diesem Layer befinden, orientieren sich an der Spalte mit diesem Namen.

In der ersten Class befindet sich eine =EXPRESSION= , ein Ausdruck. Damit ein Feature mit den Angaben in dieser Klasse dargestellt wird, muß das =CLASSITEM= auf diesen Ausdruck passen. Oder für das Beispiel: die erste Klasse findet Anwendung auf alle Shapes im Shapefile, deren NAME in der ''.dbf'' -Datei 'Wolga' lautet.

Die Classes in einem Layer werden von oben nach unten abgearbeitet, und die erste passende Class wird zur Darstellung verwendet.

Der Ausdruck in der letzten Class in diesem Beispiel bedeutet übrigens 'alle Zeichen'. Jeder mögliche Inhalt einer Spalte passt auf diesen Ausdruck. Es ergibt Sinn, eine solche 'Catch all'-Class anzulegen, um allen Features ein Standardaussehen zu verpassen, die nicht von einer der vorherigen Class abgedeckt worden sind. Eine Erklärung der möglichen Ausdrücke erfolgt im nächsten Abschnitt.

\subsection*{Mögliche Ausdrücke}

Es gibt drei verschiedene Weisen, eine =EXPRESSION= zu formulieren: mit Zeichenketten, mit regulären Ausdrücken und schließlich mit logischen Ausdrücken.

Zeichenketten sind bereits im obigen Beispiel zu sehen gewesen. Die Einträge in den Spalten der ''.dbf'' -Datei werden darauf geprüft, ob sie ''genau'' diesen Wert enthalten. Diese Art von =EXPRESSION= ist durch den MapServer am schnellsten abzuarbeiten.

Logische Ausdrücke sind Ausdrücke, die durch logische Operatoren gebildet werden können. Dazu gehören Konstrukte für gleich, ungleich, größer als, kleiner als und so weiter; darüber hinaus und, oder, nicht, und alle Kombinationen, die sich daraus ergeben. Dabei können weitere Spaltennamen in der .dbf-Datei referenziert werden. Als Beispiel ein Ausschnitt aus einem Layer:

 <code>
CLASSITEM "NAME"
CLASS
EXPRESSION ([NAME] eq "Wolga" and [SIZE] < 10)
COLOR 255 0 0
END
CLASS
EXPRESSION /^A.+e<math>/
COLOR 0 0 255
END
CLASS
EXPRESSION /./
OUTLINECOLOR 128 128 128
END
</code> 

Die erste Klasse findet Anwendung auf alle Shapes, deren Spalte =NAME= im .dbf-File den Eintrag ''Wolga'' haben und gleichzeitig einen kleineren Wert als ''10'' in der Spalte =SIZE= .

Obwohl diese Ausdrücke schon eine Menge Flexibilität bieten, kann man noch einen Schritt weiter gehen, wie man in der zweiten Klasse sehen kann. Die Art des dortigen Ausdrucks ist Informatikern als sogenannter regulärer Ausdruck bekannt. Der Ausdruck passt auf alle Einträge in der =NAME= -Spalte, auf die folgendes zutrifft: der erste Buchstabe ist ein großes ''A'' , das von einer beliebigen Anzahl beliebiger Zeichen (mindestens jedoch einem) gefolgt wird, abgeschlossen durch ein kleines ''e'' .

Die letzte Regel zeigt ebenfalls einen regulären Ausdruck. Er passt auf jedes beliebige Zeichen. Da die Classes von oben nach unten auf der Suche nach der ersten passenden Regel für ein Feature abgesucht werden, handelt es sich um eine sogenannte ''catch all'' -Regel, die auf alles zutrifft, was nicht vorher schon irgendwo gepasst hat.

Reguläre Ausdrücke sind ein ungemein mächtiges Werkzeug, das jedoch etwas Mühe zu Lernen erfordern kann. MapServer verwendet POSIX-konforme reguläre Ausdrücke, die auf jedem Unix-System in einer =man= -Page~[[man:7:regex]] erklärt werden.

=Styles=(6)\index{Styles}\index{Mapfile!Styles}

Mit MapServer 4.0 ist eine weitere Art eingeführt worden, die Darstellung eines Layers zu notieren. Um genau zu sein, sollte diese Art langsam aber sicher bevorzugt werden, zumal sie auch zusätzliche Vorteile bietet.

Aber zunächst sollen Sie natürlich erfahren, um was es geht. MapServer kennt ein neues Objekt, also eine Sektion, mit dem Namen =STYLE= . Diese Sektion trit nur innerhalb von Classes auf und wird selbstverständlich jeweils mit einem =END= abgeschlossen. Das ganze soll den Zweck haben, den gestalterischen Part einer Class vom logischen zu trennen. Anstatt also folgendes zu notieren:

 <code>
CLASS
EXPRESSION ([NAME] eq "Havel" and [SIZE] > 20)
SYMBOL "punkt"
COLOR 32 64 218
END
</code> 

würden Sie in Zukunft folgendes schreiben:

 <code>
CLASS
EXPRESSION ([NAME] eq "Havel" and [SIZE] > 20)
STYLE
SYMBOL "punkt"
COLOR 32 64 218
END
END
</code> 

Im Moment können Sie noch beides verwenden. Im Sinne einer sauberen Arbeitsweise sollte Sie allerdings dazu übergehen, Styles zu benutzen und die Parameter, die für die Darstellung zuständig sind, nicht mehr direkt in den Classes zu notieren.

Die folgenden Parameter wandern in die Style-Sektion einer Class:

*=ANTIALIAS=
*=BACKGROUNDCOLOR=
*=COLOR=
*=MAXSIZE=
*=MINSIZE=
*=OFFSET=
*=OUTLINECOLOR=
*=SIZE=
*=SYMBOL=

Die Notierung der Parameter erfolgt wie weiter vorne ab Seite~\pageref{text:mapfile:class:parameters} beschrieben.

Warum sollte man das haben wollen? Es soll in Zukunft möglich sein, Styles mit Namen zu versehen, und dadurch Styles im gesamten Mapfile durch eben ihren Namen zu referenzieren. Dadurch kann bei umfangreichen Mapfiles einiges an Schreibarbeit eingespart werden. Insbesondere wird aber zukünftig Arbeit einsparen, weil Sie dann nur noch Styles von einem Mapfile ins andere Kopieren müssen, ohne auch noch an einer Class herumhantieren zu müssen.

Des weiteren kann man mehrere Styles in einer Class haben, sie werden der Reihe nach von oben nach unten ausgewertet; dabei wird, wie schon bei den Layern im Mapfile, der oberste Style zuerst gezeichnet. Dadurch ist es endlich möglich, mehr als die bisherigen 2 Symbole übereinander zu legen, wie es bisher mit =SYMBOL= und =OVERLAYSYMBOL= geschehen ist.

Außerdem -- dieser Teil ist allerdings reine Spekulation des Autors -- dürfte eine Abspaltung des darstellenden Teils einer Class die Implementierung der so genannten ''styled layer descriptors'' vereinfachen, einem OGC-Standard~[[pdf:spec:sld10]], mit dem sich die Darstellung von Kartenfeatures über URL-Parameter beeinflussen läßt.

=Rasterdaten=(7)
\index{Rasterdaten}\index{Mapfile!Rasterdaten}

Rasterdaten sind alle Arten von Daten, deren Dimensionen in Länge und Breite in Pixeln gemessen werden kann, vulgo: Bildformate. Die Bildformate, die von MapServer unterstützt werden, müssen in zwei Kategorien eingeteilt werden: die von der Software lesbaren (Input) und die Ausgabeformate (Output).

Als Ausgabe liefert MapServer Bilder, die von Webbrowsern darstellbar sind. Da sich MapServer dabei auf die Grafikbibliothek GD stützt, ist er auf deren Fähigkeiten angewiesen.

Ein typischer Rasterlayer wird im Mapfile etwa auf folgende Art angelegt:

 <code>
LAYER
NAME "brandenburg_luftbild"
DATA "bilder/brandenburg.tif"
TYPE RASTER
STATUS ON
END
</code> 

In diesem Beispiel wird ein ''tiff'' -Bild eingebunden, das anscheinend ein Luftbild der Region Brandenburg zum Inhalt hat. Der =TYPE= des Layers ist als =RASTER= angegeben.

Welche Formate eingelesen werden können, ist im wesentlichen eine Frage, die bei der Konfiguration noch vor der Kompilierung der Software geklärt wird. Einige Formate können dabei als eingebaut angesehen werden, indem der MapServer direkt auf die entsprechenden Bibliotheken zugreift. Andere Formate werden über die Rasterbibliothek GDAL gehandhabt.

Welche Formate Ihr MapServer handhaben kann, können Sie durch das Ausführen des CGI-Binaries auf der Kommandozeile mit dem Kommandozeilenschalter
''-v'' herausfinden:

 <code>
thfischer@grobi # ./mapserv -v
MapServer version 4.0 OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF
OUTPUT=SWF SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER
SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT
INPUT=EPPL7 INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE
</code> 

In diesem Beispiel sehen wir =.jpeg= als (lesend) unterstütztes Rasterformate. Weitere Formate können durch Verwendung der GDAL-Schnittstelle angesprochen werden, insbesondere findet hier das Lesen von =.tif= -Bildern über GDAL statt. Mehr zu diesen Bibliotheken finden Sie weiter hinten im Buch.

Beachten Sie, dass es für Rasterdaten keine Queries auf den Layer geben kann, da mit den gängigen Rasterformaten keine Metadaten gespeichert werden.

==Bildkataloge==(8)
\index{Rasterdaten!Kataloge}\index{Bildkataloge}

Bilddaten können sehr schnell sehr groß werden. Detaillierte Rasterbilder können viele Megabyte, wenn nicht gar Gigabyte groß werden. Solche Datenmengen sind nur schwierig zu handhaben, sowohl für den MapServer als auch, was die Verwaltung angeht. Um die Verarbeitung zu beschleunigen und die Handhabung zu vereinfachen, kann man sich so genannter Bildkataloge bedienen.

Des weiteren kann es natürlich passieren, dass man seine Daten gleich in mehreren Bildern bekommt, aber sicherlich nicht für jedes Bild einen eigenen Layer im Mapfile anlegen möchte. Man könnte die Layer natürlich mittels =GROUP= zusammenfassen; aber man müßte eben immer noch alle Layer ins Mapfile eintragen.

Das Format von MapServer-Bildkatalogen verwendet keinen verbreiteten Standard, der dazu führen würde, dass Sie die Bildkataloge auch mit anderen Programmen einlesen könnten. Allerdings verläßt sich MapServer auf standardisierte Datenformate, sodass eine Konvertierung von dieser Seite aus keine Schwierigkeiten bereiten sollte.

Dabei werden alle Bilder (sie müssen mit Worldfiles georeferenziert sein) über ein Shapefile verortet. Das Shapefile erhält dabei die Koordinaten der einzelnen Bilder, die ''.dbf'' -Datei der Reihe nach die dazugehörigen Dateinamen der Bilder.

Die Notation solcher Kataloge im Mapfile erfolgt folgendermaßen:

 <code>
LAYER
NAME "luftbild"
TYPE RASTER
STATUS ON
TILEINDEX "luftbildshape"
TILEITEM "IMAGEFILENAME"
END
</code> 

In diesem Beispiel trägt das Katalog-Shapefile den Namen =luftbildshape= . Mit =TILEITEM= gibt man an, wie die Spalte in der ''.dbf'' -Datei heißt, die die Dateinamen der Rasterbilder trägt.

Das Erzeugen von Bildkatalogen muß durch zusätzliche Software geschehen. Die Bibliothek GDAL bringt dafür ein Werkzeug namens =gdaltindex= mit -- siehe Seite~\pageref{text:tools:gdaltindex}

Durch den Aufbau mittels eines Shapefiles lassen sich die einzelnen Kacheln selber übrigens sehr schön visualisieren, indem man das betreffende Shape als Layer einbindet.

==Rasterdaten klassifizieren==

Rasterdaten können, ähnlich wie Vektordaten, klassifiziert werden. Dabei werden alle Pixel einer bestimmten Farbe (oder einer bestimmten Menge von Farben) auf eine andere Farbe abgebildet. Das macht man gerne bei 1-Bit-Bildern. Diese bestehen nur aus zwei Farben (also schwarz und weiß). Man färbt dann alle schwarzen Pixel in der gewählten Farbe ein, und schaltet dann die weißen Pixel für gewöhnlich transparent. Auf diese Weise lassen sich viele solcher Bilder in Schichten übereinander legen.

Es können aber auch Bilder mit 256 Farben klassifiziert werden.

Schauen wir uns ein Beispiel an:

 <code>
LAYER
NAME "grundwasser"
TYPE RASTER
STATUS ON
CLASSITEM "[pixel]"
CLASS
EXPRESSION ([pixel] < 128)
COLOR 255 0 0
END
CLASS
EXPRESSION ([pixel] >= 128)
COLOR 0 0 255
END
END
</code> 

Das =CLASSITEM= , nach dem wir filtern möchten, trägt den Namen =pixel= und repräsentiert die Nummer der Farbe in der Farbpalette des Bildes. Das funktioniert im Moment übrigens nur bei GD-Ausgabetreibern korrekt; der GDAL-Treiber\footnote{Zu Ausgabeformaten und -treibern siehe auch Seite~\pageref{text:mapfile:ausgabeformate}.} biegt vor der Bearbeitung des Bildes die Farbpaletten um, sodass man sich nicht auf die Position in der Farbpalette verlassen kann.

Die erste Class verleiht nun den ersten 128 Farben in der Farbpalette des Bildes ein grelles Rot, alle anderen Pixel werden durch die zweite Class blau dargestellt.

FIXME: ist das analog für truecolor-bilder etc.?

==Umprojizieren von Rasterdaten==

Der Gedanke läuft einem zuwider, wenn man sich die Mathematik klar macht. Man betrachte ein 4000 mal 4000 großes Tiff-Bild. Wenn man dieses Bild komplett umprojizieren möchte, müssen also 16 Millionen Pixel darauf geprüft werden, ob sie im neuen Zielbild liegen. Und wenn wir nun annehmen, dass wir 16 mal 16 solcher Kacheln haben, landen wir bei über 4 Milliarden Pixeln. Dass diese Berechnung eine Weile dauert, ist auf den ersten Blick ersichtlich.

Wenn Sie es jedoch einmal ausprobieren, werden Sie erstaunt sein, wie schnell MapServer Ihnen eine umprojizierte Karte liefert. Leider immer noch nicht schnell genug, wie man es im Dauerbetrieb, beispielsweise auf einer Website, haben will. Sie können sehr wohl mit der Geschwindigkeit vor Ihren Freunden angeben. Für den Dauerbetrieb lohnt es sich aber, die Projektion für Ihre Daten vorher zu machen.

Gleiche Überlegungen gelten übrigens auch für verschiedene Zoomstufen. Es lohnt sich durchaus, im Vorhinein zu überlegen, welche Zoomstufen am häufigsten zu sehen sein werden, um dann mit =MINSCALE= und =MAXSCALE= für diese Stufen verschiedene Datensätze anzuzeigen. Weitere Überlegungen zur Performance von MapServer-Anwendungen finden Sie ab Seite~\pageref{anhang:performance}.

==Rasterdaten mit GDAL==

\begin{figure}
\begin{center}
\mmfig{0.65}{gtopo30}{Die GTOPO30-Daten, hier ein Ausschnitt des Kanals zwischen Frankreich und Großbritannien.}
\end{center}
\end{figure}

Die Bibliothek GDAL ist für das Einlesen von Rasterdaten in MapServer zuständig, die über die 'herkömmlichen' Formate wie TIFF, JPEG, PNG und so weiter hinausgehen. Eine Liste von unterstützten Formaten finden Sie auf der GDAL-Website~[[http:website:gdal]]. Für diverse Formate müssen Sie unter Umständen die eine oder andere Zusatzbibliothek installiert haben. Bei Fragen oder Problemen hilft entweder ebenfalls die GDAL-Site weiter, oder eine Anfrage auf der MapServer-Mailingliste.

Die Notation von GDAL-gelesenen Rasterdaten weicht glücklicherweise überhaupt nicht von der von herkömmlichen Rasterdaten ab. Als Beispiel sollen hier die GTOPO30-Daten herhalten, die man sich von~[[ftp:gtopo30]] herunterladen kann\footnote{Achtung, falls Sie es auf den kompletten Datensatz für die ganze Welt abgesehen haben sollten: vollständig entpackt handelt es sich um 2,1 GB Daten. Beachten Sie bitte, dass es sich dabei um =Textdateien= handelt, die Bearbeitung also durchaus zeitintensiv ist.}.

Interessant sind für die Notation die Dateien mit der Endung =.DEM= . Die Abkürzung steht für ''digital elevation model'' , also für digitales Höhenmodell.

Sie können diese Daten in ein Unterverzeichnis entpacken -- nennen wir es =gtopo30= -- und dann ''gdaltindex'' für das Erzeugen eines Bildkatalogs aufrufen:

 <code>
# gdaltindex gtopo30.shp gtopo30/*.DEM
</code> 

Haben Sie das getan, können Sie sich einfach einen Layer wie folgt konstruieren:

 <code>
LAYER
NAME "gtopo30"
TYPE RASTER
STATUS ON
TILEINDEX "gtopo30"
END
</code> 

Und damit sind Sie dann auch schon fertig! Das Ergebnis sind dann beispielsweise aus wie in Abbildung~\ref{gtopo30}. Das DEM-Format wird behandelt wie jedes andere Rasterformat auch. Dem entsprechend können Sie eine einzelne dieser DEM-Dateien auch wie gewohnt folgendermaßen einbinden:

 <code>
LAYER
NAME "gtopo30"
TYPE RASTER
STATUS ON
DATA "gtopo30/W180S60.DEM"
END
</code> 

=Vektordaten=
\index{Vektordaten}

In seinen 'Jugendzeiten' war MapServer im wesentlichen darauf ausgelegt, Shapefiles darzustellen. Das macht sich insbesondere bei der Notation im Mapfile bemerkbar, wo bei Vektordaten einige Shapfile-spezifische Termini verwendet werden.

Zuerst ein Beispiel für Vektordaten in einem Layer:

 <code>
LAYER
NAME "gruenflaechen"
TYPE POLYGON
STATUS ON
DATA "gruenflaechen_0323333"
CLASS
EXPRESSION /./
COLOR 255 240 128
OUTLINECOLOR 128 120 64
END
END
</code> 

Der Typ eines Vektorlayers kann =POINT= , =LINE= oder =POLYGON= sein. Beachten Sie dabei, dass die beiden letztgenannten intern im wesentlichen gleich sind und daher in einigen Fällen austauschbar sind.

=DATA= verweist in diesem Fall auf ein Shapefile mit dem angegebenen Namen. Dieser Name ist relativ zum =SHAPEPATH= im Header des Mapfiles.

Das war auch schon alles, was es zur Notation von Shapefile-Layern im Mapfile zu sagen gibt. MapServer ist in der Lage, über Zusatzbibliotheken weitere Vektorformate zusätzliche zu Shapefiles einzulesen und zu verarbeiten.

==Indizes für Shapefiles==\index{Index}\index{Index!Shapefiles}(9)

Mit sogenannten Quadtree-Indizes läßt sich die Bearbeitung von Shapefiles erheblich beschleunigen. Wie solche Indizes für den MapServer erstellt werden, erfahren Sie auf Seite~\pageref{text:tools:shptree}, wo das Werkzeug =shptree= vorgestellt wird. Hier soll nur kurz die dahinter stehende Idee erläutert werden.

In einem Shapfile, das beispielsweise 100 Shapes hat, muß für einen gegebenen Ausschnitt geprüft werden, ob das Shape ganz oder in Teilen in diesem Ausschnitt liegt und demnach angezeigt werden soll. Das geschieht über die Bounding Box eines Shapes, die mit im Shapefile gespeichert ist.

Ein Quadtree-Index folgt dem Gedanken, die Fläche des Shapefiles in vier Teile einzuteilen, und die darin liegenden Shapes in einem Index festzuhalten. Bei einem Zugriff wird zuerst die Fläche gesucht, in der der Ausschnitt liegt, und somit die Anzahl der zu prüfenden Shapes vermindert.

Die einzelnen Flächen lassen sich danach noch einmal in vier Unterflächen aufteilen (und diese wiederum in vier Unterflächen, und so weiter), sodass bei der Darstellung eine baumartige Struktur entsteht.

Die Größe und Lage der einzelnen Flächen muß übrigens nicht genau jeweils ein Viertel der größeren Fläche einnehmen. Die einzelnen Flächen werden nach Anzahl der darin liegenden Shapes gewichtet.

==Graticule-Layer==\index{Graticules}\index{Grids}(10)

Ein Gitternetz kann in einer Karte zur Orientierung wertvoll sein. Leider hat man nicht immer ein entsprechendes Shapefile zur Hand. Abhilfe schaffen sogenannte Graticule-Layer, mit denen sich ein solches Gitternetz einfach definieren läßt.

Betrachten wir einen solchen Layer anhand eines Beispiels:

 <code>
LAYER
NAME "gitternetz"
TYPE LINE
STATUS ON
GRID
END
CLASS
COLOR 0 0 0
LABEL
TYPE BITMAP
SIZE TINY
COLOR 0 0 0
END
END
PROJECTION
"init=epsg:4326"
END
END
</code> 

Zwei Dinge fallen sofort auf. Zuerst einmal sieht man keine =DATA= -Angabe. Brauchen wir an dieser Stelle auch gar nicht, da unser Gitter für jeden Kartenaufruf dynamisch generiert werden soll.

Außerdem findet man eine neue Sektion =GRID= . In dieser Sektion werden die Eigenschaften des Gitters gesetzt.

Der Typ eines Gitterlayers ist =LINE= . Die Gestaltung des Gitters wird wie gewohnt in einer Class vorgenommen, und das Gitter kann beschriftet werden. Die Labels für die Beschriftung erscheinen immer an allen vier Seiten einer Karte. Für TrueType-Fonts empfiehlt sich eine sehr kleine Schriftgröße, da diese Beschriftung sonst sehr schnell aufdringlich wirken kann.

Der =PROJECTION= -Block gibt die Projektion des Gitters an. Der Layer wird dann so behandelt, als würde es sich bei der Datenquelle um ein Shapefile handeln, das in eben dieser Projektion vorliegt. Ohne Projektionsblock erhalten Sie ein einfaches rechteckiges Gitter; mit Projektion ist das Gitter natürlich entsprechend verzerrt.

Beachten Sie, dass die Beschriftung des Gitters immer im Koordinatensystem der Quellprojektion erfolgt. Wenn Sie also beispielsweise den EPSG-Code 4326 als Projektion für Ihren Gitterlayer angeben, so wird dieses Gitter in Gradangaben beschriftet werden, selbst wenn Sie eine Karte mit Gauss-Krüger-Koordinaten erzeugen.

Innerhalb des =GRID= -Blocks können Sie die folgenden Angaben machen, die allesamt nur eine einzelne Zahl als Parameter erwarten:

*=MINSUBDIVIDE= und =MAXSUBDIVIDE= : Jede der Kurven (Linien), aus denen das Gitter besteht, wird als separate Linie behandelt und besteht somit aus einzelnen Punkten. Je mehr Punkte für eine Linie gezeichnet werden müssen, desto mehr Prozessorzeit kostet das offensichtlich. Mit diesen beiden Parametern können Sie festlegen, aus wievielen Punkte eine Linie minimal beziehungsweise maximal zusammengesetzt sein darf. Sind die beiden Werte gleich, bestehen die Linien immer aus genausovielen Punkten wie angegeben.
*=MININTERVAL= und =MAXINTERVAL= : Mit diesen beiden Parameter können Sie ein minimales bzw. ein maximales Intervall zwischen zwei Kurven des Gitters angeben. Die Angabe wird im Koordinatensystem des Gitters gemacht.
*=MINARCS= und =MAXARCS= : Setzt die minimale bzw. maximale Anzahl von Kurven pro Achse. Beachten Sie bitte, dass bei diesen beiden Parametern und den beiden vorhergehenden ''versucht'' wird, den Vorgaben nachzukommen. Sollten die von Ihnen notierten Werte nicht zum gewünschten Ergebnis führen, sollten Sie ein wenig experimentieren, um ein Gefühl dafür zu bekommen, wie sich der Code bei verschiedenen Werten verhält.

=Projektionen=(11)
\index{Projektion}\index{Mapfile!Projektion}(12)

Zuerst die These: die Erde ist eine Kugel. Diese Kugel muß für eine Karte auf eine Ebene abgebildet werden. Das gilt für eine Papierkarte ebenso wie für einen Computerbildschirm. Wenn man jetzt bedenkt, dass es viele verschiedene Ideen gibt, Abbildungen von der Kugel auf die Ebene vorzunehmen, und wenn man dann noch einwirft, dass die Erde ja eigentlich gar keine richtige Kugel ist -- dann ist man in der Welt der Projektionen angekommen, die ebenso faszinierend wie enervierend sein kann.

\begin{figure}
\begin{center}
\mmfig{0.75}{projektion}{Ein und dieselbe Datenquelle in zwei verschiedenen Projektionen. Links EPSG:4326, rechts EPSG:31464.}
\end{center}
\end{figure}

Der Effekt, um den es geht, ist in Abbildung~\ref{projektion} zu sehen. Die rechte Darstellung der Datenquelle verwendet die Geo-Koordinaten der Bundeslandgrenzen (Ellipsoid WGS84). Die rechte Darstellung entspricht einer Projektion in die Ebene nach der Gauss-Krüger-Methode, hier im vierten Meridianstreifen.

Der MapServer verwendet für Projektionen eine eigene Bibliothek (''proj.4'' ) die von Haus aus bereits viele Projektionen kennt. Diese Bibliothek unterstützt aber auch EPSG-Codes~[[http:website:epsg]], die seit Einführung der OGC-Konformität die gängige Art und Weise darstellen, Projektionen im Mapfile zu notieren.

Projektionen interessieren an zwei Stellen: einmal bei der Frage, in welchen Projektionen die Daten vorliegen, und in welcher Projektion die fertige Karte dargestellt werden soll. MapServer ist in der Lage, die Projektion von Vektordaten 'on the fly' vorzunehmen. Dabei können die Daten verschiedener Layer durchaus verschiedener Projektion sein. Mit Unterstützung der Bibliothek GDAL ist MapServer auch in der Lage, Rasterdaten umzuprojizieren; die benötigte Rechenleistung dafür ist jedoch beträchtlich, da in einem Rasterbild jeder einzelne Punkt umprojiziert werden muß.

Mehr zur Bibliothek GDAL erfahren Sie in Anhang~\ref{anhang:formate}, in dem die vom MapServer unterstützten Formate vorgestellt werden.

==Notation==

Projektionen sind, wie bereits angemerkt, an zwei Stellen von Bedeutung: erstens wenn festgestellt werden soll, in welcher Projektion bestimmte Daten vorliegen, zweitens bei der Frage, in welcher Projektion die Karte ausgeliefert werden soll.

Dabei können die Projektionen, in denen die Daten vorliegen, auf Layer-Ebene zugewiesen werden. Jeder Layer kann also in einer eigenen Projektion vorliegen. MapServer ist in der Lage, Vektorlayer auf Anfrage umzuprojizieren. Unter Verwendung des Bibliothek GDAL funktioniert das auch für Rasterdaten. Das Umprojizieren von Rasterdaten ist jedoch derart rechenaufwendig, dass man es in den meisten Fällen vermeiden will.

Die Ausgabeprojektion muß verständlicherweise einheitlich sein, denn die fertige Karte kann schließlich nur in einer bestimmten Projektion vorliegen. Eine Ausnahme bildet ein OGC-konformer MapServer, der verschiedene Projektionen nach außen anbieten und über einen URL-Parameter aufgefordert werden kann, eine dieser Projektionen als Ergebnis zu liefern.

Die Notation von Projektionen geschieht über eine eigene Sektion mit dem Namen =PROJECTION= . In dieser Sektion können Projektionen entweder als eine Liste von Parametern für die Projektionsbibliothek proj.4 eingetragen werden, oder mit EPSG-Codes.

Das erste Beispiel zeigt die 'klassische' Notation anhand der Projektionsbibliothek:

 <code>
PROJECTION
"proj=utm"
"ellps=GRS80"
"zone=15"
"north"
"no_defs"
END
</code> 

Die Art der möglichen Parameter für die Projektionsbibliothek proj.4 entnehmen Sie bitte der Dokumentation dieser Software~[[http:website:libproj]].

Die zweite Möglichkeit erschließt sich durch EPSG-Codes:

 <code>
PROJECTION
"init=epsg:12345"
END
</code> 

12345 ersetzen Sie an dieser Stelle selbstverständlich durch den gewünschten EPSG-Code. Intern greift die Projektionsbibliothek an dieser Stelle übrigens auf eine Tabelle zu, die diese Codes dann auf die "`Original"'-Parameter abbildet. Achten Sie unbedingt darauf, =epsg= tatsächlich in Kleinbuchstaben zu notieren. Unter Windows ist das nicht relevant; entwickeln Sie jedoch unter einem anderen System, oder soll Ihre Anwendung portierbar sein, ist das wichtig.

Die Sektion =PROJECTION= kommt für die gesamte Karte nach dem Header im Mapfile zur Anwendung; für die Layer hat die Sektion natürlich innerhalb der =LAYER= -Sektion zu stehen, allerdings außerhalb etwaiger =CLASS= es, =LABEL= s und allem Anderen, das eine eigene Sektion einleitet.

\subsubsection*{Hinweis}(13)

Man möchte eigentlich meinen, dass die EPSG-Codes in Stein gemeißelt sind. Einmal vergeben, würde sich ein solcher Code nicht mehr ändern.

Leider ist diese Annahme ein Irrtum. Die Vergangenheit hat gezeigt, dass es passieren kann, dass Projektionen um mehrere Stellen in der Liste 'verrutschen' können. Zumindest einige deutsche und teilweise auch österreichische Projektionscodes sind in der Vergangenheit bei einem Versionssprung der Projektionsbibliothek nicht mehr vorhanden gewesen. Die interne Liste für den jeweiligen Release von ''proj.4'' wird scriptgesteuert aus der Access-Tabelle generiert, die man auf der Website der EPSG findet. Änderungen in der Tabelle schlagen also sofort auf die Projektionsbibliothek durch.

Bei unerwarteten Fehlermeldungen nach einem Upgrade der Projektionsbibliothek sollten Sie also prüfen, ob Ihre Projektionscodes noch korrekt sind und diese eventuell anpassen.

Dieses unvorhersehbare Verhalten der EPSG kann natürlich zu haarsträubenden Komplikationen bei kaskadierten WMS-Servern führen, wenn nur einer der Server aktualisiert wird.

==Orthographische Projektion==

\begin{figure}
\begin{center}
\mmfig{0.55}{ortho}{Eine orthographische Projektion stellt die Daten in einem Kreis dar, der einer Aufsicht auf einem Globus ähnlich sieht. Leider ist die Funktion in MapServer noch fehlerhaft.}
\end{center}
\end{figure}

Eine orthographische Projektion sieht aus wie ein Blick auf einen Globus. Falls die fertige Karte einen großen Teil der Welt abdeckt, sehen Sie die fertige Karte als Kreis.

Das kann schick aussehen, leider hat der Code für diese Projektion in MapServer noch den einen oder anderen Bug, die dann auftreten, sobald Features dargestellt werden sollen, die teilweise hinter dem Horizont verschwinden. Dann versucht MapServer immer noch Linien zu ziehen, die dann quer durch das ganze Bild gehen.

Zum Zeitpunkt der Drucklegung war die Darstellung leider immer noch fehlerhaft. Dennoch soll Ihnen ein Überblick über die Theorie nicht vorenthalten bleiben.

Als Zielprojektion im Kopf des Mapfiles definieren Sie eine orthographische Projektion wie folgt:

 <code>
PROJECTION
"proj=ortho"
"ellps=WGS84"
"lat_0=0.0"
"lon_0=0.0"
"x_0=0.0"
"y_0=0.0"
END
</code> 

Dabei sind =lat_0= und =lon_0= die Koordinaten des Punktes, der als Mittelpunkt in der Karte zu sehen sein soll, in Längen- und Breitenangabe. Das ist sozusagen der Punkt, an dem Sie direkt auf den Globus schauen. Die beiden verbleibenden Parameter sind eine Verschiebung, jeweils ein Modifikator auf den Rechts- und den Hochwert des Punktes.

Das Ergebnis sieht dann in etwa so aus, wie Sie es in Abbildung~\ref{ortho} sehen können. Wegen der fehlerhaften Implementation ist die Darstellung von Features, die sich über den Horizont erstrecken, allerdings noch mangelhaft.

Und falls Sie später das Kapitel über MapScript lesen und Anregung für eine Übung suchen sollten, wie wäre es damit: erstellen Sie eine MapScript-Seite, die eine Karte in ortographischer Projektion darstellt. Beim Mausklick in die Karte soll allerdings nicht hinein- oder herausgezoomt werden, sondern eben dieser angeklickte Punkt soll als neuer Bezugspunkt für die Projektion dienen. Der 'Globus' wird also anhand des Klicks 'gedreht'. Viel Spaß dabei =:)=

==Projektionen im realen Einsatz==

Der Autor hat schon von Leuten gehört, die meinten, Projektionen würden die Daten 'verfälschen'. Zu einem gewissen Grad ist das sicherlich richtig; im Grunde genommen handelt es sich aber nur um eine andere Art der Darstellung.

Kartographen sind übrigens nicht die einzigen Menschen, die sich mit Projektionen in die Ebene auseinandersetzen müssen. Eine ganze Industrie in Gestalt der Spiele- und Grafikkartenindustrie lebt mit und von dem Problem, (dreidimensionale) Objekte auf eine plane Fläche (den Computerbildschirm) abzubilden.

Falls Sie in Ihrer Anwendung MapServer Daten ''on the fly'' umprojizieren lassen möchten, sollten Sie sich im Vorhinein über Ihre Zielgruppe Gedanken machen. Menschen könnten es Ihnen durchaus übelnehmen, wenn die Karten im Webbrowser wie in Abbildung~\ref{projektion} links aussehen -- nämlich angeblich 'gequetscht'. Denken Sie immer daran, wass die Benutzer wohl als Darstellung aus ihrem Atlas daheim~[[diercke:2002]] gewohnt sein könnten.

=Schriften=\index{Schriften}\index{Fonts}(14)

MapServer kennt zur Beschriftung von Features zwei Typen von Schriften: Bitmap- und TrueType-Schriften. Während erstere bereits im MapServer `"eingebaut"' sind, sind TrueType-Schriften separate Dateien, die Sie der Anwendung bereitstellen müssen. Hingegen benötigen Bitmap-Schriften keine zusätzliche Vorbereitung, um verwendet zu werden; Sie können direkt mit Abschnitt~15 fortfahren.

Ein weiteres Problem mit TrueType-Schriften können lizenzrechtlicher Natur sein. Ob Sie die Schriftdateien, die Sie für den Gebrauch mit beispielsweise Photoshop gekauft haben, einfach so zur Beschriftung und Veröffentlichung von Karten im Internet verwenden dürfen, müssen Sie individuell mit dem Hersteller der Schriften regeln.

Wie die Symbole für eine Karte werden auch die TrueType-Schriftarten in einer separaten Datei deklariert. Anders als die Symbole für ein Mapfile können die Schriften jedoch nicht alternativ direkt in das Mapfile eingetragen werden; sie müssen immer in einer separaten Datei stehen.

Der Verweis auf eine Schriftendatei erfolgt über das Schlüsselwort ''FONTPATH'' im Header des Mapfiles:

 <code>
...
FONTPATH "fonts/fonts.list"
...
</code> 

Diese Angabe kann sowohl ein absoluter Pfad im System sein, als auch relativ zum Mapfile.

Im Innern ist diese Liste sehr simpel aufgebaut:

 <code>
arial arial.ttf
times times.ttf
...
</code> 

In jeder Zeile steht zuerst ein Alias, gefolgt von mindestens einer Leerstelle (oder einem Tab) und der Name der .ttf-Datei. Das Alias ist ein Name, der im Folgenden im Mapfile verwendet wird, um auf die Schriftart Bezug zu nehmen.

Für Bitmap-Schriften müssen, wie gesagt, keine solche Vorbereitungen getroffen werden.

=Annotationen=
\index{Annotationen}
\index{Beschriftungen}
(15)

Beschriftungen von Layern sind für MapServer wiederum eigene Layer, mit einem eigenen Typ mit dem Namen =ANNOTATION= .

Die Art der Beschriftung (was wann wie beschriftet werden soll und auf welche Art) wird in den Klassen dieses Layers festgelegt. Dadurch erreicht man eine recht hohe Flexibilität, indem man Beschriftungen von Features unabhängig davon darstellen kann, ob das Feature selber zu sehen ist. Und wenn man beides unter den selben Umständen angezeigt haben möchte, verwendet man für beide Layer einfach die gleiche Klassendefinition.

Für eine Oberfläche zur Navigation in der Karte bedeutet das auf der anderen Seite zusätzliche, unerwünschte Komplexität, da die Beschriftungslayer nun unter Umständen durch den Benutzer als eigene Layer an- und abgewählt werden müssen.

Diesen Umstand kann man auf zwei Wegen umgehen. Eine Methode ist, dem Beschriftungslayer den gleichen Namen zu geben, wie dem Layer, der die Daten anzeigt. Dann werden beide Layer über diesen Namen angesprochen. Der zweite Weg ist, beide Layer zu einer =GROUP= zusammenzufassen, über deren Namen man auf beide Layer gleichzeitig zugreifen kann. Mehr über das Gruppieren von Layern erfahren Sie ab Seite~\pageref{text:mapfile:layer:group}

Man könnte auch alle Beschriftungen in einer =GROUP= zusammenfassen, sodass sie sich alle mit einem Mal an- und ausschalten lassen.

Es lassen sich im übrigen nur Vektorlayer beschriften.

Die Notation von Beschriftungslayern sieht wie folgt aus:

 <code>
LAYER
NAME "strassen_annotation"
GROUP "beschriftungen"
TYPE ANNOTATION
...
CLASSITEM "NUMMER"
LABELITEM "NUMMER"
CLASS
...
LABEL
TYPE BITMAP
SIZE NORMAL
COLOR 0 0 0
POSITION CR
PARTIALS TRUE
END
END
END
</code> 

Es werden also diverse Änderungen im Vergleich zu einem dartstellenden Layer vorgenommen. Der Typ des Layers ist =ANNOTATION= .

Das Schlüsselwort =LABELITEM= funktioniert so ähnlich wie =CLASSITEM= . Während letzteres jedoch angibt, anhand welcher Spalte in der ''.dbf'' -Datei die nachfolgenden Classes gefiltert werden sollen, definiert =LABELITEM= die Spalte, aus der der Inhalt für die Beschriftungen geholt werden soll. Auf diese Weise läßt sich also nach einem Kriterium filtern und nach einem anderen beschriften, was die Angelegenheit flexibler gestaltet.

==Die Label-Sektion==\index{Label}\index{Mapfile!Label}

Die eigentliche Definition einer Beschriftung erfolgt dann in den einzelnen Classes. Im obigen Beispiel werden die im MapServer eingebauten Bitmap-Schriften verwendet. Zur genauen Notation von Bitmap- und TrueType-Schriften siehe auch die nächsten beiden Abschnitte.

Wie so häufig kommt erhöhte Flexibilität auch an dieser Stelle auf Kosten größeren Aufwands. Für jede zu beschriftende Klasse muß eine eigene Label-Sektion eingerichtet werden.

Die folgenden Parameter finden in allen Arten von Labeln Verwendung, unabhängig davon, ob es sich um Bitmap- oder TrueType-Beschriftungen handelt:

*=BACKGROUNDCOLOR <red> <green> <blue>= Mit dieser Option bekommt das Label eine Hintergrundfarbe verpaßt; man sieht dann ein Rechteck in dieser Farbe, in dem sich dann das Label befindet. Voreinstellung ist gar keine Farbe.
*=BACKGROUNDSHADOWCOLOR <red> <green> <blue>= Wirft einen Schatten in der angegebenen Farbe um das eben genannte Rechteck. Voreinstellung ist kein Schattenwurf.
*=BACKGROUNDSHADOWCOLORSIZE <x> <y>= Legt den Offset für den genannten Schatten in x- und y-Richtung fest. Voreinstellung in beide Richtungen ist 1.
*=BUFFER <integer>= Definiert einen Abstand, den andere Beschriftungen zu einem Label mindestens haben müssen, um gezeichnet werden zu können. Erhöht die Lesbarkeit bei vielen Beschriftungen, kann aber zu Problemen führen (siehe Abschnitt~16, ''Hinweise'' ).
*=COLOR <red> <green> <blue>= Die Farbe, in der die Schrift gemalt werden soll.
*=OUTLINECOLOR <red> <green> <blue>= Umrißarbe für die Schrift.
*=FORCE <TRUE|FALSE>= Erzwingt das Zeichnen einer Beschriftung. Dadurch werden Einträge wie =BUFFER= ignoriert. Diese Option ist als Vorgabe nicht aktiviert.
*=POSITION=
*=PARTIALS <TRUE|FALSE>= Unter Umständen liegen einzelne Features so ungünstig, dass seine Beschriftung nur teilweise sichtbar wäre. Mit =PARTIALS= wird festgelegt, ob diese teilweise Beschriftungen angezeigt werden sollen.
*=WRAP <zeichen>= Legt ein Zeichen fest, das als Zeilentrenner interpretiert werden soll. Das Ergebsnis sind mehrzeilige Beschriftungen.

Labels lassen sich außer zur Beschriftung auch bei TrueType-Symbolen verwenden; siehe auch Abschnitt~18

==Bitmap-Schriften==\index{Bitmap-Schriften}
\index{Beschriftungen!Bitmap}\index{Annotationen!Bitmap}

Bitmap-Schriften skalieren schlecht und sehen, gelinde gesagt, nicht sonderlich gut aus. Sie benötigen jedoch keinen zusätzlichen Aufwand und sind in jeder MapServer-Installation automatisch vorhanden. Auch benötigen sie wesentlich weniger Rechenzeit.

Wenn Sie die Beschriftung nur um der Beschriftung willen einsetzen möchten und keine besonderen Anforderungen an ihr Aussehen stellen, sind Bitmap-Schriften das, was Sie haben möchten.

Ein =ANNOTATION= -Layer mit Bitmap-Schriften sieht beispielsweise folgendermaßen aus:

 <code>
LAYER
NAME "strassen"
STATUS ON
TYPE ANNOTATION
DATA "strassen"
LABELITEM "NUMMER"
CLASS
LABEL
TYPE BITMAP
SIZE SMALL
COLOR 0 0 0
OUTLINECOLOR 255 255 255
END
END
END
</code> 

Jedes Feature wird hier mit einer kleinen, weiß umrandeten, schwarzen Beschriftung versehen.

Die folgenden Optionen sind nur beim Einsatz von Bitmap-Schriften von Belang:

*=SIZE <TINY|SMALL|MEDIUM|LARGE|GIANT= Diese fünf verschiedenen Größen sind fix, und es gibt keine Zwischengrößen. Experimentieren Sie am besten mit allen herum, um ein Gefühl dafür zu kriegen, wie groß sie im Einsatz sind.

==TrueType-Schriften==\index{TrueType-Schriften}
\index{Beschriftungen!TrueType}\index{Annotationen!TrueType}

TrueType-Schriften skalieren besser als die im MapServer eingebauten Schriftarten und sehen generell besser aus, benötigen jedoch einiges an zusätzlicher Vorbereitung, beispielsweise bei der Installation und weil das Anlegen einer Font-Datei für den MapServer nötig wird. Auch der Aufwand an Rechenzeit ist merklich größer.

Falls Sie jedoch Wert auf qualitativ hochwertige Schriften legen oder gar eine gewisse Stimmung erzeugen möchten -- indem Sie Frakturschriften in den Karten Ihrer mittelalterlichen Rollenspielwelt verwenden, um ein Beispiel zu nennen --, so kommen Sie um TrueType-Schriften nicht herum.

 <code>
LAYER
NAME "strassen"
STATUS ON
TYPE ANNOTATION
DATA "strassen"
LABELITEM "NUMMER"
CLASS
LABEL
TYPE TRUETYPE
FONT "Arial"
SIZE 12
COLOR 0 0 0
OUTLINECOLOR 255 255 255
END
END
END
</code> 

Der Typ des Labels muß natürlich =TRUETYPE= sein. Anstelle eines von fünf festen Strings treten Angaben in Pixeln. Und natürlich muß der Name der Schrift angegeben werden -- dafür wird ein Alias verwendet, der in der Font-Datei definiert worden sein muß (siehe auch Beginn dieser Sektion).

Die folgenden Optionen im Label-Objekt lassen sich nur dann verwenden, wenn TrueType-Schriften zum Einsatz kommen:

*=ANGLE <double>= Eine Winkelangabe in Grad, um die die Beschriftung gedreht werden soll. Kann nur in Linien-Layern benutzt werden. Wird anstatt eines Zahlenwertes =AUTO= verwendet, richtet sich der Text an der Linie aus.
*=ANTIALIAS <TRUE|FALSE>= Schaltet Kantenglättung für Schriften an oder aus.
*=FONT <name>= Name der Schriftart, wie er in der Font-Datei festgelegt worden ist.

==Hinweise==(16)

Automatische Beschriftungen von ebenso automatisch generierten Karten haben einige Tücken, derer man sich bewußt sein sollte, bevor man vom Ergebnis enttäuscht wird.

Angaben wie das zuvor genannte =BUFFER= beispielsweise bewirken, dass diverse Labels gar nicht erst gezeichnet werden. Das kann zum Beispiel zur Folge haben, dass die kleinen Orte um eine große Stadt durchaus beschriftet werden -- und dann aber kein Platz mehr für eine Beschriftung neben der Stadt ist und diese dann in der fertigen Karte ohne auskommen muß.

Zu allem Überfluss können sich die Labels nach dem nächsten Zoom oder gar nur nach einem Pan so verschoben haben, dass besagte Stadt plötzlich eben doch beschriftet ist. Der Benutzer kann sich dann fragen, welch merkwürdige Karte er da vor sich hat.

Es gibt mehrere Möglichkeiten, mit diesem Phänomen umzugehen. Man kann stundenlang mit Schriftgrößen und Zoomstufen herumexperimentieren -- aber der nächste Benutzer wird eben doch die Einstellung finden, an die man nicht gedacht hat.

Sicherlich sinnvoll ist es, mit =MINSIZE= und =MAXSIZE= Maßstäbe festzulegen, ab denen bestimmte Beschriftungen zulässig werden. Features, die unter allen Umständen beschriftet werden sollen, sollten mit =FORCE TRUE= dazu gezwungen werden.

Die korrekte Vorgehensweise bei diesen Phänomen dürfte von Fall zu Fall unterschiedlich sein; auf alle Fälle sollte man sich aber der Existenz des Problems bewußt und darauf vorbereitet sein, es eventuell in Angriff nehmen zu müssen, falls jemand darauf stößt.

=Symbole=\index{Symbole}(17)

Symboldateien definieren Darstellungen, die von den normalen Formen abweichen, die also mehr sind als simple Striche für Polygonumrandungen oder Linienvektoren.

Notiert werden Symbole entweder direkt im Mapfile als einzelne Sektionen nach dem Header. Oder aber in einer eigenen Datei, genannt =SYMBOLSET= , die im Header deklariert wird -- siehe auch Seite~\pageref{text:mapfile:header}. Begonnen wird ein Symbol mit =SYMBOL= , abgeschlossen wird es mit =END= .

Farben werden für Symbole nicht in den Symbol-Sektionen definiert, sondern in den Classes, die die Symbole verwenden.

MapServer kennt die folgenden Arten von Symbolen, die in Symboldateien definiert werden können, und die in einer Symbol-Sektion über =TYPE= deklariert werden:

*=VECTOR= Ein oder mehrere Vektoren, die aneinandergefügt ein Symbol ergeben. Dadurch können Rechtecke, Dreiecke und andere geometrische Formen realisiert werden.
*=ELLIPSE= Ellipsen werden über zwei Radien definiert. Sind beide Werte gleich, entsteht ein Kreis. Ergänzt die geometrischen Formen, die mit =VECTOR= möglich sind.
*=PIXMAP= Linien können mit (möglichst kleinen) Bilddateien gezogen werden. Ebenso können Polygone mit solchen Bilder ausgefüllt werden. Das Format dieser Bilder muß vom MapServer unterstützt werden. Das schließt beispielsweise ''.gif'' -Bilder aus, wenn es sich um einen MapServer handelt, der ''.png'' -Bilder generiert.
*=TRUETYPE= Einzelne Symbole aus TrueType-Schriften können zur Annotation von Features in Karten benutzt werden. Es gibt einige TrueType-Zeichensätze, die speziell für die Verwendung in Karten erstellt worden sind.

Ferner können sogenannte Overlaysymbole für Linien definiert werden, bei denen ein Liniensymbol über ein anderes gelegt wird; mehr dazu weiter unten.

Die folgenden Parameter können für Symbole gesetzt sein, wenn es sich nicht um TrueType-Symbole handelt.

*=NAME <name>= Name des Symbols. Sollte immer gesetzt sein, falls man seine Symbole nicht über ihre Nummer innerhalb der Symboldatei referenzieren möchte -- was spätestens dann für Unheil sorgen wird, wenn man zusätzliche Symbole mitten in der Datei einfügt.
*=FILLED <TRUE|FALSE>= Das Symbol soll gefüllt sein.
*=PIXMAP <dateiname>= Eine Bilddatei, die als 'Pinsel' verwendet werden soll. Kommt nur für Symbole vom Typ =PIXMAP= zur Anwendung.
*=STYLE= Eine eigene Sektion innerhalb eines Symbols, die einen Stil für Linien-Symbole definiert. Es handelt sich um einen einzelnen Punkt (referenziert als =SYMBOL 0= ), der je nach Stil an- und wieder ausgeschaltet wird. Zur Verdeutlichung ein Beispiel: <code> STYLE 2 3 2 4 END </code> Mit diesem =STYLE= werden zwei Pixel einer Linie gezeichnet, dann drei Pixel Pause gemacht, dann werden wieder zwei Pixel gezeichnet, woraufhin wieder vier Pixel ausgelassen werden. Danach geht das ganze wieder von vorne los.
*=POINTS= Dies ist eine eigene Sektion innerhalb eines Symbols und beschreibt ein Symbol über Vektoren.
*=TRANSPARENT <index>= Der Index der Farbe in einer Farbpalette, die bei einem Pixmap-Symbol transparent geschaltet werden soll.

\subsubsection*{Points}

Vektor-Symbole werden über eine eigene Sektion innerhalb eines Symbols definiert, die mit =POINTS= beginnt, mit =END= abgeschlossen wird und Paare von Zahlen enthält; Punkte eines Vektors eben.

Ein Beispiel für ein Vektor-Symbol:

 <code>
SYMBOL
TYPE VECTOR
NAME "dreieck"
POINTS
1 1
3 3
3 1
1 1
END
END
</code> 

Dieses Symbol beschreibt ein Dreieck. Beachten Sie, dass Sie für einen geschlossenen Kantenzug immer den ersten Punkt noch einmal als letzten Punkt einfügen müssen.

Punkte, bei denen beide Koordinaten negativ sind, werden als Trenner betrachtet. Dadurch können Sie beispielsweise Kreuze und ähnliches realisieren, also Symbole, die aus mehreren Segmenten bestehen.

==TrueType-Symbole==\index{TrueType!Symbole}\index{Symbole!TrueType}(18)

TrueType-Schriften als Symbole funktionieren, indem man einzelne Zeichen aus der Schriftart herausgreift, und damit dann einzelne Punkte annotiert, oder das Symbol an einer Linie immer wieder wiederholt.

Beachten Sie, dass Unterstützung für TrueType-Schriften in den MapServer kompiliert sein muss, um diese Art von Beschriftung benutzen zu können.

Die folgenden Parameter in einer Symbol-Sektion kommen nur zum Tragen, wenn es sich um ein TrueType-Symbol handelt:

*=ANTIALIAS <FALSE|TRUE>= Gibt an, ob auf dem Symbol ein Antialiasing stattfinden soll.
*=CHARACTER <index>= Die Nummer des Zeichens innerhalb der TrueType-Datei, das als Symbol benutzt werden soll.
*=FONT <name>= Alias der TrueType-Schriftart, die für das Symbol benutzt werden soll. Dieser Alias muß im =FONTSET= definiert sein.
*=GAP= Der Abstand zwischen zwei TrueType-Symbolen. Kommt nur für Linien zur Anwendung.

Als Beispiel für ein TrueType-Symbol soll an dieser Stelle die Schriftart WebDings herhalten:

 <code>
SYMBOL
NAME "haus"
TYPE TRUETYPE
FONT "webdings"
ANTIALIAS TRUE
CHARACTER "G"
END
</code> 

Dieses Beispiel greift aus der Schriftart WingDings das Zeichen heraus, das ein kleines Häuschen darstellt. Sie könnten damit beispielsweise Ihre Ferienhäuser in der Karte markieren.

Die Notation =\&\#71;= kennen Sie vielleicht aus HTML-Seiten, wo einzelne Zeichen auf diese Weise notiert werden können. 71 ist die Position des Zeichens in der TrueType-Datei; falls Sie die Position nicht kennen, müssen Sie raten oder ein Programm zurate ziehen, dass Ihnen die einzelnen Zeichen darstellt und deren Position angibt.

==Pixmap-Symbole==

Pixmaps lassen sich entweder an Linien entlangziehen oder zum Füllen von Fläche verwenden. Natürlich kann man mit ihnen auch einzelne Punkte annotieren. Damit können Sie beispielsweise Ihr Firmenlogo an verschiedenen Filialen einblenden:

 <code>
SYMBOL
NAME "logo"
TYPE PIXMAP
IMAGE "firmenlogo.png"
TRANSPARENT 0
END
</code> 

==Overlay-Symbole==\index{Symbole!Overlay}\index{Overlaysymbole}

Overlaysymbole werden separat in den Klassen eines Layers definiert. Dabei werden ganz einfach die als Overlay deklarierten Symbole über die 'normalen' Symbole gelegt. Anwendung findet so etwas zum Beispiel bei Autobahnen:

 <code>
CLASS
...
SYMBOL 0
SIZE 4
COLOR 0 0 0
OVERLAYSYMBOL 0
OVERLAYSIZE 2
OVERLAYCOLOR 255 0 0
END
</code> 

Das Resultat ist eine vier Pixel breite schwarze Linie, auf der sich eine zwei Pixel breite rote befindet. Anders formuliert: eine zwei Pixel breite rote Linie mit einem schwarzen Rand.

Auf diese Weise kann man beispielsweise auch gestrichelte Linien auf breite Linien legen und damit Mittelstreifen symbolisieren etc.

Es gibt die folgenden Optionen für Overlaysymbole:

*=OVERLAYSYMBOL= : Definiert wie =SYMBOL= , welches Symbol verwendet werden soll.
*=OVERLAYBACKGROUNDCOLOR= : Hintergrundfarbe des Overlaysymbols
*=OVERLAYCOLOR= : Farbe des Symbols
*=OVERLAYMINSIZE= : Minimaler Maßstab, bei dem das Overlaysymbol angezeigt werden soll.
*=OVERLAYMAXSIZE= : Maximaler Maßstab, bei dem das Overlaysymbol angezeigt werden soll.
*=OVERLAYOUTLINECOLOR= : Umrandungsfarbe für das Overlaysymbol
*=OVERLAYSIZE= : Größe des Overlaysymbols.

Diese Angaben sind also allesamt äquivalent zu den Angaben in normalen Symbolen ohne den Zusatz ''OVERLAY'' .

Mit der Ankunft des =STYLE= -Objekts und der entsprechenden Möglichkeit, mehr als zwei Symbole übereinander zu legen, werden die Overlayparameter allerdings wohl ihre Daseinsberechtigung verlieren. Mehr dazu siehe Abschnitt~6.

==Beispiele==

Erfahrungsgemäß bereiten Symbole gerade dem Einsteiger Schwierigkeiten. Daher sehen wir uns einige Beispiele an, die wir nach und nach zu komplexeren Symbolen ausbauen.

Für das einfachste aller Symbole, einen Punkt, wird wohl kein Screenshot benötigt:

 <code>
SYMBOL
NAME "punkt"
TYPE ELLIPSE
POINTS
1 1
END
FILLED TRUE
END
</code> 

Dieses Symbol können Sie nun in einem Layer verwenden, und dann dementsprechend die Dicke der Linie mit =SIZE= festlegen.

''Hinweis'' : Beachten Sie bitte, dass es keinen Unterschied macht, ob Sie =1 1= oder =2 2= in diesem Beispiel schreiben. Es handelt sich hier um Vektoren, dabei spielt der Skalar vor den eigentlichen Koordinaten keine Rolle. =2 2= ist also das gleiche wie zweimal =1 1= , und dieses 'zweimal' wird verworfen. Wichtig ist das Verhältnis der Zahlen zueinander. Wenn Sie also eine Ellipse haben wollen, die doppelt so breit wie hoch ist, schreiben Sie =2 1= . Sie könnten auch =6 3= schreiben, aber dadurch würde die Ellipse in der Karte nicht größer. Die Darstellungsgröße in der Karte wird über den Parameter =SIZE= in der entsprechenden Class geregelt.

Das wichtigste Gestaltungselement bei Linien ist die Möglichkeit, Abstände auf der Linie zu bestimmen. Damit lassen sich zum Beispiel gepunktete (''dotted'' ) oder gestrichelte (''dashed'' ) Linien realisieren. Ein Beispiel für ein Punkt-Symbol für eine Linie gestrichelte und gepunktete Linie:

 <code>
SYMBOL
NAME "funky"
TYPE ELLIPSE
POINTS
1 1
END
FILLED TRUE
STYLE 2 2 1 1
END
</code> 

Dieses Symbol entspricht dem letzten, mit dem Unterschied, dass hier ein =STYLE= verwendet wird. Die Angabe bedeutet, dass die ersten zwei Pixel des Linienzuges gezeichnet werden sollen, die nächsten beiden dann wieder nicht; danach wird ein Pixel gesetzt, der folgende dann wieder nicht. Es wird also immer die bezeichnete Anzahl von Pixeln gesetzt und dann wieder nicht gesetzt. Danach fängt das ganze wieder von vorne an. Beachten Sie bitte, dass die hier benutzte =STYLE= -Eigenschaft nichts mit dem Style-Objekt zu tun hat, wie es weiter vorne beschrieben worden ist.

Auf Beispiele für Overlaysymbole soll hier nicht eingegangen werden, da diese Methode veraltet ist. Stattdessen sollten Style-Objekte in den Classes benutzt werden.

\begin{figure}
\begin{center}
\mmfig{0.65}{symbols-star}{Städte, markiert mit einem sternförmigen Vektorsymbol.}
\end{center}
\end{figure}

Falls Sie mal ein komplexeres Symbol sehen wollen, schauen Sie sich die Sternchen in Abbildung~\ref{symbols-star} an. Die Sterne kommen folgendermaßen zustande:

 <code>
SYMBOL
NAME "stern"
TYPE VECTOR
FILLED TRUE
POINTS
0 .375
.35 .375
.5 0
.65 .375
1 .375
.75 .625
.875 1
.5 .75
.125 1
.25 .625
END
END
</code> 

Es handelt sich also um ein Vektorsymbol, das aus zehn Punkten besteht. Sie können sich beim Entwurf eigener Symbole das ganze auf Karo- oder Millimeterpapier aufmalen und dann die Koordinaten ablesen. Der Ursprung für Ihr Koordinatensystem muß in der linken oberen Ecke liegen. Beachten Sie, dass der höchste Wert in den Koordinaten der Punkte =1= ist. Sie könnten die auch alle Werte beispielsweise mit zwei multiplizieren, und es würde keinen Unterschied machen. Das ist der Effekt der Vektorrechnung, der weiter oben erläutert ist.

\subsubsection*{Markierungen für Gefälle}

Insbesondere während Schulungen wird der Autor gerne gefragt, wie es sich mit der Gestaltung von Höhenlinien verhielte; dabei möchte man beispielsweise in der abfallenden Richtung einer Höhenlinie in regelmäßigen Abständen einen kleinen, parallel zur Linie verlaufenden Strich anbringen, um die Richtung des Gefälles anzuzeigen.

Dazu muß leider gesagt werden, dass diese Art der Gestaltung insbesondere bei Shapefiles ''nicht'' möglich ist, da Shapefiles keine Topologie oder eine Richtungsinformation speichern. Zwar werden Sie GIS-Programme sehen, bei denen sich eine solche Gestaltung vornehmen läßt. Allerdings speichert die betreffende Software dann eine entsprechende Information über die Laufrichtung der Shapes separat ab. Diese Möglichkeit ist MapServer wegen seiner rein darstellerischen Fähigkeiten verschlossen.

=Maßstäbe=(19)
\index{Maßstab}\index{Scalebar}\index{Mapfile!Maßstab}\index{Mapfile!Scalebar}

Maßstäbe setzen die Größen auf der Karte in eine Relation zur Realität. Dieser Zusammenhang wird einem am Computerbildschirm jedoch zum Verhängnis.

Man sollte nicht auf die Idee kommen, einen Pixelmaßstab auf dem Bildschirm auszumessen, und etwa zu sagen: "`Ah, 10 Pixel sind 100 Meter, und 10 Pixel sind 0.5 Zentimeter, also sind 0.5 Zentimeter 100 Meter."' Ein Maßstab auf dem Bildschirm steht ausschließlich in Relation zur angezeigten Karte, nicht zur realen Welt, da sich Pixel nicht in Zentimeter umrechnen lassen, sondern stets von der Größe des Bildschirms und der verwendeten Auflösung abhängig sind.

Wenn ein Maßstab für 10 Pixel in der Karte 100 Meter in der Realität angibt, dann sind diese zehn Pixel bei 1280x1024 Pixeln Auflösung auf einem 19 Zoll Bildschirm wesentlich kleiner als bei einer Auflösung von 800x600 Pixeln auf einem 14 Zoll Bildschirm.

MapServer geht bei Maßstabsangaben (=SCALE= ) immer von <math>\frac{1}{72}</math> inch pro Pixel aus. Dieser Wert kann allerdings bestenfalls als vage Annäherung betrachtet werden. Bei =SCALE= handelt es sich immer um den Kehrwert eines Maßstabes. Wenn Sie den Maßstab also beispielsweise als 1:20000 kennen, ist =SCALE= gleich 20000.

Bei den Beschriftungen für Maßstäbe im MapServer beachten Sie bitte, dass MapServer bisher noch keinen Gebrauch von TrueType-Schriften an dieser Stelle macht.

Die Sektion für Maßstäbe im Mapfile wird mit =SCALEBAR= eingeleitet. Sie darf nicht innerhalb einer anderen Sektion stehen und muss nach dem Header stehen. Die folgenden Parameter sind für diese Sektion bekannt:

*=BACKGROUNDCOLOR <red> <green> <blue>= Die Hintergrundfarbe für den Scalebar, ''nicht'' für das komplette Bild, das den Scalebar ausmacht.
*=TRANSPARENT <ON|OFF>= Schaltet Transparenz für den Hintergrund des Scalebars ein oder aus. Voreingestellt ist der Hintergrund nicht transparent.
*=IMAGECOLOR <red> <green> <blue>= Die Hintergrundfarbe für das Bild, in dem sich der Scalebar befindet.
*=COLOR <red> <green> <blue>= Die Farbe, in der der Scalebar gemalt werden soll.
*=INTERLACE <TRUE|FALSE>= legt fest, ob der fertige Maßstab interlaced sein soll.
*=SIZE <x> <y>= Breite des Scalebars in Pixeln. Das ist nicht die Größe des fertigen Bildes, sondern nur des Maßstabs im Bild. Auch Beschriftungen werden hier noch nicht einberechnet.
*=INTERVALS= Anzahl der Intervalle auf dem Maßstab. Voreinstellung ist 4.
*=UNITS <feet|inches|kilometers|meters|miles>= Die Einheit, in der der Maßstab beschriftet sein soll. Voreinstellung ist Meilen. Gradangaben sind übrigens keine sinnvollen Einheiten für einen Maßstab. Voreinstellung ist =miles= .
*=OUTLINECOLOR <red> <green> <blue>= Umrissfarbe für die einzelnen Intervalle des Maßstabs. Soll keine Umrißfarbe verwendet werden, reicht als Wert auch =-1= .
*=STYLE <0|1>= Es gibt zwei verschiedene Styles. Style =1= ist im wesentlichen ein horizontaler, beschrifteter Strich, während Stil =0= in weiße und schwarze Sektionen unterteilt ist.
*=STATUS <ON|OFF|EMBED>= Schaltet den Maßstab an oder aus. Mit =EMBED= wird der Maßstab angeschaltet und in die fertige Karte eingebettet.
*=POSITION <ul|uc|ur|ll|lc|lr>= Bei einem in die Karte eingebetteten Maßstab wird dieser an der angegebenen Position dargestellt. In der Tabelle in der PHP MapScript-Referenz, die auf Seite~\pageref{tab:ref:mapscript:const} beginnt, finden Sie eine Erklärung der möglichen Werte.
*=POSTLABELCACHE <TRUE|FALSE>= Wird nur für Maßstäbe verwendet, die in die Karte eingebettet sind. Der Maßstab wird dann erst in die Karte eingefügt, nachdem alle Labels in der Karte gezeichnet worden sind. Voreinstellung ist =FALSE= .
*=LABEL= An dieser Stelle wird ein separates =LABEL= -Objekt eingefügt, das für die Beschriftung des Maßstabs zuständig ist. Bisher können in Maßstäben keine TrueType-Schriften verwendet werden.

=Legenden=
\index{Legende}\index{Mapfile!Legende}

Legenden erklären die in der Karte verwendeten Symbole und Zeichen. Ohne eine Legende ist eine Karte prinzipiell ohne Inhalt, da man ohne sie den Linien, Farben usw. keine Bedeutung zuordnen kann.

MapServer ist in der Lage, konfigurierbare Legenden automatisch zu generieren. Diese Legenden können dann auf die bekannte Weise über Template-Tags in das Layout der Applikation eingebunden werden.

Neben den klassischen Bitmap-Legenden (die gesamte Legende ist ein einziges Bild, das in eine HTML-Seite eingebunden wird), gibt es seit der Version~{3.6} auch HTML-Legenden, die über Templates kleine HTML-Abschnitte erzeugen.

==Die klassische MapServer-Legende==

Diese Art von Legende ist ein fertiges Bild, das vom MapServer generiert wird. Auf die Gestaltung dieser Legende hat man nicht so viel Einfluss wie bei der HTML-Legende (siehe weiter unten).

Die Sektion für Legenden im Mapfile wird mit =LEGEND= eingeleitet. Sie darf nicht innerhalb einer anderen Sektion vorkommen und muß nach dem Header stehen. Die folgenden Parameter sind für diese Sektion bekannt:

\begin{figure}
\begin{center}
\mmfig{0.35}{legende}{Die drei Vektorlayertypen in einer klassischen MapServer-Legende: Punkte, Linien und Polygone}
\end{center}
\end{figure}

*=IMAGECOLOR <red> <green> <blue>= Hintergrundfarbe für die fertige Legende
*=TRANSPARENT <ON|OFF>= Schaltet Transparenz für den Hintergrund der Legende ein oder aus. Voreingestellt ist der Hintergrund nicht transparent.
*=OUTLINECOLOR <red> <green> <blue>= Umrissfarbe für die Kästchen, die die Symbole in der Legende umranden.
*=KEYSIZE <x> <y>= Breite und Höhe der Symbole in der Legende in Pixeln. Vorgabe ist 20x10.
*=KEYSPACING <x> <y>= Horizontaler und vertikaler Abstand der Symbole bzw. der Beschriftungen zueinander. Vorgabe ist 5 und 5.
*=STATUS <ON|OFF|EMBED>= Schaltet die Legende an oder aus. Mit =EMBED= wird die Legende angeschaltet und in die fertige Karte eingebettet.
*=POSITION <ul|uc|ur|ll|lc|lr>= Bei einer in die Karte eingebetteten Legende wird diese an der angegebenen Position dargestellt. In der Tabelle in der PHP MapScript-Referenz, die auf Seite~\pageref{tab:ref:mapscript:const} beginnt, finden Sie eine Erklärung der möglichen Werte.
*=INTERLACE <TRUE|FALSE>= Ob das Bild interlaced sein soll.
*=POSTLABELCACHE <TRUE|FALSE>= Wird nur für Legenden verwendet, die in die Karte eingebettet sind. Die Legende wird dann erst in die Karte eingefügt, nachdem alle Labels in der Karte gezeichnet worden sind. Voreinstellung ist =FALSE= .
*=LABEL= An dieser Stelle wird ein separates =LABEL= -Objekt eingefügt, das für die Beschriftung des Maßstabs zuständig ist. Bisher können in Maßstäben keine TrueType-Schriften verwendet werden.
*=TEMPLATE= Definiert ein Template, das für HTML-Legenden verwendet werden soll. Siehe den folgenden Abschnitt über HTML-Legenden.

In Abbildung \ref{legende} kann man sehen, wie Legenden für verschiedene Arten von Vektorlayern aussehen. Polygone werden durch ein Rechteck dargestellt, das gegebenenfalls eine Füllfarbe hat. MapServer bedient sich an dieser Stelle bei den Angaben im Mapfile. Punktlayer werden durch einen (wenig überraschend) Punkt dargestellt, während Linienlayer eine kleine gezackte Linie bekommen.

==HTML-Legenden==\index{HTML-Legenden}

Als Alternative zu den normalen .gif- beziehungsweise .png-Bildern, die als Legenden generiert werden, gibt es für die CGI-Version des MapServers noch die Möglichkeit, eigene Legenden über HTML-Templates zu gestalten. Die fertige Legende wird dabei weiterhin an der Stelle im Haupt-Template eingefügt, an der das Schlüsselwort =[legend]= steht.

Interessant wird eine HTML-Legende dann, wenn man in die kleinen Bruchstücke von HTML auch Teile des Formulars zur Navigation in der Karte einfügt -- später mehr dazu.

Im LEGEND-Block des Mapfiles kann ein TEMPLATE definiert, etwa folgendermaßen:

 <code>
LEGEND
...
TEMPLATE "legend.html"
END
</code> 

\subsubsection*{Aufbau des Templates}

Innerhalb eines Templates können drei verschiedene Blöcke definiert werden: für Groups, Layers und Classes. Diese Begriffe folgen den Bedeutungen im Mapfile. Es kann also HTML-Code für Gruppen von Layern generiert werden, für die Layer in diesen Gruppen und dann für jede einzelne Class in diesen Layern wiederum eigener Code. Dieser Aufbau eignet sich besonders für den Aufbau in HTML-Tabellen.

Alle Inhalte der Templatedatei, die sich außerhalb der möglichen Blöcke befinden werden schlicht ignoriert und eignen sich somit dafür, Kommentare einzufügen, die später in der fertigen HTML-Seite nicht erscheinen sollen. Für Kommentare innerhalb der Blöcke müssen selbstverständlich HTML-konforme Kommentare benutzt werden, die mit == abgeschlossen werden.

Für gewöhnlich werden mit Groups- und Layerblöcken Kopfzeilen für HTML-Bereiche definiert, in denen dann die einzelnen Classes der Reihe nach aufgelistet werden.

\subsubsection*{Groups}

Mit der Verwendung eines solchen Blocks legt man die Erzeugung von Legenden fest, in denen Layer gruppiert dargestellt werden, und zwar anhand ihrer Gruppierung im Mapfile. Wird eine Groups-Sektion verwendet, werden alle Gruppierungen als solche in der Legende dargestellt. Möchte man keine Gruppierung von Layern in der Legende, verwendet man diesen Block einfach nicht.

Wird dieser Block definiert, erscheinen Layer nicht in der Legende, die zu keiner Gruppe gehören, und ebensowenig sind deren Classes zu sehen.

Mit =[leg_group_html]= wird ein solcher Block eingeleitet, und mit einem entsprechenden =[/leg_group_html]= wieder abgeschlossen.

Die folgenden Tags können in einem Group-Block erscheinen:

*=[leg_group_name]= : Gibt den Namen der Gruppe aus.
*=[leg_icon <width=X> <height=Y>]= : Steht für das erzeugte Icon. Der erzeugte Text ist der URL zu diesem Icon. Im Kontext einer Group gibt dieser Tag das Icon für den ersten Layer in der Group zurück. Die beiden Parameter =width= und =height= sind optional und verändern die Breite und die Höhe des fertigen Icons.
*=[metadata name=<feld>]= : Ist der MapServer über entsprechende Einträge im Mapfile OGC-konform ausgelegt, können an dieser Stelle entsprechende Metadaten ausgegeben werden. Mehr zu OGC-konformen Mapservern gibt es in Kapitel~\ref{text:ogc} zu erfahren. Auch andere Metadaten aus der Web-Sektion, wie Sie in Abschnitt~21 beschrieben sind, lassen sich hier einfügen.

\subsubsection*{Layers}

Analog zu Groups wird mit =[leg_layer_html]= ein Block für einen Layer in der HTML-Legende eingeleitet und mit =[/leg_layer_html]= wieder abgeschlossen. Im startenden Tag können allerdings noch einige zusätzliche Parameter übergeben werden:

*=order_metadata=<schlüssel>= In Abschnitt~21 haben Sie erfahren, dass Sie in Layern beliebige Metadaten in einem eigenen Block speichern können. Anhand solcher Einträge können Sie nun die Reihenfolge der Layer in der HTML-Legende kontrollieren. Anschaulich: <code> LAYER ... METADATA legendenposition 2 END ... END </code> Haben Sie ein jedem Layer eine solche Klassifizierung, können Sie in der HTML-Legende die Sortierung kontrollieren mit: <code> [leg_layer_html order_metadata=legendenposition] ... [\leg_layer_html] </code> 
*=opt_flag=<wert>= Dieser Wert kontrolliert die Verhaltensweise dieses Layerblocks. Es handelt sich um eine Bitmaske, d.h. für eine Kombination der folgenden Optionen addieren Sie die entsprechenden Werte aufeinander auf. Sie werden immer eine eindeutige Zahl erhalten. Die Werte sind:
*
*=1= Zeigt den Layer in der Legende an, auch wenn sich der gezeigte Ausschnitt außerhalb des Layers befindet. Dieses Verhalten ist nicht voreingestellt.
*
*=2= Zeigt den Layer in der Legende an, auch wenn sein =STATUS= auf =OFF= gesetzt ist. Dieses Verhalten ist nicht voreingestellt.
*
*=4= Zeigt den Layer in der Legende an, auch wenn sein =TYPE= auf =QUERY= gesetzt ist und daher nur befragt werden kann, aber nicht in der Karte erscheint. Dieses Verhalten ist nicht voreingestellt.
*
*=8= Zeigt den Layer in der Legende an, auch wenn sein =TYPE= auf =ANNOTATION= gesetzt ist und daher nur Beschriftungen darstellt. Dieses Verhalten ist nicht voreingestellt. Möchten Sie beispielsweise die ersten beiden Optionen zulassen, setzen Sie =opt_flag= auf <math>1+2=3</math>. Selbstverständlich können in einem Layer-Block in der Legende eigene Tags verwendet werden:
*
*=[leg_layer_name]= Fügt den Namen des Layers an dieser Stelle ein.
*
*=[leg_icon width=<breite> height=<höhe>]= Fügt den URL eines automatisch generierten Legenden-Icons ein, wie man es auch aus der klassischen MapServer-Legende kennt. Die Breiten- und Höhenangaben erfolgen in Pixeln und sind optional. Wenn ein Layer mehrere Classes aufweist, wird ein Icon für die erste Class im Layer generiert.
*
*=[metadata name=<feld>]= Fügt beliebige Metadaten aus der entsprechenden Sektion des Layers ein -- siehe auch weiter oben.

\subsubsection*{Classes}

Und natürlich kommen auch die Classes in HTML-Legenden zu ihrem Recht. Sie werden mit =[leg_class_html]= eingeleitet und am Ende mit =[/leg_class_html]= wieder abgeschlossen.

Ebenso wie die Blöcke für Layer kennen auch die Blöcke für Classes den Parameter =opt_flag= . Wenn er verwendet wird, wird er auch mit den gleichen Parametern gefüttert wie sein Pendant im Layer-Block.

Bitten beachten Sie, das Classes ohne einen =NAME= nicht in HTML-Legenden auftauchen werden.

Sie können die folgenden Tags innerhalb eines Class-Blockes in HTML-Legenden verwenden:

*=[leg_class_name]= Der Name der Klasse. Jede Klasse, die überhaupt in der Legende auftauchen soll, benötigt einen Namen.
*=leg_icon width=<breite> height=<höhe>= Das Legenden-Icon für die Class, wie im Layer beschrieben.
*=[metadata name=<feld>]= Fügt beliebige Metadaten aus der entsprechenden Sektion der Class ein; siehe auch weiter oben.

\subsection*{Konditionale in HTML-Legenden}\index{HTML-Legenden!Konditionale}

Konditionale sind Wenn-Dann-Anweisungen. Aus einer Programmiersprache wie C kennt man das unter der folgenden Notation:

 <code>
if (<bedingung> {
... hier passiert etwas ...
}
else {
... hier passiert etwas anderes ...
}
</code> 

Solche Konditionale lassen sich auch in HTML-Legenden nutzen, etwa um Dinge nur unter bestimmten Bedingungen einzublenden. Es gibt eine gemeinsame Notation, aber für jeden möglichen Block (Group, Layer und Class) eigene Eigenschaften, die abgefragt werden können.

Um es ein wenig genauer zu nehmen: es handelt sich weniger um eine Wenn-Dann-Anweisung, als vielmehr um ein reines Wenn. Ein ''else'' ist nicht implementiert.

Notiert werden Konditionale folgendermaßen:

 <code>
[if name=<feld> oper=<operator> value=<wert>] ... [/if]
</code> 

Das heißt soviel wie: Vergleiche =feld= dahingehend, ob es in der Beziehung =oper= zum Wert =wert= steht. Wenn das der Fall ist, füge den Block bis zum =[/if]= ein.

Da das reichlich abstrakt ist, hier ein Beispiel:

 <code>
[leg_layer_html]
[if name=layer_type oper=eq value=2]
[leg_layer_name]
[/if]
[/leg_layer_html]
</code> 

In diesem Layer-Block wird der Name des Layers immer dann ausgegeben, wenn sein Typ gleich 2 ist. Der Typ 2 ist nur im Kontext von Layern definiert: Sie erfahren weiter unten, welche Werte wofür stehen.

Das =eq= steht für ''equal'' und bedeutet 'gleich'. Daneben gibt es noch =neq= (ist nicht gleich), =isset= (hat überhaupt einen Wert) und =isnull= (ist leer). Die Voreinstellung ist =eq= . Wenn man diesen Operator verwenden möchte, kann man den Teil mit =oper== auch weglassen.

\subsubsection*{Groups}

Die folgenden Konditionale können als =name= in Group-Blöcken in HTML-Legenden benutzt werden:

*=group_status= Der Status einer Group ist gleich dem =STATUS= des ersten Layers in der selben. Als Werte kommen in Frage: =0= für =OFF= , =1= für =ON= und =2= für =DEFAULT= .
*=<metadata>= Jeder Metadaten-Eintrag in der Web-Sektion läßt sich als Wert für ein Konditional benutzen.

\subsubsection*{Layers}

Die folgenden Konditionale können als =name= in Layer-Blöcken in HTML-Legenden benutzt werden:

*=layer_name= Der Name des Layers.
*=layer_group= Der Name der Group, in dem sich der Layer befindet.
*=layer_status= Der Status des Layers. Als Werte kommen in Frage: =0= für =OFF= , =1= für =ON= und =2= für =DEFAULT= .
*=layer_type= Der Typ des Layers. Infrage kommen: =0= für =POINT= . =1= für =LINE= , =2= für =POLYGON= , =3= für =RASTER= . =4= für =ANNOTATION= und =5= für =QUERY= .
*=<metadata>= Jeder Metadaten-Eintrag aus der Layer- wie aus der Web.Sektion läßt sich als Wert für ein Konditional benutzen.

\subsubsection*{Classes}

Schließlich bleiben noch die Konditionale, die als =name= in Class-Blöcken in HTML-Legenden benutzt werden können. Um genau zu sein, sind die Werte hier vollständig mit denen im Layer-Block identisch, sodass sich eine Aufzählung erübrigt.

\subsection*{Hinweise}

Für HTML-Legenden benötigen Sie mindestens die Version 3.5.1 des Mapervers.

Der 'traditionelle' =[legend]= -Block liefert den URL eines Bildes zurück, wohingegen HTML-Legenden (wenig überraschend) Blöcke von HTML zurückliefern.

Wenn der HTML-Legendenmodus über die aufrufende URL für den MapServer angegeben wird, aber kein Template im Mapfile für die Legende definiert ist, wird weiterhin ein Bild erzeugt.

\subsection*{Beispiel}

Ein Beispiel soll erhellen, wie man die Macht von HTML-Legenden ausschöpfen kann. Betrachten Sie die folgenden Zeilen, die ein Ausschnitt aus einem Legenden-Template sind:

 <code>
[leg_layer_html opt_flag=3]
<tr>
<td>
<input type="checkbox" name="layer"
value="[leg_layer_name]" [[leg_layer_name]_check]>
</td>
<td><img src="[leg_icon width=18 height=12]" align="center"></td>
<td>[leg_layer_name]</td>
</tr>
[/leg_layer_html]
</code> 

Das Ergebnis ist in Abbildung~\ref{mapfile-legende-html} zu sehen.

Der Block definiert, wie Legenden für die im Mapfile vorhandenen Layer in der Legende auftauchen sollen. Der Wert 3 für =opt_flag= sagt, dass ein Layer in der Legende stehen soll, auch wenn sich alle Daten des Layers außerhalb des dargestellten Ausschnitts befinden, und dass er in der Legende stehen soll, auch wenn sein =STATUS= auf =OFF= gesetzt ist.

\begin{figure}
\begin{center}
\mmfig{0.3}{mapfile-legende-html}{HTML-Legenden im Einsatz}
\end{center}
\end{figure}

Es folgt eine Zeile in einer HTML-Tabelle, die aus drei Spalten besteht. In der letzten Spalte steht der Name des Layers. In der vorletzten Spalte wird die Quelle für das Bild vom MapServer eingefügt, hier mit einer Größe von 18 mal 12 Pixeln.

Die erste Zeile ist etwas trickreicher. Hier wird eine Checkbox für ein HTML-Formular generiert, die als ''value'' den Namen des Layers erhält. Dadurch wird dem MapServer mitgeteilt, welche Layer darzustellen sind und welche nicht -- der Benutzer klickt einfach die Checkboxen an.

Der letzte Teil ist der interessante: wenn ein Layer beim letzten Aufruf angezeigt worden ist, sucht MapServer in Templates nach Tags wie =layername_check= und ersetzt diese Tags dann durch =checked= . Dadurch wird die Checkbox im Browser markiert. Die Namen der Layer werden hier jedoch nicht hartkodiert, sondern bei der Abarbeitung des Legenden-Templates der Reihe nach ersetzt. Dadurch entsteht für jeden Layer eine passende Checkbox.

Dieses Stück HTML-Code generiert also nicht nur eine Legende, sondern auch gleich die Elemente für das Navigationsformular aus dem Inhalt des Mapfiles. Wird dem Mapfile nun ein neuer Layer hinzugefügt (oder ein Layer entfernt), wird die Legende automatisch korrekt generiert, ohne dass man am Template etwas ändern müßte.

=Templates=
(20)
\index{Templates}\index{Mapfile!Templates}

In der Web-Sektion des Mapfiles können diverse Templates definiert werden, die als Ergebnis eines Aufrufs ausgeliefert werden können. Bei den Templates handelt es sich um HTML-Dateien, in denen neue, MapServer-eigene Tags definiert werden, die in eckigen Klammern notiert werden.

Damit ein Template als Ergebnis ausgeliefert wird, muß der Modus =browse= im URL angegeben sein, im Gegensatz zum Modus =map= , der lediglich die Karten als Bilder zurückliefert.

Auch für die beiden Abfragemodi =query= und =nquery= werden Templates verwendet. Was es mit Queries auf sich hat, und wie man sie in seine Applikationen einbaut, ist ab Seite~\pageref{text:mapfile:queries} in Erfahrung zu bringen.

==Die verschiedenen Arten von Templates==

Templates kommen an mehreren verschiedenen Stellen im Mapfile mit unterschiedlicher Notation vor. Hier eine Aufzählung aller Möglichkeiten, ein Template für diverse Anwendungsfälle zu deklarieren.

Grundsätzlich können Templates lokal im Dateisystem liegen, wobei dann ihr Dateiname angegeben wird. Templates können aber auch als URL deklariert werden und somit von entfernten Rechnern herbeigeholt werden.

\subsubsection*{Web-Sektion}

Die Web-Sektion kennt die folgenden Template-Angaben:

*=TEMPLATE <datei|url>= Ist das Template für die Applikation, die im Modus =browse= läuft. Das einzige Template, das beim simplen Navigieren in der Karte zum Einsatz kommt.
*=HEADER <datei|url>= Ein Kopf-Template, das ausgegeben wird, bevor irgendwelche MapServer-Ergebnisse generiert werden. Findet lediglich beim Modus =nquery= zusammen mit =FOOTER= Anwendung, um die verschiedenen Abfrageergebnisse in ein beginnendes und ein abschließendes HTML einbetten zu können.
*=FOOTER <datei|url>= Das Pendant zu =HEADER= , das nach dem Einfügen aller Ergebnisse angehängt wird.
*=MINTEMPLATE <datei|url>= Ein Template, das benutzt werden soll, wenn der minimale =SCALE= für die Anwendung (gesetzt durch =MINSCALE= in der Web-Sektion) unterschritten wird. Auf diese Weise kann man MapServer-App\-li\-ka\-tionen verschiedener Detailstufen ineinander verschachteln.
*=MAXTEMPLATE <datei|url>= Ein Template, das benutzt werden soll, wenn der maximale =SCALE= für die Anwendung (gesetzt durch =MAXSCALE= in der Web-Sektion) überschritten wird.

\subsubsection*{Layer-Sektion}

In der Layer-Sektion lassen sich die folgenden Template-Angaben machen:

*=TEMPLATE <datei|url>= Präsentiert Abfrageergebnisse. Wenn mehrere Abfrageergebnisse präsentiert werden sollen, wird für jedes der Ergebnisse dieses Template einmal eingefügt und Gebrauch von =HEADER= und =FOOTER= gemacht (siehe weiter unten).
*=FOOTER <datei|url>= Kommt bei multiplen Abfragen zum Tragen und wird angehängt, nachdem alle Ergebnisse zusammengefügt worden sind.
*=HEADER <datei|url>= Das Pendant zu =FOOTER= ; wird vor allen Abfrageergebnissen eingefügt.

Das Template via =TEMPLATE= benutzt man im wesentlichen dann, wenn man nicht, wie im folgenden beschrieben, ein solches Template in jeder Class des Layers haben möchte.

\subsubsection*{Class-Sektion}

Für eine Class gibt es nur eine Template-Angabe, namentlich die folgende:

*=TEMPLATE <datei|url>= Präsentiert Abfrageergebnisse. Wenn mehrere Abfrageergebnisse präsentiert werden sollen, wird für jedes der Ergebnisse dieses Template einmal eingefügt und Gebrauch von =HEADER= und =FOOTER= gemacht, in dem sich die Class befindet.

Wenn man nicht für jede einzelne Class ein =TEMPLATE= notieren möchte, kann man eine solche Angabe auch auf der Ebene des Layers machen.

==Aufbau==

Ein einfaches Beispiel für ein HTML-Template:

 <code>
<html>
<head><title>Beispiel</title></head>
<body>
<img src="[img]">
</body>
</html>
</code> 

Wenn der MapServer über den URL aufgerufen wird, findet er in der Web-Sektion die Angabe für das Template, ersetzt die Tags in eckigen Klammern durch seine neu generierten Werte, und liefert dann die fertige HTML-Seite aus.

Im obigen Beispiel würde der MapServer eine Karte generieren, die einen URL zugewiesen bekommt. Dieser URL würde anstelle des =[img]= -Tags eingesetzt werden.

Für die Templates, die für die Ergebnisse von multiplen Abfragen generiert werden, gilt, dass es sich nicht um komplette HTML-Dateien handeln darf. Beispielsweise möchten Sie für ein Abfrageergebnis einer Class eventuell folgendes Template definieren:

 <code>
<tr>
<td>[ID]</td>
<td>[NAME]</td>
<td>[AREA]</td>
</tr>
</code> 

Die Deklaration der Tabelle und alles andere, was für eine vollständige HTML-Datei vonnöten ist, erfolgt dann durch weitere Templates in =HEADER= und =FOOTER= .

Für Templates, die das Navigationsinterface beschreiben (=TEMPLATE= in der Web-Sektion) und solche für die Präsentation von einzelnen Abfrageergebnissen (definiert durch =TEMPLATE= in Layern) sind hingegen natürlich vollständige HTML-Dateien notwendig.

Im Folgenden nun alle möglichen Tags, die vom MapServer unterstützt werden. Sie können übrigens auch eigene Tags definieren. Wenn Sie einen Parameter im URL übergeben, der dem MapServer nicht bekannt ist, wird dieser im Template ersetzt, wenn ein entsprechender Tag vorhanden ist. Wenn im URL also =meintag=17= steht, und im Template ein Tag =[meintag]= zu finden ist, wird dieser durch 17 ersetzt. Es gibt auch immer eine Fassung, bei der Sonderzeichen (Leerzeichen etc.) durch Escapesequenzen markiert sind; für diese Tags muß dann ein =_esc= angehängt werden. Für das genannte Beispiel hieße der Tag also =[meintag_esc]= .

Zuvorderst einige allgemeine Tags:

*=[version]= : Die Versionsnummer des eingesetzten MapServers.
*=[id]= : Eine (recht)\footnote{Die Einschränkung 'recht' eindeutig soll hier nur bedeuten, dass keine Eindeutigkeit im mathematischen Sinne vorliegt. Einem Kryptographen würden sich die Haare sträuben bei der Verwendung der Session-ID als Baustein für einen 'eindeutigen' Wert. Zur Vermeidung von Kollisionen bei unseren dynamisch generierten Bildern sollte sie jedoch ausreichen.} eindeutige Session-ID für den Aufruf des MapServers, zusammengesetzt aus momentanem Datum und Zeit, sowie der Prozess-ID des Aufrufs. Diese ID ist also solange eindeutig, wie man pro Sekunde nicht mehr Anfragen bekommt, als das System gleichzeitig Prozesse starten kann. Man hätte dann allerdings noch ganz andere Probleme, als dass die ID des MapServer-Aufrufes nicht mehr eindeutig sein könnte.
*=[host]= : Der Hostname des ausführenden Rechners.
*=[port]= : Der Port, auf dem der Webserver die Anfrage entgegengenommen hat. In den meisten Fällen ist dies 80.
*=[web_meta data <key>]= : Zeigt die Metadaten aus der Web-Sektion eines OGC-konformen Mapfiles an.

Tags für Verweise auf Dateien:

*=[img]= : Der URL, an dem sich das neu generierte Kartenbild befindet.
*=[ref]= : Dito für eine eventuell erzeugte Referenzkarte.
*=[legend]= : Dito für eine eventuell erzeugte Legende.
*=[scalebar]= : Dito für eine eventuell erzeugte Maßstabsleiste.
*=[queryfile]= : Pfad zu dem File, in dem eine Query abgespeichert worden ist, falls =savequery= als Parameter gesetzt wurde. Mehr zu diesem Thema im Abschnitt über Queries, siehe Seite~\pageref{text:mapfile:query:cached}.
*=[map]= : Pfad zum Mapfile.

Die folgenden Tags lassen sich für Angaben über die Bildgeometrie verwenden:

*=[center]= : Gibt das Zentrum des Bildes in Pixeln an. Beispiel: ist das fertige Bild 300x300 Pixel groß, so steht in diesem Tag 149,149. Wofür braucht man das? Wenn man in einem Navigationsformular einen Knopf zum 'Auffrischen' der Karte hat (man möchte beispielsweise Layer hinzuschalten, aber den Ausschnitt nicht ändern), so kommt kein Klick in der Karte zustande, der den MapServer auf das neue Zentrum für den anzuzeigenden Ausschnitt hinweist. Mit diesem Tag ist jedoch im Formular folgendes Konstrukt möglich: <code> <input type="hidden" name="imgext" value="[center]"> </code> Dadurch wird ein impliziter Mausklick auf das Zentrum der Karte gesetzt.
*=[center_x]= und =[center_y]= : Die x- und y-Koordinate des Bildzentrums als einzelne Werte.
*=[mapsize]= : Die momentane Größe der Karte in Breite und Höhe in Pixeln, getrennt durch ein Leerzeichen. Mit einem =_esc= am Ende auch als escaped Version vorhanden.
*=[mapwidth]= und =[mapheight]= : Breite beziehungsweise Höhe der Karte in Pixeln.
*=[scale]= : Maßstab der Karte. Zu Maßstäben siehe vor allen Dingen auch Abschnitt~19

Angaben über die Geometrie der Karte sind mit folgenden Tags möglich. Die letzten drei Punkte in dieser Aufzählung sind nur dann verfügbar, wenn der MapServer mit der Projektionsbibliothek proj.4 kompiliert worden ist und es eine Projektionsangabe im Mapfile gibt.

*=[mapx]= und =[mapy]= : x- und y-Koordinate des Mausklicks.
*=[mapext]= und =[mapext_esc]= : Die vollen Extents der Karte, separiert durch Leerzeichen.
*=[maxx]= , =[maxy]= , =[minx]= und =[miny]= : Die einzelnen Koordinaten der Karte.
*=[rawext]= und =[rawext_esc]= : Die Extents der Karte, bevor sie auf die gewünschte Pixelgröße angepaßt worden ist, getrennt durch Leerzeichen.
*=[rawmaxx]= , =[rawmaxy]= , =[rawminx]= und =[rawminy]= : Die einzelnen Koordinaten der Extents der Karte, bevor die Karte auf die gewünschte Pixelgröße angepaßt worden ist.
*=[maplon]= und =[maplat]= : Längen- und Breitengrad des letzten Mausklicks in der Karte.
*=[mapext_latlon]= und =[mapext_latlon_esc]= : Voller Extent der Karte in Längen- und Breitengrade, separiert durch Leerzeichen.
*=[minlon]= , =[minlat]= , =[maxlon]= und =[maxlat]= : Die einzelnen Koordinaten der Extents der Karte in Längen- und Breitengraden.

Die folgenden Tags geben Aufschluss über die Layer in einer Karte:

*=[get_layers]= : Eine Aufzählung aller Layer, die in der aktuellen Karte aktiv sind, sodass sie in eine URL eingebunden werden können. Zum Beispiel: <code> layer=fluesse&layer=eisenbahn&layer=seen </code> 
*=[layers]= und =[layers_esc]= : Die Namen aller aktiven Layer, voneinander durch Leerzeichen getrennt.
*=[layername_check]= und =[layername_select]= : Im Tag muß an dieser Stelle nicht 'layer' stehen, sondern der tatsächliche Name des Layers. Ist ein Layer aktiv, wird der Tag durch das Wort =checked= bzw. =selected= ersetzt. Auf diese Weise wird von Seitenaufruf zu Seitenaufruf mitgeschleift, ob ein Layer ausgewählt ist. Ein Beispiel für einen Layer namens 'fluesse': <code> <input type="checkbox" name="layer" value="fluesse" [fluesse_select]> Flüsse </code> Wenn der Layer im URL angefordert worden ist, ist diese Checkbox automatisch selektiert.
*=[layername_meta <data> <key>]= : Dieser Tag wird, genauso wie der entsprechende Tag in der Web-Sektion, durch Metadaten aus einem OGC-konformen Mapfile gefüllt.

Auch für das Zoomverhalten gibt es einige Tags für das Template:

*=[zoomdir_<-1|0|1>]=
*=[zoom_minzoom to maxzoom_<select|check>]=

Zu guter Letzt natürlich noch die Tags, die für Queries interessant sind. Dementsprechend werden diese Tags nur dann ausgefüllt, wenn sie sich in einem Template befinden, das von einer Query abgearbeitet wird.

*=[shpext]= : Die Extents des Shapes, das das Suchergebnis darstellt.
*=[shpminx]= , =[shpmaxx]= , =[shpminy]= und =[shpmaxy]= : Dito, nur in die einzelnen Punktkoordinaten aufgeschlüsselt.
*=[shpmid]= : Der Mittelpunkt eines gewähltes Shapefiles. Steht nur zur Verfügung, wenn Queries bearbeitet werden.
*=[shpmidx]= und =[shpmidy]= : X- respektive y-Koordinate des Mittelpunkts.
*=[shpidx]= : Index des aktuellen Shapefiles. Steht nur zur Verfügung, wenn Queries bearbeitet werden.
*=[tileindex]= : Index der momentanen Rasterkachel. Steht ebenfalls nur zur Verfügung, wenn Queries bearbeitet werden.
*=[DBase column name]= : Jede beliebige Spalte einer ''.dbf'' -Datei kann in Query-Templates als Tag verwendet werden. Die entsprechenden Ergebnisse werden dann eingefügt.
*=[cl]= : Name des aktuellen Layers. Sinnvoll in Layerheadern oder -footern.
*=[lrn]= : Die Nummer eines Suchergebnisses im aktuellen Layer. Sinnvoll in Querytemplates.
*=[nl]= : Anzahl der Layer, in denen es Suchergebnisse gegeben hat. Sinnvoll in Web-Headern oder -footern.
*=[nlr]= : Gesamtzahl aller Ergebnisse im aktuellen Layer. Sinnvoll in Web-Headern und -footern.
*=[nr]= : Gesamtzahl aller Suchergebnisse. Sinnvoll in Web-Headern und -footern.
*=[rn]= : Die Nummer des Suchergebnisses innerhalb aller Suchergebnisse. Sinnvoll in Web-Headern und -footern.

=Metadaten=(21)\index{Mapfile!Metadaten}\index{Metadaten}

Die Web-Sektion (und nicht nur diese) kann zwei Arten von Metadaten aufnehmen. Zum einen sind diejenigen Daten zu nennen, die für eine OGC-konforme Interaktion mit der Außenwelt sorgen. Wie mit diesen Daten umzugehen ist, erfahren Sie in Kapitel~\ref{text:ogc}.

Des weiteren können Sie sozusagen "`freie"' Einträge vornehmen, die Sie dann -- in eckigen Klammern, siehe den nächsten Abschnitt über Templates -- als Parameter in das Template übernehmen und so in die HTML-Ausgabe einfügen können.

Ein Beispiel:

 <code>
METADATA
autor "Thorsten Fischer"
adresse "Heilbronner Strasse 10"
END
</code> 

Diese Zeilen ermöglichen Ihnen, beispielsweise das folgende im Template zu tun:

 <code>
Der Autor [autor] kann unter
der Adresse [adresse] erreicht werden
</code> 

MapServer ersetzt diese Tags dann durch die Parameter aus der =METADATA= -Sektion.

Beachten Sie, dass Sie solche Metadaten auch auf Layer-Ebene einfügen können. Diese Daten können Sie dann später beispielsweise dazu verwenden, die Layer in HTML-Legenden auf eine bestimmte Weise zu sortieren.

Eine weitere Idee zum Einsatz von Metadaten sind Links. Speichern Sie zum Layer gehörende URLs als Metadaten und fügen Sie sie später in Templates oder HTML-Legenden ein.

=Queries=\index{Queries}\index{Mapfile!Queries}(22)

Zuweilen möchte man seine Daten nicht nur betrachten. Auch wenn es die größte Stärke des MapServer ist, schnell Karten generieren zu können und diese dann ausliefern zu lassen, ist eine minimale GIS-Funktion zuweilen wünschenswert. Die Anfragen auf die den Karten zugrundeliegenden Datenbestände werden beim MapServer ''Queries'' genannt.

==Notation==

Im HTML-Template, das das Benutzer-Interface für den MapServer definiert, muß natürlich zuerst die Möglichkeit geschaffen werden, neben dem Bewegen in der Karte auch Queries zuzulassen -- man muss zwischen beiden Modi wählen können. Das kann beispielsweise durch entsprechende Radio-Buttons passieren:

 <code>
...
<input type="radio" name="mode" value="browse" checked> Browsen
<input type="radio" name="mode" value="query"> Anfrage stellen
...
</code> 

Beim Absenden des Formulars übermitteln die Radio-Buttons (wie man sie beispielsweise auch im offiziellen MapServer-Demo findet) den entsprechenden Modus an das MapServer-CGI.

Möchte man mehrere Abfrageergebnisse zulassen, benötigt man den Modus =nquery= :

 <code>
<input type="radio" name="mode" value="nquery"> Mehrere Anfragen
</code> 

Alle drei Modi können natürlich im gleichen Formular vorkommen.

Desweiteren müssen Sie in allen Layern, für die Sie Abfragen zulassen möchten, ein =TEMPLATE= definieren. Dabei können Sie einzelne Templates in den Classes des Layers definieren (die dann nur für Abfrageergebnisse der jeweiligen Klasse gelten) oder aber eine Angabe für den kompletten Layer machen; das muß dann außerhalb der Classes geschehen.

Für die einfache Query wird außerdem nur der oberste sichtbare Layer der Karte befragt\footnote{Also der letzte sichtbare Layer im Mapfile}.

Wie Templates für Abfrageergebnisse notiert werden, ist bereits in der umfänglichen Sektion über Templates beschrieben worden. Beachten Sie auf alle Fälle immer, ob Sie nur einfache oder multiple Ergebnisse bei Ihren Anfragen zulassen. Ist letzteres der Fall, sollten Sie sich über die Anordnung von =HEADER= - und =FOOTER= -Templates Gedanken machen.

Ein Beispiel. Sie haben folgendes in Ihrem Layer notiert:

 <code>
LAYER
NAME "gemeinden"
...
HEADER "gemeinden_head.html"
FOOTER "gemeinden_foot.html"
...
CLASS
TEMPLATE "gemeinden.html"
END
END
</code> 

Für eine einfach Query würde lediglich einmal =gemeinden.html= mit entsprechendem Ergebnis zurückgeliefert werden. Nehmen wir aber nun an, dass der Modues auf =nquery= gesetzt ist, und mehrere Features mit einem Mausklick erwischt worden sind -- um ein Beispiel zu wählen: 3 Stück --, so wäre das Ergebnis wie folgt:

 <code>
gemeinden_header.html
gemeinden.html
gemeinden.html
gemeinden.html
gemeinden_footer.html
</code> 

Das gleiche wiederholt sich dann noch für alle anderen Layer, die darunter liegen. Außerdem können für =nquery= auch noch ein Header sowie ein Footer in der WEB-Sektion des Mapfiles definiert werden. Diese werden dann jeweils einmal dargestellt: einmal vor allen Suchergebnissen, und einmal dahinter.

==Query maps==\index{Query map}(23)

Querymaps sind kleine Karten, die in Ergebnistemplates dazu dienen, die Resultate von Queries zu visualisieren. Sie sind als eigene Sektion im Mapfile definiert, außerhalb jeder anderen Sektion (am besten nach dem Header) und sehen beispielsweise folgendermaßen aus:

 <code>
QUERYMAP
COLOR 255 0 0
SIZE 200 200
STATUS ON
STYLE HILITE
END
</code> 

In diesem Fall wird eine 200x200 Pixel große Querymap erzeugt, in der angefragte Features rot markiert werden.

Die folgenden Optionen können in Querymap-Sektionen auftauchen:

*=COLOR <red> <green> <blue>= Gibt die Farbe an, in der die angefragten Features markiert werden. Ergibt nur Sinn, wenn der =STYLE= auf =HILITE= gesetzt ist. Voreinstellung ist gelb.
*=SIZE <x> <y>= Die Größe, in der die Querymap gezeichnet werden soll. Voreinstellung ist die Größe der Karte.
*=STATUS <ON|OFF>= Legt fest, ob die Querymap gezeichnet werden soll.
*=STYLE <NORMAL|HILITE|SELECTED>= Dieser Stil legt für den angefragten Layer fest, wie die gewählten Features gemalt werden sollen. =NORMAL= zeichnet die Karte ohne Änderung. =HILITE= zeichnet den Layer, markiert aber die gewählten Features mit der Farbe =COLOR= ; diese Art ist auch die Voreinstellung. =SELECTED= zeichnet lediglich die gewählten Features.

Wie werden Querymaps nun dargestellt? Es gibt für diese Abfragekarten kein eigenes Schlüsselwort, vielmehr ändert sich der Tag =[img]= , wenn in einen Query-Modus geschaltet wird. Es wird dann nicht mehr die Karte, sondern eben die dazugehörige Abfragekarte dargestellt.

Abgebildet wird in der Querymap der Ausschnitt der Karte, in dem man die Anfrage gestellt hat. Darin markiert sind die Abfrageergebnisse, wie man es im =QUERYMAP= -Block angegeben hat.

Sie können übrigens eine Querymap auch separat von allem anderen mit dem Modus =querymap= anfordern, genauso, wie auch eine normale =map= .

\subsubsection*{Cached Queries}(24)\index{Queries!Cached Queries}\index{Cached Queries}

Cached Queries sind eine Möglichkeit, Abfrageergebnisse abzuspeichern. Mit Cached Queries können Sie die Abfrageergebnisse in einer Karte darstellen, deren Extents Sie beliebig wählen können. Sie sind nicht auf den Ausschnitt beschränkt, an den die Anfrage gestellt wird.

Um eine Cached Query benutzen zu können, müssen Sie zuerst eine weitere Zeile in Ihr HTML-Template aufnehmen:

 <code>
<input type="hidden" name="savequery" value="true">
</code> 

Dadurch werden nun bei Query-Aufrufen temporäre Dateien angelegt, wie es etwa auch für generierte Karten geschieht. Der Name dieser Datei läßt sich in einem Template nun mit Hilfe von Template-Tags rekonstruieren:

 <code>
<img src="[program]&map=[map]&
queryfile=[map_image_path]<NAME>[id].qy
[get_layers]&mode=map&size=200+200
</code> 

Der Wert =[map]= wird sowieso immer übergeben, und =get_layers= wird bei jedem Aufruf des MapServers automatisch aus den übergebenen Layern erstellt.\\ =map_image_path= fügt der MapServer ebenfalls automatisch aus dem Mapfile ein. Der Wert von =[id]= ist eine eindeutige ID für den jeweiligen MapServer-Aufruf und wird auch vom MapServer ausgefüllt. Der String =<NAME>= ist der Wert, der im Mapfile als =NAME= im Mapfile für die Karte gesetzt ist, und muß von Ihnen von Hand eingetragen werden.

Der Trick ist nun, dieser Karte eine Bounding Box in bekannter Notation nach Ihrem Wunsch mitzugeben; man erhält somit beliebige Kartenausschnitte, in denen Abfrageergebnisse angezeigt werden.

==Joins==\index{Joins}

Der Grundgedanke bei Joins entspricht dem gleichlautenden Begriff bei SQL-Da\-ten\-ban\-ken: die Inhalte zweiter Dateien mit Daten werden zu einem einzigen Datensatz zusammengefügt. Dazu benötigt man in beiden Datensätzen ein gemeinsames Datum, wie zum Beispiel eine ID, um den Inhalt den einen Datensatzes dem anderen zuordnen zu können.

In MapServer kommt das Konzept vor allen Dingen zum Einsatz, um die Inhalte zweier DBF-Dateien zu einem einzigen zusammenzufügen, der dann dazu benutzt wird, die Expressions in Classes oder auch Query-Ergebnisse zu evaluieren.

FIXME: funktioniert nicht?

==Weitere Arten von Queries==

Über die beiden Modi =query= und =nquery= hinaus definiert MapServer noch eine ganze Menge weiterer Typen für Datenanfragen. Auf einige dieser Modi soll hier noch im Detail eingegangen werden.

===indexquery===

Eine Indexquery sucht ein Shape über seine ID im Shapefile heraus. Im Aufruf sieht das beispielsweise folgendermaßen aus:

 <code>
http://www.example.com/cgi-bin/mapserv
? map=/pfad/zum/mapfile.map
& mode=indexquery
& qlayer=bundeslaender
& shapeindex=15
</code> 

Der Aufruf dieser Art von Query erfolgt über den Modus =indexquery= . Der Layer, der das Ziel der Anfrage sein soll, wird mit =qlayer= bestimmt.

Für das Ergebnis dieses Aufrufs wird wie gewohnt das Template benutzt, das sie im entsprechenden Layer definiert haben (bzw. in den dortigen Classes). Anstatt aber nun die Koordinaten eines Mausklicks auszuwerten, wird gezielt nach einem bestimmten Shape gesucht. Das obige Beispiel zum Beispiel sucht nach dem sechszehnten Shape im Layer =bundeslaender= , und die Darstellung im Query-Template sieht dann dementsprechend aus.

Falls Sie eine Querymap definiert haben sollten, so werden bei der Darstellung der Karte beim obigen Aufruf die Extents verwendet, die im Mapfile definiert sind. Der CGI-Parameter =mapext= kann verwendet werden, um wie im Modus =browse= einen anderen Kartenausschnitt festzulegen. Falls Sie diesen Parameter nicht auf bestimmte Werte setzen, sondern stattdessen =mapext=shapes= verwenden, wird direkt auf das Ergebnisshape gezoomt.

Nur die Querymap als Bild können Sie sich übrigens mit dem Modus =indexquerymap= zurückliefern lassen.

Zusätzlich zu den Parametern im gezeigten Beispielaufruf gibt es auch noch =tileindex= , für den Fall, dass sie gekachelte Shape-Daten verwenden.

===itemquery und itemnquery===

Durch eine Itemquery können Sie Features anhand von nichträumlichen Eigenschaften auswählen. Bei Daten aus Shapefiles (auf die wir uns hier konzentrieren wollen) kommen diese Eigenschaften selbstverständlich aus den =.dbf= -Dateien.

Um über den URL auf diese Eigenschaften zugreifen zu können, müssen wir sie mit einem Namen bekannt machen. Dazu benutzen wir den Parameter =FILTER= im entsprechenden Layer:

 <code>
LAYER
...
DATA "bundeslaender"
FILTERITEM "NAME"
FILTER "
...
END
</code> 

In diesem Beispiel verwenden wir die DBF-Tabellenspalte =NAME= und machen sie nach außen als =name= bekannt.

Zugriff erhalten wir nun über diesen Namen. Im URL notieren wir jetzt folgendes:

 <code>
FIXME
</code> 

FIXME:mehr

Da diese Art von Query mit Angabe einer Zeichenkette funktioniert, ist es in den meisten Fällen sinnvoll, dem Benutzer eine Auswahlliste zur Verfügung zu stellen, aus der er sich dann Features nach Namen auswählen kann.

FIXME

===featurequery und featurenquery===

\begin{figure}
\begin{center}
\mmfig{0.55}{featurenquery-berlin}{Eine =featurenquery= . Hier wurde das Bundesland Berlin gewählt und nach allen Features (Postleitzahlgebieten und bestimmte Kacheln) gefragt, die von der Fläche des Bundeslandes geschnitten werden.}
\end{center}
\end{figure}

In diesem Modus wird ein Feature ausgewählt, und alle dafür eingestellten Layer werden befragt, welche Features durch dieses Feature geschnitten werden. Sie können ein Beispiel dafür in Abbildung~\ref{featurenquery-berlin} sehen: Hier wurde das Bundesland Berlin durch einen Mausklick ausgewählt, und das Ergebnis ist eine Liste aller Features, die die Fläche eben dieses Bundeslandes schneiden.

Beachten Sie bitte, dass wir an dieser Stelle nur die Fassung dieser Query mit dem =n= im Namen betrachten. =featurequery= funktioniert analog zum Paar =query= /=nquery= mit nur einem einzigen Suchergebnis.

Als erstes benötigen Sie für diese Art von Query selbstverständlich einen entsprechenden Modus:

 <code>
... & mode = featurenquery & ...
</code> 

Danach muß spezifiziert werden, anhand welchen Layers die Auswahl getroffen werden soll. Vorstellbar wäre zum Beispiel eine Auswahlbox mit einer Liste aller Layer, aus der dann ein Layer als Bezugsebene ausgewählt werden kann. Der zuständige Parameter heißt =slayer= . Heißt der Layer beispielsweise =gruenflaechen= , so notiert man:

 <code>
... & slayer = gruenflaechen & ...
</code> 

Jeder Layer, der über =layer== im URL spezifiziert wird und ein =TEMPLATE= gesetzt hat, wird nun für den Vergleich herangezogen.

Das Abarbeiten der Query-Templates läuft in der gewohnten Weise ab; für jedes Ergebnis in einer Class werden die Templates hintereinander gehangen, für den Layer dann eventuell noch Header davor und Footer dahinter, und um das ganze herum dann eventuell vorhandene Header und Footer aus der Web-Sektion.

''Hinweis'' : Zum Zeitpunkt der Drucklegung funktionierte diese Art von Query nicht mit umprojizierten Daten. Quell- und Zielprojektion mußten übereinstimmen, um Suchergebnisse zu erhalten.

===itemfeaturequery und itemfeaturenquery===

FIXME

=PostgreSQL und PostGIS=
\index{PostGIS}\index{PostgreSQL}

PostGIS, ein Zusatz für die freie Datenbank PostgreSQL, ist die 'Standard'-Daten\-bank\-an\-bindung für den MapServer. PostGIS setzt einen großen Teil der Simple Features des OGC um und kann nicht nur als Datenquelle für den MapServer dienen, sondern generell raumbezogene SQL-Anfragen verarbeiten.

Die Anbindung einer PostGIS-Datenbank wird in Kapitel~\ref{text:database} ab Seite~\pageref{text:database:postgis} beschrieben.

=OGR=\index{OGR}(25)

Die OGR-Bibliothek ist das vektor-orientierte Gegenstück zu GDAL. Obwohl es sich um eine eigenständige Bibliothek handelt, wird sie zusammen mit GDAL ausgeliefert.

Neben den Shapefiles gibt es nämlich noch eine ganze Reihe anderer Vektorformate. Shapefiles sind so ziemlich das minimalistischste, was man sich vorstellen kann, sie beinhaltet lediglich die Koordinaten von Punkten. Viele Vektorformate sind allerdings etwas komplexer, und enthalten gleich mehrere Datensätze, einen Haufen zusätzliche Metadaten oder gleich Informationen über die Gestaltung der Daten.

Besonders bei der letztgenannten Klasse von Formaten sollte man vorsichtig sein und von OGR nicht zuviel erwarten. Zwar gibt es für diese Formate die Möglichkeit, das Layout der Daten auszulesen, aber nicht immer kann diese Information auch umgesetzt werden.

Von der Notation her gibt es, ähnlich wie bei Datenanbindungen, nur eine grundlegende Änderung: Im Layer wird nun nicht mehr =DATA= als Schlüsselwort für die Datenquellen verwendet, sondern die beiden Parameter =CONNECTIONTYPE= (dieser ist dann immer =OGR= ) und =CONNECTION= . Dabei wird =CONNECTION= dann von den notwendigen Details wie dem gewünschten Layer aus dem Datensatz usw. gefolgt.

FIXME: vervollständigen!1!

=Spezifikation von Ausgabeformaten=(26)

Mit Version 4.0 des MapServers ist man nun endlich in der Lage, mehrere verschiedene Ausgabeformate für die fertige Karte zu spezifizieren. Bisher war man auf ein einziges Rasterbild-Format festgelegt (PNG respektive GIF).

FIXME: mehr

Ein Mapfile kann eine, mehr als eine oder sogar gar keine OUTPUTFORMAT-Sektion haben. Ohne jede Angabe wird bei einkompilierter GD-Bibliothek ein PNG-Bild zurückgeliefert.

Eine OUTPUTFORMAT-Sektion sieht typischerweise so aus:

 <code>
OUTPUTFORMAT
NAME "png"
DRIVER "GD/PNG"
MIMETYPE "image/png"
IMAGEMODE RGB
EXTENSION "png"
END
</code> 

Zuerst erhält die Sektion einen Namen. Danach wird ein "Treiber" für die Erstellung des Bildes angegeben. Für die typische PNG-Ausgabe mit der Bibliothek GD steht hier ''GD/PNG'' .

Der Mimetype ist wichtig, um dem Browser, der die fertige Karte entgegennimmt, mizuteilen, welcher Art die Daten sind, die da ankommen\footnote{Für Windows-Benutzer: Nein, der Dateiname sagt nichts über die Art einer Datei aus. Er ist im Grunde nicht einmal Bestandteil einer Datei. Microsoft hat das aber schon vor einer ganzen Weile vergessen.}. Er ist für diese Sektion allerdings Optional, da MapServer auch versucht, ihn automatisch zu bestimmen.

Der IMAGEMODE gibt unter anderem die Farbtiefe des Bildes an (siehe die Sektion über Rasterbilder; ist aber auch für Flash relevant), und schließlich die Dateinamenerweiterung des Outputs.

Im folgenden sollen für die verschiedenen Anwendungsfälle alle möglichen Optionen in der OUTPUTFORMAT-Sektion angegeben werden.

==Rasterbilder==

Bisher gibt es gibt es nur zwei Treiber für Rasterbildformate im MapServer: die inzwischen klassische Ausgabe mittels GD, und ganz neu GDAL. Letzteres kann bisher nur GeoTIFF-Bilder produzieren, aber es ist ein Anfang.

FIXME: blah

Der Parameter =IMAGEMODE= sagt aus, in welcher Farbtiefe das Bild produziert werden soll, und wie Transparenzen gehandhabt werden sollen:

*=PC256= : Produziert ein Bild mit einer eigenständigen Farbpalette mit (maximal) 256 Farben. Dies ist der klassische MapServer-Modus. Der Raster-Treiber ''GD/GIF'' kennt ausschließlich diesen Modus. TRansparenz ist mit diesem Modus möglich.
*=RGB= : 24-Bit RGB-Farbbild. Ohne Transparenz.
*=RGBA= : 32-Bit RGBA-Farbbild mit Alphakanal (Transparenz).
*FIXME: mehr?

Über alle diese Optionen hinaus gibt es noch treiberabhängige Angaben, die sogenannten FORMATOPTIONs. Sie werden folgendermaßen notiert:

 <code>
OUTPUTFORMAT
NAME "jpg"
DRIVER "GD/JPEG"
MIMETYPE "image/jpeg"
IMAGEMODE RGB
EXTENSION "jpg"
FORMATOPTION "QUALITY=75"
END
</code> 

Jedes OUTPUTFORMAT kann dabei keine, eine oder mehrere (passende!) Angaben für FORMATOPTIONs haben. Im folgenden sind alle diese Optionen für die einzelnen Treiber beschrieben.

===Der GD-Treiber===

Der GD-Treiber kennt die folgenden, optionalen Parameter in der OUTPUTFORMAT-Sektion:

*=QUALITY= Legt für JPEG-Bilder die Kompression fest. Liegt zwischen =0= (niedrigste Qualität, höchste Kompression) und =100= (höchste Qualität, niedrigste Komprimierung).
*=INTERLACE= Legt fest, ob PNG- bzw. GIF-Bilder interlaced sein sollen (=ON= ) oder nicht (=OFF= ).

FIXME: mehr

===Der GDAL-Treiber===

Generell kann man dem GDAL-Treiber alles als Parameter mitgeben, was die Bibliothek als Optionen kennt; was alles in Frage kommt, erfahren Sie in der Dokumentation von der Website~[[http:website:gdal]].

FIXME: vervollständigen!1!

==Vektorformate==(27)

Vektorausgabeformate sind ein neues Feature in MapServer 4.0. Die Fülle von Einstellungen, die man dabei theoretisch machen kann, wird durch die Einführung von =OUTPUTFORMAT= abgefangen.

Alle bisher unterstützten Vektorformate zeichnen sich durch die Eigenschaft aus, dass sie nicht von sich aus im Browser darstellbar sind, sondern eine zusätzliche Bearbeitung oder doch zumindest den Einsatz von separaten Plugins im Webbrowser notwendig machen.

Wachsender Beliebtheit bei den Vektorformaten im Web erfreut sich auch SVG, ein XML-basiertes Format. Folglich sind Fragen nach einer Unterstützung für dieses Format auf der Mailingliste an der Tagesordnung. Bisher hat sich aber noch niemand die Mühe gemacht, Unterstützung für dieses Format zu implementieren. Das kann sich im Laufe der Zeit selbstverständlich ändern.

===PDF===

Unterstützung für die Ausgabe von PDF-Dateien wird mit der Bibliothek PDFLib realisiert. Dafür wird MapServer beim Kompilieren ganz einfach gegen diese Bibliothek gelinkt.

Das Ausgabeformat wird recht simpel folgendermaßen notiert:

 <code>
OUTPUTFORMAT
NAME "pdf"
MIMETYPE "application/pdf"
DRIVER PDF
END
</code> 

Da man PDF nicht einfach über einen =<img>= -Tag in seine HTML-Seite einbinden kann, bietet sich ein anderes Vorgehen an. Man baut ein Template zum Browsen der Karte wie gewohnt, gibt dem Benutzer aber noch einen Link mit einer Beschriftung wie 'diese Karte als PDF herunterladen' mit auf den Weg. Diesen Link kann man sich für den aktuellen Kartenausschnitt mit den entsprechenden MapServer-Tags bauen, zum Beispiel wie folgt:

 <code>
<a href="/cgi-bin/mapserv?map=[map]&imgext=[mapext]&FIXME=pdf ...">
</code> 

Die Liste der Parameter ist hier nicht vollständig, aber die Idee wird klar.

Wer den Verlauf der Entwicklung von MapServer 4.0 mitverfolgt hat, hat vielleicht mitbekommen, dass zu Beginn der PDF-Unterstützung lediglich ein PNG-Bild erzeugt worden ist, das dann in ein PDF-Dokument eingebettet wurde. Das ist nicht mehr der Fall, nun liefert MapServer für Vektordaten richtiges PDF zurück.

Wenn man eine Weile mit diesem Ausgabeformat experimentiert, wird man merken, dass die reine Ausgabe einfach nur einer Karte im PDF-Format recht unbefriedigend ist. Wer gestalterisch tätig werden möchte, der muß mit einer Skriptsprache Hand anlegen.

''Hinweis'' : Beachten Sie bitte unbedingt, dass die Nutzung für die hier verwendete Bibliothek PDFLib nicht für ausnahmslos alle Nutzungen kostenlos ist. Bitte informieren Sie sich auf der Website~[[http:website:pdflib]] der Bibliothek über die Details.

Außerdem ist die Erzeugung von PDF eine recht rechenintensive Sache, deren Einsatz man demnach mit Bedacht planen sollte.

===Shockwave Flash===

Flash ist ein Vektorformat, das im Web vor allen Dingen dafür verwendet wird, Animationen darzustellen. Daher spricht man bei einem Flash-Element in einer Website gewöhnlich von einem 'Movie', sogar dann, wenn es sich eigentlich um statischen Inhalt handelt. MapServer bietet mit Version 4.0 nun auch die Möglichkeit, fertige Karten als Flash-Movies auszuliefern.

Dabei stützt sich MapServer auf die Bibliothek Ming~[[http:website:ming]], die im Moment von Wolfgang Hamann weiterentwickelt wird, nachdem er diese Aufgabe im November 2002 vom ursprünglichen Entwickler übernommen hat\footnote{Leider hat sie im Laufe der Zeit keine Updates mehr erfahren.}. Die Software zeichnet sich insbesondere durch ihre vielfältigen Bindungen an andere Programmiersprachen aus.

Die Installation für Flash-Unterstützung wird für das Selberkompilieren von Binaries ab Seite~\pageref{anhang:installation:compile:flash} besprochen.

Es gibt für uns zwei Arten, Flash-Output zu generieren: einmal einen Movie für die komplette Karte, und einmal einen Movie für jede einzelnen Layer:

 <code>
OUTPUTFORMAT
NAME "swf"
MIMETYPE "application/x-shockwave-flash"
DRIVER swf
IMAGEMODE PC256
FORMATOPTION "OUTPUT_MOVIE=SINGLE"
# FORMATOPTION "OUTPUT_MOVIE=MULTIPLE"
END
</code> 

Wenn Sie mit diesem =OUTPUTFORMAT= einen Aufruf durchführen, werden Sie feststellen, dass Sie eine Datei (oder mehrere, wenn Sie =MULTIPLE= statt =SINGLE= im Beispiel gewählt haben) mit der Endung =.swf= in Ihrem temporären Verzeichnis aufgetaucht ist.

Bevor Sie diese Dateien tatsächlich benutzen können, müssen Sie sich aber noch ein wenig Arbeit machen. Was Sie benötigen, ist Kenntnis in der Sprache ActionScript, und ein Flash-SDK. Leider würde es den Rahmen dieses Buches sprengen, das eine oder das andere zu erläutern. Daher bleibt mir nur der Verweis auf das Archiv der MapServer-Mailingliste, wo Sie auf der Suche nach Beispielapplikationen und Diskussionen fündig werden können.

=Features=(28)

Für manche Dinge ist es nicht nötig -- oder schlicht zu aufwendig -- ein eigenes Shapefile oder eine andere Datenquelle zu haben. Sie können einfache Features auch als =FEATURE= -Block direkt im Mapfile notieren. Ein Beispiel:

 <code>
FEATURE
POINTS
1 1
10 10
10 1
1 1
END
TEXT "Dreieck"
END
</code> 

Hier definieren wir ein Dreieck in der linken oberen Ecke der fertigen Karte. Der Parameter =TEXT= definiert die Beschriftung des Features.

Beachten Sie, dass für einen geschlossenen Linienzug der letzte Punkt dem ersten Punkt entsprechen muß. Für die Einbettung eines =FEATURE= in einen Layer schauen Sie sich bitte den nächsten Abschnitt an.

==Fix positionierte Elemente==

Zuweilen möchte man in eine fertige Karte noch eine Information einfügen, die immer gleich bleibt; ein Logo, eine Urhebernotiz, was auch immer. Das Problem ist natürlich, dass bisher immer alles georeferenziert war und daher immer auf einen bestimmten Punkt fixiert.

\begin{figure}
\begin{center}
\mmfig{0.60}{transform-label}{Ein fixes Label in einer Karte, hier der URL der MapMedia-Website.}
\end{center}
\end{figure}

Mit dem Parameter =TRANSFORM= in einem Layer können Sie dieses Verhalten jedoch ein wenig manipulieren. Dieser Parameter gibt an, ob das Koordinatensystem der Datenquelle im Verhältnis zum fertigen Bild transformiert werden soll oder nicht. Die Standardeinstellung ist immer =TRUE= , was nicht weiter verwundert, denn bisher wurde immer das Koordinatensystem der Daten in das Koordinatensystem des Bildes (Angabe in Pixeln und Ursprung links oben) umgewandelt.

Setzen Sie diesen Wert jedoch auf =FALSE= , können Sie neue Dinge tun, unter anderem auch mit einer =FEATURE= -Sektion, beispielsweise wie folgt:

 <code>
LAYER
NAME "credits"
STATUS DEFAULT
TRANSFORM FALSE
TYPE ANNOTATION
FEATURE
POINTS
10 10
END
TEXT 'http://www.mapmedia.de/'
END
CLASS
LABEL
TYPE TRUETYPE
FONT "arial"
SIZE 11
ANTIALIAS TRUE
COLOR 0 0 0
END
END
END
</code> 

Dieser Layer besteht aus nur einem Feature, einem Punkt, dessen Koordinaten fest angegeben sind, und ebenso seine Beschriftung. In der dazugehörigen Class ist die Beschriftung mit Schriftart, Farbe usw. definiert. Dadurch, dass der Status auf =DEFAULT= gesetzt ist, und dass man diesen Layer als letzten Layer im Mapfile notiert, hat man einen Effekt wie in Abbildung~\ref{transform-label}: eine Beschriftung, die immer in der Karte zu sehen ist.

FIXME: raster?

=CGI-Parameter=(29)

FIXME:aufzählung

==Parameter einschränken==(30)

FIXME:Restriktion durch eine EXPRESSION

\subsection*{Ändern des Mapfiles}

Von außen (über den aufrufenden URL) können auch praktisch alle Inhalte des Mapfiles verändert werden. Der Aufbau dieser neuen Parameter ist recht simpel und orientiert sich an der Struktur eines Mapfiles.

Betrachten wir den Aufbau eines Mapfiles: eine Map beinhaltet (mindestens einen) Layer, dieser mindestens eine Klasse (wenn es sich um einen Vektorlayer handelt). Diese Klasse kann nun wiederum ein Label beinhalten, welches seinerseits eine Farbe hat.

Die Adressierung kann auf verschiedene Weise geschehen. Zuerst einmal über Nummern. Im folgenden Beispiel bekommt die erste Klasse im zweiten Layer die Farbe Rot zugewiesen:

 <code>
...&map_layer_1_class_0_color=255
</code> 

Das '\

Darüber hinaus lassen sich Layer auch über ihren Namen referenzieren:

 <code>
...&map_fluesse_class_0_color=255
</code> 

Wenn der Layer nur eine Klasse hat, sollte man den Index einfach weglassen.

Des weiteren lassen sich auf diesem Weg simple Features zu einem Layer hinzufügen. Der Layer muß existieren. Hier das Beispiel aus der offiziellen MapServer-Dokumentation:

 <code>
...&map_user_feature=new&map_user_feature_points=12345.6789+12345.6789
&map_user_feature_text=My+House!
</code> 

Dem Layer ''user'' wird auf diese Weise ein Punkt mit den angegebenen Koordinaten hinzugefügt, und er wird auch gleich beschriftet. Wird ein Layername mehrfach verwendet, wird das Feature einfach erweitert. Auf diese Weise lassen sich beispielweise Polygone mit 'Löchern' hinzufügen.

=Logs=(31)

Für einen Serverdienst möchte man selbstverständlich Log-Dateien angelegt bekommen. Ein Server läuft die ganze Zeit vor sich hin, sodass man, im Gegensatz zu einer Desktop-Anwendung, im Fehlerfall meistens nicht anwesend ist. Dann sind Protokolle der Serveraktivitäten natürlich notwendig für die Fehlersuche.

Aber auch für den Entwickler sind Logfiles wichtig, zeigen sie ihm doch, wo er nach Ursachen zu suchen hat, wenn sich die Anwendung, an der er arbeitet, nicht so verhält wie erwartet.

Wofür auch immer man seine Logs verwendet, definiert wird die Logdatei in MapServer in der Web-Sektion:

 <code>
WEB
...
LOG "/pfad/zur/datei.log"
END
</code> 

Es gibt nur eine einzige Logdatei pro Mapfile, in der MapServer sowohl Fehlermeldungen als auch erfolgreiche Zugriffe loggen kann.

Das Format für Logfiles ist leider nict dokumentiert, sodass man sich mit einem Blick in den Quellcode weiterhelfen muß\footnote{Siehe Funktion =writeLog= in =mapserv.c= }. Ein Eintrag in einem Logfile sieht beispielsweise folgendermaßen aus:

 <code>
Fri Mar 21 16:02:48 2003,1031,10.0.1.2,demonstration,0, \
7.848750 49.445625 19.098750 55.070625,13.473750 52.258125, \
bundeslaender,normal execution
</code> 

So ein Eintrag erstreckt sich immer über eine einzelne Zeile. Alle Bestandteile sind durch Kommata voneinander getrennt. Die vorliegende Zeile ist im einzelnen wie folgt zu verstehen:

*=Fri Mar 21 16:02:48 2003= Ist ein Zeitstempel; Datum und Uhrzeit des Aufrufs.
*=1031= Die aktuelle Prozess-ID.
*=10.0.1.2= Die IP-Adresse des aufrufenden Hosts. Wird aus der Umgebungsvariable =REMOTE_ADDR= gelesen und ist =NULL= \footnote{Hier ist die Zeichenkette ='NULL'= gemeint}, wenn diese Variable nicht gesetzt ist.
*=demonstration= Der Name des Mapfiles, wie er mit =NAME= im Header gesetzt ist.
*=0= Der Modus des Aufrufes, also z.B. =map= , =browse= und so weiter. Es gibt 26 verschiedene, die allesamt in =maptemplate.h= in einem Aufzählungstyp definiert sind.
*=7.848750 49.445625 19.098750 55.070625= sind die Extents des angezeigten Kartenausschnitts.
*=13.473750 52.258125= Ist der Punkt in der Karte, der angeklickt worden ist. Dieser Punkt hat den Aufruf des MapServers verursacht.
*=bundeslaender= Eine Liste der angeforderten Layer, durch Leerzeichen voneinander getrennt.
*=normal execution= Ist alles glatt gelaufen, findet sich dieser Eintrag am Ende einer Zeile.

Für ausführlicheres Logging gibt es den Parameter =DEBUG= , der im Header, in Layern und in Classes definiert werden kann. Mit dieser Einstellung produzieren bisher allerdings im wesentlichen nur Raster- und WMS-konforme Layer ausführlichere Fehlermeldungen. Es steht zu erwarten, dass dieser Parameter noch weiter ausgebaut wird.

\subsubsection*{Log-Dateien im Webserver}

Neben den Logs des MapServers haben Sie im Fehlerfall natürlich immer noch die Logs Ihres Webservers zur Verfügung. Im Fehlerfall finden Sie hier auch die HTTP-Fehlercodes, die dann nützlich sind, wenn es nicht MapServer-Fehler sind, die Ihnen Probleme bereiten. Insbesondere bei der Apache-Fehlermeldung ''Internal Server Error'' finden Sie normalerweise detaillierte Einträge, die Ihnen helfen können, die Ursache des Problems schnell zu lokalisieren.

=Logging=

Mit Mapserver 5.0 wurden die Möglichkeiten des Loggings erheblich erweitert. Zur Konfiguration sind zwei Punkte zu beachten:

* Die Variable MS_ERRORFILE muss gesetzt werden.
* Auf Map- bzw. Layer-Ebene wird ein Debuglevel gesetzt

'''''MS_ERRORFILE <Wert>'''''

Die Variable MS_ERRORFILE kann entweder mittels Umgebungsvariable oder per CONFIG-Direktive in dem Mapfile gesetzt werden. Die CONFIG-Direktive hat dabei Vorrang, falls beide Möglichkeiten genutzt werden.
Hiermit wird angegeben wohin die Logmeldungen geschrieben werden. Je nach Wert gibt es ''folgende Werte'':
; stderr : Ausgabe wird an die Standardfehlerausgabe gesandt. Bei Apache ist dies die per error_log angegebene Datei. Beim IIS wird es per Standardausgabe ausgegeben.
; stdout : Ausgabe wird an die Standardausgabe gesandt
; windowsdebug : Ausgabe wird an die Windows OutputDebugString API gesandt. Dadurch kann mit Programmen wie Debugview (Microsoft/Sysinternals) die Ausgabe verfolgt werden.
; PFAD : eine absolute Pfadangabe zum Logfile

Wird diese Variable nicht gesetzt, ist das Logging deaktiviert.

Beispiel:

CONFIG "MS_ERRORFILE" "/Pfad/zum/Logfile"

oder

CONFIG "MS_ERRORFILE" "stderr"

Dabei sollten Pfade immer als absoluter Pfad angegeben werden.

'''''DEBUG <level>'''''

Das DEBUG-Level wird entweder global oder auf Layerebene gesetzt. Zur Verfügung stehen ''folgende 6 Level'':
; Level 0 : Es werden ausschließlich Fehler geloggt. Entspricht DEBUG OFF bzw. DEBUG 0
; Level 1 : zusätzlich Warnungen zu nicht-fatalen Fehlern wie z.B. fehlende oder falsche Werte für bestimmte Parameter, fehlende Shapefiles in tileindex oder Zeitüberschreitung bei externen WMS-Diensten
; Level 2 : zusätzlich Hinweise mit Zeitinformationen
; Level 3 : zusätzlich Debugausgaben wie WMS-Verbindungs-URLs, Datenbank-Verbindungs-Informationen usw.
; Level 4 : weitere Ausgaben
; Level 5 : detaillierte Informationen die für Entwickler gedacht sind

Das Debuglevel kann global entweder per Umgebungsvariable MS_DEBUGLEVEL oder im Mapfile gesetzt werden. Werden beide Möglichkeiten genutzt, hat die Angabe im Mapfile Vorrang. Bei der Ausgabe wird für jeden Layer das gleiche Debuglevel genutzt.
Das Debuglevel auf Layerebene überschreibt ein evtl. gesetztes globales Debuglevel. Dadurch kann bis auf Layerebene die Fehlerausgabe individuell eingestellt werden.

Wird die Umgebungsvariable benutzt so werden auch Meldungen z.B. zur Initialisierung ausgegeben die außerhalb von Layer- oder Map-Context erfolgen.

=Includes=

Bei manchen Projekten kann das Mapfile sehr groß werden. Durch die INCLUDE-Direktive kann man die Übersichtlichkeit wieder erhöhen, in dem man einzelne Abschnitte in separate Dateien auslagert. Für hochperformante Mapserveranwendungen wird dieses Vorgehen nicht empfohlen, da ein gewisser Overhead entsteht. Eine Standardanwendung wird bei Verwendung von INCLUDE-Direktiven nicht spürbar verlangsamt.

Beispielaufruf:

INCLUDE "basislayer.map"

Folgende Hinweise sind bei der Verwendung zu beachten:

* Der Name der Datei '''sollte''' in Anführungszeichen stehen
* Die maximale Verschachtelungtiefe beträgt 5
* Die Pfadangabe kann absolut oder relativ zum Mapfile erfolgen
* Die Fehlerverfolgung wird erschwert da z.B. die angegebene Zeilennummer ggf. nicht mehr stimmt

[[Category:UMN MapServer Handbuch]]

HBUMNMapServer ger Capter 2

2009-01-23T07:04:42Z

Wiki-Mikee63: /* featurequery und featurenquery */

HBUMNMapServer ger Capter 2

2009-01-23T07:03:51Z

Wiki-Mikee63: /* itemquery und itemnquery */

HBUMNMapServer ger Capter 2

2009-01-23T07:02:56Z

Wiki-Mikee63: /* indexquery */

HBUMNMapServer ger Capter 2

2009-01-23T07:00:33Z

Wiki-Mikee63: /* Notation */

HBUMNMapServer ger Capter 2

2009-01-23T06:55:56Z

Wiki-Mikee63: /* Aufbau */

HBUMNMapServer ger Capter 2

2009-01-23T06:53:19Z

Wiki-Mikee63: /* Aufbau */

[[User:Lars]] (logging, includes, fastcgi) 
[[User:Simon Appelt]] (Web-Sektion, Layer, Weitere Layer-Optionen)
= Mapfile =
\index{Mapfile}

Das Mapfile wird Ihnen größte Freude bereiten. Sie werden die meisten Ihrer Fehler damit machen, und die meiste Zeit, die Sie mit dem MapServer überhaupt verbringen, wird das Editieren Ihrer Mapfiles zum Inhalt haben.

=Bedeutung des Mapfiles=

Das Mapfile ist die zentrale Layout- und Konfigurationsdatei einer MapServer-Anwendung,sozusagen das "Herz". Sie beschreibt Inhalt und Darstellung der fertigen Karte und enthält zusätzliche Informationen, um Maßstäbe, Legenden und Referenzkarten passend zur fertigen Karte zu erstellen.

Auch die Metadaten, die zur OGC-konformen Funktionsweise benötigt werden, sind im Mapfile angegeben.

Bevor wir jedoch in alle Details des Mapfiles einsteigen, werfen wir einen Blick auf die generelle Funktionsweise des MapServers.

==MapServer als CGI==\index{CGI}(2)

Dies ist der "Standard"-Weg, den MapServer zu benutzen: indem er als Programm in einem Webserver wie beispielsweise dem Apache residiert. Über den URL bekommt das Programm Parameter zugewiesen und ändert seine Ausgabe anhand dieser Parameter.

Ein Beispiel. Ein typischer URL sieht etwa folgendermaßen aus:

 <code>
http://www.example.com/cgi-bin/mapserv \
? map=/usr/local/www/mapfile.map
</code> 

Das ganze ist für den Druck umgebrochen, es handelt sich um eine einzige Zeile, und die Leestellen im URL sind ebenfalls nur für die Lesbarkeit hinzugefügt. Backslashes an den Enden zeigen an, dass die Zeile noch nicht beendet ist. Diese Unix-typische Notation wird im folgenden im ganzen Buch Verwendung finden.

Beachten Sie bitte, dass die Domain =example.com= für anschauliche Zwecke in der Literatur~[[rfc2606]] reserviert ist und Ihnen ''kein Ergebnis'' bei einem Aufruf anzeigen wird. Ersetzen Sie diesen Domainnamen durch den tatsächlichen Namen Ihres Hosts.

Der MapServer, das eigentliche Programm, das die Arbeit macht, liegt offensichtlich in einem =cgi-bin= genannten Verzeichnis des Webservers. Ruft man ihn einfach ohne Parameter auf, also etwa folgendermaßen:

 <code>
http://www.example.com/cgi-bin/mapserv
</code> 

dann sollte man als Antwort folgendes in seinem Browser sehen:

 <code>
No query information to decode. QUERY_STRING is set, but empty.
</code> 

\begin{figure}
\begin{center}
\mmfig{0.35}{motzing}{Der MapServer motzt herum; genau das, was man am Anfang sehen möchte.}
\end{center}
\end{figure}

Also wie in Abbildung~\ref{motzing}. Wie reagiert man darauf? Indem man sich freut, denn alles ist in Ordnung; hurra, er kann schon rummotzen! Dies ist die Meldung, die man sehen möchte. MapServer beschwert sich lediglich, dass er keine Parameter zur Verarbeitung genannt bekommen hat. Nach einer neuen Installation ist diese Meldung nach dem ersten Testaufruf das gewünschte Ergebnis.

Der erste Parameter wird mit einem Fragezeichen =?= eingeleitet, alle weiteren werden mit einem Kaufmanns-Und =\&= voneinander getrennt.

Zwingend notwendig ist die Angabe eines Mapfiles über den Parameter =map== \footnote{Man kann diese Preisgabe des Ortes, an dem das Mapfile liegt, auch nach außen verbergen. Mehr dazu später.}, damit dem MapServer bekannt ist, welches Layout für die Karte zur Anwendung kommen soll.

Liegt Ihr Mapfile unter Unix etwa unter =/usr/local/maps/mymap.map= , so wäre also folgender Aufruf korrekt:

 <code>
http://www.example.com/cgi-bin/mapserv?map=/usr/local/maps/mymap.map
</code> 

Pfade unter Windows werden ebenfalls so angegeben, wie Sie es gewohnt sind, also beispielweise mit =C:= am Anfang.

==Die Modi==

MapServer kennt nun verschiedene Betriebs''modi'' , die über den Parameter =mode== notiert werden. Es gibt die folgenden Modi:

*=browse= : Läßt Sie die Karte browsen. Das bedeutet im wesentlichen, dass MapServer die Templates berücksichtigt, die im Mapfile angegeben sind, und somit HTML-Dateien mit Navigationselementen ausliefert. Wenn kein Modus angegeben ist, geht MapServer immer von =browse= aus. Was es mit Templates genau auf sich hat, erfahren Sie in Abschnitt~20 ab Seite~\pageref{text:mapfile:templates}.
*=map= : Dieser Modus läßt den MapServer Template-Angaben ignorieren und nur die Karte ausliefern. Zum Testen Ihres Mapfiles ist dies wahrscheinlich genau der Modus, den Sie haben möchten.
*=query= : Dieser Modus und seine Funktion, das Abfragen von Daten, die der Karte zugrunde liegen, werden ab Seite~\pageref{text:mapfile:queries} beschrieben.
*=nquery= : Wo =query= immer nur ein Ergebnis zurückliefern kann, kann =nquery= mehrere Ergebnisse liefern, sowohl im gleichen Layer als auch aus verschiedenen Layern (und auch beides zusammen, natürlich). Die Template-Angaben für diesen Modus können recht umfangreich sein.

Wenn Sie also Ihr Mapfile =mymap.map= im Modus =map= aufrufen wollten -- wodurch lediglich eine Karte, aber kein HTML-Interface produziert würde --, würden Sie folgendes notieren:

 <code>
http://www.example.com/cgi-bin/mapserv \
? map=/usr/local/maps/mymap.map \
& mode=map
</code> 

==Die weiteren Parameter==

Alle Variablen, die das Aussehen einer Karte beeinflussen können, werden über solche Parameter übergeben. Das schließt das Mapfile und den Modus mit ein, und darüberhinaus \ldots\ nun, eben alles andere, inklusive der Kartenebenen, die Sie sehen möchten, die Eckpunkte des gewünschten Kartenausschnitts, und noch diverse andere Dinge mehr. Da kann ein URL schnell einmal wie folgt aussehen:

 <code>
http://www.example.com/cgi-bin/mapserv \
? map=/usr/local/maps/mymap.map \
& mode=map \
& layer=postleitzahlen&layer=fluesse&layer=strassen \
& imgext=18.0+9.0+30.0+15.0
</code> 

Und sie kann noch viel viel länger werden. Und Ihr erster Gedanke, wenn Sie das sehen, ist natürlich vollkommen korrekt: Das will kein Mensch jedesmal eintippen müssen.

Daher werden diese Parameter für gewöhnlich über Eingaben in einem HTML-Formular generiert. Dazu gehört dann beispielsweise auch die Karte, die Sie im Browserfenster anklicken. Diese Formulare werden aus den Templates generiert, die weiter oben schon einmal erwähnt worden sind.

Für das erste setzen wir uns ausschließlich mit der Gestaltung der Karte auseinander, wofür Sie nur den Modus =map= ohne zusätzliche Parameter benötigten. Wenn ab Seite~\pageref{text:mapfile:templates} die Templates dazukommen, wird Ihr Wissen um eine Navigation in der Karte erweitert. Ab Seite~\pageref{text:mapfile:cgiparams} finden Sie schließlich eine Aufzählung aller möglichen CGI-Parameter.

Neben der CGI-Fassung gibt es zwei weitere Wege, die Funktionalitäten des MapServers zu nutzen. Beide unterscheiden sich zum Teil radikal von der Weise, die in diesem Kapitel behandelt wird.

\subsubsection*{Der OGC-konforme MapServer}\index{OGC}

Der OGC-konforme MapServer arbeitet ebenfalls als CGI-Programm und muß vor allen Dingen mit Metadaten versorgt werden, die dann bei der Kommunikation mit anderen Servern und mit Client-Appli\-ka\-tio\-nen verwendet werden.

Leider weicht sowohl die Notation des aufrufenden URL als auch die Notation der Metadaten im Mapfile ein wenig von der des MapServers im 'Normalbetrieb' ab, was nicht zur Lesbarkeit der ganzen Datei beiträgt. Die Unterschiede in der Notation werden im entsprechenden Kapitel ab Seite~\pageref{text:ogc} natürlich erläutert.

\subsubsection*{MapScript}\index{MapScript}

MapScript muß nicht gezwungenermaßen mit einem Mapfile arbeiten, z.B. wenn man damit nur Shapefiles bearbeiten möchte. Sobald man beginnt, mit Karten arbeiten zu wollen, wird man jedoch auch mit MapScript ein Mapfile laden, das dann verwendet werden kann.

Alle Sektionen im Mapfile werden dann als Objekte in einer Programmiersprache behandelt. Grundsätzlich ist nicht einmal ein Webserver vonnöten, auch lokale Applikationen lassen sich mit MapScript realisieren.

Am häufigsten sieht man MapScript jedoch in seiner Variante für PHP im Einsatz, die dann natürlich wieder in Webservern läuft. Als Beispiel konzentrieren wir uns in diesem Handbuch auf eben diese Version von MapScript.

=Grundlegender Aufbau des Mapfiles=

Werfen wir zuerst einen ganz allgemeinen Blick darauf, wie Inhalte im Mapfile notiert werden, bevor dann näher beschrieben wird, welche Einträge es denn gibt.

Das Mapfile besteht aus einzelnen Blöcken, die mit einem Schlüsselwort beginnen und mit einem =END= abgeschlossen werden:

 <code>
WEB
...
END
</code> 

Dieses Beispiel zeigt den Beginn und das Ende eines =WEB= -Blocks. Innerhalb eines solchen Blocks folgen Deklarationen von Schlüsselworten und dazugehörigen Werten, oder wieder neue Blöcke. Beispiele für Blöcke in Blöcken sind Classes innerhalb von Layern.

Ausnahmen für diese Notation sind der Header des Mapfiles und das Mapfile selber, das zwar mit einem END abgeschlossen werden muss, aber kein einleitendes Schlüsselwort kennt.

Wann immer im folgenden drei Punkte in Beispielen zu sehen sind, sollen diese Punkte nicht tatsächlich eingegeben werden; es handelt sich vielmehr um Platzhalter, die zeigen, dass etwas weggelassen worden ist.

Es können drei verschiedene Dinge als Werte notiert werden: Schlüsselworte, Zahlen oder Zeichenketten.

 <code>
SCHLÜSSELWORT SCHLÜSSEL
STATUS ON

SCHLÜSSELWORT "ZEICHENKETTE"
DATA "myshapefile"

SCHLÜSSELWORT ZAHL [ZAHL ...]
EXTENT 0 0 4000 4000
</code> 

Im Gegensatz zu Schlüsselworten und Zeichenketten ist es bei Zahlen in den meisten Fällen nötig, mehr als nur eine zu schreiben. So benötigt man für den Extent einer Karte stets vier Zahlen, die die beiden Koordinaten jeweils eines Eckpunktes bezeichnen.

Zeichenketten sollten generell nicht mit Zahlen beginnen: =zweiterlayer= ist als Layername in Ordnung, =2terlayer= nicht.

Ausnahmen dazu bilden Angaben zu Projektionen von Karten und Layern und die Metadaten in diversen Sektionen. Deren Notation wird in den entsprechenden Abschnitten näher beschrieben.

Zwei Arten von Angaben verdienen besondere Beachtung: Pfade in das Dateisystem und Farben.

\subsubsection*{Notation von Pfaden}

Pfade können absolute oder relative Angaben sein. Absolute Angaben sehen etwa folgendermaßen aus:

 <code>
SHAPEPATH "c:\mapserver\daten"
SHAPEPATH "/usr/local/GIS/daten/"
</code> 

Absolute Pfade heißen so, weil sie den vollständigen Pfad von der Wurzel des Dateisystems bis hin zur Datei angeben.

Relative Pfade bewegen sich immer in Relation zu etwas, in unserem Fall zum Mapfile:

 <code>
SHAPEPATH "daten/"
</code> 

In diesem Fall gibt es also im Verzeichnis des Mapfiles ein Unterverzeichnis mit dem Namen =daten= .

\subsubsection*{Farbwerte}

Farben werden als RGB-Werte angegeben, also bestehend aus ihren jeweiligen Anteilen von Rot, Grün und Blau, in Werten von 0 bis 255\footnote{Dadurch lassen sich theoretisch <math>2^{24}</math> Farben, also die bekannten 16 Millionen darstellen}. Einige Beispiele:

 <code>
COLOR 0 0 0 # schwarz
COLOR 255 255 255 # weiß
COLOR 255 0 0 # rot
COLOR 0 255 0 # grün
COLOR 0 0 255 # blau
</code> 

Und so weiter. Farben, bei denen alle drei Zahlen gleich sind, ergeben Grautöne. Im Web finden sich einige Farb- und Umrechnungstabellen.

Beachten Sie bitte: Ohne weitere Angaben zum Ausgabeformat -- siehe Seite~\pageref{text:mapfile:ausgabeformate} -- produziert MapServer nur Bilder mit einer Palette von 256 Farben. Mehr über Farben in MapServer erfahren Sie in eben diesem Abschnitt.

=Der Header=
\index{Header}\index{Mapfile!Header}(3)

Der Header im Mapfile enthält globale Angaben, die sich auf alle Sektionen im
Mapfile beziehen oder das Aussehen des fertigen Bildes bestimmen, das produziert
werden soll. Der Header ist die einzige Sektion, die nicht durch ein END
abgeschlossen wird. Er besitzt auch kein einleitendes Schlüsselwort.

Ein Beispiel für einen kompletten Header\footnote{Um keinen Fehler im Modus =map= zu produzieren, reichen eigentlich schon SIZE und EXTENT, zusammen mit einem END für ein vollständiges Mapfile.}:

 <code>
NAME "brandenburg"
EXTENT 0.0 0.0 1.0 1.0
SIZE 450 450
SHAPEPATH "daten/brandenburg/"
</code> 

Sie können die folgenden Angaben im Header Ihres Mapfiles machen:

*=NAME <name>= Ein Name als Beschreibung der Karte. Dieser Name sollte einzigartig sein und im weiteren nicht als Name für Layer verwendet werden. Der Name der Karte wird für WMS-konforme Aufrufe verwendet -- siehe auch das entsprechende Kapitel --, als auch als Prefix für die Namen temporär erzeugter Dateien des MapServer.
*=STATUS <ON|OFF>= : Der Status der Karte, ob an oder aus. Da man ein Mapfile normalerweise schreibt, um eine Karte anzuzeigen, drängt sich =ON= geradezu auf.\\ Ausschalten will man das nur dann, wenn man nur die anderen Elemente benutzen will, die man im Mapfile definiert, also zum Beispiel Maßstäbe und Legenden.
*=EXTENT <minx miny maxx maxy>= : Eine Bounding Box um die Daten herum. Wird im URL für den MapServer keine Bounding Box explizit angegeben, ist diese Angabe im Mapfile eine Standardeinstellung, die automatisch verwendet wird. Dieser Wert muß zwingendermaßen vorhanden sein.\\ Sorgen Sie dafür, dass hier ein sinnvoller Wert steht. MapServer ist nicht in der Lage, aus den vorliegenden Daten einen 'Default'-Extent zu ermitteln. Auf das Problem angesprochen, meinten die Entwickler, so ein Feature auch nicht implementieren zu wollen, zumal einige Datenformate gar keinen Extent speichern und das Errechnen aus den Daten selbst viel zu aufwendig wäre.
*=SIZE <width height>= : Die Größe des zu produzierenden Bildes, anzugeben in Breite und Höhe in Pixeln. Auch dies ist eine Voreinstellung, die Verwendung findet, wenn es keine andere explizite Angabe gibt. Die Größe des zu produzierenden Bildes ist auf 2048 Pixel im Quadrat beschränkt.
*=SHAPEPATH <path>= : Der Ort im Dateisystem, an dem die Daten liegen. Kann ein relativer Pfad zum Mapfile sein, oder ein absoluter, der irgendwo anders in das lokale Dateisystem weist.
*=SYMBOLSET <filename>= : Die Datei, in der Symbole definiert werden. Was es mit Symbolen auf sich hat, und wie Symbole im Mapfile selber anstatt in einer separaten Datei notiert werden können, erfahren Sie in Abschnitt~17.
*=FONTSET <filename>= : Die Datei, die Aliase für TrueType-Schriften enthält. Zum Aufbau dieser Datei und der Verwendung von Schriften im MapServer siehe den Abschnitt ab Seite~\pageref{text:mapfile:fonts}.
*=IMAGECOLOR <red green blue>= : Hintergrundfarbe des fertigen Kartenbildes, in RGB-Werten.
*=IMAGEFORMAT <name>= : Name des Ausgabeformats, das produziert werden soll. Muß ein interner Name für ein Bildformat sein, oder der Name eines Ausgabeformates, der mit einer =OUTPUTFORMAT= -Sektion definiert worden ist. Mehr zu Ausgabeformaten finden Sie ab Seite~\pageref{text:mapfile:ausgabeformate}.

\subsubsection*{Das Wort MAP}

Sie können ein Mapfile auch mit dem Schlüsselwort =MAP= einleiten:

 <code>
MAP
NAME "brandenburg"
SIZE 400 400
...
END
</code> 

Das ist nicht notwendig. Sie können so allerdings dem abschließenden =END= am Ende des Mapfiles sozusagen einen Startparameter zur Seite stellen. Es sieht hübscher aus, hat aber keine Funktion.

=Die Web-Sektion=
\index{Web}\index{Mapfile!Web}

Der Web-Block im Mapfile definiert das Verhalten des MapServer-Interface nach außen und beinhaltet URLs für verschiedene Gelegenheiten, einige interne Informationen, die nicht nach außen weitergegeben werden, sowie eventuell Metadaten für verschiedene Anwendungsfälle, für gewöhnlich zum Beispiel für OGC-konformes Verhalten.

Der Web-Block wird mit den Schlüsselwort =WEB= eingeleitet und durch ein =END= abgeschlossen.

'Web' ist als Name eigentlich irreführend, da die Daten in diesem Abschnitt nicht notwendigerweise nur von Web-Diensten genutzt werden. Aber der MapServer wurde als Web-Applikation entwickelt, und daher ist es unwahrscheinlich, dass sich an dieser Benennung etwas ändern wird.

Die folgenden Elemente können in der Web-Sektion verwendet werden:

*=ERROR <url>= \index{ERROR}: Definiert einen URL, an den der Benutzer weitergeleitet wird, wenn ein Fehler in der MapServer-Applikation auftritt. Kann eine absolute URL sein, die mit =http://= eingeleitet wird, oder ein Pfad relativ zur Lage des Mapfiles. Wird =ERROR= nicht definiert, wird einfach nur die Fehlernachricht als Text ausgegeben.\\ Beachten Sie dabei, dass das für das Debuggen während der Entwicklung Ihrer Anwendung nicht begehrenswert ist, da keine der MapServer-Fehlermeldungen mehr ausgegeben werden. Das will man für gewöhnlich nur für das fertige System haben, sobald man seine Benutzer nicht mehr mit den Fehlermeldungen des MapServers konfrontieren möchte, sondern mit einer hübschen Fehlerseite.
*=EMPTY <url>= \index{EMPTY}: URL, an den der Benutzer weitergeleitet wird, wenn ein Query keine Resultate erbracht hat. Wenn =EMPTY= nicht definiert ist, wird dafür der Wert von =ERROR= benutzt.
*=FOOTER <filename>= \index{FOOTER}: Der Fußteil einer fertigen Ausgabe. Kommt nur bei Queries zur Anwendung, die mehrere Ergebnisse zurückliefern sollen.
*=HEADER <filename>= \index{HEADER}: Der Kopfteil einer fertigen Ausgabe. Kommt nur bei Queries zur Anwendung, die mehrere Ergebnisse zurückliefern sollen.
*=TEMPLATE <url|filename>= \index{TEMPLATE}: Das Template, das das eigentliche Interface zum Benutzer darstellt. Darstellung der Karte und die Navigation darin werden durch das Template übernommen. Der Aufbau eines Templates wird detailliert in Abschnitt~20 behandelt.
*=IMAGEPATH= \index{IMAGEPATH}: Der Pfad zu dem Verzeichnis, in dem die vom MapServer generierten Bilder abgelegt werden sollen. Dieser Pfad muß auf dem System existieren und muß vom Webserver (bzw. von dem Benutzer, mit dessen Rechten der Webserver läuft) beschreibbar sein. Diese Angabe muß mit dem Verzeichnistrenner der jeweiligen Plattform enden, also =/= auf Unix-Systemen und so weiter.
*=IMAGEURL= \index{IMAGEURL}: Der URL zum genannten =IMAGEPATH= . =IMAGEURL= wird vom Webbrowser zurückgegeben und muß daher im Webserver so konfiguriert sein, dass =IMAGEURL= auf =IMAGEPATH= abgebildet wird. Auf Unix-Systemen wird meistens der URL =/tmp= auf das lokale Verzeichnis =/tmp/= (oder auch =/var/tmp/= ) abgebildet. Damit gibt man jedoch auch sein temporäres Verzeichnis dem öffentlichen Zugriff preis. Sinnvoller ist es, ein eigenes Verzeichnis für diese Dateien anzulegen. Mehr Überlegungen zu diesem Thema finden Sie in Anhang~\ref{anhang:sicherheit}.
*=LOG <filename>= \index{LOG}: Die Logdatei für den MapServer. Diese Datei muß auf dem System existieren und muss vom Webserver (bzw. von dem Benutzer, mit dessen Rechten der Webserver läuft) beschreibbar sein. Mehr zu Log-Dateien erfahren Sie weiter unten in Abschnitt~31.
*=METADATA<filename>= \index{LOG}: Die Sektion Metadata ermöglicht es, weiterführende Informationen über den WMS-Dienst bereitzustellen, um nach aussen eine gewisse Transparents zu schaffen. So gibt es zum Beispiel den erforderlichen Parameter "wms_title", über dem das Kind einen Namen bekommt. Nähre Information zu den einzelenen Parametern, finden Sie im Kapitell 3, Sektion 3.2.3 WMS-Metadaten im Mapfile.
*=MINSCALEDENOM= \index{MINSCALE}: Der minimale =SCALE= , in dem Karten zu sehen sind. Wird eine Karte mit einem kleineren =SCALE= vom Client angefordert, liefert MapServer eine Karte in dem =SCALE= zurück, der =MINSCALE= entspricht. Mehr zur Verwendung von =SCALE= -ähnlichen Parametern im Mapfile finden Sie in Sektion~19.
*=MAXSCALEDENOM= \index{MAXSCALE}: Der maximale =SCALE= , in dem Karten zu sehen sind. Wird eine Karte mit einem größeren =SCALE= vom Client angefordert, liefert MapServer eine Karte in dem =SCALE= zurück, der =MAXSCALE= entspricht. Mehr zur Verwendung von =SCALE= -ähnlichen Parametern im Mapfile finden Sie in Sektion~19.
*=MINTEMPLATE= \index{MINTEMPLATE}: Template, das anstelle von =TEMPLATE= benutzt werden soll, wenn der Client eine Karte angefordert hat, deren =SCALE= unter =MINSCALEDENOM= liegt. Mit einem solchen Template lassen sich Applikationen ineinander verschachteln, indem ab bestimmten Zoomtiefen einfach andere Templates benutzt werden.
*=MAXTEMPLATE= \index{MAXTEMPLATE}: Template, das anstelle von =TEMPLATE= benutzt werden soll, wenn der Client eine Karte angefordert hat, deren =SCALE= über =MAXSCALEDENOM= liegt. Mit einem solchen Template lassen sich Applikationen ineinander verschachteln, indem ab bestimmten Zoomtiefen einfach andere Templates benutzt werden.

Der Parameter =IMAGEQUALITY= , mit dem sich Kompressionsraten für produzierte JPEG-Bilder setzen ließ, wird nicht mehr unterstützt. Verwenden Sie stattdessen einen entsprechenden Parameter in einer =OUTPUTFORMAT= -Sektion (siehe weiter hinten). Das gleiche gilt für =INTERLACED= .

=Layer=
\index{Layer}\index{Mapfile!Layer}

MapServer organisiert seine Daten in Schichten, die übereinander liegen -- eben den Layern. Diese Schichten werden dann zu einem fertigen Bild zusammengefügt. Einzelne Sets von Raster- oder Polygondaten müssen jeweils in einen eigenen Layer eingebunden werden. Über die Layer werden auch Queries definiert, die dazu verwendet werden, Anfragen an zusätzlich gespeicherte Daten zu stellen. Auf diese Weise können beispielsweise Flächen angeklickt und detaillierte Informationen zu diesen angezeigt werden.

Bei nicht-OGC-konformen MapServern spielt die Reihenfolge der Layer im Mapfile eine wichtige Rolle.
Dies können sie sich wie eine Art Stapelverarbeitung vorstellen. Der Layer, der oben auf dem Stapel liegt, wird als erstes abgearbeitet und gezeichnet, somit liegt dieser in der Kartendarstellung ganz unten. Rasterbilder bieten sich meist als unterster Layer an. Auf den ersten Layer wird dann der zweite Layer im Mapfile gezeichnet, und so weiter.

Wir betrachten im folgenden den Aufbau eines Vektorlayers mit Zugriff auf ein Shapfile. Rasterdaten werden in Abschnitt~7 besprochen.

*=NAME <name>= : Ein Name als Beschreibung des Layers. Mehrere Layer können identische Namen tragen und werden dann als ein einziger Layer behandelt. Diese Vorgehensweise wird manchmal für Beschriftungen (Annotationen, siehe weiter hinten) gewählt, um in einem Zug den Layer samt Beschriftung ein- oder ausblenden zu können. Ansonsten sollte der Name so gewählt werden, dass er eindeutig ist. Um mögliche Fehlerquellen bei der Wahl des Layernames von vornherein zu vermeiden,
ist es empfehlenswert den Layernamen so zu bestimmen, dass weder Sonderzeichen, noch Zahlen und Umlaute enthalten sind.

*=DATA <filename>= : Der Dateiname des Shapefiles. Dieser Name ist relativ zum =SHAPEPATH= im Header des Mapfiles. Die Zeichenkette hier wird also einfach angehangen. Der Name sollte ohne den Anhang ''.shp'' angegeben werden. Bitte beachten Sie, dass die zum Shapefile gehörige ''.dbf'' -Datei immer vorhanden sein muss, auch wenn man nicht auf ihren Inhalt zugreift. Das gleiche gilt natürlich auch für die Indexdatei mit der Endung ''.shx'' , nur wird diese ja beim Zugriff auf das Shape tatsächlich verwendet. Des weiteren können Sie hier auch einfach den absoluten Pfadnamen einer Datei angeben.
*=STATUS <ON|OFF|DEFAULT>= : Der Status des Layers. Es gilt drei verschiedene Stadien zu unterscheiden. =DEFAULT= stellt den betreffenden Layer auf jeden Fall dar, unabhängig davon, ob der Benutzer ihn über den URL anfordert. Auf diese Weise läßt sich die Darstellung beispielsweise eines Hintergrundbildes erzwingen, ohne dass man ihn von außen abschalten kann. =OFF= stellt den Layer gar nicht da, unabhängig davon, ob er von außen angefordert worden ist. =ON= hingegen macht den Layer darstellbar, und er wird angezeigt, wenn er über den entsprechenden Parameter des URL angefordert worden ist.
*=TYPE <POINT|LINE|POLYGON>= : Für Vektorlayer kommen nur diese drei verschiedenen Typen in Frage. Punktlayer sind offensichtlich nur für Punktdaten geeignet. Generell lassen sich Linien- und Vektordaten als das jeweils andere darstellen. Das wirkt sich im wesentlich auf die Art und Weise aus, mit der MapServer die Definitionen in den Klassen des Layers interpretiert. Mehr dazu im Abschnitt über Classes.

Beachten Sie bitte, dass in den Layer-Sektionen mit diesen Angaben noch keine Aussagen über das Layout der Daten gemacht werden. Diese Aussagen werden erst in den Klassen innerhalb eines Layers getroffen!

==Gruppierungen von Layern==
(4)
\index{Groups}\index{Layer!Groups}

Zuweilen möchte man mehrere Layer gleichzeitig ansprechen, indem man sie beispielsweise in einem Schwung an- und wieder ausschaltet. Wenn man für jeden dieser Layer einen eigenen Eintrag in der Navigation zuläßt, kann es schnell unübersichtlich werden.

Eine Möglichkeit ist, zusammengehörigen Layern den gleichen Namen zu geben. Wenn man also drei Layer hat, die beispielsweise Landstraßen, Autobahnen und Bundesstraßen darstellen, kann man sie alle drei =strasse= nennen und ist fertig.

Das widerspricht jedoch ein wenig der Idee, drei verschiedene Layer zu haben. Man hätte dann ebenso gut alle Daten in einem Shapefile unterbringen und die Art der Darstellung mit entsprechenden Classes über die Daten in der ''.dbf'' -Datei erledigen können.

Das Schlüsselwort =GROUP= erlaubt die Gruppierung von Layern unter Beibehaltung ihrer Namen mitsamt der Möglichkeit, sie alle auf einmal ansprechen zu können. Man schaue sich folgendes Fragment an:

 <code>
LAYER
NAME "autobahnen"
GROUP "strassen"
...
END

LAYER
NAME "bundesstrassen"
GROUP "strassen"
...
END

LAYER
NAME "landstrassen"
GROUP "strassen"
...
END
</code> 

Nun ist es möglich, im URL eines MapServer-Aufrufs weiterhin folgendes zu schreiben:

 <code>
...&layer=landstrassen&layer=autobahnen&...
</code> 

Zusätzlich gewinnt man aber auch die folgende Notation:

 <code>
...&layer=strassen&...
</code> 

==Weitere Layer-Optionen==

Im folgenden eine Liste aller weiteren Schlüsselworte, die in Layern Verwendung finden können. Falls Sie dieses Buch von vorne nach hinten durchlesen\footnote{Sowas soll's geben.}, werden Sie einige der Begriffe wahrscheinlich noch nicht kennen. Sie sollten dann später noch einmal hierher zurückkehren und sich die Bedeutung der Dinge klarmachen.

*=REQUIRES <expression>= Legt bestimmte Voraussetzungen fest, unter denen ein Layer angezeigt wird. Ein Beispiel: <code> LAYER NAME "gruenflaechen" STATUS ON REQUIRES "[parks] != 1" ... END </code> Dieser Layer würde also nur dann angezeigt, wenn ein anderer Layer mit dem Namen =parks= ''nicht'' zu sehen ist. Logische Operatoren wie =AND= und =OR= können hier Verwendung finden.
*=MAXSCALE <double>= Der maximale SCALE, bei dem der Layer noch gezeichnet werden soll. Dieser Wert ist unter Umständen nicht vertrauenswürdig -- siehe auch den Abschnitt~19 über Maßstäbe.
*=MINSCALE <double>= Das gleiche für einen minimalen SCALE.
*=LABELANGLEITEM <colname>= Gibt bei einem Shapefile die Spalte in der ''.dbf'' -Datei an, in der ein Winkel stehen soll, um den ein Label im Layer gedreht werden soll.
*=LABELMAXSCALE <integer>= Der maximale SCALE, in dem Labels in diesem Layer gezeichnet werden sollen. Anmerkungen zu diesem Wert siehe weiter oben.
*=LABELMINSCALE <integer>= Der minimale SCALE, bei dem Labels in diesem Layer noch gezeichnet werden sollen.
*=LABELREQUIRES <expression>= Siehe weiter oben das =REQUIRES= -Schlüsselwort; wirkt sich aber nur auf die Label in einem Layer aus.
*=MAXFEATURES <integer>= Die maximale Anzahl an Features, die in diesem Layer gezeichnet werden sollen.
*=OFFSITE <integer>= Kommt nur bei Rasterbildern zur Anwendung und gibt die Nummer der Farbe in der Farbpalette an, die transparent geschaltet werden soll.
*=POSTLABELCACHE <true|false>= Gibt an, ob der Layer vor oder nach allen Labels gezeichnet werden soll. Voreinstellung ist =false= .
*=SYMBOLSCALE <double>= Der SCALE, bei dem Labels (und Symbole) in ihrer vollen Größe gezeichnet werden. Auf diese Weise erreicht man Beschriftungen, die beim Herein- und Herauszoomen mitskalieren.
*=TRANSFORM <true|false>= Definiert, ob ein Layer von dem Koordinatensystem seiner Daten in ein Bildkoordinatensystem transformiert werden soll. Voreinstellung ist =true= . Eine nützliche Funktion, wenn man Bilder an festen Stellen in jeder Karte einbinden möchte, beispielsweise Nordpfeile oder Logos.
*=CLASSITEM <colname>=
*=CLASSGROUP <name>=
*=CONNECTIONTYP<local|sde|ogr|postgis|oraclespatial|wms>=
*=CONNECTION <string>=
*=DEBUG<off|on|0|1|2|3|4|5>= Der DEBUG Befehl kommt dann zum Einsatz, sobald sie ihr Mapfile speziell testen möchten. So geben die einzelnen Level detailierte Antworten,zum Beispiel über die Darstellungsdauer des einzelnen Layer. Um den DEBUG Parameter verwendeen zu können, muss im Vorfeld im oberen MAP-Teil ein MS_ERRORFILE definiert werden, über dem die Ausgabedatei bestimmt wird. Näheres dazu finden sie im Kapitel 12 Logging.
*=DUMP<true|false>= Ist default mäßig auf =false=, sollten sie später mit WMS GetFeatureInfo arbeiten empfiehlt es sich, diesen Parameter auf =true= zusetzen, damit der MapServer die Anfrage bearbeiten kann. Die Antwort liefert der MapServer als GML Datei.
*=FILTER<string>=
*=FILTERITEM<attribute>=
*=LABELCACHE<on|off>=
*=LABELITEM<colname>= Mit diesem Befehl, lassen sich ihre Vektordaten beschriften (labeln), hierfür geben sie die Spalte, aus der gewünschten Datenquelle, an in der sich der gewünschte, darzustellende Zeichensatz befindet. Zur Beschriftung mit Inhalten aus mehreren Datenspalten kann der TEXT-Eintrag in der CLASS genutzt werden in der Form: TEXT ([colname 1], [colname 2]). Möglich ist damit auch, dynamische Einträge aus den Tabellenspalten mit fixen Textbestandteilen zu mischen. In diesen Fällen kann LABELITEM entfallen.

 <code>
Bsp. 1: Mischung aus zwei Tabellenspalten
CLASS
...
TEXT ([stadtteil]-[stadtviertel])
END

oder
Bsp. 2: Mischung aus einer Tabellenspalte und fixen Text (''GK:'')

CLASS
...
TEXT (GK:[gk-zone])
END
</code> 

*=OPACITY<integer|alpha>= Definiert die Tranpsarents eines Layers, hierbei können sie mit zwei unterschiedlichen Operanten arbeiten. Die am häufigsten verwendete Methode ist die Angabe des Wertebereichs von 0 bis 100 als Integerzahl, wobei 100 den Layer komplett transparent darstellt. Die zweite Möglichkeit kommt eher selten zum Einsatz, dabei wird...
*=PROCESSING<string>=
*=REQUIRES<expression>=
*=SIZEUNITS<pixels|feet|inches|kilometers|meters|miles>=
*=STYLEITEM<attribute]>=
*=TILEINDEX<filename|layername>=
*=TILEITEM<attribute>=
*=TOLERANCE<double>=
*=TOLERANCEUNITS<pixels|feet|inches|kilometers|meters|miles|dd>=
*=UNITS<feet|inches|kilometers|meters|miles|dd|pixels|percentages>=
*=HEADER<filename>=
*=FOOTER<filename>=

=Classes=\index{Classes}\index{Klassen}\index{Mapfile!Classes}

''Hinweis'' : Beachten Sie auf alle Fälle die Hinweise in Abschnitt~6, insbesondere, wenn Sie bisher älteren MapServer-Versionen als 4.0 gearbeitet haben.

Classes residieren ausschließlich innerhalb eines Layers. Sie definieren, wie die Daten innerhalb eines Layers tatsächlich dargestellt werden.

Zur Illustration ein erstes kleines Beispiel:

 <code>
LAYER
NAME "fluesse"
DATA "shapes/fluesse"
TYPE LINE
STATUS ON
CLASS
COLOR 0 0 255
END
END
</code> 

In diesem Vektorlayer gibt es lediglich eine einzige Class, was bedeutet, dass alle Shapes aus dem Shapefile auf die gleiche Weise dargestellt werden. In diesem Fall sind sie blau eingefärbt.

Beachten Sie, dass Sie zur Einfärbung von Linien und Punkten das Attribut =COLOR= benutzen müssen, wohingegen dieser Wert bei Polygonen die Füllfarbe bezeichnet. Der Rand des Polygons wird durch =OUTLINECOLOR= angesprochen.

\subsection*{Datenabhängiges Einfärben}

Wozu aber nun Classes einführen, wenn man diese Angaben auch direkt in den Layer schreiben könnte? Weil man durch Classes themenbezogene Darstellungen erreichen kann. Sehen wir uns das folgende Beispiel an:

 <code>
LAYER
NAME "fluesse"
DATA "shapes/fluesse"
TYPE LINE
STATUS ON
CLASSITEM "NAME"
CLASS
EXPRESSION "Wolga"
COLOR 255 31 31
END
CLASS
EXPRESSION /./
COLOR 31 31 255
END
END
</code> 

Wir sehen zuerst ein neues Schlüsselwort, =CLASSITEM= . Die Zeichenkette dahinter benennt die Spalte in der ''.dbf'' -Tabelle, anhand derer wir im folgenden filtern wollen. Alle Angaben in den Classes, die sich in diesem Layer befinden, orientieren sich an der Spalte mit diesem Namen.

In der ersten Class befindet sich eine =EXPRESSION= , ein Ausdruck. Damit ein Feature mit den Angaben in dieser Klasse dargestellt wird, muß das =CLASSITEM= auf diesen Ausdruck passen. Oder für das Beispiel: die erste Klasse findet Anwendung auf alle Shapes im Shapefile, deren NAME in der ''.dbf'' -Datei 'Wolga' lautet.

Die Classes in einem Layer werden von oben nach unten abgearbeitet, und die erste passende Class wird zur Darstellung verwendet.

Der Ausdruck in der letzten Class in diesem Beispiel bedeutet übrigens 'alle Zeichen'. Jeder mögliche Inhalt einer Spalte passt auf diesen Ausdruck. Es ergibt Sinn, eine solche 'Catch all'-Class anzulegen, um allen Features ein Standardaussehen zu verpassen, die nicht von einer der vorherigen Class abgedeckt worden sind. Eine Erklärung der möglichen Ausdrücke erfolgt im nächsten Abschnitt.

\subsection*{Mögliche Ausdrücke}

Es gibt drei verschiedene Weisen, eine =EXPRESSION= zu formulieren: mit Zeichenketten, mit regulären Ausdrücken und schließlich mit logischen Ausdrücken.

Zeichenketten sind bereits im obigen Beispiel zu sehen gewesen. Die Einträge in den Spalten der ''.dbf'' -Datei werden darauf geprüft, ob sie ''genau'' diesen Wert enthalten. Diese Art von =EXPRESSION= ist durch den MapServer am schnellsten abzuarbeiten.

Logische Ausdrücke sind Ausdrücke, die durch logische Operatoren gebildet werden können. Dazu gehören Konstrukte für gleich, ungleich, größer als, kleiner als und so weiter; darüber hinaus und, oder, nicht, und alle Kombinationen, die sich daraus ergeben. Dabei können weitere Spaltennamen in der .dbf-Datei referenziert werden. Als Beispiel ein Ausschnitt aus einem Layer:

 <code>
CLASSITEM "NAME"
CLASS
EXPRESSION ([NAME] eq "Wolga" and [SIZE] < 10)
COLOR 255 0 0
END
CLASS
EXPRESSION /^A.+e<math>/
COLOR 0 0 255
END
CLASS
EXPRESSION /./
OUTLINECOLOR 128 128 128
END
</code> 

Die erste Klasse findet Anwendung auf alle Shapes, deren Spalte =NAME= im .dbf-File den Eintrag ''Wolga'' haben und gleichzeitig einen kleineren Wert als ''10'' in der Spalte =SIZE= .

Obwohl diese Ausdrücke schon eine Menge Flexibilität bieten, kann man noch einen Schritt weiter gehen, wie man in der zweiten Klasse sehen kann. Die Art des dortigen Ausdrucks ist Informatikern als sogenannter regulärer Ausdruck bekannt. Der Ausdruck passt auf alle Einträge in der =NAME= -Spalte, auf die folgendes zutrifft: der erste Buchstabe ist ein großes ''A'' , das von einer beliebigen Anzahl beliebiger Zeichen (mindestens jedoch einem) gefolgt wird, abgeschlossen durch ein kleines ''e'' .

Die letzte Regel zeigt ebenfalls einen regulären Ausdruck. Er passt auf jedes beliebige Zeichen. Da die Classes von oben nach unten auf der Suche nach der ersten passenden Regel für ein Feature abgesucht werden, handelt es sich um eine sogenannte ''catch all'' -Regel, die auf alles zutrifft, was nicht vorher schon irgendwo gepasst hat.

Reguläre Ausdrücke sind ein ungemein mächtiges Werkzeug, das jedoch etwas Mühe zu Lernen erfordern kann. MapServer verwendet POSIX-konforme reguläre Ausdrücke, die auf jedem Unix-System in einer =man= -Page~[[man:7:regex]] erklärt werden.

=Styles=(6)\index{Styles}\index{Mapfile!Styles}

Mit MapServer 4.0 ist eine weitere Art eingeführt worden, die Darstellung eines Layers zu notieren. Um genau zu sein, sollte diese Art langsam aber sicher bevorzugt werden, zumal sie auch zusätzliche Vorteile bietet.

Aber zunächst sollen Sie natürlich erfahren, um was es geht. MapServer kennt ein neues Objekt, also eine Sektion, mit dem Namen =STYLE= . Diese Sektion trit nur innerhalb von Classes auf und wird selbstverständlich jeweils mit einem =END= abgeschlossen. Das ganze soll den Zweck haben, den gestalterischen Part einer Class vom logischen zu trennen. Anstatt also folgendes zu notieren:

 <code>
CLASS
EXPRESSION ([NAME] eq "Havel" and [SIZE] > 20)
SYMBOL "punkt"
COLOR 32 64 218
END
</code> 

würden Sie in Zukunft folgendes schreiben:

 <code>
CLASS
EXPRESSION ([NAME] eq "Havel" and [SIZE] > 20)
STYLE
SYMBOL "punkt"
COLOR 32 64 218
END
END
</code> 

Im Moment können Sie noch beides verwenden. Im Sinne einer sauberen Arbeitsweise sollte Sie allerdings dazu übergehen, Styles zu benutzen und die Parameter, die für die Darstellung zuständig sind, nicht mehr direkt in den Classes zu notieren.

Die folgenden Parameter wandern in die Style-Sektion einer Class:

*=ANTIALIAS=
*=BACKGROUNDCOLOR=
*=COLOR=
*=MAXSIZE=
*=MINSIZE=
*=OFFSET=
*=OUTLINECOLOR=
*=SIZE=
*=SYMBOL=

Die Notierung der Parameter erfolgt wie weiter vorne ab Seite~\pageref{text:mapfile:class:parameters} beschrieben.

Warum sollte man das haben wollen? Es soll in Zukunft möglich sein, Styles mit Namen zu versehen, und dadurch Styles im gesamten Mapfile durch eben ihren Namen zu referenzieren. Dadurch kann bei umfangreichen Mapfiles einiges an Schreibarbeit eingespart werden. Insbesondere wird aber zukünftig Arbeit einsparen, weil Sie dann nur noch Styles von einem Mapfile ins andere Kopieren müssen, ohne auch noch an einer Class herumhantieren zu müssen.

Des weiteren kann man mehrere Styles in einer Class haben, sie werden der Reihe nach von oben nach unten ausgewertet; dabei wird, wie schon bei den Layern im Mapfile, der oberste Style zuerst gezeichnet. Dadurch ist es endlich möglich, mehr als die bisherigen 2 Symbole übereinander zu legen, wie es bisher mit =SYMBOL= und =OVERLAYSYMBOL= geschehen ist.

Außerdem -- dieser Teil ist allerdings reine Spekulation des Autors -- dürfte eine Abspaltung des darstellenden Teils einer Class die Implementierung der so genannten ''styled layer descriptors'' vereinfachen, einem OGC-Standard~[[pdf:spec:sld10]], mit dem sich die Darstellung von Kartenfeatures über URL-Parameter beeinflussen läßt.

=Rasterdaten=(7)
\index{Rasterdaten}\index{Mapfile!Rasterdaten}

Rasterdaten sind alle Arten von Daten, deren Dimensionen in Länge und Breite in Pixeln gemessen werden kann, vulgo: Bildformate. Die Bildformate, die von MapServer unterstützt werden, müssen in zwei Kategorien eingeteilt werden: die von der Software lesbaren (Input) und die Ausgabeformate (Output).

Als Ausgabe liefert MapServer Bilder, die von Webbrowsern darstellbar sind. Da sich MapServer dabei auf die Grafikbibliothek GD stützt, ist er auf deren Fähigkeiten angewiesen.

Ein typischer Rasterlayer wird im Mapfile etwa auf folgende Art angelegt:

 <code>
LAYER
NAME "brandenburg_luftbild"
DATA "bilder/brandenburg.tif"
TYPE RASTER
STATUS ON
END
</code> 

In diesem Beispiel wird ein ''tiff'' -Bild eingebunden, das anscheinend ein Luftbild der Region Brandenburg zum Inhalt hat. Der =TYPE= des Layers ist als =RASTER= angegeben.

Welche Formate eingelesen werden können, ist im wesentlichen eine Frage, die bei der Konfiguration noch vor der Kompilierung der Software geklärt wird. Einige Formate können dabei als eingebaut angesehen werden, indem der MapServer direkt auf die entsprechenden Bibliotheken zugreift. Andere Formate werden über die Rasterbibliothek GDAL gehandhabt.

Welche Formate Ihr MapServer handhaben kann, können Sie durch das Ausführen des CGI-Binaries auf der Kommandozeile mit dem Kommandozeilenschalter
''-v'' herausfinden:

 <code>
thfischer@grobi # ./mapserv -v
MapServer version 4.0 OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF
OUTPUT=SWF SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER
SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT
INPUT=EPPL7 INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE
</code> 

In diesem Beispiel sehen wir =.jpeg= als (lesend) unterstütztes Rasterformate. Weitere Formate können durch Verwendung der GDAL-Schnittstelle angesprochen werden, insbesondere findet hier das Lesen von =.tif= -Bildern über GDAL statt. Mehr zu diesen Bibliotheken finden Sie weiter hinten im Buch.

Beachten Sie, dass es für Rasterdaten keine Queries auf den Layer geben kann, da mit den gängigen Rasterformaten keine Metadaten gespeichert werden.

==Bildkataloge==(8)
\index{Rasterdaten!Kataloge}\index{Bildkataloge}

Bilddaten können sehr schnell sehr groß werden. Detaillierte Rasterbilder können viele Megabyte, wenn nicht gar Gigabyte groß werden. Solche Datenmengen sind nur schwierig zu handhaben, sowohl für den MapServer als auch, was die Verwaltung angeht. Um die Verarbeitung zu beschleunigen und die Handhabung zu vereinfachen, kann man sich so genannter Bildkataloge bedienen.

Des weiteren kann es natürlich passieren, dass man seine Daten gleich in mehreren Bildern bekommt, aber sicherlich nicht für jedes Bild einen eigenen Layer im Mapfile anlegen möchte. Man könnte die Layer natürlich mittels =GROUP= zusammenfassen; aber man müßte eben immer noch alle Layer ins Mapfile eintragen.

Das Format von MapServer-Bildkatalogen verwendet keinen verbreiteten Standard, der dazu führen würde, dass Sie die Bildkataloge auch mit anderen Programmen einlesen könnten. Allerdings verläßt sich MapServer auf standardisierte Datenformate, sodass eine Konvertierung von dieser Seite aus keine Schwierigkeiten bereiten sollte.

Dabei werden alle Bilder (sie müssen mit Worldfiles georeferenziert sein) über ein Shapefile verortet. Das Shapefile erhält dabei die Koordinaten der einzelnen Bilder, die ''.dbf'' -Datei der Reihe nach die dazugehörigen Dateinamen der Bilder.

Die Notation solcher Kataloge im Mapfile erfolgt folgendermaßen:

 <code>
LAYER
NAME "luftbild"
TYPE RASTER
STATUS ON
TILEINDEX "luftbildshape"
TILEITEM "IMAGEFILENAME"
END
</code> 

In diesem Beispiel trägt das Katalog-Shapefile den Namen =luftbildshape= . Mit =TILEITEM= gibt man an, wie die Spalte in der ''.dbf'' -Datei heißt, die die Dateinamen der Rasterbilder trägt.

Das Erzeugen von Bildkatalogen muß durch zusätzliche Software geschehen. Die Bibliothek GDAL bringt dafür ein Werkzeug namens =gdaltindex= mit -- siehe Seite~\pageref{text:tools:gdaltindex}

Durch den Aufbau mittels eines Shapefiles lassen sich die einzelnen Kacheln selber übrigens sehr schön visualisieren, indem man das betreffende Shape als Layer einbindet.

==Rasterdaten klassifizieren==

Rasterdaten können, ähnlich wie Vektordaten, klassifiziert werden. Dabei werden alle Pixel einer bestimmten Farbe (oder einer bestimmten Menge von Farben) auf eine andere Farbe abgebildet. Das macht man gerne bei 1-Bit-Bildern. Diese bestehen nur aus zwei Farben (also schwarz und weiß). Man färbt dann alle schwarzen Pixel in der gewählten Farbe ein, und schaltet dann die weißen Pixel für gewöhnlich transparent. Auf diese Weise lassen sich viele solcher Bilder in Schichten übereinander legen.

Es können aber auch Bilder mit 256 Farben klassifiziert werden.

Schauen wir uns ein Beispiel an:

 <code>
LAYER
NAME "grundwasser"
TYPE RASTER
STATUS ON
CLASSITEM "[pixel]"
CLASS
EXPRESSION ([pixel] < 128)
COLOR 255 0 0
END
CLASS
EXPRESSION ([pixel] >= 128)
COLOR 0 0 255
END
END
</code> 

Das =CLASSITEM= , nach dem wir filtern möchten, trägt den Namen =pixel= und repräsentiert die Nummer der Farbe in der Farbpalette des Bildes. Das funktioniert im Moment übrigens nur bei GD-Ausgabetreibern korrekt; der GDAL-Treiber\footnote{Zu Ausgabeformaten und -treibern siehe auch Seite~\pageref{text:mapfile:ausgabeformate}.} biegt vor der Bearbeitung des Bildes die Farbpaletten um, sodass man sich nicht auf die Position in der Farbpalette verlassen kann.

Die erste Class verleiht nun den ersten 128 Farben in der Farbpalette des Bildes ein grelles Rot, alle anderen Pixel werden durch die zweite Class blau dargestellt.

FIXME: ist das analog für truecolor-bilder etc.?

==Umprojizieren von Rasterdaten==

Der Gedanke läuft einem zuwider, wenn man sich die Mathematik klar macht. Man betrachte ein 4000 mal 4000 großes Tiff-Bild. Wenn man dieses Bild komplett umprojizieren möchte, müssen also 16 Millionen Pixel darauf geprüft werden, ob sie im neuen Zielbild liegen. Und wenn wir nun annehmen, dass wir 16 mal 16 solcher Kacheln haben, landen wir bei über 4 Milliarden Pixeln. Dass diese Berechnung eine Weile dauert, ist auf den ersten Blick ersichtlich.

Wenn Sie es jedoch einmal ausprobieren, werden Sie erstaunt sein, wie schnell MapServer Ihnen eine umprojizierte Karte liefert. Leider immer noch nicht schnell genug, wie man es im Dauerbetrieb, beispielsweise auf einer Website, haben will. Sie können sehr wohl mit der Geschwindigkeit vor Ihren Freunden angeben. Für den Dauerbetrieb lohnt es sich aber, die Projektion für Ihre Daten vorher zu machen.

Gleiche Überlegungen gelten übrigens auch für verschiedene Zoomstufen. Es lohnt sich durchaus, im Vorhinein zu überlegen, welche Zoomstufen am häufigsten zu sehen sein werden, um dann mit =MINSCALE= und =MAXSCALE= für diese Stufen verschiedene Datensätze anzuzeigen. Weitere Überlegungen zur Performance von MapServer-Anwendungen finden Sie ab Seite~\pageref{anhang:performance}.

==Rasterdaten mit GDAL==

\begin{figure}
\begin{center}
\mmfig{0.65}{gtopo30}{Die GTOPO30-Daten, hier ein Ausschnitt des Kanals zwischen Frankreich und Großbritannien.}
\end{center}
\end{figure}

Die Bibliothek GDAL ist für das Einlesen von Rasterdaten in MapServer zuständig, die über die 'herkömmlichen' Formate wie TIFF, JPEG, PNG und so weiter hinausgehen. Eine Liste von unterstützten Formaten finden Sie auf der GDAL-Website~[[http:website:gdal]]. Für diverse Formate müssen Sie unter Umständen die eine oder andere Zusatzbibliothek installiert haben. Bei Fragen oder Problemen hilft entweder ebenfalls die GDAL-Site weiter, oder eine Anfrage auf der MapServer-Mailingliste.

Die Notation von GDAL-gelesenen Rasterdaten weicht glücklicherweise überhaupt nicht von der von herkömmlichen Rasterdaten ab. Als Beispiel sollen hier die GTOPO30-Daten herhalten, die man sich von~[[ftp:gtopo30]] herunterladen kann\footnote{Achtung, falls Sie es auf den kompletten Datensatz für die ganze Welt abgesehen haben sollten: vollständig entpackt handelt es sich um 2,1 GB Daten. Beachten Sie bitte, dass es sich dabei um =Textdateien= handelt, die Bearbeitung also durchaus zeitintensiv ist.}.

Interessant sind für die Notation die Dateien mit der Endung =.DEM= . Die Abkürzung steht für ''digital elevation model'' , also für digitales Höhenmodell.

Sie können diese Daten in ein Unterverzeichnis entpacken -- nennen wir es =gtopo30= -- und dann ''gdaltindex'' für das Erzeugen eines Bildkatalogs aufrufen:

 <code>
# gdaltindex gtopo30.shp gtopo30/*.DEM
</code> 

Haben Sie das getan, können Sie sich einfach einen Layer wie folgt konstruieren:

 <code>
LAYER
NAME "gtopo30"
TYPE RASTER
STATUS ON
TILEINDEX "gtopo30"
END
</code> 

Und damit sind Sie dann auch schon fertig! Das Ergebnis sind dann beispielsweise aus wie in Abbildung~\ref{gtopo30}. Das DEM-Format wird behandelt wie jedes andere Rasterformat auch. Dem entsprechend können Sie eine einzelne dieser DEM-Dateien auch wie gewohnt folgendermaßen einbinden:

 <code>
LAYER
NAME "gtopo30"
TYPE RASTER
STATUS ON
DATA "gtopo30/W180S60.DEM"
END
</code> 

=Vektordaten=
\index{Vektordaten}

In seinen 'Jugendzeiten' war MapServer im wesentlichen darauf ausgelegt, Shapefiles darzustellen. Das macht sich insbesondere bei der Notation im Mapfile bemerkbar, wo bei Vektordaten einige Shapfile-spezifische Termini verwendet werden.

Zuerst ein Beispiel für Vektordaten in einem Layer:

 <code>
LAYER
NAME "gruenflaechen"
TYPE POLYGON
STATUS ON
DATA "gruenflaechen_0323333"
CLASS
EXPRESSION /./
COLOR 255 240 128
OUTLINECOLOR 128 120 64
END
END
</code> 

Der Typ eines Vektorlayers kann =POINT= , =LINE= oder =POLYGON= sein. Beachten Sie dabei, dass die beiden letztgenannten intern im wesentlichen gleich sind und daher in einigen Fällen austauschbar sind.

=DATA= verweist in diesem Fall auf ein Shapefile mit dem angegebenen Namen. Dieser Name ist relativ zum =SHAPEPATH= im Header des Mapfiles.

Das war auch schon alles, was es zur Notation von Shapefile-Layern im Mapfile zu sagen gibt. MapServer ist in der Lage, über Zusatzbibliotheken weitere Vektorformate zusätzliche zu Shapefiles einzulesen und zu verarbeiten.

==Indizes für Shapefiles==\index{Index}\index{Index!Shapefiles}(9)

Mit sogenannten Quadtree-Indizes läßt sich die Bearbeitung von Shapefiles erheblich beschleunigen. Wie solche Indizes für den MapServer erstellt werden, erfahren Sie auf Seite~\pageref{text:tools:shptree}, wo das Werkzeug =shptree= vorgestellt wird. Hier soll nur kurz die dahinter stehende Idee erläutert werden.

In einem Shapfile, das beispielsweise 100 Shapes hat, muß für einen gegebenen Ausschnitt geprüft werden, ob das Shape ganz oder in Teilen in diesem Ausschnitt liegt und demnach angezeigt werden soll. Das geschieht über die Bounding Box eines Shapes, die mit im Shapefile gespeichert ist.

Ein Quadtree-Index folgt dem Gedanken, die Fläche des Shapefiles in vier Teile einzuteilen, und die darin liegenden Shapes in einem Index festzuhalten. Bei einem Zugriff wird zuerst die Fläche gesucht, in der der Ausschnitt liegt, und somit die Anzahl der zu prüfenden Shapes vermindert.

Die einzelnen Flächen lassen sich danach noch einmal in vier Unterflächen aufteilen (und diese wiederum in vier Unterflächen, und so weiter), sodass bei der Darstellung eine baumartige Struktur entsteht.

Die Größe und Lage der einzelnen Flächen muß übrigens nicht genau jeweils ein Viertel der größeren Fläche einnehmen. Die einzelnen Flächen werden nach Anzahl der darin liegenden Shapes gewichtet.

==Graticule-Layer==\index{Graticules}\index{Grids}(10)

Ein Gitternetz kann in einer Karte zur Orientierung wertvoll sein. Leider hat man nicht immer ein entsprechendes Shapefile zur Hand. Abhilfe schaffen sogenannte Graticule-Layer, mit denen sich ein solches Gitternetz einfach definieren läßt.

Betrachten wir einen solchen Layer anhand eines Beispiels:

 <code>
LAYER
NAME "gitternetz"
TYPE LINE
STATUS ON
GRID
END
CLASS
COLOR 0 0 0
LABEL
TYPE BITMAP
SIZE TINY
COLOR 0 0 0
END
END
PROJECTION
"init=epsg:4326"
END
END
</code> 

Zwei Dinge fallen sofort auf. Zuerst einmal sieht man keine =DATA= -Angabe. Brauchen wir an dieser Stelle auch gar nicht, da unser Gitter für jeden Kartenaufruf dynamisch generiert werden soll.

Außerdem findet man eine neue Sektion =GRID= . In dieser Sektion werden die Eigenschaften des Gitters gesetzt.

Der Typ eines Gitterlayers ist =LINE= . Die Gestaltung des Gitters wird wie gewohnt in einer Class vorgenommen, und das Gitter kann beschriftet werden. Die Labels für die Beschriftung erscheinen immer an allen vier Seiten einer Karte. Für TrueType-Fonts empfiehlt sich eine sehr kleine Schriftgröße, da diese Beschriftung sonst sehr schnell aufdringlich wirken kann.

Der =PROJECTION= -Block gibt die Projektion des Gitters an. Der Layer wird dann so behandelt, als würde es sich bei der Datenquelle um ein Shapefile handeln, das in eben dieser Projektion vorliegt. Ohne Projektionsblock erhalten Sie ein einfaches rechteckiges Gitter; mit Projektion ist das Gitter natürlich entsprechend verzerrt.

Beachten Sie, dass die Beschriftung des Gitters immer im Koordinatensystem der Quellprojektion erfolgt. Wenn Sie also beispielsweise den EPSG-Code 4326 als Projektion für Ihren Gitterlayer angeben, so wird dieses Gitter in Gradangaben beschriftet werden, selbst wenn Sie eine Karte mit Gauss-Krüger-Koordinaten erzeugen.

Innerhalb des =GRID= -Blocks können Sie die folgenden Angaben machen, die allesamt nur eine einzelne Zahl als Parameter erwarten:

*=MINSUBDIVIDE= und =MAXSUBDIVIDE= : Jede der Kurven (Linien), aus denen das Gitter besteht, wird als separate Linie behandelt und besteht somit aus einzelnen Punkten. Je mehr Punkte für eine Linie gezeichnet werden müssen, desto mehr Prozessorzeit kostet das offensichtlich. Mit diesen beiden Parametern können Sie festlegen, aus wievielen Punkte eine Linie minimal beziehungsweise maximal zusammengesetzt sein darf. Sind die beiden Werte gleich, bestehen die Linien immer aus genausovielen Punkten wie angegeben.
*=MININTERVAL= und =MAXINTERVAL= : Mit diesen beiden Parameter können Sie ein minimales bzw. ein maximales Intervall zwischen zwei Kurven des Gitters angeben. Die Angabe wird im Koordinatensystem des Gitters gemacht.
*=MINARCS= und =MAXARCS= : Setzt die minimale bzw. maximale Anzahl von Kurven pro Achse. Beachten Sie bitte, dass bei diesen beiden Parametern und den beiden vorhergehenden ''versucht'' wird, den Vorgaben nachzukommen. Sollten die von Ihnen notierten Werte nicht zum gewünschten Ergebnis führen, sollten Sie ein wenig experimentieren, um ein Gefühl dafür zu bekommen, wie sich der Code bei verschiedenen Werten verhält.

=Projektionen=(11)
\index{Projektion}\index{Mapfile!Projektion}(12)

Zuerst die These: die Erde ist eine Kugel. Diese Kugel muß für eine Karte auf eine Ebene abgebildet werden. Das gilt für eine Papierkarte ebenso wie für einen Computerbildschirm. Wenn man jetzt bedenkt, dass es viele verschiedene Ideen gibt, Abbildungen von der Kugel auf die Ebene vorzunehmen, und wenn man dann noch einwirft, dass die Erde ja eigentlich gar keine richtige Kugel ist -- dann ist man in der Welt der Projektionen angekommen, die ebenso faszinierend wie enervierend sein kann.

\begin{figure}
\begin{center}
\mmfig{0.75}{projektion}{Ein und dieselbe Datenquelle in zwei verschiedenen Projektionen. Links EPSG:4326, rechts EPSG:31464.}
\end{center}
\end{figure}

Der Effekt, um den es geht, ist in Abbildung~\ref{projektion} zu sehen. Die rechte Darstellung der Datenquelle verwendet die Geo-Koordinaten der Bundeslandgrenzen (Ellipsoid WGS84). Die rechte Darstellung entspricht einer Projektion in die Ebene nach der Gauss-Krüger-Methode, hier im vierten Meridianstreifen.

Der MapServer verwendet für Projektionen eine eigene Bibliothek (''proj.4'' ) die von Haus aus bereits viele Projektionen kennt. Diese Bibliothek unterstützt aber auch EPSG-Codes~[[http:website:epsg]], die seit Einführung der OGC-Konformität die gängige Art und Weise darstellen, Projektionen im Mapfile zu notieren.

Projektionen interessieren an zwei Stellen: einmal bei der Frage, in welchen Projektionen die Daten vorliegen, und in welcher Projektion die fertige Karte dargestellt werden soll. MapServer ist in der Lage, die Projektion von Vektordaten 'on the fly' vorzunehmen. Dabei können die Daten verschiedener Layer durchaus verschiedener Projektion sein. Mit Unterstützung der Bibliothek GDAL ist MapServer auch in der Lage, Rasterdaten umzuprojizieren; die benötigte Rechenleistung dafür ist jedoch beträchtlich, da in einem Rasterbild jeder einzelne Punkt umprojiziert werden muß.

Mehr zur Bibliothek GDAL erfahren Sie in Anhang~\ref{anhang:formate}, in dem die vom MapServer unterstützten Formate vorgestellt werden.

==Notation==

Projektionen sind, wie bereits angemerkt, an zwei Stellen von Bedeutung: erstens wenn festgestellt werden soll, in welcher Projektion bestimmte Daten vorliegen, zweitens bei der Frage, in welcher Projektion die Karte ausgeliefert werden soll.

Dabei können die Projektionen, in denen die Daten vorliegen, auf Layer-Ebene zugewiesen werden. Jeder Layer kann also in einer eigenen Projektion vorliegen. MapServer ist in der Lage, Vektorlayer auf Anfrage umzuprojizieren. Unter Verwendung des Bibliothek GDAL funktioniert das auch für Rasterdaten. Das Umprojizieren von Rasterdaten ist jedoch derart rechenaufwendig, dass man es in den meisten Fällen vermeiden will.

Die Ausgabeprojektion muß verständlicherweise einheitlich sein, denn die fertige Karte kann schließlich nur in einer bestimmten Projektion vorliegen. Eine Ausnahme bildet ein OGC-konformer MapServer, der verschiedene Projektionen nach außen anbieten und über einen URL-Parameter aufgefordert werden kann, eine dieser Projektionen als Ergebnis zu liefern.

Die Notation von Projektionen geschieht über eine eigene Sektion mit dem Namen =PROJECTION= . In dieser Sektion können Projektionen entweder als eine Liste von Parametern für die Projektionsbibliothek proj.4 eingetragen werden, oder mit EPSG-Codes.

Das erste Beispiel zeigt die 'klassische' Notation anhand der Projektionsbibliothek:

 <code>
PROJECTION
"proj=utm"
"ellps=GRS80"
"zone=15"
"north"
"no_defs"
END
</code> 

Die Art der möglichen Parameter für die Projektionsbibliothek proj.4 entnehmen Sie bitte der Dokumentation dieser Software~[[http:website:libproj]].

Die zweite Möglichkeit erschließt sich durch EPSG-Codes:

 <code>
PROJECTION
"init=epsg:12345"
END
</code> 

12345 ersetzen Sie an dieser Stelle selbstverständlich durch den gewünschten EPSG-Code. Intern greift die Projektionsbibliothek an dieser Stelle übrigens auf eine Tabelle zu, die diese Codes dann auf die "`Original"'-Parameter abbildet. Achten Sie unbedingt darauf, =epsg= tatsächlich in Kleinbuchstaben zu notieren. Unter Windows ist das nicht relevant; entwickeln Sie jedoch unter einem anderen System, oder soll Ihre Anwendung portierbar sein, ist das wichtig.

Die Sektion =PROJECTION= kommt für die gesamte Karte nach dem Header im Mapfile zur Anwendung; für die Layer hat die Sektion natürlich innerhalb der =LAYER= -Sektion zu stehen, allerdings außerhalb etwaiger =CLASS= es, =LABEL= s und allem Anderen, das eine eigene Sektion einleitet.

\subsubsection*{Hinweis}(13)

Man möchte eigentlich meinen, dass die EPSG-Codes in Stein gemeißelt sind. Einmal vergeben, würde sich ein solcher Code nicht mehr ändern.

Leider ist diese Annahme ein Irrtum. Die Vergangenheit hat gezeigt, dass es passieren kann, dass Projektionen um mehrere Stellen in der Liste 'verrutschen' können. Zumindest einige deutsche und teilweise auch österreichische Projektionscodes sind in der Vergangenheit bei einem Versionssprung der Projektionsbibliothek nicht mehr vorhanden gewesen. Die interne Liste für den jeweiligen Release von ''proj.4'' wird scriptgesteuert aus der Access-Tabelle generiert, die man auf der Website der EPSG findet. Änderungen in der Tabelle schlagen also sofort auf die Projektionsbibliothek durch.

Bei unerwarteten Fehlermeldungen nach einem Upgrade der Projektionsbibliothek sollten Sie also prüfen, ob Ihre Projektionscodes noch korrekt sind und diese eventuell anpassen.

Dieses unvorhersehbare Verhalten der EPSG kann natürlich zu haarsträubenden Komplikationen bei kaskadierten WMS-Servern führen, wenn nur einer der Server aktualisiert wird.

==Orthographische Projektion==

\begin{figure}
\begin{center}
\mmfig{0.55}{ortho}{Eine orthographische Projektion stellt die Daten in einem Kreis dar, der einer Aufsicht auf einem Globus ähnlich sieht. Leider ist die Funktion in MapServer noch fehlerhaft.}
\end{center}
\end{figure}

Eine orthographische Projektion sieht aus wie ein Blick auf einen Globus. Falls die fertige Karte einen großen Teil der Welt abdeckt, sehen Sie die fertige Karte als Kreis.

Das kann schick aussehen, leider hat der Code für diese Projektion in MapServer noch den einen oder anderen Bug, die dann auftreten, sobald Features dargestellt werden sollen, die teilweise hinter dem Horizont verschwinden. Dann versucht MapServer immer noch Linien zu ziehen, die dann quer durch das ganze Bild gehen.

Zum Zeitpunkt der Drucklegung war die Darstellung leider immer noch fehlerhaft. Dennoch soll Ihnen ein Überblick über die Theorie nicht vorenthalten bleiben.

Als Zielprojektion im Kopf des Mapfiles definieren Sie eine orthographische Projektion wie folgt:

 <code>
PROJECTION
"proj=ortho"
"ellps=WGS84"
"lat_0=0.0"
"lon_0=0.0"
"x_0=0.0"
"y_0=0.0"
END
</code> 

Dabei sind =lat_0= und =lon_0= die Koordinaten des Punktes, der als Mittelpunkt in der Karte zu sehen sein soll, in Längen- und Breitenangabe. Das ist sozusagen der Punkt, an dem Sie direkt auf den Globus schauen. Die beiden verbleibenden Parameter sind eine Verschiebung, jeweils ein Modifikator auf den Rechts- und den Hochwert des Punktes.

Das Ergebnis sieht dann in etwa so aus, wie Sie es in Abbildung~\ref{ortho} sehen können. Wegen der fehlerhaften Implementation ist die Darstellung von Features, die sich über den Horizont erstrecken, allerdings noch mangelhaft.

Und falls Sie später das Kapitel über MapScript lesen und Anregung für eine Übung suchen sollten, wie wäre es damit: erstellen Sie eine MapScript-Seite, die eine Karte in ortographischer Projektion darstellt. Beim Mausklick in die Karte soll allerdings nicht hinein- oder herausgezoomt werden, sondern eben dieser angeklickte Punkt soll als neuer Bezugspunkt für die Projektion dienen. Der 'Globus' wird also anhand des Klicks 'gedreht'. Viel Spaß dabei =:)=

==Projektionen im realen Einsatz==

Der Autor hat schon von Leuten gehört, die meinten, Projektionen würden die Daten 'verfälschen'. Zu einem gewissen Grad ist das sicherlich richtig; im Grunde genommen handelt es sich aber nur um eine andere Art der Darstellung.

Kartographen sind übrigens nicht die einzigen Menschen, die sich mit Projektionen in die Ebene auseinandersetzen müssen. Eine ganze Industrie in Gestalt der Spiele- und Grafikkartenindustrie lebt mit und von dem Problem, (dreidimensionale) Objekte auf eine plane Fläche (den Computerbildschirm) abzubilden.

Falls Sie in Ihrer Anwendung MapServer Daten ''on the fly'' umprojizieren lassen möchten, sollten Sie sich im Vorhinein über Ihre Zielgruppe Gedanken machen. Menschen könnten es Ihnen durchaus übelnehmen, wenn die Karten im Webbrowser wie in Abbildung~\ref{projektion} links aussehen -- nämlich angeblich 'gequetscht'. Denken Sie immer daran, wass die Benutzer wohl als Darstellung aus ihrem Atlas daheim~[[diercke:2002]] gewohnt sein könnten.

=Schriften=\index{Schriften}\index{Fonts}(14)

MapServer kennt zur Beschriftung von Features zwei Typen von Schriften: Bitmap- und TrueType-Schriften. Während erstere bereits im MapServer `"eingebaut"' sind, sind TrueType-Schriften separate Dateien, die Sie der Anwendung bereitstellen müssen. Hingegen benötigen Bitmap-Schriften keine zusätzliche Vorbereitung, um verwendet zu werden; Sie können direkt mit Abschnitt~15 fortfahren.

Ein weiteres Problem mit TrueType-Schriften können lizenzrechtlicher Natur sein. Ob Sie die Schriftdateien, die Sie für den Gebrauch mit beispielsweise Photoshop gekauft haben, einfach so zur Beschriftung und Veröffentlichung von Karten im Internet verwenden dürfen, müssen Sie individuell mit dem Hersteller der Schriften regeln.

Wie die Symbole für eine Karte werden auch die TrueType-Schriftarten in einer separaten Datei deklariert. Anders als die Symbole für ein Mapfile können die Schriften jedoch nicht alternativ direkt in das Mapfile eingetragen werden; sie müssen immer in einer separaten Datei stehen.

Der Verweis auf eine Schriftendatei erfolgt über das Schlüsselwort ''FONTPATH'' im Header des Mapfiles:

 <code>
...
FONTPATH "fonts/fonts.list"
...
</code> 

Diese Angabe kann sowohl ein absoluter Pfad im System sein, als auch relativ zum Mapfile.

Im Innern ist diese Liste sehr simpel aufgebaut:

 <code>
arial arial.ttf
times times.ttf
...
</code> 

In jeder Zeile steht zuerst ein Alias, gefolgt von mindestens einer Leerstelle (oder einem Tab) und der Name der .ttf-Datei. Das Alias ist ein Name, der im Folgenden im Mapfile verwendet wird, um auf die Schriftart Bezug zu nehmen.

Für Bitmap-Schriften müssen, wie gesagt, keine solche Vorbereitungen getroffen werden.

=Annotationen=
\index{Annotationen}
\index{Beschriftungen}
(15)

Beschriftungen von Layern sind für MapServer wiederum eigene Layer, mit einem eigenen Typ mit dem Namen =ANNOTATION= .

Die Art der Beschriftung (was wann wie beschriftet werden soll und auf welche Art) wird in den Klassen dieses Layers festgelegt. Dadurch erreicht man eine recht hohe Flexibilität, indem man Beschriftungen von Features unabhängig davon darstellen kann, ob das Feature selber zu sehen ist. Und wenn man beides unter den selben Umständen angezeigt haben möchte, verwendet man für beide Layer einfach die gleiche Klassendefinition.

Für eine Oberfläche zur Navigation in der Karte bedeutet das auf der anderen Seite zusätzliche, unerwünschte Komplexität, da die Beschriftungslayer nun unter Umständen durch den Benutzer als eigene Layer an- und abgewählt werden müssen.

Diesen Umstand kann man auf zwei Wegen umgehen. Eine Methode ist, dem Beschriftungslayer den gleichen Namen zu geben, wie dem Layer, der die Daten anzeigt. Dann werden beide Layer über diesen Namen angesprochen. Der zweite Weg ist, beide Layer zu einer =GROUP= zusammenzufassen, über deren Namen man auf beide Layer gleichzeitig zugreifen kann. Mehr über das Gruppieren von Layern erfahren Sie ab Seite~\pageref{text:mapfile:layer:group}

Man könnte auch alle Beschriftungen in einer =GROUP= zusammenfassen, sodass sie sich alle mit einem Mal an- und ausschalten lassen.

Es lassen sich im übrigen nur Vektorlayer beschriften.

Die Notation von Beschriftungslayern sieht wie folgt aus:

 <code>
LAYER
NAME "strassen_annotation"
GROUP "beschriftungen"
TYPE ANNOTATION
...
CLASSITEM "NUMMER"
LABELITEM "NUMMER"
CLASS
...
LABEL
TYPE BITMAP
SIZE NORMAL
COLOR 0 0 0
POSITION CR
PARTIALS TRUE
END
END
END
</code> 

Es werden also diverse Änderungen im Vergleich zu einem dartstellenden Layer vorgenommen. Der Typ des Layers ist =ANNOTATION= .

Das Schlüsselwort =LABELITEM= funktioniert so ähnlich wie =CLASSITEM= . Während letzteres jedoch angibt, anhand welcher Spalte in der ''.dbf'' -Datei die nachfolgenden Classes gefiltert werden sollen, definiert =LABELITEM= die Spalte, aus der der Inhalt für die Beschriftungen geholt werden soll. Auf diese Weise läßt sich also nach einem Kriterium filtern und nach einem anderen beschriften, was die Angelegenheit flexibler gestaltet.

==Die Label-Sektion==\index{Label}\index{Mapfile!Label}

Die eigentliche Definition einer Beschriftung erfolgt dann in den einzelnen Classes. Im obigen Beispiel werden die im MapServer eingebauten Bitmap-Schriften verwendet. Zur genauen Notation von Bitmap- und TrueType-Schriften siehe auch die nächsten beiden Abschnitte.

Wie so häufig kommt erhöhte Flexibilität auch an dieser Stelle auf Kosten größeren Aufwands. Für jede zu beschriftende Klasse muß eine eigene Label-Sektion eingerichtet werden.

Die folgenden Parameter finden in allen Arten von Labeln Verwendung, unabhängig davon, ob es sich um Bitmap- oder TrueType-Beschriftungen handelt:

*=BACKGROUNDCOLOR <red> <green> <blue>= Mit dieser Option bekommt das Label eine Hintergrundfarbe verpaßt; man sieht dann ein Rechteck in dieser Farbe, in dem sich dann das Label befindet. Voreinstellung ist gar keine Farbe.
*=BACKGROUNDSHADOWCOLOR <red> <green> <blue>= Wirft einen Schatten in der angegebenen Farbe um das eben genannte Rechteck. Voreinstellung ist kein Schattenwurf.
*=BACKGROUNDSHADOWCOLORSIZE <x> <y>= Legt den Offset für den genannten Schatten in x- und y-Richtung fest. Voreinstellung in beide Richtungen ist 1.
*=BUFFER <integer>= Definiert einen Abstand, den andere Beschriftungen zu einem Label mindestens haben müssen, um gezeichnet werden zu können. Erhöht die Lesbarkeit bei vielen Beschriftungen, kann aber zu Problemen führen (siehe Abschnitt~16, ''Hinweise'' ).
*=COLOR <red> <green> <blue>= Die Farbe, in der die Schrift gemalt werden soll.
*=OUTLINECOLOR <red> <green> <blue>= Umrißarbe für die Schrift.
*=FORCE <TRUE|FALSE>= Erzwingt das Zeichnen einer Beschriftung. Dadurch werden Einträge wie =BUFFER= ignoriert. Diese Option ist als Vorgabe nicht aktiviert.
*=POSITION=
*=PARTIALS <TRUE|FALSE>= Unter Umständen liegen einzelne Features so ungünstig, dass seine Beschriftung nur teilweise sichtbar wäre. Mit =PARTIALS= wird festgelegt, ob diese teilweise Beschriftungen angezeigt werden sollen.
*=WRAP <zeichen>= Legt ein Zeichen fest, das als Zeilentrenner interpretiert werden soll. Das Ergebsnis sind mehrzeilige Beschriftungen.

Labels lassen sich außer zur Beschriftung auch bei TrueType-Symbolen verwenden; siehe auch Abschnitt~18

==Bitmap-Schriften==\index{Bitmap-Schriften}
\index{Beschriftungen!Bitmap}\index{Annotationen!Bitmap}

Bitmap-Schriften skalieren schlecht und sehen, gelinde gesagt, nicht sonderlich gut aus. Sie benötigen jedoch keinen zusätzlichen Aufwand und sind in jeder MapServer-Installation automatisch vorhanden. Auch benötigen sie wesentlich weniger Rechenzeit.

Wenn Sie die Beschriftung nur um der Beschriftung willen einsetzen möchten und keine besonderen Anforderungen an ihr Aussehen stellen, sind Bitmap-Schriften das, was Sie haben möchten.

Ein =ANNOTATION= -Layer mit Bitmap-Schriften sieht beispielsweise folgendermaßen aus:

 <code>
LAYER
NAME "strassen"
STATUS ON
TYPE ANNOTATION
DATA "strassen"
LABELITEM "NUMMER"
CLASS
LABEL
TYPE BITMAP
SIZE SMALL
COLOR 0 0 0
OUTLINECOLOR 255 255 255
END
END
END
</code> 

Jedes Feature wird hier mit einer kleinen, weiß umrandeten, schwarzen Beschriftung versehen.

Die folgenden Optionen sind nur beim Einsatz von Bitmap-Schriften von Belang:

*=SIZE <TINY|SMALL|MEDIUM|LARGE|GIANT= Diese fünf verschiedenen Größen sind fix, und es gibt keine Zwischengrößen. Experimentieren Sie am besten mit allen herum, um ein Gefühl dafür zu kriegen, wie groß sie im Einsatz sind.

==TrueType-Schriften==\index{TrueType-Schriften}
\index{Beschriftungen!TrueType}\index{Annotationen!TrueType}

TrueType-Schriften skalieren besser als die im MapServer eingebauten Schriftarten und sehen generell besser aus, benötigen jedoch einiges an zusätzlicher Vorbereitung, beispielsweise bei der Installation und weil das Anlegen einer Font-Datei für den MapServer nötig wird. Auch der Aufwand an Rechenzeit ist merklich größer.

Falls Sie jedoch Wert auf qualitativ hochwertige Schriften legen oder gar eine gewisse Stimmung erzeugen möchten -- indem Sie Frakturschriften in den Karten Ihrer mittelalterlichen Rollenspielwelt verwenden, um ein Beispiel zu nennen --, so kommen Sie um TrueType-Schriften nicht herum.

 <code>
LAYER
NAME "strassen"
STATUS ON
TYPE ANNOTATION
DATA "strassen"
LABELITEM "NUMMER"
CLASS
LABEL
TYPE TRUETYPE
FONT "Arial"
SIZE 12
COLOR 0 0 0
OUTLINECOLOR 255 255 255
END
END
END
</code> 

Der Typ des Labels muß natürlich =TRUETYPE= sein. Anstelle eines von fünf festen Strings treten Angaben in Pixeln. Und natürlich muß der Name der Schrift angegeben werden -- dafür wird ein Alias verwendet, der in der Font-Datei definiert worden sein muß (siehe auch Beginn dieser Sektion).

Die folgenden Optionen im Label-Objekt lassen sich nur dann verwenden, wenn TrueType-Schriften zum Einsatz kommen:

*=ANGLE <double>= Eine Winkelangabe in Grad, um die die Beschriftung gedreht werden soll. Kann nur in Linien-Layern benutzt werden. Wird anstatt eines Zahlenwertes =AUTO= verwendet, richtet sich der Text an der Linie aus.
*=ANTIALIAS <TRUE|FALSE>= Schaltet Kantenglättung für Schriften an oder aus.
*=FONT <name>= Name der Schriftart, wie er in der Font-Datei festgelegt worden ist.

==Hinweise==(16)

Automatische Beschriftungen von ebenso automatisch generierten Karten haben einige Tücken, derer man sich bewußt sein sollte, bevor man vom Ergebnis enttäuscht wird.

Angaben wie das zuvor genannte =BUFFER= beispielsweise bewirken, dass diverse Labels gar nicht erst gezeichnet werden. Das kann zum Beispiel zur Folge haben, dass die kleinen Orte um eine große Stadt durchaus beschriftet werden -- und dann aber kein Platz mehr für eine Beschriftung neben der Stadt ist und diese dann in der fertigen Karte ohne auskommen muß.

Zu allem Überfluss können sich die Labels nach dem nächsten Zoom oder gar nur nach einem Pan so verschoben haben, dass besagte Stadt plötzlich eben doch beschriftet ist. Der Benutzer kann sich dann fragen, welch merkwürdige Karte er da vor sich hat.

Es gibt mehrere Möglichkeiten, mit diesem Phänomen umzugehen. Man kann stundenlang mit Schriftgrößen und Zoomstufen herumexperimentieren -- aber der nächste Benutzer wird eben doch die Einstellung finden, an die man nicht gedacht hat.

Sicherlich sinnvoll ist es, mit =MINSIZE= und =MAXSIZE= Maßstäbe festzulegen, ab denen bestimmte Beschriftungen zulässig werden. Features, die unter allen Umständen beschriftet werden sollen, sollten mit =FORCE TRUE= dazu gezwungen werden.

Die korrekte Vorgehensweise bei diesen Phänomen dürfte von Fall zu Fall unterschiedlich sein; auf alle Fälle sollte man sich aber der Existenz des Problems bewußt und darauf vorbereitet sein, es eventuell in Angriff nehmen zu müssen, falls jemand darauf stößt.

=Symbole=\index{Symbole}(17)

Symboldateien definieren Darstellungen, die von den normalen Formen abweichen, die also mehr sind als simple Striche für Polygonumrandungen oder Linienvektoren.

Notiert werden Symbole entweder direkt im Mapfile als einzelne Sektionen nach dem Header. Oder aber in einer eigenen Datei, genannt =SYMBOLSET= , die im Header deklariert wird -- siehe auch Seite~\pageref{text:mapfile:header}. Begonnen wird ein Symbol mit =SYMBOL= , abgeschlossen wird es mit =END= .

Farben werden für Symbole nicht in den Symbol-Sektionen definiert, sondern in den Classes, die die Symbole verwenden.

MapServer kennt die folgenden Arten von Symbolen, die in Symboldateien definiert werden können, und die in einer Symbol-Sektion über =TYPE= deklariert werden:

*=VECTOR= Ein oder mehrere Vektoren, die aneinandergefügt ein Symbol ergeben. Dadurch können Rechtecke, Dreiecke und andere geometrische Formen realisiert werden.
*=ELLIPSE= Ellipsen werden über zwei Radien definiert. Sind beide Werte gleich, entsteht ein Kreis. Ergänzt die geometrischen Formen, die mit =VECTOR= möglich sind.
*=PIXMAP= Linien können mit (möglichst kleinen) Bilddateien gezogen werden. Ebenso können Polygone mit solchen Bilder ausgefüllt werden. Das Format dieser Bilder muß vom MapServer unterstützt werden. Das schließt beispielsweise ''.gif'' -Bilder aus, wenn es sich um einen MapServer handelt, der ''.png'' -Bilder generiert.
*=TRUETYPE= Einzelne Symbole aus TrueType-Schriften können zur Annotation von Features in Karten benutzt werden. Es gibt einige TrueType-Zeichensätze, die speziell für die Verwendung in Karten erstellt worden sind.

Ferner können sogenannte Overlaysymbole für Linien definiert werden, bei denen ein Liniensymbol über ein anderes gelegt wird; mehr dazu weiter unten.

Die folgenden Parameter können für Symbole gesetzt sein, wenn es sich nicht um TrueType-Symbole handelt.

*=NAME <name>= Name des Symbols. Sollte immer gesetzt sein, falls man seine Symbole nicht über ihre Nummer innerhalb der Symboldatei referenzieren möchte -- was spätestens dann für Unheil sorgen wird, wenn man zusätzliche Symbole mitten in der Datei einfügt.
*=FILLED <TRUE|FALSE>= Das Symbol soll gefüllt sein.
*=PIXMAP <dateiname>= Eine Bilddatei, die als 'Pinsel' verwendet werden soll. Kommt nur für Symbole vom Typ =PIXMAP= zur Anwendung.
*=STYLE= Eine eigene Sektion innerhalb eines Symbols, die einen Stil für Linien-Symbole definiert. Es handelt sich um einen einzelnen Punkt (referenziert als =SYMBOL 0= ), der je nach Stil an- und wieder ausgeschaltet wird. Zur Verdeutlichung ein Beispiel: <code> STYLE 2 3 2 4 END </code> Mit diesem =STYLE= werden zwei Pixel einer Linie gezeichnet, dann drei Pixel Pause gemacht, dann werden wieder zwei Pixel gezeichnet, woraufhin wieder vier Pixel ausgelassen werden. Danach geht das ganze wieder von vorne los.
*=POINTS= Dies ist eine eigene Sektion innerhalb eines Symbols und beschreibt ein Symbol über Vektoren.
*=TRANSPARENT <index>= Der Index der Farbe in einer Farbpalette, die bei einem Pixmap-Symbol transparent geschaltet werden soll.

\subsubsection*{Points}

Vektor-Symbole werden über eine eigene Sektion innerhalb eines Symbols definiert, die mit =POINTS= beginnt, mit =END= abgeschlossen wird und Paare von Zahlen enthält; Punkte eines Vektors eben.

Ein Beispiel für ein Vektor-Symbol:

 <code>
SYMBOL
TYPE VECTOR
NAME "dreieck"
POINTS
1 1
3 3
3 1
1 1
END
END
</code> 

Dieses Symbol beschreibt ein Dreieck. Beachten Sie, dass Sie für einen geschlossenen Kantenzug immer den ersten Punkt noch einmal als letzten Punkt einfügen müssen.

Punkte, bei denen beide Koordinaten negativ sind, werden als Trenner betrachtet. Dadurch können Sie beispielsweise Kreuze und ähnliches realisieren, also Symbole, die aus mehreren Segmenten bestehen.

==TrueType-Symbole==\index{TrueType!Symbole}\index{Symbole!TrueType}(18)

TrueType-Schriften als Symbole funktionieren, indem man einzelne Zeichen aus der Schriftart herausgreift, und damit dann einzelne Punkte annotiert, oder das Symbol an einer Linie immer wieder wiederholt.

Beachten Sie, dass Unterstützung für TrueType-Schriften in den MapServer kompiliert sein muss, um diese Art von Beschriftung benutzen zu können.

Die folgenden Parameter in einer Symbol-Sektion kommen nur zum Tragen, wenn es sich um ein TrueType-Symbol handelt:

*=ANTIALIAS <FALSE|TRUE>= Gibt an, ob auf dem Symbol ein Antialiasing stattfinden soll.
*=CHARACTER <index>= Die Nummer des Zeichens innerhalb der TrueType-Datei, das als Symbol benutzt werden soll.
*=FONT <name>= Alias der TrueType-Schriftart, die für das Symbol benutzt werden soll. Dieser Alias muß im =FONTSET= definiert sein.
*=GAP= Der Abstand zwischen zwei TrueType-Symbolen. Kommt nur für Linien zur Anwendung.

Als Beispiel für ein TrueType-Symbol soll an dieser Stelle die Schriftart WebDings herhalten:

 <code>
SYMBOL
NAME "haus"
TYPE TRUETYPE
FONT "webdings"
ANTIALIAS TRUE
CHARACTER "G"
END
</code> 

Dieses Beispiel greift aus der Schriftart WingDings das Zeichen heraus, das ein kleines Häuschen darstellt. Sie könnten damit beispielsweise Ihre Ferienhäuser in der Karte markieren.

Die Notation =\&\#71;= kennen Sie vielleicht aus HTML-Seiten, wo einzelne Zeichen auf diese Weise notiert werden können. 71 ist die Position des Zeichens in der TrueType-Datei; falls Sie die Position nicht kennen, müssen Sie raten oder ein Programm zurate ziehen, dass Ihnen die einzelnen Zeichen darstellt und deren Position angibt.

==Pixmap-Symbole==

Pixmaps lassen sich entweder an Linien entlangziehen oder zum Füllen von Fläche verwenden. Natürlich kann man mit ihnen auch einzelne Punkte annotieren. Damit können Sie beispielsweise Ihr Firmenlogo an verschiedenen Filialen einblenden:

 <code>
SYMBOL
NAME "logo"
TYPE PIXMAP
IMAGE "firmenlogo.png"
TRANSPARENT 0
END
</code> 

==Overlay-Symbole==\index{Symbole!Overlay}\index{Overlaysymbole}

Overlaysymbole werden separat in den Klassen eines Layers definiert. Dabei werden ganz einfach die als Overlay deklarierten Symbole über die 'normalen' Symbole gelegt. Anwendung findet so etwas zum Beispiel bei Autobahnen:

 <code>
CLASS
...
SYMBOL 0
SIZE 4
COLOR 0 0 0
OVERLAYSYMBOL 0
OVERLAYSIZE 2
OVERLAYCOLOR 255 0 0
END
</code> 

Das Resultat ist eine vier Pixel breite schwarze Linie, auf der sich eine zwei Pixel breite rote befindet. Anders formuliert: eine zwei Pixel breite rote Linie mit einem schwarzen Rand.

Auf diese Weise kann man beispielsweise auch gestrichelte Linien auf breite Linien legen und damit Mittelstreifen symbolisieren etc.

Es gibt die folgenden Optionen für Overlaysymbole:

*=OVERLAYSYMBOL= : Definiert wie =SYMBOL= , welches Symbol verwendet werden soll.
*=OVERLAYBACKGROUNDCOLOR= : Hintergrundfarbe des Overlaysymbols
*=OVERLAYCOLOR= : Farbe des Symbols
*=OVERLAYMINSIZE= : Minimaler Maßstab, bei dem das Overlaysymbol angezeigt werden soll.
*=OVERLAYMAXSIZE= : Maximaler Maßstab, bei dem das Overlaysymbol angezeigt werden soll.
*=OVERLAYOUTLINECOLOR= : Umrandungsfarbe für das Overlaysymbol
*=OVERLAYSIZE= : Größe des Overlaysymbols.

Diese Angaben sind also allesamt äquivalent zu den Angaben in normalen Symbolen ohne den Zusatz ''OVERLAY'' .

Mit der Ankunft des =STYLE= -Objekts und der entsprechenden Möglichkeit, mehr als zwei Symbole übereinander zu legen, werden die Overlayparameter allerdings wohl ihre Daseinsberechtigung verlieren. Mehr dazu siehe Abschnitt~6.

==Beispiele==

Erfahrungsgemäß bereiten Symbole gerade dem Einsteiger Schwierigkeiten. Daher sehen wir uns einige Beispiele an, die wir nach und nach zu komplexeren Symbolen ausbauen.

Für das einfachste aller Symbole, einen Punkt, wird wohl kein Screenshot benötigt:

 <code>
SYMBOL
NAME "punkt"
TYPE ELLIPSE
POINTS
1 1
END
FILLED TRUE
END
</code> 

Dieses Symbol können Sie nun in einem Layer verwenden, und dann dementsprechend die Dicke der Linie mit =SIZE= festlegen.

''Hinweis'' : Beachten Sie bitte, dass es keinen Unterschied macht, ob Sie =1 1= oder =2 2= in diesem Beispiel schreiben. Es handelt sich hier um Vektoren, dabei spielt der Skalar vor den eigentlichen Koordinaten keine Rolle. =2 2= ist also das gleiche wie zweimal =1 1= , und dieses 'zweimal' wird verworfen. Wichtig ist das Verhältnis der Zahlen zueinander. Wenn Sie also eine Ellipse haben wollen, die doppelt so breit wie hoch ist, schreiben Sie =2 1= . Sie könnten auch =6 3= schreiben, aber dadurch würde die Ellipse in der Karte nicht größer. Die Darstellungsgröße in der Karte wird über den Parameter =SIZE= in der entsprechenden Class geregelt.

Das wichtigste Gestaltungselement bei Linien ist die Möglichkeit, Abstände auf der Linie zu bestimmen. Damit lassen sich zum Beispiel gepunktete (''dotted'' ) oder gestrichelte (''dashed'' ) Linien realisieren. Ein Beispiel für ein Punkt-Symbol für eine Linie gestrichelte und gepunktete Linie:

 <code>
SYMBOL
NAME "funky"
TYPE ELLIPSE
POINTS
1 1
END
FILLED TRUE
STYLE 2 2 1 1
END
</code> 

Dieses Symbol entspricht dem letzten, mit dem Unterschied, dass hier ein =STYLE= verwendet wird. Die Angabe bedeutet, dass die ersten zwei Pixel des Linienzuges gezeichnet werden sollen, die nächsten beiden dann wieder nicht; danach wird ein Pixel gesetzt, der folgende dann wieder nicht. Es wird also immer die bezeichnete Anzahl von Pixeln gesetzt und dann wieder nicht gesetzt. Danach fängt das ganze wieder von vorne an. Beachten Sie bitte, dass die hier benutzte =STYLE= -Eigenschaft nichts mit dem Style-Objekt zu tun hat, wie es weiter vorne beschrieben worden ist.

Auf Beispiele für Overlaysymbole soll hier nicht eingegangen werden, da diese Methode veraltet ist. Stattdessen sollten Style-Objekte in den Classes benutzt werden.

\begin{figure}
\begin{center}
\mmfig{0.65}{symbols-star}{Städte, markiert mit einem sternförmigen Vektorsymbol.}
\end{center}
\end{figure}

Falls Sie mal ein komplexeres Symbol sehen wollen, schauen Sie sich die Sternchen in Abbildung~\ref{symbols-star} an. Die Sterne kommen folgendermaßen zustande:

 <code>
SYMBOL
NAME "stern"
TYPE VECTOR
FILLED TRUE
POINTS
0 .375
.35 .375
.5 0
.65 .375
1 .375
.75 .625
.875 1
.5 .75
.125 1
.25 .625
END
END
</code> 

Es handelt sich also um ein Vektorsymbol, das aus zehn Punkten besteht. Sie können sich beim Entwurf eigener Symbole das ganze auf Karo- oder Millimeterpapier aufmalen und dann die Koordinaten ablesen. Der Ursprung für Ihr Koordinatensystem muß in der linken oberen Ecke liegen. Beachten Sie, dass der höchste Wert in den Koordinaten der Punkte =1= ist. Sie könnten die auch alle Werte beispielsweise mit zwei multiplizieren, und es würde keinen Unterschied machen. Das ist der Effekt der Vektorrechnung, der weiter oben erläutert ist.

\subsubsection*{Markierungen für Gefälle}

Insbesondere während Schulungen wird der Autor gerne gefragt, wie es sich mit der Gestaltung von Höhenlinien verhielte; dabei möchte man beispielsweise in der abfallenden Richtung einer Höhenlinie in regelmäßigen Abständen einen kleinen, parallel zur Linie verlaufenden Strich anbringen, um die Richtung des Gefälles anzuzeigen.

Dazu muß leider gesagt werden, dass diese Art der Gestaltung insbesondere bei Shapefiles ''nicht'' möglich ist, da Shapefiles keine Topologie oder eine Richtungsinformation speichern. Zwar werden Sie GIS-Programme sehen, bei denen sich eine solche Gestaltung vornehmen läßt. Allerdings speichert die betreffende Software dann eine entsprechende Information über die Laufrichtung der Shapes separat ab. Diese Möglichkeit ist MapServer wegen seiner rein darstellerischen Fähigkeiten verschlossen.

=Maßstäbe=(19)
\index{Maßstab}\index{Scalebar}\index{Mapfile!Maßstab}\index{Mapfile!Scalebar}

Maßstäbe setzen die Größen auf der Karte in eine Relation zur Realität. Dieser Zusammenhang wird einem am Computerbildschirm jedoch zum Verhängnis.

Man sollte nicht auf die Idee kommen, einen Pixelmaßstab auf dem Bildschirm auszumessen, und etwa zu sagen: "`Ah, 10 Pixel sind 100 Meter, und 10 Pixel sind 0.5 Zentimeter, also sind 0.5 Zentimeter 100 Meter."' Ein Maßstab auf dem Bildschirm steht ausschließlich in Relation zur angezeigten Karte, nicht zur realen Welt, da sich Pixel nicht in Zentimeter umrechnen lassen, sondern stets von der Größe des Bildschirms und der verwendeten Auflösung abhängig sind.

Wenn ein Maßstab für 10 Pixel in der Karte 100 Meter in der Realität angibt, dann sind diese zehn Pixel bei 1280x1024 Pixeln Auflösung auf einem 19 Zoll Bildschirm wesentlich kleiner als bei einer Auflösung von 800x600 Pixeln auf einem 14 Zoll Bildschirm.

MapServer geht bei Maßstabsangaben (=SCALE= ) immer von <math>\frac{1}{72}</math> inch pro Pixel aus. Dieser Wert kann allerdings bestenfalls als vage Annäherung betrachtet werden. Bei =SCALE= handelt es sich immer um den Kehrwert eines Maßstabes. Wenn Sie den Maßstab also beispielsweise als 1:20000 kennen, ist =SCALE= gleich 20000.

Bei den Beschriftungen für Maßstäbe im MapServer beachten Sie bitte, dass MapServer bisher noch keinen Gebrauch von TrueType-Schriften an dieser Stelle macht.

Die Sektion für Maßstäbe im Mapfile wird mit =SCALEBAR= eingeleitet. Sie darf nicht innerhalb einer anderen Sektion stehen und muss nach dem Header stehen. Die folgenden Parameter sind für diese Sektion bekannt:

*=BACKGROUNDCOLOR <red> <green> <blue>= Die Hintergrundfarbe für den Scalebar, ''nicht'' für das komplette Bild, das den Scalebar ausmacht.
*=TRANSPARENT <ON|OFF>= Schaltet Transparenz für den Hintergrund des Scalebars ein oder aus. Voreingestellt ist der Hintergrund nicht transparent.
*=IMAGECOLOR <red> <green> <blue>= Die Hintergrundfarbe für das Bild, in dem sich der Scalebar befindet.
*=COLOR <red> <green> <blue>= Die Farbe, in der der Scalebar gemalt werden soll.
*=INTERLACE <TRUE|FALSE>= legt fest, ob der fertige Maßstab interlaced sein soll.
*=SIZE <x> <y>= Breite des Scalebars in Pixeln. Das ist nicht die Größe des fertigen Bildes, sondern nur des Maßstabs im Bild. Auch Beschriftungen werden hier noch nicht einberechnet.
*=INTERVALS= Anzahl der Intervalle auf dem Maßstab. Voreinstellung ist 4.
*=UNITS <feet|inches|kilometers|meters|miles>= Die Einheit, in der der Maßstab beschriftet sein soll. Voreinstellung ist Meilen. Gradangaben sind übrigens keine sinnvollen Einheiten für einen Maßstab. Voreinstellung ist =miles= .
*=OUTLINECOLOR <red> <green> <blue>= Umrissfarbe für die einzelnen Intervalle des Maßstabs. Soll keine Umrißfarbe verwendet werden, reicht als Wert auch =-1= .
*=STYLE <0|1>= Es gibt zwei verschiedene Styles. Style =1= ist im wesentlichen ein horizontaler, beschrifteter Strich, während Stil =0= in weiße und schwarze Sektionen unterteilt ist.
*=STATUS <ON|OFF|EMBED>= Schaltet den Maßstab an oder aus. Mit =EMBED= wird der Maßstab angeschaltet und in die fertige Karte eingebettet.
*=POSITION <ul|uc|ur|ll|lc|lr>= Bei einem in die Karte eingebetteten Maßstab wird dieser an der angegebenen Position dargestellt. In der Tabelle in der PHP MapScript-Referenz, die auf Seite~\pageref{tab:ref:mapscript:const} beginnt, finden Sie eine Erklärung der möglichen Werte.
*=POSTLABELCACHE <TRUE|FALSE>= Wird nur für Maßstäbe verwendet, die in die Karte eingebettet sind. Der Maßstab wird dann erst in die Karte eingefügt, nachdem alle Labels in der Karte gezeichnet worden sind. Voreinstellung ist =FALSE= .
*=LABEL= An dieser Stelle wird ein separates =LABEL= -Objekt eingefügt, das für die Beschriftung des Maßstabs zuständig ist. Bisher können in Maßstäben keine TrueType-Schriften verwendet werden.

=Legenden=
\index{Legende}\index{Mapfile!Legende}

Legenden erklären die in der Karte verwendeten Symbole und Zeichen. Ohne eine Legende ist eine Karte prinzipiell ohne Inhalt, da man ohne sie den Linien, Farben usw. keine Bedeutung zuordnen kann.

MapServer ist in der Lage, konfigurierbare Legenden automatisch zu generieren. Diese Legenden können dann auf die bekannte Weise über Template-Tags in das Layout der Applikation eingebunden werden.

Neben den klassischen Bitmap-Legenden (die gesamte Legende ist ein einziges Bild, das in eine HTML-Seite eingebunden wird), gibt es seit der Version~{3.6} auch HTML-Legenden, die über Templates kleine HTML-Abschnitte erzeugen.

==Die klassische MapServer-Legende==

Diese Art von Legende ist ein fertiges Bild, das vom MapServer generiert wird. Auf die Gestaltung dieser Legende hat man nicht so viel Einfluss wie bei der HTML-Legende (siehe weiter unten).

Die Sektion für Legenden im Mapfile wird mit =LEGEND= eingeleitet. Sie darf nicht innerhalb einer anderen Sektion vorkommen und muß nach dem Header stehen. Die folgenden Parameter sind für diese Sektion bekannt:

\begin{figure}
\begin{center}
\mmfig{0.35}{legende}{Die drei Vektorlayertypen in einer klassischen MapServer-Legende: Punkte, Linien und Polygone}
\end{center}
\end{figure}

*=IMAGECOLOR <red> <green> <blue>= Hintergrundfarbe für die fertige Legende
*=TRANSPARENT <ON|OFF>= Schaltet Transparenz für den Hintergrund der Legende ein oder aus. Voreingestellt ist der Hintergrund nicht transparent.
*=OUTLINECOLOR <red> <green> <blue>= Umrissfarbe für die Kästchen, die die Symbole in der Legende umranden.
*=KEYSIZE <x> <y>= Breite und Höhe der Symbole in der Legende in Pixeln. Vorgabe ist 20x10.
*=KEYSPACING <x> <y>= Horizontaler und vertikaler Abstand der Symbole bzw. der Beschriftungen zueinander. Vorgabe ist 5 und 5.
*=STATUS <ON|OFF|EMBED>= Schaltet die Legende an oder aus. Mit =EMBED= wird die Legende angeschaltet und in die fertige Karte eingebettet.
*=POSITION <ul|uc|ur|ll|lc|lr>= Bei einer in die Karte eingebetteten Legende wird diese an der angegebenen Position dargestellt. In der Tabelle in der PHP MapScript-Referenz, die auf Seite~\pageref{tab:ref:mapscript:const} beginnt, finden Sie eine Erklärung der möglichen Werte.
*=INTERLACE <TRUE|FALSE>= Ob das Bild interlaced sein soll.
*=POSTLABELCACHE <TRUE|FALSE>= Wird nur für Legenden verwendet, die in die Karte eingebettet sind. Die Legende wird dann erst in die Karte eingefügt, nachdem alle Labels in der Karte gezeichnet worden sind. Voreinstellung ist =FALSE= .
*=LABEL= An dieser Stelle wird ein separates =LABEL= -Objekt eingefügt, das für die Beschriftung des Maßstabs zuständig ist. Bisher können in Maßstäben keine TrueType-Schriften verwendet werden.
*=TEMPLATE= Definiert ein Template, das für HTML-Legenden verwendet werden soll. Siehe den folgenden Abschnitt über HTML-Legenden.

In Abbildung \ref{legende} kann man sehen, wie Legenden für verschiedene Arten von Vektorlayern aussehen. Polygone werden durch ein Rechteck dargestellt, das gegebenenfalls eine Füllfarbe hat. MapServer bedient sich an dieser Stelle bei den Angaben im Mapfile. Punktlayer werden durch einen (wenig überraschend) Punkt dargestellt, während Linienlayer eine kleine gezackte Linie bekommen.

==HTML-Legenden==\index{HTML-Legenden}

Als Alternative zu den normalen .gif- beziehungsweise .png-Bildern, die als Legenden generiert werden, gibt es für die CGI-Version des MapServers noch die Möglichkeit, eigene Legenden über HTML-Templates zu gestalten. Die fertige Legende wird dabei weiterhin an der Stelle im Haupt-Template eingefügt, an der das Schlüsselwort =[legend]= steht.

Interessant wird eine HTML-Legende dann, wenn man in die kleinen Bruchstücke von HTML auch Teile des Formulars zur Navigation in der Karte einfügt -- später mehr dazu.

Im LEGEND-Block des Mapfiles kann ein TEMPLATE definiert, etwa folgendermaßen:

 <code>
LEGEND
...
TEMPLATE "legend.html"
END
</code> 

\subsubsection*{Aufbau des Templates}

Innerhalb eines Templates können drei verschiedene Blöcke definiert werden: für Groups, Layers und Classes. Diese Begriffe folgen den Bedeutungen im Mapfile. Es kann also HTML-Code für Gruppen von Layern generiert werden, für die Layer in diesen Gruppen und dann für jede einzelne Class in diesen Layern wiederum eigener Code. Dieser Aufbau eignet sich besonders für den Aufbau in HTML-Tabellen.

Alle Inhalte der Templatedatei, die sich außerhalb der möglichen Blöcke befinden werden schlicht ignoriert und eignen sich somit dafür, Kommentare einzufügen, die später in der fertigen HTML-Seite nicht erscheinen sollen. Für Kommentare innerhalb der Blöcke müssen selbstverständlich HTML-konforme Kommentare benutzt werden, die mit == abgeschlossen werden.

Für gewöhnlich werden mit Groups- und Layerblöcken Kopfzeilen für HTML-Bereiche definiert, in denen dann die einzelnen Classes der Reihe nach aufgelistet werden.

\subsubsection*{Groups}

Mit der Verwendung eines solchen Blocks legt man die Erzeugung von Legenden fest, in denen Layer gruppiert dargestellt werden, und zwar anhand ihrer Gruppierung im Mapfile. Wird eine Groups-Sektion verwendet, werden alle Gruppierungen als solche in der Legende dargestellt. Möchte man keine Gruppierung von Layern in der Legende, verwendet man diesen Block einfach nicht.

Wird dieser Block definiert, erscheinen Layer nicht in der Legende, die zu keiner Gruppe gehören, und ebensowenig sind deren Classes zu sehen.

Mit =[leg_group_html]= wird ein solcher Block eingeleitet, und mit einem entsprechenden =[/leg_group_html]= wieder abgeschlossen.

Die folgenden Tags können in einem Group-Block erscheinen:

*=[leg_group_name]= : Gibt den Namen der Gruppe aus.
*=[leg_icon <width=X> <height=Y>]= : Steht für das erzeugte Icon. Der erzeugte Text ist der URL zu diesem Icon. Im Kontext einer Group gibt dieser Tag das Icon für den ersten Layer in der Group zurück. Die beiden Parameter =width= und =height= sind optional und verändern die Breite und die Höhe des fertigen Icons.
*=[metadata name=<feld>]= : Ist der MapServer über entsprechende Einträge im Mapfile OGC-konform ausgelegt, können an dieser Stelle entsprechende Metadaten ausgegeben werden. Mehr zu OGC-konformen Mapservern gibt es in Kapitel~\ref{text:ogc} zu erfahren. Auch andere Metadaten aus der Web-Sektion, wie Sie in Abschnitt~21 beschrieben sind, lassen sich hier einfügen.

\subsubsection*{Layers}

Analog zu Groups wird mit =[leg_layer_html]= ein Block für einen Layer in der HTML-Legende eingeleitet und mit =[/leg_layer_html]= wieder abgeschlossen. Im startenden Tag können allerdings noch einige zusätzliche Parameter übergeben werden:

*=order_metadata=<schlüssel>= In Abschnitt~21 haben Sie erfahren, dass Sie in Layern beliebige Metadaten in einem eigenen Block speichern können. Anhand solcher Einträge können Sie nun die Reihenfolge der Layer in der HTML-Legende kontrollieren. Anschaulich: <code> LAYER ... METADATA legendenposition 2 END ... END </code> Haben Sie ein jedem Layer eine solche Klassifizierung, können Sie in der HTML-Legende die Sortierung kontrollieren mit: <code> [leg_layer_html order_metadata=legendenposition] ... [\leg_layer_html] </code> 
*=opt_flag=<wert>= Dieser Wert kontrolliert die Verhaltensweise dieses Layerblocks. Es handelt sich um eine Bitmaske, d.h. für eine Kombination der folgenden Optionen addieren Sie die entsprechenden Werte aufeinander auf. Sie werden immer eine eindeutige Zahl erhalten. Die Werte sind:
*
*=1= Zeigt den Layer in der Legende an, auch wenn sich der gezeigte Ausschnitt außerhalb des Layers befindet. Dieses Verhalten ist nicht voreingestellt.
*
*=2= Zeigt den Layer in der Legende an, auch wenn sein =STATUS= auf =OFF= gesetzt ist. Dieses Verhalten ist nicht voreingestellt.
*
*=4= Zeigt den Layer in der Legende an, auch wenn sein =TYPE= auf =QUERY= gesetzt ist und daher nur befragt werden kann, aber nicht in der Karte erscheint. Dieses Verhalten ist nicht voreingestellt.
*
*=8= Zeigt den Layer in der Legende an, auch wenn sein =TYPE= auf =ANNOTATION= gesetzt ist und daher nur Beschriftungen darstellt. Dieses Verhalten ist nicht voreingestellt. Möchten Sie beispielsweise die ersten beiden Optionen zulassen, setzen Sie =opt_flag= auf <math>1+2=3</math>. Selbstverständlich können in einem Layer-Block in der Legende eigene Tags verwendet werden:
*
*=[leg_layer_name]= Fügt den Namen des Layers an dieser Stelle ein.
*
*=[leg_icon width=<breite> height=<höhe>]= Fügt den URL eines automatisch generierten Legenden-Icons ein, wie man es auch aus der klassischen MapServer-Legende kennt. Die Breiten- und Höhenangaben erfolgen in Pixeln und sind optional. Wenn ein Layer mehrere Classes aufweist, wird ein Icon für die erste Class im Layer generiert.
*
*=[metadata name=<feld>]= Fügt beliebige Metadaten aus der entsprechenden Sektion des Layers ein -- siehe auch weiter oben.

\subsubsection*{Classes}

Und natürlich kommen auch die Classes in HTML-Legenden zu ihrem Recht. Sie werden mit =[leg_class_html]= eingeleitet und am Ende mit =[/leg_class_html]= wieder abgeschlossen.

Ebenso wie die Blöcke für Layer kennen auch die Blöcke für Classes den Parameter =opt_flag= . Wenn er verwendet wird, wird er auch mit den gleichen Parametern gefüttert wie sein Pendant im Layer-Block.

Bitten beachten Sie, das Classes ohne einen =NAME= nicht in HTML-Legenden auftauchen werden.

Sie können die folgenden Tags innerhalb eines Class-Blockes in HTML-Legenden verwenden:

*=[leg_class_name]= Der Name der Klasse. Jede Klasse, die überhaupt in der Legende auftauchen soll, benötigt einen Namen.
*=leg_icon width=<breite> height=<höhe>= Das Legenden-Icon für die Class, wie im Layer beschrieben.
*=[metadata name=<feld>]= Fügt beliebige Metadaten aus der entsprechenden Sektion der Class ein; siehe auch weiter oben.

\subsection*{Konditionale in HTML-Legenden}\index{HTML-Legenden!Konditionale}

Konditionale sind Wenn-Dann-Anweisungen. Aus einer Programmiersprache wie C kennt man das unter der folgenden Notation:

 <code>
if (<bedingung> {
... hier passiert etwas ...
}
else {
... hier passiert etwas anderes ...
}
</code> 

Solche Konditionale lassen sich auch in HTML-Legenden nutzen, etwa um Dinge nur unter bestimmten Bedingungen einzublenden. Es gibt eine gemeinsame Notation, aber für jeden möglichen Block (Group, Layer und Class) eigene Eigenschaften, die abgefragt werden können.

Um es ein wenig genauer zu nehmen: es handelt sich weniger um eine Wenn-Dann-Anweisung, als vielmehr um ein reines Wenn. Ein ''else'' ist nicht implementiert.

Notiert werden Konditionale folgendermaßen:

 <code>
[if name=<feld> oper=<operator> value=<wert>] ... [/if]
</code> 

Das heißt soviel wie: Vergleiche =feld= dahingehend, ob es in der Beziehung =oper= zum Wert =wert= steht. Wenn das der Fall ist, füge den Block bis zum =[/if]= ein.

Da das reichlich abstrakt ist, hier ein Beispiel:

 <code>
[leg_layer_html]
[if name=layer_type oper=eq value=2]
[leg_layer_name]
[/if]
[/leg_layer_html]
</code> 

In diesem Layer-Block wird der Name des Layers immer dann ausgegeben, wenn sein Typ gleich 2 ist. Der Typ 2 ist nur im Kontext von Layern definiert: Sie erfahren weiter unten, welche Werte wofür stehen.

Das =eq= steht für ''equal'' und bedeutet 'gleich'. Daneben gibt es noch =neq= (ist nicht gleich), =isset= (hat überhaupt einen Wert) und =isnull= (ist leer). Die Voreinstellung ist =eq= . Wenn man diesen Operator verwenden möchte, kann man den Teil mit =oper== auch weglassen.

\subsubsection*{Groups}

Die folgenden Konditionale können als =name= in Group-Blöcken in HTML-Legenden benutzt werden:

*=group_status= Der Status einer Group ist gleich dem =STATUS= des ersten Layers in der selben. Als Werte kommen in Frage: =0= für =OFF= , =1= für =ON= und =2= für =DEFAULT= .
*=<metadata>= Jeder Metadaten-Eintrag in der Web-Sektion läßt sich als Wert für ein Konditional benutzen.

\subsubsection*{Layers}

Die folgenden Konditionale können als =name= in Layer-Blöcken in HTML-Legenden benutzt werden:

*=layer_name= Der Name des Layers.
*=layer_group= Der Name der Group, in dem sich der Layer befindet.
*=layer_status= Der Status des Layers. Als Werte kommen in Frage: =0= für =OFF= , =1= für =ON= und =2= für =DEFAULT= .
*=layer_type= Der Typ des Layers. Infrage kommen: =0= für =POINT= . =1= für =LINE= , =2= für =POLYGON= , =3= für =RASTER= . =4= für =ANNOTATION= und =5= für =QUERY= .
*=<metadata>= Jeder Metadaten-Eintrag aus der Layer- wie aus der Web.Sektion läßt sich als Wert für ein Konditional benutzen.

\subsubsection*{Classes}

Schließlich bleiben noch die Konditionale, die als =name= in Class-Blöcken in HTML-Legenden benutzt werden können. Um genau zu sein, sind die Werte hier vollständig mit denen im Layer-Block identisch, sodass sich eine Aufzählung erübrigt.

\subsection*{Hinweise}

Für HTML-Legenden benötigen Sie mindestens die Version 3.5.1 des Mapervers.

Der 'traditionelle' =[legend]= -Block liefert den URL eines Bildes zurück, wohingegen HTML-Legenden (wenig überraschend) Blöcke von HTML zurückliefern.

Wenn der HTML-Legendenmodus über die aufrufende URL für den MapServer angegeben wird, aber kein Template im Mapfile für die Legende definiert ist, wird weiterhin ein Bild erzeugt.

\subsection*{Beispiel}

Ein Beispiel soll erhellen, wie man die Macht von HTML-Legenden ausschöpfen kann. Betrachten Sie die folgenden Zeilen, die ein Ausschnitt aus einem Legenden-Template sind:

 <code>
[leg_layer_html opt_flag=3]
<tr>
<td>
<input type="checkbox" name="layer"
value="[leg_layer_name]" [[leg_layer_name]_check]>
</td>
<td><img src="[leg_icon width=18 height=12]" align="center"></td>
<td>[leg_layer_name]</td>
</tr>
[/leg_layer_html]
</code> 

Das Ergebnis ist in Abbildung~\ref{mapfile-legende-html} zu sehen.

Der Block definiert, wie Legenden für die im Mapfile vorhandenen Layer in der Legende auftauchen sollen. Der Wert 3 für =opt_flag= sagt, dass ein Layer in der Legende stehen soll, auch wenn sich alle Daten des Layers außerhalb des dargestellten Ausschnitts befinden, und dass er in der Legende stehen soll, auch wenn sein =STATUS= auf =OFF= gesetzt ist.

\begin{figure}
\begin{center}
\mmfig{0.3}{mapfile-legende-html}{HTML-Legenden im Einsatz}
\end{center}
\end{figure}

Es folgt eine Zeile in einer HTML-Tabelle, die aus drei Spalten besteht. In der letzten Spalte steht der Name des Layers. In der vorletzten Spalte wird die Quelle für das Bild vom MapServer eingefügt, hier mit einer Größe von 18 mal 12 Pixeln.

Die erste Zeile ist etwas trickreicher. Hier wird eine Checkbox für ein HTML-Formular generiert, die als ''value'' den Namen des Layers erhält. Dadurch wird dem MapServer mitgeteilt, welche Layer darzustellen sind und welche nicht -- der Benutzer klickt einfach die Checkboxen an.

Der letzte Teil ist der interessante: wenn ein Layer beim letzten Aufruf angezeigt worden ist, sucht MapServer in Templates nach Tags wie =layername_check= und ersetzt diese Tags dann durch =checked= . Dadurch wird die Checkbox im Browser markiert. Die Namen der Layer werden hier jedoch nicht hartkodiert, sondern bei der Abarbeitung des Legenden-Templates der Reihe nach ersetzt. Dadurch entsteht für jeden Layer eine passende Checkbox.

Dieses Stück HTML-Code generiert also nicht nur eine Legende, sondern auch gleich die Elemente für das Navigationsformular aus dem Inhalt des Mapfiles. Wird dem Mapfile nun ein neuer Layer hinzugefügt (oder ein Layer entfernt), wird die Legende automatisch korrekt generiert, ohne dass man am Template etwas ändern müßte.

=Templates=
(20)
\index{Templates}\index{Mapfile!Templates}

In der Web-Sektion des Mapfiles können diverse Templates definiert werden, die als Ergebnis eines Aufrufs ausgeliefert werden können. Bei den Templates handelt es sich um HTML-Dateien, in denen neue, MapServer-eigene Tags definiert werden, die in eckigen Klammern notiert werden.

Damit ein Template als Ergebnis ausgeliefert wird, muß der Modus =browse= im URL angegeben sein, im Gegensatz zum Modus =map= , der lediglich die Karten als Bilder zurückliefert.

Auch für die beiden Abfragemodi =query= und =nquery= werden Templates verwendet. Was es mit Queries auf sich hat, und wie man sie in seine Applikationen einbaut, ist ab Seite~\pageref{text:mapfile:queries} in Erfahrung zu bringen.

==Die verschiedenen Arten von Templates==

Templates kommen an mehreren verschiedenen Stellen im Mapfile mit unterschiedlicher Notation vor. Hier eine Aufzählung aller Möglichkeiten, ein Template für diverse Anwendungsfälle zu deklarieren.

Grundsätzlich können Templates lokal im Dateisystem liegen, wobei dann ihr Dateiname angegeben wird. Templates können aber auch als URL deklariert werden und somit von entfernten Rechnern herbeigeholt werden.

\subsubsection*{Web-Sektion}

Die Web-Sektion kennt die folgenden Template-Angaben:

*=TEMPLATE <datei|url>= Ist das Template für die Applikation, die im Modus =browse= läuft. Das einzige Template, das beim simplen Navigieren in der Karte zum Einsatz kommt.
*=HEADER <datei|url>= Ein Kopf-Template, das ausgegeben wird, bevor irgendwelche MapServer-Ergebnisse generiert werden. Findet lediglich beim Modus =nquery= zusammen mit =FOOTER= Anwendung, um die verschiedenen Abfrageergebnisse in ein beginnendes und ein abschließendes HTML einbetten zu können.
*=FOOTER <datei|url>= Das Pendant zu =HEADER= , das nach dem Einfügen aller Ergebnisse angehängt wird.
*=MINTEMPLATE <datei|url>= Ein Template, das benutzt werden soll, wenn der minimale =SCALE= für die Anwendung (gesetzt durch =MINSCALE= in der Web-Sektion) unterschritten wird. Auf diese Weise kann man MapServer-App\-li\-ka\-tionen verschiedener Detailstufen ineinander verschachteln.
*=MAXTEMPLATE <datei|url>= Ein Template, das benutzt werden soll, wenn der maximale =SCALE= für die Anwendung (gesetzt durch =MAXSCALE= in der Web-Sektion) überschritten wird.

\subsubsection*{Layer-Sektion}

In der Layer-Sektion lassen sich die folgenden Template-Angaben machen:

*=TEMPLATE <datei|url>= Präsentiert Abfrageergebnisse. Wenn mehrere Abfrageergebnisse präsentiert werden sollen, wird für jedes der Ergebnisse dieses Template einmal eingefügt und Gebrauch von =HEADER= und =FOOTER= gemacht (siehe weiter unten).
*=FOOTER <datei|url>= Kommt bei multiplen Abfragen zum Tragen und wird angehängt, nachdem alle Ergebnisse zusammengefügt worden sind.
*=HEADER <datei|url>= Das Pendant zu =FOOTER= ; wird vor allen Abfrageergebnissen eingefügt.

Das Template via =TEMPLATE= benutzt man im wesentlichen dann, wenn man nicht, wie im folgenden beschrieben, ein solches Template in jeder Class des Layers haben möchte.

\subsubsection*{Class-Sektion}

Für eine Class gibt es nur eine Template-Angabe, namentlich die folgende:

*=TEMPLATE <datei|url>= Präsentiert Abfrageergebnisse. Wenn mehrere Abfrageergebnisse präsentiert werden sollen, wird für jedes der Ergebnisse dieses Template einmal eingefügt und Gebrauch von =HEADER= und =FOOTER= gemacht, in dem sich die Class befindet.

Wenn man nicht für jede einzelne Class ein =TEMPLATE= notieren möchte, kann man eine solche Angabe auch auf der Ebene des Layers machen.

==Aufbau==

Ein einfaches Beispiel für ein HTML-Template:

 <code>
<html>
<head><title>Beispiel</title></head>
<body>
<img src="[img]"> 
</body>
</html>
</code> 

Wenn der MapServer über den URL aufgerufen wird, findet er in der Web-Sektion die Angabe für das Template, ersetzt die Tags in eckigen Klammern durch seine neu generierten Werte, und liefert dann die fertige HTML-Seite aus.

Im obigen Beispiel würde der MapServer eine Karte generieren, die einen URL zugewiesen bekommt. Dieser URL würde anstelle des =[img]= -Tags eingesetzt werden.

Für die Templates, die für die Ergebnisse von multiplen Abfragen generiert werden, gilt, dass es sich nicht um komplette HTML-Dateien handeln darf. Beispielsweise möchten Sie für ein Abfrageergebnis einer Class eventuell folgendes Template definieren:

 <code>
<tr>
<td>[ID]</td>
<td>[NAME]</td>
<td>[AREA]</td>
</tr>
</code> 

Die Deklaration der Tabelle und alles andere, was für eine vollständige HTML-Datei vonnöten ist, erfolgt dann durch weitere Templates in =HEADER= und =FOOTER= .

Für Templates, die das Navigationsinterface beschreiben (=TEMPLATE= in der Web-Sektion) und solche für die Präsentation von einzelnen Abfrageergebnissen (definiert durch =TEMPLATE= in Layern) sind hingegen natürlich vollständige HTML-Dateien notwendig.

Im Folgenden nun alle möglichen Tags, die vom MapServer unterstützt werden. Sie können übrigens auch eigene Tags definieren. Wenn Sie einen Parameter im URL übergeben, der dem MapServer nicht bekannt ist, wird dieser im Template ersetzt, wenn ein entsprechender Tag vorhanden ist. Wenn im URL also =meintag=17= steht, und im Template ein Tag =[meintag]= zu finden ist, wird dieser durch 17 ersetzt. Es gibt auch immer eine Fassung, bei der Sonderzeichen (Leerzeichen etc.) durch Escapesequenzen markiert sind; für diese Tags muß dann ein =_esc= angehängt werden. Für das genannte Beispiel hieße der Tag also =[meintag_esc]= .

Zuvorderst einige allgemeine Tags:

*=[version]= : Die Versionsnummer des eingesetzten MapServers.
*=[id]= : Eine (recht)\footnote{Die Einschränkung 'recht' eindeutig soll hier nur bedeuten, dass keine Eindeutigkeit im mathematischen Sinne vorliegt. Einem Kryptographen würden sich die Haare sträuben bei der Verwendung der Session-ID als Baustein für einen 'eindeutigen' Wert. Zur Vermeidung von Kollisionen bei unseren dynamisch generierten Bildern sollte sie jedoch ausreichen.} eindeutige Session-ID für den Aufruf des MapServers, zusammengesetzt aus momentanem Datum und Zeit, sowie der Prozess-ID des Aufrufs. Diese ID ist also solange eindeutig, wie man pro Sekunde nicht mehr Anfragen bekommt, als das System gleichzeitig Prozesse starten kann. Man hätte dann allerdings noch ganz andere Probleme, als dass die ID des MapServer-Aufrufes nicht mehr eindeutig sein könnte.
*=[host]= : Der Hostname des ausführenden Rechners.
*=[port]= : Der Port, auf dem der Webserver die Anfrage entgegengenommen hat. In den meisten Fällen ist dies 80.
*=[web_meta data <key>]= : Zeigt die Metadaten aus der Web-Sektion eines OGC-konformen Mapfiles an.

Tags für Verweise auf Dateien:

*=[img]= : Der URL, an dem sich das neu generierte Kartenbild befindet.
*=[ref]= : Dito für eine eventuell erzeugte Referenzkarte.
*=[legend]= : Dito für eine eventuell erzeugte Legende.
*=[scalebar]= : Dito für eine eventuell erzeugte Maßstabsleiste.
*=[queryfile]= : Pfad zu dem File, in dem eine Query abgespeichert worden ist, falls =savequery= als Parameter gesetzt wurde. Mehr zu diesem Thema im Abschnitt über Queries, siehe Seite~\pageref{text:mapfile:query:cached}.
*=[map]= : Pfad zum Mapfile.

Die folgenden Tags lassen sich für Angaben über die Bildgeometrie verwenden:

*=[center]= : Gibt das Zentrum des Bildes in Pixeln an. Beispiel: ist das fertige Bild 300x300 Pixel groß, so steht in diesem Tag 149,149. Wofür braucht man das? Wenn man in einem Navigationsformular einen Knopf zum 'Auffrischen' der Karte hat (man möchte beispielsweise Layer hinzuschalten, aber den Ausschnitt nicht ändern), so kommt kein Klick in der Karte zustande, der den MapServer auf das neue Zentrum für den anzuzeigenden Ausschnitt hinweist. Mit diesem Tag ist jedoch im Formular folgendes Konstrukt möglich: <code> <input type="hidden" name="imgext" value="[center]"> </code> Dadurch wird ein impliziter Mausklick auf das Zentrum der Karte gesetzt.
*=[center_x]= und =[center_y]= : Die x- und y-Koordinate des Bildzentrums als einzelne Werte.
*=[mapsize]= : Die momentane Größe der Karte in Breite und Höhe in Pixeln, getrennt durch ein Leerzeichen. Mit einem =_esc= am Ende auch als escaped Version vorhanden.
*=[mapwidth]= und =[mapheight]= : Breite beziehungsweise Höhe der Karte in Pixeln.
*=[scale]= : Maßstab der Karte. Zu Maßstäben siehe vor allen Dingen auch Abschnitt~19

Angaben über die Geometrie der Karte sind mit folgenden Tags möglich. Die letzten drei Punkte in dieser Aufzählung sind nur dann verfügbar, wenn der MapServer mit der Projektionsbibliothek proj.4 kompiliert worden ist und es eine Projektionsangabe im Mapfile gibt.

*=[mapx]= und =[mapy]= : x- und y-Koordinate des Mausklicks.
*=[mapext]= und =[mapext_esc]= : Die vollen Extents der Karte, separiert durch Leerzeichen.
*=[maxx]= , =[maxy]= , =[minx]= und =[miny]= : Die einzelnen Koordinaten der Karte.
*=[rawext]= und =[rawext_esc]= : Die Extents der Karte, bevor sie auf die gewünschte Pixelgröße angepaßt worden ist, getrennt durch Leerzeichen.
*=[rawmaxx]= , =[rawmaxy]= , =[rawminx]= und =[rawminy]= : Die einzelnen Koordinaten der Extents der Karte, bevor die Karte auf die gewünschte Pixelgröße angepaßt worden ist.
*=[maplon]= und =[maplat]= : Längen- und Breitengrad des letzten Mausklicks in der Karte.
*=[mapext_latlon]= und =[mapext_latlon_esc]= : Voller Extent der Karte in Längen- und Breitengrade, separiert durch Leerzeichen.
*=[minlon]= , =[minlat]= , =[maxlon]= und =[maxlat]= : Die einzelnen Koordinaten der Extents der Karte in Längen- und Breitengraden.

Die folgenden Tags geben Aufschluss über die Layer in einer Karte:

*=[get_layers]= : Eine Aufzählung aller Layer, die in der aktuellen Karte aktiv sind, sodass sie in eine URL eingebunden werden können. Zum Beispiel: <code> layer=fluesse&layer=eisenbahn&layer=seen </code> 
*=[layers]= und =[layers_esc]= : Die Namen aller aktiven Layer, voneinander durch Leerzeichen getrennt.
*=[layername_check]= und =[layername_select]= : Im Tag muß an dieser Stelle nicht 'layer' stehen, sondern der tatsächliche Name des Layers. Ist ein Layer aktiv, wird der Tag durch das Wort =checked= bzw. =selected= ersetzt. Auf diese Weise wird von Seitenaufruf zu Seitenaufruf mitgeschleift, ob ein Layer ausgewählt ist. Ein Beispiel für einen Layer namens 'fluesse': <code> <input type="checkbox" name="layer" value="fluesse" [fluesse_select]> Flüsse </code> Wenn der Layer im URL angefordert worden ist, ist diese Checkbox automatisch selektiert.
*=[layername_meta <data> <key>]= : Dieser Tag wird, genauso wie der entsprechende Tag in der Web-Sektion, durch Metadaten aus einem OGC-konformen Mapfile gefüllt.

Auch für das Zoomverhalten gibt es einige Tags für das Template:

*=[zoomdir_<-1|0|1>]=
*=[zoom_minzoom to maxzoom_<select|check>]=

Zu guter Letzt natürlich noch die Tags, die für Queries interessant sind. Dementsprechend werden diese Tags nur dann ausgefüllt, wenn sie sich in einem Template befinden, das von einer Query abgearbeitet wird.

*=[shpext]= : Die Extents des Shapes, das das Suchergebnis darstellt.
*=[shpminx]= , =[shpmaxx]= , =[shpminy]= und =[shpmaxy]= : Dito, nur in die einzelnen Punktkoordinaten aufgeschlüsselt.
*=[shpmid]= : Der Mittelpunkt eines gewähltes Shapefiles. Steht nur zur Verfügung, wenn Queries bearbeitet werden.
*=[shpmidx]= und =[shpmidy]= : X- respektive y-Koordinate des Mittelpunkts.
*=[shpidx]= : Index des aktuellen Shapefiles. Steht nur zur Verfügung, wenn Queries bearbeitet werden.
*=[tileindex]= : Index der momentanen Rasterkachel. Steht ebenfalls nur zur Verfügung, wenn Queries bearbeitet werden.
*=[DBase column name]= : Jede beliebige Spalte einer ''.dbf'' -Datei kann in Query-Templates als Tag verwendet werden. Die entsprechenden Ergebnisse werden dann eingefügt.
*=[cl]= : Name des aktuellen Layers. Sinnvoll in Layerheadern oder -footern.
*=[lrn]= : Die Nummer eines Suchergebnisses im aktuellen Layer. Sinnvoll in Querytemplates.
*=[nl]= : Anzahl der Layer, in denen es Suchergebnisse gegeben hat. Sinnvoll in Web-Headern oder -footern.
*=[nlr]= : Gesamtzahl aller Ergebnisse im aktuellen Layer. Sinnvoll in Web-Headern und -footern.
*=[nr]= : Gesamtzahl aller Suchergebnisse. Sinnvoll in Web-Headern und -footern.
*=[rn]= : Die Nummer des Suchergebnisses innerhalb aller Suchergebnisse. Sinnvoll in Web-Headern und -footern.

=Metadaten=(21)\index{Mapfile!Metadaten}\index{Metadaten}

Die Web-Sektion (und nicht nur diese) kann zwei Arten von Metadaten aufnehmen. Zum einen sind diejenigen Daten zu nennen, die für eine OGC-konforme Interaktion mit der Außenwelt sorgen. Wie mit diesen Daten umzugehen ist, erfahren Sie in Kapitel~\ref{text:ogc}.

Des weiteren können Sie sozusagen "`freie"' Einträge vornehmen, die Sie dann -- in eckigen Klammern, siehe den nächsten Abschnitt über Templates -- als Parameter in das Template übernehmen und so in die HTML-Ausgabe einfügen können.

Ein Beispiel:

 <code>
METADATA
autor "Thorsten Fischer"
adresse "Heilbronner Strasse 10"
END
</code> 

Diese Zeilen ermöglichen Ihnen, beispielsweise das folgende im Template zu tun:

 <code>
Der Autor [autor] kann unter
der Adresse [adresse] erreicht werden
</code> 

MapServer ersetzt diese Tags dann durch die Parameter aus der =METADATA= -Sektion.

Beachten Sie, dass Sie solche Metadaten auch auf Layer-Ebene einfügen können. Diese Daten können Sie dann später beispielsweise dazu verwenden, die Layer in HTML-Legenden auf eine bestimmte Weise zu sortieren.

Eine weitere Idee zum Einsatz von Metadaten sind Links. Speichern Sie zum Layer gehörende URLs als Metadaten und fügen Sie sie später in Templates oder HTML-Legenden ein.

=Queries=\index{Queries}\index{Mapfile!Queries}(22)

Zuweilen möchte man seine Daten nicht nur betrachten. Auch wenn es die größte Stärke des MapServer ist, schnell Karten generieren zu können und diese dann ausliefern zu lassen, ist eine minimale GIS-Funktion zuweilen wünschenswert. Die Anfragen auf die den Karten zugrundeliegenden Datenbestände werden beim MapServer ''Queries'' genannt.

==Notation==

Im HTML-Template, das das Benutzer-Interface für den MapServer definiert, muß natürlich zuerst die Möglichkeit geschaffen werden, neben dem Bewegen in der Karte auch Queries zuzulassen -- man muss zwischen beiden Modi wählen können. Das kann beispielsweise durch entsprechende Radio-Buttons passieren:

 <code>
...
<input type="radio" name="mode" value="browse" checked> Browsen
<input type="radio" name="mode" value="query"> Anfrage stellen
...
</code> 

Beim Absenden des Formulars übermitteln die Radio-Buttons (wie man sie beispielsweise auch im offiziellen MapServer-Demo findet) den entsprechenden Modus an das MapServer-CGI.

Möchte man mehrere Abfrageergebnisse zulassen, benötigt man den Modus =nquery= :

 <code>
<input type="radio" name="mode" value="nquery"> Mehrere Anfragen
</code> 

Alle drei Modi können natürlich im gleichen Formular vorkommen.

Desweiteren müssen Sie in allen Layern, für die Sie Abfragen zulassen möchten, ein =TEMPLATE= definieren. Dabei können Sie einzelne Templates in den Classes des Layers definieren (die dann nur für Abfrageergebnisse der jeweiligen Klasse gelten) oder aber eine Angabe für den kompletten Layer machen; das muß dann außerhalb der Classes geschehen.

Für die einfache Query wird außerdem nur der oberste sichtbare Layer der Karte befragt\footnote{Also der letzte sichtbare Layer im Mapfile}.

Wie Templates für Abfrageergebnisse notiert werden, ist bereits in der umfänglichen Sektion über Templates beschrieben worden. Beachten Sie auf alle Fälle immer, ob Sie nur einfache oder multiple Ergebnisse bei Ihren Anfragen zulassen. Ist letzteres der Fall, sollten Sie sich über die Anordnung von =HEADER= - und =FOOTER= -Templates Gedanken machen.

Ein Beispiel. Sie haben folgendes in Ihrem Layer notiert:

 <code>
LAYER
NAME "gemeinden"
...
HEADER "gemeinden_head.html"
FOOTER "gemeinden_foot.html"
...
CLASS
TEMPLATE "gemeinden.html"
END
END
</code> 

Für eine einfach Query würde lediglich einmal =gemeinden.html= mit entsprechendem Ergebnis zurückgeliefert werden. Nehmen wir aber nun an, dass der Modues auf =nquery= gesetzt ist, und mehrere Features mit einem Mausklick erwischt worden sind -- um ein Beispiel zu wählen: 3 Stück --, so wäre das Ergebnis wie folgt:

 <code>
gemeinden_header.html
gemeinden.html
gemeinden.html
gemeinden.html
gemeinden_footer.html
</code> 

Das gleiche wiederholt sich dann noch für alle anderen Layer, die darunter liegen. Außerdem können für =nquery= auch noch ein Header sowie ein Footer in der WEB-Sektion des Mapfiles definiert werden. Diese werden dann jeweils einmal dargestellt: einmal vor allen Suchergebnissen, und einmal dahinter.

==Query maps==\index{Query map}(23)

Querymaps sind kleine Karten, die in Ergebnistemplates dazu dienen, die Resultate von Queries zu visualisieren. Sie sind als eigene Sektion im Mapfile definiert, außerhalb jeder anderen Sektion (am besten nach dem Header) und sehen beispielsweise folgendermaßen aus:

 <code>
QUERYMAP
COLOR 255 0 0
SIZE 200 200
STATUS ON
STYLE HILITE
END
</code> 

In diesem Fall wird eine 200x200 Pixel große Querymap erzeugt, in der angefragte Features rot markiert werden.

Die folgenden Optionen können in Querymap-Sektionen auftauchen:

*=COLOR <red> <green> <blue>= Gibt die Farbe an, in der die angefragten Features markiert werden. Ergibt nur Sinn, wenn der =STYLE= auf =HILITE= gesetzt ist. Voreinstellung ist gelb.
*=SIZE <x> <y>= Die Größe, in der die Querymap gezeichnet werden soll. Voreinstellung ist die Größe der Karte.
*=STATUS <ON|OFF>= Legt fest, ob die Querymap gezeichnet werden soll.
*=STYLE <NORMAL|HILITE|SELECTED>= Dieser Stil legt für den angefragten Layer fest, wie die gewählten Features gemalt werden sollen. =NORMAL= zeichnet die Karte ohne Änderung. =HILITE= zeichnet den Layer, markiert aber die gewählten Features mit der Farbe =COLOR= ; diese Art ist auch die Voreinstellung. =SELECTED= zeichnet lediglich die gewählten Features.

Wie werden Querymaps nun dargestellt? Es gibt für diese Abfragekarten kein eigenes Schlüsselwort, vielmehr ändert sich der Tag =[img]= , wenn in einen Query-Modus geschaltet wird. Es wird dann nicht mehr die Karte, sondern eben die dazugehörige Abfragekarte dargestellt.

Abgebildet wird in der Querymap der Ausschnitt der Karte, in dem man die Anfrage gestellt hat. Darin markiert sind die Abfrageergebnisse, wie man es im =QUERYMAP= -Block angegeben hat.

Sie können übrigens eine Querymap auch separat von allem anderen mit dem Modus =querymap= anfordern, genauso, wie auch eine normale =map= .

\subsubsection*{Cached Queries}(24)\index{Queries!Cached Queries}\index{Cached Queries}

Cached Queries sind eine Möglichkeit, Abfrageergebnisse abzuspeichern. Mit Cached Queries können Sie die Abfrageergebnisse in einer Karte darstellen, deren Extents Sie beliebig wählen können. Sie sind nicht auf den Ausschnitt beschränkt, an den die Anfrage gestellt wird.

Um eine Cached Query benutzen zu können, müssen Sie zuerst eine weitere Zeile in Ihr HTML-Template aufnehmen:

 <code>
<input type="hidden" name="savequery" value="true">
</code> 

Dadurch werden nun bei Query-Aufrufen temporäre Dateien angelegt, wie es etwa auch für generierte Karten geschieht. Der Name dieser Datei läßt sich in einem Template nun mit Hilfe von Template-Tags rekonstruieren:

 <code>
<img src="[program]&map=[map]&
queryfile=[map_image_path]<NAME>[id].qy
[get_layers]&mode=map&size=200+200
</code> 

Der Wert =[map]= wird sowieso immer übergeben, und =get_layers= wird bei jedem Aufruf des MapServers automatisch aus den übergebenen Layern erstellt.\\ =map_image_path= fügt der MapServer ebenfalls automatisch aus dem Mapfile ein. Der Wert von =[id]= ist eine eindeutige ID für den jeweiligen MapServer-Aufruf und wird auch vom MapServer ausgefüllt. Der String =<NAME>= ist der Wert, der im Mapfile als =NAME= im Mapfile für die Karte gesetzt ist, und muß von Ihnen von Hand eingetragen werden.

Der Trick ist nun, dieser Karte eine Bounding Box in bekannter Notation nach Ihrem Wunsch mitzugeben; man erhält somit beliebige Kartenausschnitte, in denen Abfrageergebnisse angezeigt werden.

==Joins==\index{Joins}

Der Grundgedanke bei Joins entspricht dem gleichlautenden Begriff bei SQL-Da\-ten\-ban\-ken: die Inhalte zweiter Dateien mit Daten werden zu einem einzigen Datensatz zusammengefügt. Dazu benötigt man in beiden Datensätzen ein gemeinsames Datum, wie zum Beispiel eine ID, um den Inhalt den einen Datensatzes dem anderen zuordnen zu können.

In MapServer kommt das Konzept vor allen Dingen zum Einsatz, um die Inhalte zweier DBF-Dateien zu einem einzigen zusammenzufügen, der dann dazu benutzt wird, die Expressions in Classes oder auch Query-Ergebnisse zu evaluieren.

FIXME: funktioniert nicht?

==Weitere Arten von Queries==

Über die beiden Modi =query= und =nquery= hinaus definiert MapServer noch eine ganze Menge weiterer Typen für Datenanfragen. Auf einige dieser Modi soll hier noch im Detail eingegangen werden.

===indexquery===

Eine Indexquery sucht ein Shape über seine ID im Shapefile heraus. Im Aufruf sieht das beispielsweise folgendermaßen aus:

 <code>
http://www.example.com/cgi-bin/mapserv
? map=/pfad/zum/mapfile.map
& mode=indexquery
& qlayer=bundeslaender
& shapeindex=15
</code> 

Der Aufruf dieser Art von Query erfolgt über den Modus =indexquery= . Der Layer, der das Ziel der Anfrage sein soll, wird mit =qlayer= bestimmt.

Für das Ergebnis dieses Aufrufs wird wie gewohnt das Template benutzt, das sie im entsprechenden Layer definiert haben (bzw. in den dortigen Classes). Anstatt aber nun die Koordinaten eines Mausklicks auszuwerten, wird gezielt nach einem bestimmten Shape gesucht. Das obige Beispiel zum Beispiel sucht nach dem sechszehnten Shape im Layer =bundeslaender= , und die Darstellung im Query-Template sieht dann dementsprechend aus.

Falls Sie eine Querymap definiert haben sollten, so werden bei der Darstellung der Karte beim obigen Aufruf die Extents verwendet, die im Mapfile definiert sind. Der CGI-Parameter =mapext= kann verwendet werden, um wie im Modus =browse= einen anderen Kartenausschnitt festzulegen. Falls Sie diesen Parameter nicht auf bestimmte Werte setzen, sondern stattdessen =mapext=shapes= verwenden, wird direkt auf das Ergebnisshape gezoomt.

Nur die Querymap als Bild können Sie sich übrigens mit dem Modus =indexquerymap= zurückliefern lassen.

Zusätzlich zu den Parametern im gezeigten Beispielaufruf gibt es auch noch =tileindex= , für den Fall, dass sie gekachelte Shape-Daten verwenden.

===itemquery und itemnquery===

Durch eine Itemquery können Sie Features anhand von nichträumlichen Eigenschaften auswählen. Bei Daten aus Shapefiles (auf die wir uns hier konzentrieren wollen) kommen diese Eigenschaften selbstverständlich aus den =.dbf= -Dateien.

Um über den URL auf diese Eigenschaften zugreifen zu können, müssen wir sie mit einem Namen bekannt machen. Dazu benutzen wir den Parameter =FILTER= im entsprechenden Layer:

 <code>
LAYER
...
DATA "bundeslaender"
FILTERITEM "NAME"
FILTER "
...
END
</code> 

In diesem Beispiel verwenden wir die DBF-Tabellenspalte =NAME= und machen sie nach außen als =name= bekannt.

Zugriff erhalten wir nun über diesen Namen. Im URL notieren wir jetzt folgendes:

 <code>
FIXME
</code> 

FIXME:mehr

Da diese Art von Query mit Angabe einer Zeichenkette funktioniert, ist es in den meisten Fällen sinnvoll, dem Benutzer eine Auswahlliste zur Verfügung zu stellen, aus der er sich dann Features nach Namen auswählen kann.

FIXME

===featurequery und featurenquery===

\begin{figure}
\begin{center}
\mmfig{0.55}{featurenquery-berlin}{Eine =featurenquery= . Hier wurde das Bundesland Berlin gewählt und nach allen Features (Postleitzahlgebieten und bestimmte Kacheln) gefragt, die von der Fläche des Bundeslandes geschnitten werden.}
\end{center}
\end{figure}

In diesem Modus wird ein Feature ausgewählt, und alle dafür eingestellten Layer werden befragt, welche Features durch dieses Feature geschnitten werden. Sie können ein Beispiel dafür in Abbildung~\ref{featurenquery-berlin} sehen: Hier wurde das Bundesland Berlin durch einen Mausklick ausgewählt, und das Ergebnis ist eine Liste aller Features, die die Fläche eben dieses Bundeslandes schneiden.

Beachten Sie bitte, dass wir an dieser Stelle nur die Fassung dieser Query mit dem =n= im Namen betrachten. =featurequery= funktioniert analog zum Paar =query= /=nquery= mit nur einem einzigen Suchergebnis.

Als erstes benötigen Sie für diese Art von Query selbstverständlich einen entsprechenden Modus:

 <code>
... & mode = featurenquery & ...
</code> 

Danach muß spezifiziert werden, anhand welchen Layers die Auswahl getroffen werden soll. Vorstellbar wäre zum Beispiel eine Auswahlbox mit einer Liste aller Layer, aus der dann ein Layer als Bezugsebene ausgewählt werden kann. Der zuständige Parameter heißt =slayer= . Heißt der Layer beispielsweise =gruenflaechen= , so notiert man:

 <code>
... & slayer = gruenflaechen & ...
</code> 

Jeder Layer, der über =layer== im URL spezifiziert wird und ein =TEMPLATE= gesetzt hat, wird nun für den Vergleich herangezogen.

Das Abarbeiten der Query-Templates läuft in der gewohnten Weise ab; für jedes Ergebnis in einer Class werden die Templates hintereinander gehangen, für den Layer dann eventuell noch Header davor und Footer dahinter, und um das ganze herum dann eventuell vorhandene Header und Footer aus der Web-Sektion.

''Hinweis'' : Zum Zeitpunkt der Drucklegung funktionierte diese Art von Query nicht mit umprojizierten Daten. Quell- und Zielprojektion mußten übereinstimmen, um Suchergebnisse zu erhalten.

===itemfeaturequery und itemfeaturenquery===

FIXME

=PostgreSQL und PostGIS=
\index{PostGIS}\index{PostgreSQL}

PostGIS, ein Zusatz für die freie Datenbank PostgreSQL, ist die 'Standard'-Daten\-bank\-an\-bindung für den MapServer. PostGIS setzt einen großen Teil der Simple Features des OGC um und kann nicht nur als Datenquelle für den MapServer dienen, sondern generell raumbezogene SQL-Anfragen verarbeiten.

Die Anbindung einer PostGIS-Datenbank wird in Kapitel~\ref{text:database} ab Seite~\pageref{text:database:postgis} beschrieben.

=OGR=\index{OGR}(25)

Die OGR-Bibliothek ist das vektor-orientierte Gegenstück zu GDAL. Obwohl es sich um eine eigenständige Bibliothek handelt, wird sie zusammen mit GDAL ausgeliefert.

Neben den Shapefiles gibt es nämlich noch eine ganze Reihe anderer Vektorformate. Shapefiles sind so ziemlich das minimalistischste, was man sich vorstellen kann, sie beinhaltet lediglich die Koordinaten von Punkten. Viele Vektorformate sind allerdings etwas komplexer, und enthalten gleich mehrere Datensätze, einen Haufen zusätzliche Metadaten oder gleich Informationen über die Gestaltung der Daten.

Besonders bei der letztgenannten Klasse von Formaten sollte man vorsichtig sein und von OGR nicht zuviel erwarten. Zwar gibt es für diese Formate die Möglichkeit, das Layout der Daten auszulesen, aber nicht immer kann diese Information auch umgesetzt werden.

Von der Notation her gibt es, ähnlich wie bei Datenanbindungen, nur eine grundlegende Änderung: Im Layer wird nun nicht mehr =DATA= als Schlüsselwort für die Datenquellen verwendet, sondern die beiden Parameter =CONNECTIONTYPE= (dieser ist dann immer =OGR= ) und =CONNECTION= . Dabei wird =CONNECTION= dann von den notwendigen Details wie dem gewünschten Layer aus dem Datensatz usw. gefolgt.

FIXME: vervollständigen!1!

=Spezifikation von Ausgabeformaten=(26)

Mit Version 4.0 des MapServers ist man nun endlich in der Lage, mehrere verschiedene Ausgabeformate für die fertige Karte zu spezifizieren. Bisher war man auf ein einziges Rasterbild-Format festgelegt (PNG respektive GIF).

FIXME: mehr

Ein Mapfile kann eine, mehr als eine oder sogar gar keine OUTPUTFORMAT-Sektion haben. Ohne jede Angabe wird bei einkompilierter GD-Bibliothek ein PNG-Bild zurückgeliefert.

Eine OUTPUTFORMAT-Sektion sieht typischerweise so aus:

 <code>
OUTPUTFORMAT
NAME "png"
DRIVER "GD/PNG"
MIMETYPE "image/png"
IMAGEMODE RGB
EXTENSION "png"
END
</code> 

Zuerst erhält die Sektion einen Namen. Danach wird ein "Treiber" für die Erstellung des Bildes angegeben. Für die typische PNG-Ausgabe mit der Bibliothek GD steht hier ''GD/PNG'' .

Der Mimetype ist wichtig, um dem Browser, der die fertige Karte entgegennimmt, mizuteilen, welcher Art die Daten sind, die da ankommen\footnote{Für Windows-Benutzer: Nein, der Dateiname sagt nichts über die Art einer Datei aus. Er ist im Grunde nicht einmal Bestandteil einer Datei. Microsoft hat das aber schon vor einer ganzen Weile vergessen.}. Er ist für diese Sektion allerdings Optional, da MapServer auch versucht, ihn automatisch zu bestimmen.

Der IMAGEMODE gibt unter anderem die Farbtiefe des Bildes an (siehe die Sektion über Rasterbilder; ist aber auch für Flash relevant), und schließlich die Dateinamenerweiterung des Outputs.

Im folgenden sollen für die verschiedenen Anwendungsfälle alle möglichen Optionen in der OUTPUTFORMAT-Sektion angegeben werden.

==Rasterbilder==

Bisher gibt es gibt es nur zwei Treiber für Rasterbildformate im MapServer: die inzwischen klassische Ausgabe mittels GD, und ganz neu GDAL. Letzteres kann bisher nur GeoTIFF-Bilder produzieren, aber es ist ein Anfang.

FIXME: blah

Der Parameter =IMAGEMODE= sagt aus, in welcher Farbtiefe das Bild produziert werden soll, und wie Transparenzen gehandhabt werden sollen:

*=PC256= : Produziert ein Bild mit einer eigenständigen Farbpalette mit (maximal) 256 Farben. Dies ist der klassische MapServer-Modus. Der Raster-Treiber ''GD/GIF'' kennt ausschließlich diesen Modus. TRansparenz ist mit diesem Modus möglich.
*=RGB= : 24-Bit RGB-Farbbild. Ohne Transparenz.
*=RGBA= : 32-Bit RGBA-Farbbild mit Alphakanal (Transparenz).
*FIXME: mehr?

Über alle diese Optionen hinaus gibt es noch treiberabhängige Angaben, die sogenannten FORMATOPTIONs. Sie werden folgendermaßen notiert:

 <code>
OUTPUTFORMAT
NAME "jpg"
DRIVER "GD/JPEG"
MIMETYPE "image/jpeg"
IMAGEMODE RGB
EXTENSION "jpg"
FORMATOPTION "QUALITY=75"
END
</code> 

Jedes OUTPUTFORMAT kann dabei keine, eine oder mehrere (passende!) Angaben für FORMATOPTIONs haben. Im folgenden sind alle diese Optionen für die einzelnen Treiber beschrieben.

===Der GD-Treiber===

Der GD-Treiber kennt die folgenden, optionalen Parameter in der OUTPUTFORMAT-Sektion:

*=QUALITY= Legt für JPEG-Bilder die Kompression fest. Liegt zwischen =0= (niedrigste Qualität, höchste Kompression) und =100= (höchste Qualität, niedrigste Komprimierung).
*=INTERLACE= Legt fest, ob PNG- bzw. GIF-Bilder interlaced sein sollen (=ON= ) oder nicht (=OFF= ).

FIXME: mehr

===Der GDAL-Treiber===

Generell kann man dem GDAL-Treiber alles als Parameter mitgeben, was die Bibliothek als Optionen kennt; was alles in Frage kommt, erfahren Sie in der Dokumentation von der Website~[[http:website:gdal]].

FIXME: vervollständigen!1!

==Vektorformate==(27)

Vektorausgabeformate sind ein neues Feature in MapServer 4.0. Die Fülle von Einstellungen, die man dabei theoretisch machen kann, wird durch die Einführung von =OUTPUTFORMAT= abgefangen.

Alle bisher unterstützten Vektorformate zeichnen sich durch die Eigenschaft aus, dass sie nicht von sich aus im Browser darstellbar sind, sondern eine zusätzliche Bearbeitung oder doch zumindest den Einsatz von separaten Plugins im Webbrowser notwendig machen.

Wachsender Beliebtheit bei den Vektorformaten im Web erfreut sich auch SVG, ein XML-basiertes Format. Folglich sind Fragen nach einer Unterstützung für dieses Format auf der Mailingliste an der Tagesordnung. Bisher hat sich aber noch niemand die Mühe gemacht, Unterstützung für dieses Format zu implementieren. Das kann sich im Laufe der Zeit selbstverständlich ändern.

===PDF===

Unterstützung für die Ausgabe von PDF-Dateien wird mit der Bibliothek PDFLib realisiert. Dafür wird MapServer beim Kompilieren ganz einfach gegen diese Bibliothek gelinkt.

Das Ausgabeformat wird recht simpel folgendermaßen notiert:

 <code>
OUTPUTFORMAT
NAME "pdf"
MIMETYPE "application/pdf"
DRIVER PDF
END
</code> 

Da man PDF nicht einfach über einen =<img>= -Tag in seine HTML-Seite einbinden kann, bietet sich ein anderes Vorgehen an. Man baut ein Template zum Browsen der Karte wie gewohnt, gibt dem Benutzer aber noch einen Link mit einer Beschriftung wie 'diese Karte als PDF herunterladen' mit auf den Weg. Diesen Link kann man sich für den aktuellen Kartenausschnitt mit den entsprechenden MapServer-Tags bauen, zum Beispiel wie folgt:

 <code>
<a href="/cgi-bin/mapserv?map=[map]&imgext=[mapext]&FIXME=pdf ...">
</code> 

Die Liste der Parameter ist hier nicht vollständig, aber die Idee wird klar.

Wer den Verlauf der Entwicklung von MapServer 4.0 mitverfolgt hat, hat vielleicht mitbekommen, dass zu Beginn der PDF-Unterstützung lediglich ein PNG-Bild erzeugt worden ist, das dann in ein PDF-Dokument eingebettet wurde. Das ist nicht mehr der Fall, nun liefert MapServer für Vektordaten richtiges PDF zurück.

Wenn man eine Weile mit diesem Ausgabeformat experimentiert, wird man merken, dass die reine Ausgabe einfach nur einer Karte im PDF-Format recht unbefriedigend ist. Wer gestalterisch tätig werden möchte, der muß mit einer Skriptsprache Hand anlegen.

''Hinweis'' : Beachten Sie bitte unbedingt, dass die Nutzung für die hier verwendete Bibliothek PDFLib nicht für ausnahmslos alle Nutzungen kostenlos ist. Bitte informieren Sie sich auf der Website~[[http:website:pdflib]] der Bibliothek über die Details.

Außerdem ist die Erzeugung von PDF eine recht rechenintensive Sache, deren Einsatz man demnach mit Bedacht planen sollte.

===Shockwave Flash===

Flash ist ein Vektorformat, das im Web vor allen Dingen dafür verwendet wird, Animationen darzustellen. Daher spricht man bei einem Flash-Element in einer Website gewöhnlich von einem 'Movie', sogar dann, wenn es sich eigentlich um statischen Inhalt handelt. MapServer bietet mit Version 4.0 nun auch die Möglichkeit, fertige Karten als Flash-Movies auszuliefern.

Dabei stützt sich MapServer auf die Bibliothek Ming~[[http:website:ming]], die im Moment von Wolfgang Hamann weiterentwickelt wird, nachdem er diese Aufgabe im November 2002 vom ursprünglichen Entwickler übernommen hat\footnote{Leider hat sie im Laufe der Zeit keine Updates mehr erfahren.}. Die Software zeichnet sich insbesondere durch ihre vielfältigen Bindungen an andere Programmiersprachen aus.

Die Installation für Flash-Unterstützung wird für das Selberkompilieren von Binaries ab Seite~\pageref{anhang:installation:compile:flash} besprochen.

Es gibt für uns zwei Arten, Flash-Output zu generieren: einmal einen Movie für die komplette Karte, und einmal einen Movie für jede einzelnen Layer:

 <code>
OUTPUTFORMAT
NAME "swf"
MIMETYPE "application/x-shockwave-flash"
DRIVER swf
IMAGEMODE PC256
FORMATOPTION "OUTPUT_MOVIE=SINGLE"
# FORMATOPTION "OUTPUT_MOVIE=MULTIPLE"
END
</code> 

Wenn Sie mit diesem =OUTPUTFORMAT= einen Aufruf durchführen, werden Sie feststellen, dass Sie eine Datei (oder mehrere, wenn Sie =MULTIPLE= statt =SINGLE= im Beispiel gewählt haben) mit der Endung =.swf= in Ihrem temporären Verzeichnis aufgetaucht ist.

Bevor Sie diese Dateien tatsächlich benutzen können, müssen Sie sich aber noch ein wenig Arbeit machen. Was Sie benötigen, ist Kenntnis in der Sprache ActionScript, und ein Flash-SDK. Leider würde es den Rahmen dieses Buches sprengen, das eine oder das andere zu erläutern. Daher bleibt mir nur der Verweis auf das Archiv der MapServer-Mailingliste, wo Sie auf der Suche nach Beispielapplikationen und Diskussionen fündig werden können.

=Features=(28)

Für manche Dinge ist es nicht nötig -- oder schlicht zu aufwendig -- ein eigenes Shapefile oder eine andere Datenquelle zu haben. Sie können einfache Features auch als =FEATURE= -Block direkt im Mapfile notieren. Ein Beispiel:

 <code>
FEATURE
POINTS
1 1
10 10
10 1
1 1
END
TEXT "Dreieck"
END
</code> 

Hier definieren wir ein Dreieck in der linken oberen Ecke der fertigen Karte. Der Parameter =TEXT= definiert die Beschriftung des Features.

Beachten Sie, dass für einen geschlossenen Linienzug der letzte Punkt dem ersten Punkt entsprechen muß. Für die Einbettung eines =FEATURE= in einen Layer schauen Sie sich bitte den nächsten Abschnitt an.

==Fix positionierte Elemente==

Zuweilen möchte man in eine fertige Karte noch eine Information einfügen, die immer gleich bleibt; ein Logo, eine Urhebernotiz, was auch immer. Das Problem ist natürlich, dass bisher immer alles georeferenziert war und daher immer auf einen bestimmten Punkt fixiert.

\begin{figure}
\begin{center}
\mmfig{0.60}{transform-label}{Ein fixes Label in einer Karte, hier der URL der MapMedia-Website.}
\end{center}
\end{figure}

Mit dem Parameter =TRANSFORM= in einem Layer können Sie dieses Verhalten jedoch ein wenig manipulieren. Dieser Parameter gibt an, ob das Koordinatensystem der Datenquelle im Verhältnis zum fertigen Bild transformiert werden soll oder nicht. Die Standardeinstellung ist immer =TRUE= , was nicht weiter verwundert, denn bisher wurde immer das Koordinatensystem der Daten in das Koordinatensystem des Bildes (Angabe in Pixeln und Ursprung links oben) umgewandelt.

Setzen Sie diesen Wert jedoch auf =FALSE= , können Sie neue Dinge tun, unter anderem auch mit einer =FEATURE= -Sektion, beispielsweise wie folgt:

 <code>
LAYER
NAME "credits"
STATUS DEFAULT
TRANSFORM FALSE
TYPE ANNOTATION
FEATURE
POINTS
10 10
END
TEXT 'http://www.mapmedia.de/'
END
CLASS
LABEL
TYPE TRUETYPE
FONT "arial"
SIZE 11
ANTIALIAS TRUE
COLOR 0 0 0
END
END
END
</code> 

Dieser Layer besteht aus nur einem Feature, einem Punkt, dessen Koordinaten fest angegeben sind, und ebenso seine Beschriftung. In der dazugehörigen Class ist die Beschriftung mit Schriftart, Farbe usw. definiert. Dadurch, dass der Status auf =DEFAULT= gesetzt ist, und dass man diesen Layer als letzten Layer im Mapfile notiert, hat man einen Effekt wie in Abbildung~\ref{transform-label}: eine Beschriftung, die immer in der Karte zu sehen ist.

FIXME: raster?

=CGI-Parameter=(29)

FIXME:aufzählung

==Parameter einschränken==(30)

FIXME:Restriktion durch eine EXPRESSION

\subsection*{Ändern des Mapfiles}

Von außen (über den aufrufenden URL) können auch praktisch alle Inhalte des Mapfiles verändert werden. Der Aufbau dieser neuen Parameter ist recht simpel und orientiert sich an der Struktur eines Mapfiles.

Betrachten wir den Aufbau eines Mapfiles: eine Map beinhaltet (mindestens einen) Layer, dieser mindestens eine Klasse (wenn es sich um einen Vektorlayer handelt). Diese Klasse kann nun wiederum ein Label beinhalten, welches seinerseits eine Farbe hat.

Die Adressierung kann auf verschiedene Weise geschehen. Zuerst einmal über Nummern. Im folgenden Beispiel bekommt die erste Klasse im zweiten Layer die Farbe Rot zugewiesen:

 <code>
...&map_layer_1_class_0_color=255
</code> 

Das '\

Darüber hinaus lassen sich Layer auch über ihren Namen referenzieren:

 <code>
...&map_fluesse_class_0_color=255
</code> 

Wenn der Layer nur eine Klasse hat, sollte man den Index einfach weglassen.

Des weiteren lassen sich auf diesem Weg simple Features zu einem Layer hinzufügen. Der Layer muß existieren. Hier das Beispiel aus der offiziellen MapServer-Dokumentation:

 <code>
...&map_user_feature=new&map_user_feature_points=12345.6789+12345.6789
&map_user_feature_text=My+House!
</code> 

Dem Layer ''user'' wird auf diese Weise ein Punkt mit den angegebenen Koordinaten hinzugefügt, und er wird auch gleich beschriftet. Wird ein Layername mehrfach verwendet, wird das Feature einfach erweitert. Auf diese Weise lassen sich beispielweise Polygone mit 'Löchern' hinzufügen.

=Logs=(31)

Für einen Serverdienst möchte man selbstverständlich Log-Dateien angelegt bekommen. Ein Server läuft die ganze Zeit vor sich hin, sodass man, im Gegensatz zu einer Desktop-Anwendung, im Fehlerfall meistens nicht anwesend ist. Dann sind Protokolle der Serveraktivitäten natürlich notwendig für die Fehlersuche.

Aber auch für den Entwickler sind Logfiles wichtig, zeigen sie ihm doch, wo er nach Ursachen zu suchen hat, wenn sich die Anwendung, an der er arbeitet, nicht so verhält wie erwartet.

Wofür auch immer man seine Logs verwendet, definiert wird die Logdatei in MapServer in der Web-Sektion:

 <code>
WEB
...
LOG "/pfad/zur/datei.log"
END
</code> 

Es gibt nur eine einzige Logdatei pro Mapfile, in der MapServer sowohl Fehlermeldungen als auch erfolgreiche Zugriffe loggen kann.

Das Format für Logfiles ist leider nict dokumentiert, sodass man sich mit einem Blick in den Quellcode weiterhelfen muß\footnote{Siehe Funktion =writeLog= in =mapserv.c= }. Ein Eintrag in einem Logfile sieht beispielsweise folgendermaßen aus:

 <code>
Fri Mar 21 16:02:48 2003,1031,10.0.1.2,demonstration,0, \
7.848750 49.445625 19.098750 55.070625,13.473750 52.258125, \
bundeslaender,normal execution
</code> 

So ein Eintrag erstreckt sich immer über eine einzelne Zeile. Alle Bestandteile sind durch Kommata voneinander getrennt. Die vorliegende Zeile ist im einzelnen wie folgt zu verstehen:

*=Fri Mar 21 16:02:48 2003= Ist ein Zeitstempel; Datum und Uhrzeit des Aufrufs.
*=1031= Die aktuelle Prozess-ID.
*=10.0.1.2= Die IP-Adresse des aufrufenden Hosts. Wird aus der Umgebungsvariable =REMOTE_ADDR= gelesen und ist =NULL= \footnote{Hier ist die Zeichenkette ='NULL'= gemeint}, wenn diese Variable nicht gesetzt ist.
*=demonstration= Der Name des Mapfiles, wie er mit =NAME= im Header gesetzt ist.
*=0= Der Modus des Aufrufes, also z.B. =map= , =browse= und so weiter. Es gibt 26 verschiedene, die allesamt in =maptemplate.h= in einem Aufzählungstyp definiert sind.
*=7.848750 49.445625 19.098750 55.070625= sind die Extents des angezeigten Kartenausschnitts.
*=13.473750 52.258125= Ist der Punkt in der Karte, der angeklickt worden ist. Dieser Punkt hat den Aufruf des MapServers verursacht.
*=bundeslaender= Eine Liste der angeforderten Layer, durch Leerzeichen voneinander getrennt.
*=normal execution= Ist alles glatt gelaufen, findet sich dieser Eintrag am Ende einer Zeile.

Für ausführlicheres Logging gibt es den Parameter =DEBUG= , der im Header, in Layern und in Classes definiert werden kann. Mit dieser Einstellung produzieren bisher allerdings im wesentlichen nur Raster- und WMS-konforme Layer ausführlichere Fehlermeldungen. Es steht zu erwarten, dass dieser Parameter noch weiter ausgebaut wird.

\subsubsection*{Log-Dateien im Webserver}

Neben den Logs des MapServers haben Sie im Fehlerfall natürlich immer noch die Logs Ihres Webservers zur Verfügung. Im Fehlerfall finden Sie hier auch die HTTP-Fehlercodes, die dann nützlich sind, wenn es nicht MapServer-Fehler sind, die Ihnen Probleme bereiten. Insbesondere bei der Apache-Fehlermeldung ''Internal Server Error'' finden Sie normalerweise detaillierte Einträge, die Ihnen helfen können, die Ursache des Problems schnell zu lokalisieren.

=Logging=

Mit Mapserver 5.0 wurden die Möglichkeiten des Loggings erheblich erweitert. Zur Konfiguration sind zwei Punkte zu beachten:

* Die Variable MS_ERRORFILE muss gesetzt werden.
* Auf Map- bzw. Layer-Ebene wird ein Debuglevel gesetzt

'''''MS_ERRORFILE <Wert>'''''

Die Variable MS_ERRORFILE kann entweder mittels Umgebungsvariable oder per CONFIG-Direktive in dem Mapfile gesetzt werden. Die CONFIG-Direktive hat dabei Vorrang, falls beide Möglichkeiten genutzt werden.
Hiermit wird angegeben wohin die Logmeldungen geschrieben werden. Je nach Wert gibt es ''folgende Werte'':
; stderr : Ausgabe wird an die Standardfehlerausgabe gesandt. Bei Apache ist dies die per error_log angegebene Datei. Beim IIS wird es per Standardausgabe ausgegeben.
; stdout : Ausgabe wird an die Standardausgabe gesandt
; windowsdebug : Ausgabe wird an die Windows OutputDebugString API gesandt. Dadurch kann mit Programmen wie Debugview (Microsoft/Sysinternals) die Ausgabe verfolgt werden.
; PFAD : eine absolute Pfadangabe zum Logfile

Wird diese Variable nicht gesetzt, ist das Logging deaktiviert.

Beispiel:

CONFIG "MS_ERRORFILE" "/Pfad/zum/Logfile"

oder

CONFIG "MS_ERRORFILE" "stderr"

Dabei sollten Pfade immer als absoluter Pfad angegeben werden.

'''''DEBUG <level>'''''

Das DEBUG-Level wird entweder global oder auf Layerebene gesetzt. Zur Verfügung stehen ''folgende 6 Level'':
; Level 0 : Es werden ausschließlich Fehler geloggt. Entspricht DEBUG OFF bzw. DEBUG 0
; Level 1 : zusätzlich Warnungen zu nicht-fatalen Fehlern wie z.B. fehlende oder falsche Werte für bestimmte Parameter, fehlende Shapefiles in tileindex oder Zeitüberschreitung bei externen WMS-Diensten
; Level 2 : zusätzlich Hinweise mit Zeitinformationen
; Level 3 : zusätzlich Debugausgaben wie WMS-Verbindungs-URLs, Datenbank-Verbindungs-Informationen usw.
; Level 4 : weitere Ausgaben
; Level 5 : detaillierte Informationen die für Entwickler gedacht sind

Das Debuglevel kann global entweder per Umgebungsvariable MS_DEBUGLEVEL oder im Mapfile gesetzt werden. Werden beide Möglichkeiten genutzt, hat die Angabe im Mapfile Vorrang. Bei der Ausgabe wird für jeden Layer das gleiche Debuglevel genutzt.
Das Debuglevel auf Layerebene überschreibt ein evtl. gesetztes globales Debuglevel. Dadurch kann bis auf Layerebene die Fehlerausgabe individuell eingestellt werden.

Wird die Umgebungsvariable benutzt so werden auch Meldungen z.B. zur Initialisierung ausgegeben die außerhalb von Layer- oder Map-Context erfolgen.

=Includes=

Bei manchen Projekten kann das Mapfile sehr groß werden. Durch die INCLUDE-Direktive kann man die Übersichtlichkeit wieder erhöhen, in dem man einzelne Abschnitte in separate Dateien auslagert. Für hochperformante Mapserveranwendungen wird dieses Vorgehen nicht empfohlen, da ein gewisser Overhead entsteht. Eine Standardanwendung wird bei Verwendung von INCLUDE-Direktiven nicht spürbar verlangsamt.

Beispielaufruf:

INCLUDE "basislayer.map"

Folgende Hinweise sind bei der Verwendung zu beachten:

* Der Name der Datei '''sollte''' in Anführungszeichen stehen
* Die maximale Verschachtelungtiefe beträgt 5
* Die Pfadangabe kann absolut oder relativ zum Mapfile erfolgen
* Die Fehlerverfolgung wird erschwert da z.B. die angegebene Zeilennummer ggf. nicht mehr stimmt

[[Category:UMN MapServer Handbuch]]