Hilfe:Erweiterung »WorldMap«/wmap

Wiimm hat eine Mediawiki-Erweiterung namens »WorldMap« für dieses Wiki erstellt. Ein Teil dieser Erweiterung erzeugt aus einer Gesamtkarte der Welt und einer Liste von Optionen Teilkarten mit Markierungen. Für die Positionsangaben wird ein kartesisches Namensschema verwendet, so dass die tatsächliche Größe der Gesamtkarte für die Referenzen keine Rolle spielt.

»WorldMap« bietet hierfür 2 Schnittstellen an:

• Die HTML-Markup-Sprache wird durch den Tag (aus dem englischen, ausgesprochen: tæg) <wmap ... /> ergänzt. Diese zuerst entwickelte Schnittstelle zeigt aber Probleme bei der Verwendung mit Vorlagen. Dieses liegt Hauptsächlich an der Verwendung von Gleichheitszeichen und Anführungsstriche, die sowohl for Tag-Attribute als auch für Vorlagen Sonderbedeutungen haben.
• Die neue Parser-Funktion {{#wmap: ... }} ist eine Alternative zur HTML-Erweiterung. Wegen der höheren Flexibilität können Ersatzzeichen verwendet werden. Dieses vereinfacht die Verarbeitung in Vorlagen erheblich.

Syntax

HTML-Markup-Sprache

Für die HTML-Markup-Sprache gilt die folgende generelle Syntax:

<wmap attrib1="wert1" attrib2="wert2" ... />

Die Anführungszeichen werden nur benötigt, wenn ein Wert Leerzeichen oder andere Zeichen mit spezieller Bedeutung enthalten. Siehe hierzu auch die Beispiele.

Parser-Funktion

Für die Parser-Funktion gilt die folgende generelle Syntax:

{{#wmap: attrib1=wert1 | attrib2=wert2 | ... }}
{{#wmap: attrib1:wert1 ! attrib2:wert2 ! ... }}

Wichtig ist, dass die einzelnen Attribute durch ein Pipe-Zeichen (»|«) oder durch ein Ausrufezeichen (»!«) voneinander getrennt sind. Beide Zeichen können auch gemischt verwendet werden. Das Ausrufezeichen hat den Vorteil, dass es keine Parameter beim Aufruf von Vorlagen trennt. Anführungszeichen werden nicht benötigt und sollen auch nicht genutzt werden, da alles bis zum nächsten Trennzeichen zum Attribut gehört.

Außerdem kann der Doppelpunkt (»:«) als Alternative zum Gleichheitszeichen (»=«) verwendet werden. Auch dieses vereinfacht die Nutzung mit Vorlagen, bei denen das Gleichheitszeichen eine Sonderbedeutung hat.

Attribute

Attribute der Erweiterung

Attribut	Parameter	Standard- wert	Beschreibung
pos	text		Die Positionsangabe. Dieses Attribut muss angegeben werden. Siehe unten für Details und Beispiele.
point	name		Falls gesetzt, dann wird die durch pos gesetzte Fläche auf eine Punkt reduziert. name ist dabei die Abkürzung einer Himmelsrichtung (z.B. »@@w« oder »@@se«) um einen der 8 Randpunkte zu wählen. Für den Osten ist sowohl »e« für »east« als auch »o« für »Ost« möglich. Alternativ selektiert »@@mid« für das Zentrum des Rechtecks. Diese Option hat dieselbe Wirkung wie »@@name«.
mode	name	raw	Der Darstellungsmodus. Siehe unten für Details.
map	name	default	Name für die Verwendete Karte bzw. Kartensammlung. Siehe unten für Details.
scale	scale xscale[,yscale]	1, 1	Der Kartenausschnitt wird um den Faktor scale (Fließkommazahl) vergrößert. Werte zwischen 0.0 und 1.0 sorgen für eine Verkleinerung. Wird nur ein Wert angegeben, dann wird dieser für beide Richtungen genutzt.
grow	grow xgrow[,ygrow]	0, 0	Der Kartenausschnitt wird um grow Zellen (Fließkommazahl relativ zur Größe eines Feldes) vergrößert, wobei auch negative Werte für Verkleinerungen möglich sind. Wird nur ein Wert angegeben, dann wird dieser für beide Richtungen genutzt.
width	int	500	Breite des Bildes inklusive des Rahmens (border=). Bei Werten >0 wird die Karte je nach Bedarf vergrößert oder verkleinert. Bei negativen Werten wird der Absolutwert als maximale Größe verwendet und Karten nur verkleinert.
grid	mode[,maxwd][,color]		Mit dem Attribut wird ein Gitternetz der Farbe color aktiviert. Wird keine Farbe angegeben, dann wird eine Standard-Farbe verwendet. Diese Standard-Farbe ist abhängig von der ausgewählten map. mode legt den Modus fest. »a« oder »auto« aktivieren einen automatischen Modus. Der Wert »0« schaltet das Gitternetz ab. Werte >0 legen die Verfeinerungs-Ebene fest, für die noch Gitterlinien gezeichnet werden sollen. Die Werte 1 bis 4 bedeuten, dass Quadrate der Verfeinerungsebenen 0 bis 3 mit Linien versehen werden. Allerdings gibt es einen Grenzwert, so dass der Linienabstand mindestens 10 Pixel beträgt. Im automatischen Modus ist der Mindestabstand 20. Beide Werte werden ggf. noch geändert. maxwd legt die maximale Strichbreite in Pixel fest. Das kleinste Raster wird mit Strichbreite 1 gezeichnet, das nächst-größere mit 2, dann mit 3 usw. Allerdings wird die Strichweite den Wert maxwd nicht übersteigen, so dass maxwd=1 für eine einheitliche Strichbreite sorgt. Ohne Angabe wird der Wert 2 verwendet.
rect	pos,wd,color [;pos,wd,color] ...		Um den Kartenausschnitt pos wird ein Rechteck mit Linienstärke wd und Farbe color gezeichnet. Wird für den Kartenausschnitt pos ein Stern (*) angegeben, dann wird der Kartenausschnitt des Attributes pos verwendet. Dieses ist sinnvoll in Verbindung mit den Attributen scale oder grow. Die Mitte der Linie liegt auf dem Grenzbereich von pos. Wird der Linienstärke wd ein Kleinerzeichen (<) vorangestellt, dann befindet sich die Linie vollständig im Kartenausschnitt. Wird ein Größerzeichen (>) vorangestellt, dann befindet sich die Linie außerhalb des Kartenausschnitts. Es können beliebig viele Rechtecke definiert werden. Dazu werden mehrere durch Semikola getrennte Einzel-Definitionen angegeben.
ellipse	pos,scale,wd,color [;pos,scale,wd,color] ...		Um den Kartenausschnitt pos wird eine Ellipse mit Linienstärke wd und Farbe color gezeichnet. Wird für den Kartenausschnitt pos ein Stern (*) angegeben, dann wird der Kartenausschnitt des Attributes pos verwendet. Dieses ist sinnvoll in Verbindung mit den Attributen scale oder grow. scale gibt des Skalierungsfaktor für die beiden Radien an. Bei einem neutralen Faktor von 1 liegt die Linie in den vier Hauptrichtungen auf den vier Seiten des Rechtecks. Die Ecken liegen dadurch außerhalb der Ellipse. Es können beliebig viele Ellipsen definiert werden. Dazu werden mehrere durch Semikola getrennte Einzel-Definitionen angegeben.
circ	pos,scale,wd,color [;pos,scale,wd,color] ...		Um den Kartenausschnitt pos wird ein Kreis mit Linienstärke wd und Farbe color gezeichnet. Wird für den Kartenausschnitt pos ein Stern (*) angegeben, dann wird der Kartenausschnitt des Attributes pos verwendet. Dieses ist sinnvoll in Verbindung mit den Attributen scale oder grow. scale gibt des Skalierungsfaktor für den Radius an. Es können beliebig viele Kreise definiert werden. Dazu werden mehrere durch Semikola getrennte Einzel-Definitionen angegeben.
border	wd[,color]	0	Es wird ein Rahmen um die Karte mit Linienstärke wd und Farbe color gezeichnet. Dabei wird die eigentliche Karte verkleinert. Der Rand kann nicht größer als 1/4 der Bildbreite (width=) sein. Wird keine Rahmenfarbe angegeben, dann wird eine Standard-Farbe verwendet. Diese Standard-Farbe ist abhängig von der ausgewählten map.
align	name		Ist der Name left oder right, dann wird das Bild als floating image an den linken oder rechten Rand gestellt. Alle anderen Werte werden ignoriert.
type	type	image	Die Option legt die Art der Darstellung fest. Ist der Typ »link«, dann wird align ignoriert und ein HTML-Link auf die Karte erzeugt. Ist der Typ »url«, dann wird nur die URL und bei »relurl« die relative URL ohne Domain als Ergebnis geliefert. Anderenfalls wird die Karte angezeigt.
zoom	width[,mult][,add]	0	Ist width>0, dann ist der Kartenausschnitt anklickbar. Hinter dem Links verbirgt sich eine Karte mit der Breite width, wobei diese ein Stück breiter als das Original sein sollte. Mit den beiden anderen Parametern kann man den Kartenausschnitt vergrößern. Er vergrößert sich um den angegeben Faktor und um den abgegebenen Additionswert. Strichbreiten und Radien der anderen Attribute werden maßstabsgetreu umgerechnet. In Verbindung mit type=link, type=url und type=relurl wird dieser Zoom-Link verwendet. Die Vorlage:map-std verwendet die Einstellung »zoom=800,,0.5«.
debug	int	0	Falls >0, dann wird kein Bild, sondern eine textuelle Kontrollausgabe erzeugt. Diese Ausgabe wird auch bei einem Fehler erzeugt. Ist der Wert jedoch <0, dann erfolgt im Fehlerfalle keinerlei Ausgabe.

Die Operationen werden in dieser Reihenfolge ausgeführt:

• scale, grow, width, grid, rect, ellipse, circ, border

Attribut »pos«

Feldnamen (Koordinaten)

Mit »pos« wird die Position angegeben. Dazu ist die Karte vertikal in 20 Streifen unterteilt, die als D bis W benannt sind. Die restlichen 6 Buchstaben sind als Reserve eingeplant, falls noch bisher unbekannte Gebiete dazukommen.

Die Spalten werden mit Nummern beginnend bei 10 bezeichnet. Ein einzelnes Feld, wie z.B. »R20« ist quadratisch. Daher ergibt sich die tatsächliche Anzahl der Spalten aus dem Seitenverhältnis der Karte (siehe auch »Hilfe:Kartografie«).

Die Abbildung rechts verdeutlicht das Namensschema. Bei den roten Markierungen handelt es sich um die Felder D10, I20, R30 und K40.

Verfeinerung der Position

Gibt man nun ein Feld mit Namen an, dann ist die gesamte Fläche selektiert. Um kleinere Bereiche zu wählen, kann man hinter der Zahl einen Buchstaben anhängen, z.B. »R20g«. Damit wird das selektierte Feld auf ein Teilfeld verkleinert. Die Bedeutung der Buchstaben kann dem Bild rechts entnommen werden. Dieses Verfahren nennt sich hier »Verfeinerung des Position«.

Die Verfeinerung kann auch mehrfach angewendet werden. So bedeutet z.B. »R20gxb«: Feld »R20«, davon Teilbereich »g«, davon Teilbereich »x« und davon Teilbereich »b«.

Punkte

Auf obige Art wird immer eine quadratische Fläche selektiert. Es besteht aber auch die Möglichkeit, die Fläche auf einen Punkt zu reduzieren. Dazu hängt man an die Positionsangabe ein AT-Symbol (»@«) gefolgt von der Abkürzung einer Himmelsrichtung (z.B. »@n« oder »@sw«) um einen der 8 Randpunkte zu wählen. Für den Osten ist sowohl »e« für »east« als auch »o« für »Ost« möglich. Alternativ selektiert »@mid« für das Zentrum des Quadrates. Vergleiche hierzu die Abbildung recht.

Ein Punkt hat übrigens eine Weite und und Höhe von jeweils 0.

Rechtecke

Bisher wurde eine quadratische Fläche oder ein einzelner Punkt selektiert. Man hat aber auch die Möglichkeit, beliebige Rechtecke anzugeben. Dazu gibt man zwei Postionen der gegenüberliegenden Ecken an, die mit einem Minuszeichen getrennt sind, z.B. »R20g-R21x«. Das Programm ermittelt nun das kleinste mögliche Rechteck, welches beide genannten Positionen enthält.

Die Erweiterung ist sogar so tolerant, dass es Eingaben wie z.B. »R22-S21-T23« zulässt. Tatsächlich können beliebig viele Positionen durch Minuszeichen getrennt angegeben werden. Jede Position wird dann einzeln berechnet um letztendlich das kleinste mögliche Rechteck zu bestimmen, welches alle genannten Positionen enthält.

Punkte eines Rechtecks

Auch von einem selektierten Rechteck kann man einen Punkt auswählen. Dazu hängt man an die Positionsangabe ein doppeltes AT-Symbol (»@@«) gefolgt von der Abkürzung einer Himmelsrichtung (z.B. »@@w« oder »@@se«) um einen der 8 Randpunkte zu wählen. Für den Osten ist sowohl »e« für »east« als auch »o« für »Ost« möglich. Alternativ selektiert »@@mid« für das Zentrum des Rechtecks. Vergleiche hierzu die Abbildung weiter oben.

Vordefinierte Gebietsnamen

Anstatt eine Positionsangabe durch Koordinaten anzugeben, können auch vordefinierte Gebietsnamen verwendet werden. Wegen der Unterscheidbarkeit beginnen diese mit einem Unterstrich. So kann man z.B. »_hyrule« anstatt »J18ml-R25k« oder »J18.2.48-R26.0.4« angeben. Für diese Art der Auswahl sind auch die Optionen scale und grow gedacht. So kann die Umgebung des Zielgebiets angezeigt werden, z.B. mit »pos=_hyrule grow=0.5«.

→ siehe Hilfe:Liste der vordefinierten Gebiete

Punkte durch Dezimalbrüche

Neben der Verfeinerung mit Kacheln sind auch Dezimalbrüche möglich. Die Syntax ist »FELD.X.Y«. Mit »FELD«  wird eine Position ausgewählt, wie sie oben beschrieben ist. Dann wird der Punkt ausgewählt, der innerhalb des Feldes an relativer Position »0,X« (horizontal von links nach rechts) und »0,Y« (vertikal von oben nach unten liegt). Die Null vor dem Komma wird automatisch hinzugefügt. Wichtig ist, dass so ein Punkt anstatt einer Fläche selektiert wird.

So bedeutet z.B. »R10.5.25«: Nimm das Feld »R10« und bestimme den Punkt, der horizontal bei 50% (0,5) und vertikal bei 25% (0,25) liegt.

Diese Dezimalbrüche lassen sich auch zusammen mit Gebietsnamen verwenden. So ist z.B. »_hyrule.5.5« der Mittelpunkt von Hyrule.

Beispiele für Positionsangaben

Position	Beschreibung	Kartenausschnitt
R11	Hier wurde Feld »R11« ausgewählt. Der blaue Rahmen zeigt den ausgewählten Bereich.
R11b	Dieses Beispiel zeigt eine Verfeinerung der ersten Stufe.
R11bx	Und hier folgt eine Verfeinerung der zweiten Stufe.
R11b -R12d -R11f	Dieses Beispliel zeigt die Berechnung des kleinsten Rechtecks (blau) um die drei einzelnen Positionen (rot).
R11.3.25 -R11.7.75	Dieses Beispiel zeigt die Verwendung von Dezimalbrüchen.
_hyrule	Dieses Beispiel zeigt die Verwendung eines vordefinierten Gebietsnamen.

Attribut »mode«

Mit dem Attribut »mode« wird die Art der Darstellung bestimmt. Im Moment ist nur Modus raw möglich.

Attribut »map«

Mit dem Attribut »map« wird die Basiskarte ausgewählt. Im Moment wird nur eine sinnvolle Karte (default) sowie 4 weitere Karten zur Demonstration und für den Test angeboten:

verfügbare Karten

Name der Karte	Beschreibung	Muster mit Standardfarbe
default	Standard-Karte.
test0l	Eine Karte zum Testen der Karten-Software und für Beispiele. Im Original ist jedes Kleinstfeld 5x5 Pixel groß. Jedes rote, gelbe, blaue und lila Quadrat ist 25x25 Pixel groß und jede rot/gelb- und blau/lila-Kombination 125x125 Pixel. Letzteres entspricht einem Hauptfeld (z.B. R21). Das »l« am Ende steht für »light«, da es die hellere Variante von 2 sonst identischen Test-Karten ist (siehe test0d).
test1l	Eine weitere Karte zum Testen der Karten-Software und für Beispiele. Sie ist identisch zur Basiskarte test0l, die Hauptfelder sind aber zur Orientierung zusätzlich beschriftet.
test0d	Eine Alterntive zur Karte test0l. Das »d« am Ende steht für »dark«, da es die dunklere Variante (kräftigere Farben) von 2 sonst identischen Test-Karten ist.
test1d	Eine weitere Karte zum Testen der Karten-Software und für Beispiele. Sie ist identisch zur Basiskarte test0d, die Hauptfelder sind aber zur Orientierung zusätzlich beschriftet.

Beispiele

Für die Kartenausschnitte sollte üblicherweise eine der beiden Vorlagen »Vorlage:map-std« oder »Vorlage:map-link« verwendet werden. So wird der homogene Einsatz der Weltkartenausschnitte gewährleistet. Dieses bezieht den größeren Ausschnitt nach Anklicken des Bildes mit ein. Die folgenden Beispiele nutzen dagegen direkt die Erweiterung.

Veränderte Kartenausschnitte

<wmap align=right width=200 border=2 pos=L11-K13 map=test1l />

Rechts sieht man einen Kartenausschnitt, der aus 6 ganzen Zellen besteht. Zur Erinnerung: Die Größe der Zellen ist so gewählt, dass die Karten vertikal in 20 Reihen aufgeteilt ist.

Man erkennt, dass es bei Bereichen unerheblich ist, in welcher Ecke man beginnt, da das kleinste Rechteck errechnet wird, in dem alle genannten Felder enthalten sind.

<wmap align=right width=200 border=2 pos=L11-K13 map=test1l scale=1.2 />

Hier haben wir dieselbe Karte, wobei der Kartenausschnitt um den Faktor 1.2 vergrößert wurde (scale=1.2).

{{#wmap: align:right ! width:200 ! border:2 ! pos:L11-K13 ! map:test1 ! scale:1.2,0.8 }}

Es besteht auch die Möglichkeit, den horizontalen und vertikalen Skalierungsfaktor getrennt einzugeben. Hier bewirkt yscale:0.8 einen schmaleren Ausschnitt in vertikaler Richtung.

{{#wmap: align:right ! width:200 ! border:2 ! pos:L11-K13 ! map:test1 ! grow:0.2 }}

Anstatt scale als multiplikative Skalierung kann man auch kann grow für eine additive Skalierung des Kartenausschnitts verwenden.

{{#wmap: align:right ! width:200 ! border:2 ! pos:L11-K13 ! map:test1 ! grow:0.2,-0.2 }}

Auch hier sind getrennte Angaben für horizontal und vertikal möglich. Bei negativen Werten wird der Ausschnitt verkleinert.

Markierungen

<wmap align=right width=200 border=2 pos=L11-L13 map=test0l rect=L11h-L11s,3,blue ellipse=L12h-L12s,1,3,black circ=L13h-L13s,1,3,green />

Es besteht die Möglichkeit, Bereiche durch einen Rahmen zu markieren. Dabei stehen Rechtecke, Ellipsen und Kreise zur Verfügung.

{{#wmap: align=right ! width=200 ! border=2 ! pos=L11 ! map=test1l ! grow=0.2 ! rect=*,3,blue }}

Wird als Position pos ein Stern (»*«) angegeben, dann wird der ursprüngliche Kartenteil vor der Skalierung umrahmt. In diesem Beispiel wurde das das Feld mit grow=0.2 vergrößert.

{{map-std | Q21.48.48 | align:right }}

Um einzelne Orte zu markieren kann die Vorlage map-std verwendet werden. Größe und Skalierung sind hierbei fest vorgegeben.

Rahmen

<wmap align=right width=200 border=15,green pos=L11a-L11p map=test0l />

Auch der Rahmen eines Bildes ist veränderbar. Dabei gibt man die Pixel-Größe des Randes und die Farbe an. Die Nutzfläche des Bildes verkleinert sich um die Rahmenbreite.

{{#wmap: align=right!width=200!border=15!pos=L11a-L11p!map=test0l!grid=a}}

Ohne die Angabe einer Rahmen-Farbe wird eine Standard-Farbe verwendet. Diese Standard-Farbe ist für jede Basiskarte getrennt definiert und bietet einen guten Kontrast zur restlichen Karte. Hier wurde auch ein Gitternetz eingezeichnet.

Konkretes Beispiel

{{#wmap: align=right ! width=200 ! border=3 ! pos=Q19rm-S22 ! map=nelde0 ! ellipse=r20t-s23g,1,2,red }}

Hier wird die Große Hochebene angezeigt und der Tempel der Zeit inklusive Schriftzug durch eine rote Ellipse markiert.

{{#wmap: align=right ! width=200 ! border=3 ! pos=Q19rm-S22 ! map=nelde0 ! ellipse=r20t-s23g,1,2,red ! grid=auto }}

Und hier die selbe Karte mit Gitternetz.

Technische Umsetzung

Das Script map.php, welches den Kartenausschnitt erstellt, arbeitet logisch wie folgt:

1. Zuerst werden alle Parameter und Optionen eingelesen und ausgewertet.
2. Aus den Parametern und Optionen wird ein eindeutiger Dateiname für den Cache berechnet.
3. Falls die Datei im Cache-Verzeichnis existiert, dann der Inhalt als PNG-Datei ausgeliefert und die Bearbeitung beendet.
4. Die Basis-Karte wird geladen, beschnitten und skaliert.
5. Alle durch Optionen festgelegten Elemente werden nacheinander eingezeichnet.
6. Die Karte wird ein Temp-Verzeichnis mit einem eindeutigen Namen gespeichert. Dieses verhindert Probleme mit der Nebenläufigkeit, falls 2 oder mehr Prozesse gleichzeitig dasselbe Abbild erzeugen.
7. Die temporäre Datei wird in das Cache-Verzeichnis verschoben. Da Temp- und Cache-Verzeichnis sich auf der selben Daten-Partition befinden, ist das Verschieben eine atomare Operation. Dieses ist wegen der Nebenläufigkeit wichtig.
8. Der Inhalt der neuen Datei wird als PNG-Datei ausgeliefert.

Aussicht

Es gibt schon mehrere Ideen für zukünftige Erweiterungen. Einige lassen sich aber erst nach Erstellung einer echten Karte ohne Verzerrungen realisieren:

• Unterstützung von Grafik-Ebenen um bestimmte Dinge einzublenden.
• Eine interaktive Karte zum genauen Lokalisieren von Objekten und Gebieten.