Template:Image label marker/doc

Purpose
The purpose of this template is to allow accurate placement of an image and/or text label over another source image, irrespective of scaling of the source image. It is based on the Image label template. However, a drawback with that template is that the placement gets slightly inaccurate if you scale the source image (because of the way calculations are done), and thus you might have to manually recalculate the placement.

This template also has similarities with the Overlay template. That template however sadly doesn't allow for scaling. It is also limited to 30 labels, although for most purposes that is probably more than enough.

This template is however much more bloated than either of those templates, and you might want to consider if you can use one of the templates that are simpler and easier to use.

Example usage
This template assumes you first introduce a background image by calling Image label begin. By doing so this also requires it to be ended with Image label end. Example with two smilies placed as the “eyes” on this beach image. 

For full list of available options/parameters see further below. In this example the following are used
 * is the width of the scaled image. This should correspond to the width you supplied when using Image label begin.
 * is in this example the width of the original beach image, which can be found out through various methods. One way to find out is the way Wikipedia/Commons lists it below the image where it says “Full resolution” when you view the image information and its license.
 * is the x-coordinate on the full resolution image where the [[Image:Face-grin.svg|15px]] is to be placed. There are various methods to find out this, and depends on what tools you have available.
 * is the y-coordinate on the full resolution image where the [[Image:Face-grin.svg|15px]] is to be placed.
 * is the image to be used as a marker, since the default marker image [[Image:Red pog.svg|9px]] is not used.
 * is the width of the marker image [[Image:Face-grin.svg|15px]].

If scaling the beach image down (or up), the only changes that need to be done is changing every occurrence of the width parameter, and the placement of overlying marker images (and their corresponding text) should scale accordingly. 

Minimal use skeleton
If you want to use a different marker/image than the default , you can add it with | image        = | marker_size  =

Full skeleton
Please note that many of these parameters are used in calculations. Due to constraints the template will think a parameter that is given, but is actually empty or contains spaces, still has a value and thus will give an error during calculations. The error might look something like this:.

Calculations
Default calculations used for placing the marker image. With the use of the template's parameter options xadjust and yadjust the placement can be slightly modified.


 * $$x_{marker} = {x_{marker\_orig} \over x_{orig}} \cdot x_{scaled} - {marker\_size \over 2} + x_{adjust}$$

and


 * $$y_{marker} = {y_{marker\_orig} \over y_{orig}} \cdot y_{scaled} - {marker\_size \over 2} + y_{adjust}$$

Where yscaled by default is calculated from the percentage the image is resized


 * $$y_{scaled} = {x_{scaled} \over x_{orig}} \cdot y_{orig}$$

Default calculations for the text placement, more specifically the upper left corner of the text's bounding box. The calculation inherits xadjust and yadjust from the marker image's placement. With the use of the template's parameter options xtextadjust and ytextadjust the text placement can be additionally modified.


 * $$x_{text} = {x_{marker\_orig} \over x_{orig}} \cdot x_{scaled} + {marker\_size \over 2} + x_{adjust} + x_{textadjust}$$

and


 * $$y_{text} = {y_{marker\_orig} \over y_{orig}} \cdot y_{scaled} - {marker\_size \over 2} + y_{adjust} + y_{textadjust}$$

Template parameters
None of the template parameters are technically required, however not supplying a few of them will make the template behave oddly, or make the use of this template unnecessary. For this reason some of the parameters are listed as "required".