Template:Location map polarx/doc

Creates a location map as a composite image of an existing map in either equirectangular projection or skewed projection, with multiple markers and optional labels superimposed onto it. This template functions in the style of Template:Location_map, but can auto-skew latitudes and longitudes and allows multiple markers and labels (rather than just one marker). Note: For brevity, parameters "pos" and "bg" are aliases (for parameters "position" & "background").
 * (Documentation transcluded from: Template:Location map polarx/doc)

The differences between mapping templates are as follows:
 * Template:Location map - uses straight lines for latitude (not curved arcs);
 * Template:Location map polarx - curves latitude for 4 polar markers/labels;
 * Template:Location map many polarx - allows 5 markers/labels and has "many" in the template name:.

Also see: Template:Location_map_100x100 to overlay markers on any map/image, by
 * using rectangular coordinates from 0-100, as a 100x100 image grid.

Usage
Parameter locname refers to {Template:Location map locname} containing the image name and coordinates of a particular map.

BEWARE: Omit "px" from marksize or that marker might be placed off-center. The MediaWiki-language coding of the template cannot detect "px" inside numeric parameters.

Available maps
List of live templates named Template:Location_map_polarx_  (without "Template:"):

Location_map_CanadaGeo Location_map_CanadaTerrain Location_map_SwedenCIAx

Creating new maps

 * 1) Find an appropriate map for the region, such as a polar half-circle (does not need to be mapped in equirectangular projection).
 * 2) Create a template named "Template:Location_map_locname" (copy the content of any other map template into it and enter appropriate values or examples).
 * 3) Set default parameter values (using those parameter names), such as setting "mark" with image-file name and "marksize" for pixels wide/tall, or set default label font size ("label_size = 78" percent).
 * 4) Parameter names not used by "Template:Location_map" will be ignored by it, and only used by templates which handle multiple-markers (such as defaulting "label2_size = 78" percent, or "mark2size=7" pixels).

Implementation notes
The map and markers are implemented using the typical wiki parser-functions ( "" ), described at: WikiMedia Help:ParserFunctions.

Template limits increased in 2008

 * Technical article: WikiQueer:Template_limits.

As of February 2008, templates are restricted mainly by the amount of output text generated, rather than by the number of if-statements or switch-options contained within a template. The output size limit is measured as the amount of HTML code generated to display a formatted WikiQueer page (limited to about 1MB of HTML). As of February 2008, the templates are processed by a MediaWiki recursive-descent parser, which bypasses the template coding based on conditional logic in the parser, and so does NOT expand templates in a "false" branch during formatting.

Prior to January 2008, the MediaWiki (version 1.6) language was still a beta-level technology, something of a toy language, limited by handling of noinclude-tags ("&lt;noinclude>"), which filled template-processing buffers and killed template if-statements, depending on complexity of conditional expressions. The template size-limit had severely restricted coding for handling polar-skewing of map markers. Each time a template was run within an article, resources were depleted further, limiting the number of times a large template could be included within one article: the reducing of map-definition template size by moving noinclude-sections into "/doc" sub-files allowed more templates to run. Map templates (such as "Location_map_Croatia") have been reduced by moving most descriptive text & the interwiki language-links into "/doc" sub-files.

Note: Template sizes and the page-buffer size have been purposely limited to combat vandalism from users who might submit very large pages to attack wiki server performance. Although the wiki servers might be capable of more, the limits have been imposed to prevent denial-of-service caused by expanding very large article pages (typically, huge pages exceeding 1MB of formatted text).

Explanation of skewing
The skewing of map coordinates, when placing markers/labels on the map image, is performed by a linear interpolation of the longitude relative to the height of the latitude (higher latitudes skew longitude more). A skew factor < 1.0 squeezes longitudes together near the top, while a skew factor > 1.0 spreads longitudes apart near the top.

Although longitude is skewed by a linear interpolation, the latitude is skewed by a quadratic interpolation, which squares the delta difference from longitude center, to form an arc line, further scaled depending on the current latitude. Higher latitudes are scaled less, to align with shorter arcs closer to the poles.

The latitude arcs, such as the Arctic Circle, at north latitude 66.5, are approximated by quadratic interpolation, of the form: y = b.x2 + c, where x is the longitudinal distance from the center longitude. Locations with longitudes farther from the center will skew to higher positions along the arc: x depends on dividing longitude-offset by 90 degrees, to keep x between -1 to 0 to 1, but is scaled by factor b, which depends on latitude. Whereas x varies with longitude offset, b uses only the latitude, to raise the arc less for smaller arcs at higher latitudes.

The formulas are roughly:


 * To skew by latitude ratio (skewing longitude more towards top):
 * skew factor = ( (1 - skew) * lat_ratio + skew ), where:
 * lat_ratio = (maxlat - latitude) / (maxlat-minlat).


 * To skew latitude:
 * latitude = lat_skew * ( (longitude - cen) / 90 )**2 * lat_scale;
 * where, lat_scale = (90 - latitude) / 90 * 75.0, and
 * where, cen = (minlon + maxlon) * 0.5 + lon_shift,
 * where, lon_shift adjusts middle longitude as if map center line.
 * Note: Skewed latitude depends upon both longitude & latitude.

The longitude-skew coding in MediaWiki language is:

#if: | }}

Although the above formulas are approximations, devised to fit the actual data, the resulting skewed longitudes and latitudes have been tested to almost exactly pinpoint locations on calibrated maps. However, for maps that are not precisely calibrated, each marker can be shifted slightly, by adjusting its particular skew factors: for example, skew3 or lat3_skew could be adjusted to overlap the mark3 image symbol over a spot which might be slightly off-center on a particular map (lower skew3 moves inward, lower lat3_skew moves downward).

Use of HTML divisions
The map with markers/labels is implemented as nested HTML divisions. The map-image is in an HTML division, containing each point as a percent-locator division containing a marker-image sub-division plus a label sub-division. Each point is calculated (for a percent-locator division) with X or Y coordinate "XX.X%" or "YY.Y%" as follows:


 * The div-tag is "&lt;div style="position: absolute; z-index: 2; top: XX.X%; left: YY.Y%; ...&gt;"
 * For placing latitude, the calculation is:
 * YY.Y% = 100 * (top - (lat_deg + latmin/60 + latsec/3600) ) / (top - bottom)
 * If lat_deg is empty, the combined decimal latitude is used from "lat".
 * If lat_dir is "S" (south), the latitude is multiplied by -1.
 * (Note latitude YY.Y% is reversed, with larger YY.Y% at bottom.)


 * For placing longitude, the calculation is:
 * XX.X% = 100 * ( (lon_deg + lonmin/60 + lonsec/3600) - left ) / (right - left)
 * If lon_deg is empty, the combined decimal longitude is used as "long".
 * If lon_dir is "W" (west), the longitude is multiplied by -1.


 * The div-tag is ended as "height: 0; width: 0; margin: 0; padding: 0;"&gt;".
 * Within that division the marker/label sub-divisions are coded as:
 * &lt;div style="position: relative text-align: center; ..."&gt;.


 * For label position, the options are shifted as:
 * when position=left, adds "left: -6.5em; text-align: right;"
 * when position=right, adds "left: 0.5em; text-align: left;"
 * when position=top, adds "top:-2.65em; left:-3em; text-align: center;"
 * when position=bottom, adds "top:-0.15em; left: -3em; text-align: center;" to div-tag.

Accuracy of numeric calculations depends on the particular wiki server handling the webpage.