Bản mẫu:Bản đồ định vị OSM/doc

This template provides a map in a frame, for any location and scale. At its simplest it shows the OpenStreetMap image and a scale indicator for a given region of the globe. Optionally locations on the map can be highlighted using markers and text labels or numbered dots, a heading and caption can be added, and a mini-locator map can be shown to provide context for the map. The frame also provides a link to an 'Interactive fullscreen' version that allows the user to zoom and scroll and that can also display images at marked locations.

**Purpose== 
OSM Location map allows an editor to include a map in a frame for anywhere in the world, at any scale from the whole world down to one or two streets. It makes use of the OpenStreetMap mapping data, and enables a place-based page or topic to simply show the area being described, without the need for pre-determined map templates or external graphics. The underlying map will be updated and improved automatically as the OSM data develops. A zoom level appropriate to the topic can be selected and a scale marker is provided in the bottom right corner. This only offers a rough guide to the distances on the map, as the map projection results in scale changes depending on the latitude. Some allowance has been made for this, but only in large 20 degree chunks.
The map can also be made to show multiple marks, images and labels (currently limited to 60). The resulting framed map also has a link to an interactive full-screen version, which shows the same location 'over the top' of the current page. This is not able to show any text or other images, so is limited to pointer marks. However in other respects it has a richer map interface, can be re-scaled and panned by the user, can be given popup thumbnail images and captions on the marker points, and also provides yet further links to access a wide range of maps, satellite images etc. (The fullscreen option uses the  mapping provision.)
OSM Location map is in effect a wrapper above another template called Graph:Street map with marks. Where very large datasets are being used it may be better to utilise the Graph template directly as that allows unlimited numbers of marks and labels. However it requires a different coding mark-up (GeoJSON) and is not well suited to hand-coding. It is particularly suited to using data-sets directly extracted via automatic searches of Wikidata.

**Comparison with Maplink**
From 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 only add either points (numbered or icon-style pointy dots), or various lines and areas can be imported from OpenStreetMap via wikidata Q values (at present limited to boundaries, and roads). Thus the framed map and fullscreen version will show identical information. The OSM Location map on the other hand, cannot add the Q value lines and areas except to the interactive fullscreen click-through. On the other hand it can use the framed map to show a much richer selection of dots, shapes, overlays, images and especially text to convey specific details relevant to a particular article.

**Usage**
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.

**Single marker**
By using mostly default settings a map with a 'Red pog' marker and dark red label can be produced. The example below also adds some additional items (the last three parameters) that are used by the Interactive fullscreen version.
Code blank

**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.

**Multiple markers**

**Inherited values**
To minimise repetition of code, there is a sliding scale of inheritance that applies to each value in each parameter set. For example, if label-size4=16 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 label-sizeD= ). If no Default has been set, it will inherit the value set by the 'master parameter set', label-size1=. If that is also undefined it will fall back to the underlying default, which in the case of label-size is 12. 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.)

**Adding a Minimap in the left or right corner**
Many pages with info-boxes already include a locator map to give readers a proper sense of where the topic or place is located within a broader area. For those that don't it might be helpful to include one within your map. The underling 'Graph' module that OSM Location map uses offers a built-in map of the world option, which will act as a mini locator map and automatically adds a red locator dot (minimap = on). Unfortunately it is too general for most purposes, so an alternative, but rather less automated, option is to make use of an existing 'Location map' file. This can be seen in the Llanfechell map example. 
The width and height of the Location map both have to be decided upon, specified (and calculated so as to not distort the map dimensions). 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 minimap=file bottom left, minimap=file top left and minimap=file top right.
The dot will remain in the right place even if you subsequently choose a different size for the minimap. (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, so as to show the bounds of the main map. To use this feature, simply specify the width of the required box: minimap-boxwidth=xx 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-x and minipog-y. 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.

**arcText 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.

**Multi marker example**


**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 mark1=, 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). 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 for a way to acheive linear graphics such as this using text labels and  Box Drawing Characters.)

**Text color**
Color of label text can be specified using label-color = . 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**
Also available is 'background1' (#F9F5E7), which matches the most common map background. Useful for blanking out a bit of map using '█' character, to make a plainer background for putting a second label over the top. (This can be tricky to retain the right numbers with numbered dots, and really messes things up if using auto-caption.)

**Text and Shape opacity and giving a shape a halo**
With the 2021 changes to how the maps are displayed it has become possible to use opacity settings for both labels and the built-in shapes. For labels, use an additional '50%' indicator after the color name. (eg | label-color1 = soft grey 50% will make that text semi-transparent. Additional parameters are available to allow for transparency of both the shapes and outlines. In implementing this, it also became possible to offer a semi-transparent halo around built-in shapes and also around marks such as Red pog.svg. The table below shows a variety of possibilities for using these features.

**Text effects**
multi-line label: Where label text is too long to fit on a single line, using label = , two further label lines can be used: labela =  and labelb = . 
Label with no mark: If mark-size=0 this has the effect of a free-floating label with no marker
Angled label: It is possible to specify a label-angle = , 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, illustrated by the 'Preseli Hills' text on the Pentre Ifan map. For stylistic consistency settlement and building names should not normally be given an angle.

**Numbered dots**
If numbered dots are needed, instead of (or as well as) text labels, this can be achieved using the built in shapes. For example, shape1=n-circle will place a numbered dot at that coord position (or l-circle for letters). Generally it is much better to use the dots in sequence, so each numbered mark gives a numbered dot, and they will match the full screen ones. If auto-caption=1 then the caption will generate a numbered list using the mark-title entries.  For example:-
The other built-in shapes can be used in the same way (n-square, n-diamond etc.). The shape-outline1= value sets the colour for the number (unlike normal, when it sets the shape-outline), and as with the others, only the mark1 parameter values need to be set, to establish the default for this map, which can be overridden as required. The numbered1..2..3 etc parameters can override the automatic numbers or letters to use your own values for each mark. Flushing Meadows-Corona Park map is a useful real life example in template form.

**Use in infoboxes**
can be imbedded in infoboxes which allow the module parameter, for instance infobox school by using the instruction |module=. 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**
It is possible to use text labels to show simple graphics on a map, particularly by using unicode items in the  Box Drawing selection. Copy and paste the individual characters as required, and set the relevant label-angle and label-size. Set the mark-size to 0 to avoid also getting a shape/dot. See example.

**List of parameters**

**Parameters**

label-pos
Sets the position of the label, relative to the marker: left, right, top or bottom. Default=left. Top and bottom text is center-justified, whereas left and right align against the marker. The label aims to be an appropriate distance from the edge of the marker, but irregular shapes and larger sizes may need further adjustment using the label-offsets.
label-angle
It is possible to specify a label-angle = , which will pivot the label text around the centre of the marker point by the specified number of degrees. (+ve angle rotates clockwise, -ve anticlockwise) If mark-size is set to zero, this has the effect of a free-floating label with no marker, useful for various geographic and linear features. For stylistic consistency all settlement names should not be given an angle.
label-offset-x label-offset-y
Allows adjustment of the label location in an x and y direction, relative to its mark coordinates, by the specified number of pixels. It can be +ve or -ve numbers. Higher -x values will move the label to the right. Higher -y values move it down the map. Default is 0,0.
Additional content for Full screen link
The 'full screen' map uses the same OSM base map, in a different map environment, including the option for users to scale in and out, to pan across the map, and to find (via the 'More details' button) other maps and satellite imagery for the location. It also includes numbered markers, for which tooltip-style titles, and image thumbnails with captions can be brought up. This makes most sense where there are several markers on the map. The content for this facility is set with the following three parameters - which need to be numbered for each mark as for the other mark attibutes:
Parameter
Description
mark-title
This title appears as a tooltip and also a thumbnail title, accessed via the marker. if mark-title=none that will exclude that marker from the full screen map. (it will still show as normal on the main map).
mark-image
This provides a pop-up thumbnail image when the marker is clicked. Include only the image name from Wikimedia commons etc. (i.e. no brackets, or 'File:').
mark-description
Caption text, which will either accompany a pop-up photo, or if no photo then as a text box, when the marker is clicked. This can include wikilinks etc., to link on to additional relevant articles.
Arc Text: label placed on an arc
The use of arc-text parameters allows a short text (up to 20 characters) to be placed along on arc, with parameters to control the tightness of the circle (radius) and the looseness of the text (gap). The nature of the earth's coordinate system means that there will be some variation in an arc at different latitudes and at different zoom levels. Some allowance is factored in, but there will still be residual variation. Similarly, changes in radius will also have some effect on the gap size, with a larger radius opening out the gap somewhat. There will therefore need to be a degree of trial and correction to get the shape and effect desired. As a general rule, identify the coordinates of the required start-point, then choose a starter-pattern from the selection at OSM Location map#Text on an arc, and then adjust parameters to fit the requirement of the map. The parameters below are for set A. Sets B and C are also available.
Parameter
Description
arc-coordA
coordinates of first letter, using =
arc-textA=
Add your text here 
arc-angleA 
in degrees, -180 to 180. 0 will start as horizontal, -90 straight up, 90 straight down 
arc-gapA  
1= a notional 'standard'. 0.2 is very tight, 10 is very wide. Applying a negative gap will invert the letters and run the other way around the circle 
arc-radiusA 
1= a notional 'standard' 0.5 is quite a tight circle, 8 is so wide as to be almost flat, dependent on latitude and zoom level 
arc-text-colorA 
sets text color. #000000 color hexes and standardised OSM Location map colors are accepted 
ellipse-factorA
will squash or stretch the circle. 1= notionally circular, 0.5 to 1.0 will flattern top and bottom, above 1.0 flattens the sides.

**Underlying technology**
OSM Location map itself has no map or display ability of its own. Everything within the frame is produced through the template Graph:Street map with marks, created by User:Yurik. This in turn calls internal processes that turn all the data supplied at edit time into a rendered bitmap image, so that there is no calculation overhead by the time the page is read by a user, any more than any other commons image. 
Whilst the map is being edited and previewed, the page is supplied with a rasterised image, collating the base-map, marks, labels, etc. on the fly. It will be particularly noticeable on small fonts that when the 'Publish Changes' button is pressed, the resulting bitmap has much worse fonts than the preview. (Maybe this will be improved at some point). The process of updating the map image and providing the right bitmap is all handled internally and invisibly. One of the consequences of the 'bitmap' solution, which is different from the standard Location map method, is that there is no text or objects on the final image, so there is no possibility of adding wikilinks within the template. 
The full screen option, which can be clicked through from below the map, provides an entirely different mapping approach, using the same base-map data. This provides an interactive map that can be panned and zoomed. It also replicates (although at present only as numbered markers) the various marks from the page map. These can then be given more content, by way of a title, caption and image along with displaying the coordinate values. The caption and title can then be given all the wikilinks and other markup features that may be desired, providing a map-based page that will offer another way of engaging with the article content.
Future development of the various mapping technologies is likely to result in further options for showing maps on Wikipedia. In particular, maplink, which initially just created a text link to a full-screen map, can now create a framed image including dot-markers, roads, boundaries, etc., and can acquire data directly from wikidata to do this. Again, the processor overheads are reduced by initially showing a bitmap, which can be clicked to become interactive within its frame. Maplink is being effectively rolled out within info-boxes, where the map is automatically generated from already available data. 
This template, on the other hand, is probably better suited to 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 within this template, but is available via the inderlying Graph:Street map with marks template, is to draw the data from Wikidata, using a SPARKL query that provides the selection of marks requested. 
The 'Graph' technology used here is described as under development, so while it is highly likely that this or a similar solution will still be available, it may evolve over time.

**See also**
 Wikipedia:Maps for Wikipedia - A list of mapping tools available on Wikipedia- Location map - Placing one marker/label by latitude/longitude.- Location map+ - Placing unlimited list of markers/labels.- Location map many - For displaying multiple marks using latitude and longitude.- :Commons:Category:Map pointers - List of the many Wikimedia Commons pointer symbols.- Overlay - Allows image numbered, textual number, or color tag overlays to be positioned over an image to indicate particular features in the image.