OGF:Using the MultiMaps extension

From OpenGeofiction Encyclopedia
Jump to: navigation, search

The MultiMaps extension is a powerful tool that can be used on any wiki page to highlight locations on the OGF map, tell a story through maps, or to display collaborative efforts. This page will highlight some of the ways the MultiMaps extension can be used.

About Extension:MultiMaps

The MultiMaps extension for wiki markup allows displaying dynamic maps on pages within the OGF wiki. It is a simple code structure that allows the user to define the size of the map, its level of zoom, and place dynamic elements like lines and markers. The original wiki documentation can be found on MediaWiki.

Map basics

A basic map can be placed by including the initial code like a template, and 6 basic attributes. A sample code might look like this: {{#multimaps: | center = 45.0,28.8 | width = 450px | height = 575px | zoom = 7 | maxzoom = 19 | minzoom = 1 }}. The following table shows you how each of these properties of the code breaks down. The sample listed is shown in the table.

Property Explanation Example Map
{{#multimaps: Like starting a template, this is the "magic word" that starts the map generation process.

Loading map...

| center = 45.0,28.8 This sets the center location on a map. The first number is the latitude in degrees and the second number is the longitude. The numbers are separated by a comma, can be positive or negative, and can include decimals as needed.
| width = 450px The width and height properties set the size of the map on the wiki page. Both are numerical values in pixels (px). The map at right has a pixel width of 480px and a height of a slightly larger 550px. The size of the map you desire changes depending on where it fits on your page.
| height = 575px
| zoom = 7 This sets the default zoom of the map. Be careful here! The zoom is equal to what is seen on the OGF map but only within the size you defined above. Compare the image of Roantra at right with how it appears on the map. The zoom level is the same, but your browser size may be larger or smaller than the map you have on the wiki page.
| maxzoom = 19 The maxzoom and minzoom properties tell the wiki map how far in or out someone can zoom on that map. The maxzoom is the furthest in the map should be able to zoom. It must be number ≤19. Minzoom is the furthest out the map should be able to zoom and must be a number ≥1. These restrictions are useful depending on how you want the map to function.
| minzoom = 1
}} Like templates, the two braces are needed to close out the syntax. Without it, the MultiMap will not work properly.

You might have noticed that on the map, there are icons in the upper corners. The upper left icons (+ and -) allow the user to zoom. The icon in the upper right allows the user to switch the style layers. Here, you can toggle between the main OSM-style map, the topographic map, and the "Histor" version. Clicking on these, however, does not change them permanently. The map generates with the OSM style by default.

Shortcuts for finding coordinates of a location: You can easily find the exact location by right clicking on the OGF map and selecting "centre map here." This feature centers the map on your location and updates the coordinates in the status bar of your browser. Be sure, however, to replace the slash with a comma if copying the location and pasting it into the multimap markup. For users that prefer JOSM, you can find the exact coordinates of a node by simply selecting it. Its coordinates appear in the selection pane on the right side of the screen.

Adding more elements to the map

Once a basic map is placed, it is easy to add additional elements to mark or highlight different things. Every element can be customized to some degree. A basic blue marker is the easiest to place, but it may not meet the needs of what you want to show. Often times, a combination of elements can produce a very powerful map. Elements are highly customizable and share many of the same parameters. In adding any element, please make sure the parameter syntax is completely correct, or the map will not render properly.

To place an element on the map, add the appropriate code on a new line before the two closing braces (}}) listed above. To add multiple elements, see the section below.

Markers

Loading map...

A basic blue marker can be placed by adding the following syntax:

{{#multimaps:
[…]
| Marker = Coordinates ~ Title ~ Text ~ Icon
}}

Like the pipe (|) that separates the elements and properties in a template or MultiMap, the tilde (~) separates the parameters of the individual element. The only required parameter is "coordinates." This is placed as a series of numbers separated by a comma, as you did with the map center above. For example, a marker may be placed on Tulip Hill in Gobras City to highlight its location. This is seen at right. The syntax for the marker is | marker = 20.70831,86.67670 ~Title=Tulip Hill ~Text=Hill in Gobras City Botanic Gardens. To see the title and subordinate text, click on the marker.

Loading map...

Can markers be customized? Yes! Any image can be turned into a marker, but icons of about 20–25px in size are best. The reason is that images cannot be resized within the MultiMap. Some existing icons can be found here. To use an icon as a marker, simply add the image location to icon parameter of the marker syntax. For example, the map at right highlights the location of the Khaiwoon International Airport with a red marker found at File:Marker-airport2a.png. The syntax for this marker is | marker = 18.5904,89.6062 ~Title=Khaiwoon International Airport ~Icon=Marker-airport2a.png Notice that the "File:" portion of the wiki location is dropped from the image name.

The code can be written in an alternate way without the parameters defined. You have to remember, however, that the syntax order is really important. The MultiMap will always process the information in the order listed above (coordinates, title, text, icon). The marker placed on Tulip Hill would simply be | marker = 20.70831,86.67670 ~Tulip Hill ~Hill in Gobras City Botanic Gardens. All that is defined are the coordinates, title, and text—in that order. This shorthand can be useful, but it can cause problems if the "title" or "text" parameter needs to be skipped. In those cases, it is usually best to define the parameters.

Circles and rectangles

Loading map...

Like markers, circles and rectangles can be placed on a map. These items involve more parameters and can be customized in many different ways. The code for each contains 10 parameters. Although, the two operate the same, as 9 parameters work the exact same way.

Circles
A circle can be drawn by defining the parameters of the following syntax:

{{#multimaps:
[…]
| Circle = Coordinates : radius ~ Title ~ Text ~ Color ~ Weight ~ Opacity ~ FillColor ~ FillOpacity ~ Fill
}}

The circle at right has the syntax | circle = 19.6187,93.9956 :5000~Title=Sankt Theodorus ~Color=red ~Weight=5 ~Opacity=1 ~FillColor=#ff6600 ~FillOpacity=0.5 Like markers, the title and text parameters are seen in a popup box when the circle is clicked. The coordinates dictate the center of the circle, and the radius sets the size. Color, weight, and opacity define the outer line of the circle. The final three parameters dictate how the circle is filled in. Here are some guidelines to consider:

  • The radius, always after a colon, defines how big the circle is. The number put in states how many meters it is from the center to the outside of the circle. Notice that there is no space between the radius number and the next tilde!
  • Colors can be defined by name or by hexadecimal color number. (This example illustrates both.)
  • The weight parameter is in pixels, but the unit of measurement is never typed in.
  • The opacity parameter must be a number defined as 0 ≤ n ≤ 1. 0 means that the line is invisible, and 1 means that it is not opaque at all.
  • The fill parameter is best defined as "yes" or "no." If the parameter is left blank, the circle is assumed to be filled. If the parameter is defined as "no," the circle is unfilled.

Loading map...

Rectangles
The syntax of a rectangle is nearly identical to that of a circle:

{{#multimaps:
[…]
| Rectangle = Coordinates : Coordinates2 ~ Title ~ Text ~ Color ~ Weight ~ Opacity ~ FillColor ~ FillOpacity ~ Fill
}}

The biggest difference is found in the first two parameters. Unlike a circle, the "coordinates" parameter does not define the center of the element. Instead, it defines one of the outer corners. The second coordinate parameter defines the opposite corner. For example, the syntax for the rectangle showing the Darcodian Sea is | rectangle = 42.066,114.829 :52.576,130.642 ~Title=Darcodian Sea ~Color=#00008B ~Weight=5 ~Opacity=0.5 ~Fill=no The first coordinate places the southwest corner of the rectangle, while the second coordinate indicates the northeastern corner. It does not matter in which order they appear or which corners are chosen so long as they are opposing (NW–SE, NE–SW, etc.). Also, in this instance, note that the rectangle is unfilled. The fill parameter is used here in contrast to the circle shown above. The line also has an opacity of 0.75, which allows you to somewhat see through it.

Lines

Loading map...

Lines follow a simple syntax by defining points along the line. Like rectangles, multiple coordinates are used. There is not a limit to how many points can be placed, but the line is defined by the order of coordinates. All coordinates are separated by a colon.

{{#multimaps:
[…]
| Line = Coordinates : Coordinates2 [: Coordinates3 : Coordinates 4 etc.…] ~ Title ~ Text ~ Color ~ Weight ~ Opacity
}}

The line at right only has two points plotted, and this is the minimum needed for a line. The syntax for this particular example is quite simple and straight forward: | line = -68.47982,14.88138 :-68.49488,14.94492 ~Title=Runway at Latina Scientific Station ~Color=#000000 ~Weight=7 ~Opacity=0.5 The biggest thing to remember is that the line will generate using the coordinates in the order they are listed. Whichever point is listed first and last become the two endpoints of the line.

Polygons

Loading map...

Polygons are the most complicated but also most powerful element that can be added to a map. In effect, the syntax operates like a line for the coordinates and a circle or rectangle for everything else. All polygons must include at least three points, and like lines, polygon points are generated in the listed order.

{{#multimaps:
[…]
| Polygon = Coordinates : Coordinates2 : Coordinates3 [: Coordinates 4 etc.…] ~ Title ~ Text ~ Color ~ Weight ~ Opacity ~ FillColor ~ FillOpacity ~ Fill
}}

The polygon at right shows an approximate outline of the country Drevet. This particular polygon has 27 unique points. The first and last point are the same location, which closes the shape. A sample of the code illustrates the similarities to lines and other closed shapes: | polygon = 22.0205002,3.4932476 :21.0403873,3.6970326 :20.520103,3.6999939 :20.0346816,3.5184839 :19.5194485,3.5282723 :19.6566855,5.0634525 :18.9663282,4.7141325 […] :22.0245456,4.296875 :22.0205002,3.4932476 ~Title={{Drevet}} ~Color=#990066 ~Weight=1 ~Opacity=0.25 ~FillColor=#990066 ~FillOpacity=0.25

Getting the points for a polygon can be tedious and time consuming. There are ways to extract them from OSM data, JOSM, and other means. The amount of detail you desire depends on the context of the MultiMap and level of zoom.

One possibility to extract the points of a relation is to use the Relation Area Calculator. Just type in the relation number you want to extract and press enter. After the relation is selected it is shown on the map. Select "Multimap" and open/download the file with the nodes.

General tips

The best advice is to take your time and make the map look how you want it. One way to do this is to use the "show preview" function on the wiki editing page instead of immediately saving the changes. This allows you to sample how the map (and all other content) appears. From there, you can scroll down and continue to make adjustments as needed.

Next, multiple elements can be placed on a single map. Keep in mind, however, that the MultiMap is rendered in the order of the syntax. If two objects overlap, the second one in the code will appear on top of the first.