Template:OSM Location map/doc

Return to Service, 2024
For a full description of how this template has been able to return to something close to full functionality, and new options now possible, see Template:OSM Location map/Return to service. The documentation below has been updated and includes all the new possibilities, so can be used in conjunction with the above.

Documentation
This template provides
 * A map (from OpenStreetMap) in a frame, for any location, anywhere in the world, at scale from global to an indiviual building.
 * Optional multiple markers, text labels, numbered dots, live wikilinks and other graphical elements.
 * A link (top right corner) to a fullscreen interactive version, which can have 'dots and details' from the article/map.
 * A mini-locator map can be shown to provide context for the map.

Purpose
OSM Location map allows an editor to include a map in a frame with a zoom level appropriate to the topic. A scale marker is provided in the bottom right corner. This is at best a rough guide to the distances on the map, as the map projection results in scale changes depending on the latitude. Allowance has been made for this, but only in large 20 degree chunks.

The multiple marks, images and labels (currently limited to 60, and that might exceed size limits on very large pages) can be a shape or image, include a text label, and potentially 'pointer-lines' and other graphical elements. The fullscreen map on the other hand will show them as pointer marks, which can be given popup thumbnail images and captions, as well as providing links to access other maps and satellite images, and an option to show locations of other articles nearby.

A selection of example maps, along with links to an even wider range if use-types, is at Template:OSM Location map/examples.

Scenario 1: Minimal version
An unadorned map centred on a latitude and longitiude coordinates, via a coord value. Set the zoom to give a scale that fits the subject (0=whole world, 18=a street). With just these options set, all other parameters use the defaults, or are left unused. It also gives a link to the interactive fullscreen version.

Scenario 2: Single marker with text label
A default 'Red pog' marker and accompanying label. Additional items (the last three parameters) don't show up on the page, but give extra information when hovering/clicking on a dot in the fullscreen version.

The mark-title can optionally be wiki-linked, and the dot on the map becomes a live link, even if the page doesn't exist. The label can also be wiki-linked, but as in the case here will display the page that contains a subsection as the live link rather than a picture of the feature as is shown on full screen. It can work well when there is a page on the specific subject.

Multiple markers, labels and images
In addition to the un-numbered mark parameter set, there are 60 numbered ones. These are otherwise identical to the one above, but the name terminates in a number (1-60). Each mark and label has its own set of parameters (mark1, mark-coord1, label1, label-pos1 etc...mark2, mark-coord2, label2, label-pos2 etc.) Values can be inherited either from the 'mark1 master parameter set', or from a special 'markD' Default set that provides override defaults. When set, these values are inherited by the other numbered sets to avoid having to repeat for each, whilst they can still be set individually where required.

Scenario 3: Numbered dots with labels and auto-caption
Source-code for the map can be seen by clicking the 'Edit' link. Some noteworthy points about the numbered-dot map example:
 * The dots are given numbers when  (square, triangle and diamond also available)
 * Depending on use cases, and on the number and density of dots, you might choose not to set some (or any) labels, relying on captions/links/main text to explain which feature is which.
 * To avoid over-writing, a label position can be adjusted in relation to its dot using ldx and ldy parameters to set + or - pixel offsets horizontally and vertically. (Down and right are +ve, up and left -ve).
 * To avoid a crowded area of the map, shape4 uses  to move the label much further away, and add a line linking the label to its shape.
 * Line breaks can be added to any label by adding a ^ symbol wherever needed, to split a long label.
 * By setting, numbered shapes are all listed within the caption, using the 'mark-title' values, which as with shape2 here, might include links or explanations of multiple different items.
 * Instead of a 1, which gives a full-width caption area, this example sets  which requests a column width of at least 14 ems. The template then adds as many columns as that width permits.
 * By default, each dot will be given the same number as its 'mark-number'. If each dot is used in turn the numbers will go in sequence, and will match the numbers on the fullscreen version. Fullscreen numbers always run in sequence from 1 upwards, so if you don't use some mark-numbers, or over-ride them with 'numbered=', the fullscreen dots won't match. But they are self-documenting via their hover/click links, so that is not a problematic outcome, if that is desired.

Flushing Meadows-Corona Park map is a useful real life example in template form.

Inherited values
Each mark and label can be given a unique set of attributes (size, colour, outline, angle, relative position, etc.) To minimise repetition of code, there is a sliding scale of inheritance that applies to each value in each parameter set. For example, if  is set, that will always take precedence. If label-size4 has not been set, it will inherit the value from the special Default setting (defined using ). If no Default has been set, it will inherit the value set by the 'master parameter set',. If that is also undefined it will fall back to the underlying default, which in the case of label-size is 13. The same is true of all the variables relating to marks and labels, (although not to the coordinates, labels themselves, or mark-titles, which are always unique to the particular mark they relate to.)

Scenario 4: Using marks to add graphical elements to the map
Noteworthy Points illustrated by the map of Banwen area:
 * Each of these marks has a very different appearance, and some are sized to be 'map features' rather than markers.
 * Mark-size can be used not just to set width, but also height, by adding a second, comma-separated value. This allows a 'box' to be given a rectangular shape. In the case of 'box' a third value sets a radius for the corners, which gives the rounded corners of the two Roman forts. eg
 * The Marching fort has a transparent colour, so only the outline shows up, set to give a wide, dashed outline.
 * Label-pos2 is set to 'center', so the words appear within the shape, rather than alongside it.
 * There are now various ways to add a line to the map. The Roman road on this map is included by using . A rule has 'shape-outline' attributes, which are all set by  color and line-width are required. Opacity% and 'style' are optional. The style options are solid, dashed, dotted or double.
 * If you look at the fullscreen version, you will only see the first three marks. An item can be excluded by setting, for example.
 * All three of the fullscreen marks here show as white, but for different reasons. Mark-color1 is set to white. Mark-color3 is not defined, (Red pog.svg, being an image item, brings its own color), so the fullscreen dot 'inherits' white from Mark1. Mark-color2 is set to transparent, which shows as white for the fullscreen dot. Adding more diverse items to the map can affect the fullscreen colors, intended or otherwise.
 * This map also shows the county boundary. See the Parameters Section for details of how Qvalues can be used to show 'map-data' lines from OpenStreetMap.
 * 'curveA', an arrow-curve has been added to this (contrived) example. curveC (clockwise version) is also available.

Adding a Minimap in the left or right corner
Many pages with info-boxes already include a locator map showing where the topic or place is located. For those that don't it might be helpful to include one within your map. It is possible to incorporate an existing 'Location map' (from Wikimedia Commons) in a corner of this map.

The width and height of the Location map both have to be decided upon, specified (and calculated so as to not shift the map away from the corner). Some location maps may already highlight the feature, but if not, an optional locator 'pog' can be placed by calculating and specifying the minipog-gx and -gy values, using a 100x100 grid across the minimap. (so gx and gy values of 25 and 50 would place a dot a quarter of the way across and half way down the minimap. It does not pick up or use latitude and longitude values. The origin (0,0) is in the top left of the minimap and the map itself defaults to the bottom right corner, but can also use,   and.

The dot will remain in the right place even if you alter minimap size. (Note, the now redundant minipog-x and minipog-y are retained for compatibility. These used the same pixel dimensions as the width and height of the map, which made them harder to calculate/guess and needed to be re-done if the size was changed. Much better to use gx and gy from here on.)

If the area of the actual map is a large portion of the mini-map, an open red box can be included instead of a dot, to show the bounds of the main map. To use this feature, simply specify the width of the required box:  where xx = the percentage of the minimap width for the box. In general anything much below xx=15 will be better served by a dot. The box will be centered at the coordinates minipog-gx and minipog-gy. The required width will require some trial and error to pin down. The box height is then matched in proportion to the actual map and will scale if the minimap size changes.

Text on an arc
Text for broader geographic features can be placed around an arc, to convey a sense of a broader area, or to follow the curve of a river, mountain range, coastline, etc. This works entirely separately from the other labels. It does not attach itself to any mark or dot, and does not create any fullscreen markers. It requires coordinates for the first letter, parameters for the starting angle, radius of arc and gap between letters. Text size and color can also be specified, or inherited from Default settings.

Alternative marks
Instead of using the standard 'Red pog' for mark points on the map, other images can be used. Any image from Wikimedia Commons can be specified. The Pentre Ifan example above uses 'Archaeological site icon (red).svg'. If a particular image file is specified in, all subsequent marks will use it as well unless they name their own image file. If the image is not square, a dimension value also needs to be set (width ratio for a height of 1)

Transparent overlay
A marker image does not have to be small and opaque. A larger overlay image (with a transparent background) can be used to show particular features not included in the base map, such as a town's former walls (see the adjacent map, whic is using ). Such images can be created in several ways (such as tracing over a copy of the base map); they are invoked like any other marker image file. (For a detailed guide to creating and deploying an overlay for these maps see User:J. Johnson/OSM overlay how-to). (See below more direct ways to show linear graphics.)

Legend/Key/Information panel within the map
This is a new (for 2024) feature, using. It uses the normal coordinate system to place both the top-left corner of the panel, and any marks/explanations that are placed over them (even though they have no real relationship with that point on the map).

With no numbers or labels, the use-case here is showing the scatter of different types of sites. The individual dots can still be 'interrogated' for further information, particularly using the fullscreen version, but only if 'looked for' rather than presented up-front. Different page content will have different needs. A map should aim to show the most relevant information, and editors can make choices on how to best make the map a part of the article's narrative.

(A note on order of drawing: The un-numbered mark is drawn first. Numbered marks are drawn starting with 60 and drawing shape1 last, which is therefore 'on top'. The overlay uses the un-numbered mark, to go below everything else. The panel in this example uses the shape20 set to place it underneath the two legend marks (16 and 17) so that they show on top of it.)

Text color
Color of label text can be specified using. Standard html colors can be specified by name, and any color can be specified using the hex triplets coding #xxyyzz (see Web colors). However, to create a consistent look and feel across the wikipedia maps, there are some OSM Location map specific colors, with a more muted tone range that fit well with the color scheme of the base maps. In general it is best to make use of this range, unless there are good reasons for using other particular shades for specific features. Under normal usage, the following label color scheme should be followed:-

Full table of color options
New to 2024: All colors can have an opacity value as well as the color name. eg  will set a 30% opacity. (The '50%' and 'opacity' parameters are now deprecated. ie they still work, but are not needed anymore)

It is also possible to specify any HTML Hex color using the six-figure hex-code, eg #AAAAAA, but sticking to defaults allows a consistency between pages

If no valid color is specified the color will be set to a default of 'hard grey'

Text, shape and outline opacity
With the 2024 changes it is now possible to easily set the opacity value of any specified color. For 'label-color' and 'shape-color', this is a second, comma-separated value. For 'shape-outline' it is the third item, (it takes color name,line-width,opacity,style). eg  would add a transparent red outline 8px thick around the shape. (Note, the opacity is given as a %. For historical reasons, an opacity of 0 and 100 both give fully opaque colours. To set as entirely transparent, use a value of 1 - or the colour name 'transparent'.)


 * Alternatively: . It is possible to set an opacity value when using #hexvalues instead of just named colours from the HTML color-space. The opacity is an additional two-digit hex value to make an 8 digit #value, with the opacity digits ranging from 00 (opaque) to FF (transparent).

There was previously an option to specify 'Halo' features around shapes. These were rarely used (it at all) and would have made considerable resource demands through the use of multiple additional shapes. With the template size risking difficulties when many dots are used, the halo parameter has been removed for now. Various halo-like effects can be obtained using the shape-outline option.

Text effects

 * multi-line label: Where label text is too long to fit on a single line, using, any line can now be split as many times as desired using the ^ hat symbol. This supersedes the now deprecated   and  . To put an actual ^ in your label, use the   entity.


 * Label with no mark: If  this has the effect of a free-floating label with no marker


 * Angled label: It is possible to specify a, which will pivot the label text around the centre of the marker point by the specified angle. Using an angled label which also has no marker is particularly good for labelling various geographic and linear features. A more characterful alternative is to set the text on an arc, using the ArcText options. For stylistic consistency settlement and building names should not normally be given an angle.


 * Wiki markup: New to 2024, all text is shown as standard wiki text. This means you can use  bold  and  italic  as normal. Wikilinks are also possible, but note that they will then take standard wikilink colors, including red-link for non-existant links.


 * And one for the geeks: if you are desparate to use other fonts or font-effects, you can include elements such as your text here as part of your label. But use with caution and care. the aim is not to overwhelm the map with fancy effects. However, used appropriately it could be just the solution you are looking for - provided you know enough html/css/etc.

Use in infoboxes
OSM Location map can be imbedded in infoboxes which allow the  parameter, for instance infobox school by using the instruction. For an example, see St John Fisher Catholic School which uses the map to show its two sites within an infobox map. Some infoboxes also allow it to be incorporated within the caption below an image. However, this only works if an image and some caption text are also present. (see Inishmore Lighthouse).

Using label text to draw graphic features
With the arrival of various outline and line-drawing features, there is less need to resort to text labels as a way of showing simple graphics. However, for certain cases, some of the many unicode items in the Box Drawing list may be of use.

Comparison with Maplink
Since May 2018 it has also been possible to create a map in a frame via Maplink, which in some respects does a similar job to OSM Location map. In both cases a static map image can be added to an article, for anywhere in the world, pulling in the map from OpenStreetMap data. The differences are in what they can and can't add to the base map. Maplink, in both its framed and fullscreen versions, can add points (numbered or icon-style pointy dots), and various, lines and areas generally imported from OpenStreetMap via wikidata Q values. A large part of its role is in providing an 'automated' map, using wikidata to give quick results, often within an infobox. With OSM Location map the process is much more hand-built, drawing together elements from the article. The framed map can show a much richer selection of dots, shapes, graphics, overlays, images and especially text to convey specific details relevant to a particular article. It has now also been enabled to show Q value (at present limited to boundaries, and roads). The fullscreen equivalent is much closer to a Maplink fullscreen item, re-using as point-items the details supplied for the framed map.

Underlying technology
OSM Location map itself has no map or display ability of its own. Until 2023 everything within the frame was produced through the template Graph:Street map with marks, created by User:Yurik. It made use of the Vega visualisation package which displayed both the base map and a range of text and graphic features. In its original incarnation the result was a rendered bitmap image, making the viewing overhead very low compared to editing, but with a low-resolution output. In 2020, the bitmap creation process was withdrawn, resulting in a much clearer page view, but adding considerably to the resource overhead.

In April 2023 the Vega package was withdrawn, along with all of its 'graph' dependencies, amid security concerns. After a protracted period of uncertainty (still unresolved as of April 2024) a way was found to replicate the outcomes previously handled by 'graph'. By making use of Extension:Kartographer, through its tag, the base map could be displayed within an html  element. Iinline CSS coding could then be used to show the graphics and text within the resulting frame. The Mercator 'coords' are converted to x,y pixel values to match the map location and zoom level. This switch not only got the existing stock of 5,600 templates back in a working state, but also allowed the implementation of additional graphical items, as well as gaining a more standard use of wikimarkup and wikilinks.

The full screen option, which can be clicked through from the framed map, provides an entirely different mapping approach, although also using Kartographer to access the OSM base-map data. This uses to provide a fullscreen interactive map that can be panned and zoomed. It also replicates (as numbered markers) the various marks and colors from the framed map. These can then be given extra content, by way of a title, image and description, along with displaying the coordinate values. The result is a map-based page that offers another way of engaging with the article content.

Further development of mapping technology is currently not a Wikimedia Foundation priority area. Having established maplink, which initially just created a text link to a full-screen map, to the point where it provides a framed image with data directly from wikidata, there are no active developments for different mapping solutuions. (Please tell us if you know differently!). The processor overheads are reduced by showing a static image in the frame, which can be clicked to become interactive in fullscreen. Maplink is now effectively rolled out within info-boxes, where the map is automatically generated from already available data.

This template is geared rather to producing a hand-editable map, in which the area displayed and the selection of items and labels included are selected, edited, and added to, to suit the specifics of the subject in hand. A further approach, which is not currently supported by any mapping template, is to draw the data from external live data, such as using a SPARQL query, to generate, for example large-area scatter-plots to show different distributions across a map. The security and maintainability aspects of such tasks, as with other graph visualisations of live data, are a major barrier to implementation.

The technology used here (Kartographer plus inline-css) is probably best described as 'reasonably well developed'. As of late April 2024 it would seem to be in a stable and sustainable state, so should not see the kind of hiatus experienced by 'Graph' in 2023. It is highly likely that this or a comparable solution will still be available into the future. Of the possible evolutions over time one may be through svg-based graphics, allowing a richer graphical content and maybe even moving towards a proper visually-based editing environment. In the opposite direction, there is a demand for maps that can show more dots with less resource impact, perhaps by paring back on the feature set. But these should most likely be seen as alternatives rather than replacements for this template.