<map-input>
The <map-input> element is an extended HTML input by type for use in Web
map <map-extent> elements. The attributes that apply to the input depend on
the type attribute. There are several types of <map-input> that can be used.
The <map-input> declares a variable that will be set and used by the polyfill
according to its attributes, as the map changes viewport extent in response to
user gestures.
Attributes
name
Sets the name of the variable created by the input. The variable can then be
referenced by the URL template <map-link> tref attribute,
using the {name} variable reference notation.
type
Sets the type of the input.
| Type | Description |
|---|---|
| zoom | Integer value that ranges from 0 to some fixed number of values, depending on the projection, less than or equal to 25. |
| location | A location input captures one axis value of a two-dimensional point ( represented by a coordinate pair) from the map extent, e.g. top-right, or, for server queries, the location in the map where the user clicks or touches. |
| width | A width input captures the width of the map viewport's extent in standardized pixels |
| height | A height input captures the height of the map viewport's extent in standardized pixels |
| hidden | Establishes a variable that may be used to pass a fixed value to the server when requesting map resources. |
value
In general, the value is set and used by the polyfill when generating URLs from
URL templates, for fetching server resources such as tiles, images
and map documents.
In particular, value is used by authors to specify values for inputs of
type="zoom". In the case of type="zoom", value defines the zoom level of
associated sibling <map-input type="location"> elements' min and max
attribute values. Allows authors to establish native / server resource bounds,
on a per-<map-link tref="..."> basis.
Inputs are associated by their variables being referenced by a
<map-link tref="https://example.org/{z}/{col}/{row}/" ...> value. The {z},
{row}, and {col} variable references in the above example associate the
variables (<map-input>'s) named z, row and col.
axis
This attribute applies only to inputs of type="location". It establishes the axis
of the coordinate to be serialized as a named variable. This value also
identifies the axis that the min and max attributes apply to, so that the
polyfill will not make requests for spatial resources (tiles etc) outside the
native axis bounds. Possible values of axis are:
| Axis name | CRS | Description |
|---|---|---|
row | tilematrix | Vertical axis, positive down the screen. The origin is at the upper left. Units are tiles. Each zoom level is a distinct tilematrix crs, so coordinate values apply only to that zoom level. |
column | tilematrix | Horizontal axis, positive to the right. The origin is at the upper left. Units are tiles. Each zoom level is a distinct tilematrix crs, so coordinate values apply only to that zoom level. |
easting | pcrs | Horizontal axis, positive to the right. The origin is defined a geographic location. Units are ususally meters, although for some projections (specifically WGS84), the transformation from geographic CRS, i.e. from longitude to easting is the identity transformation, in which case the easting values could be said to be in decimal degrees. pcrs stands for "projected coordinate reference system". Note that because pcrs is an 'infinite canvas', there exist locations for which a transformation from pcrs coordinates to gcrs coordinates is undefined. |
northing | pcrs | Vertical axis, positive to the right. The origin is defined a geographic location. Units are ususally meters, although for some projections (specifically WGS84), the transformation from geographic CRS, i.e. from latitude to northing is the identity transformation, in which case the northing values could be said to be decimal degrees. Note that because pcrs is an 'infinite canvas', there exist locations for which a transformation from pcrs coordinates to gcrs coordinates is undefined. |
latitude | gcrs | The latitude of a point on an ellipsoid is the angle between a line perpendicular to the surface of the ellipsoid at the given point and the plane of the equator. gcrs stands for "geographic coordinate reference system". |
longitude | gcrs | The longitude of a point specifies its east–west position on the reference body's (Earth's) surface. |
x | tcrs | Horizontal axis, positive to the right. The origin is at the upper left. Units are defined-size pixels. Each zoom level is a distinct tcrs, so coordinate values apply only to that zoom level. tcrs stands for "tiled coordinate reference system". The tiles of each tilematrix crs are defined as aggregations of pixels in the corresponding zoom level tcrs. |
y | tcrs | Vertical axis, positive down the screen. The origin is at the upper left. Units are defined-size pixels. The origin is at the upper left. Units are scaled pixels. Each zoom level is a distinct tcrs, so coordinate values apply only to that zoom level. |
i | tile, map | Horizontal axis, positive to the right. Each tile, and the map viewport, has a defined-size pixel-based crs that has its origin at the upper left (of each tile in the case of the tile crs, and of the map viewport, in the case of the map crs). |
j | tile, map | Vertical axis, positive down the screen. Each individual tile, and the map viewport has a defined-size pixel-based crs that has its origin at the upper left (of each tile in the case of the tile crs, and of the map viewport, in the case of the map crs). |
When requesting a the coordinate axis of whole tile in the OSMTILE projection,
a location input might use a <map-input name="y" type="location" units="tilematrix" axis="row">
input to establish a variable named y, referenced by {y} in an associated URL template,
which would serialize the tilematrix crs row axis values. A series of
location events is genereated by the polyfill as required by the map to cover
the viewport in tiles.
units
Identifies the associated specific coordinate reference system that a location input event is referred to. The term "projection" in MapML is synonymous with the set of CRS that are related together by the projection name. In all cases for any projection, there exist a set of CRS that are related mathematically. These CRS are known and identified within the namespace of the projection name by the following table of keyword values:
| CRS | Description |
|---|---|
| tcrs | For each zoom level (i.e. at a pre-defined scale denominator value), locations are expressed in terms of scaled pixels, with the origin of pixel space at the upper left corner. The pixel coordinates of a location at a single zoom level are independent of the pixel coordinates of a location any other zoom level. In other words, you need to know the zoom level of a tcrs coordinate in order to locate it on a map or otherwise process it. |
| tilematrix | Each zoom level has an array of tiles, called a tilematrix. The individual tiles constitute the coordinates in this CRS, and the axes are know as row and column. The tiles are defined as squares of 256 pixels in the associated tcrs of the particular zoom level. |
| pcrs | Projected CRS (pcrs) are defined by a mathematical relationship with an underlying gcrs, using a technique called "projection". pcrs coordinates are scale- and zoom level-independent, and are designed to represent geographic coordinates on a planar surface, such as a device screen. The measurement units of pcrs coordinates is usually meters (a notable exception being pcrs coordinates in the WGS84 projection). |
| gcrs | Geographic coordinates are referenced to various ellipsoids, and are not necessarily comparable across projections. A common ellipsoid today is WGS 84, which is defined and used by the global positioning satellite (GPS) constellation. |
| map | The map CRS is dynamic, in the sense that it has its origin at the upper left of the user's viewport, with scaled pixels as units. This is used to identify image coordinates for use, typically by WMS and similar services which use a virtual image to enable query of map feature property information, without necessarily transferring the features over the network. |
| tile | Each tile in any zoom level has an implicit scaled-pixel coordinate system ranging from 0 to 255 in both horizontal and vertical directions. These coordinates are used by WMTS and similar services to identify a pixel for query of feature property values, without transferring the feature geometry over the network. |
Sometimes, location inputs are used to generate "brownie-cutter" (square) requests
for tiles from WMS and similar un-tiled services. In such a case, it is possible
for the units to be specified as tilematrix, implying that the location event
expected is that of a tile, and the position keyword is then used to describe
the corner of the tile for which the coordinate should be serialized. In such a
case, the axis value may be specified as easting or other axis name
associated with the projection, to obtain coordinate of the corner of the tile
that is being processed by the polyfill:
<map-input name="xmin" type="location" units="tilematrix" position="top-left" axis="easting">
Internally, the crs of the requested coordinate is deduced from the axis
name, instead of requiring the author to explicitly specify the axis' crs as an
additional attribute of the <map-input>.
position
Allows the author to specify a predefined corner of the viewport or tile to be used
as the location value to be serialized. If position is not present, the input
location coordinates will be generated by user click or touch on the map, which
is used to generate interactive server queries.
| position keyword | keyword description |
|---|---|
| top-left | Identifies the location at the top left corner of the tile or viewport |
| top-right | Identifies the location at the top right corner of the tile or viewport |
| bottom-left | Identifies the location at the bottom left corner of the tile or viewport |
| bottom-right | Identifies the location at the bottom right corner of the tile or viewport |
Other values of position are possible, but are not implemented yet.
rel
Specifies the entity to which the position applies. Possible values are tile and image.
The default value, if unspecified, is image. It is used to help identify what crs the
coordinate serialized by the input exists in.
min
Establishes the minimum of the axis on the server . Requests for coordinates less than this value will not be created by the polyfill.
max
Establishes the maximum of the axis on the server. Requests for coordinates greater than this value will not be created by the polyfill.
step
Sets the zoom interval according to which resources will be requested within the zoom range. The step is always calculated from a base value of 0. At zoom values that fall within a step interval, resources will be requested as required, and scaled to the current zoom level. For example, with a min=0 and a max=7 for a given zoom input with a step=4, tiles will be requested at only zoom=0 and scaled to zoom values of 1, 2 and 3 as the map is rendered at those levels. Use of this attribute can conserve user bandwidth while having little visual effect, depending on the nature of the content.
Examples
Input step
<mapml-viewer projection="OSMTILE" zoom="0" lat="45.409071" lon="-75.703411" controls>
<map-layer label="OpenStreetMap" checked>
<map-extent units="OSMTILE" checked>
<map-input name="z" type="zoom" value="18" min="0" max="18" step="3"></map-input>
<map-input name="x" type="location" units="tilematrix" axis="column" min="0" max="262144" ></map-input>
<map-input name="y" type="location" units="tilematrix" axis="row" min="0" max="262144" ></map-input>
<map-link rel="tile" tref="https://tile.openstreetmap.org/{z}/{x}/{y}.png" ></map-link>
</map-extent>
</map-layer>
</mapml-viewer>
Input rel=tile to generate WMS requests for tiles
WMS behaviour can seem slow, even when it is fast. Painting the map using tiles generated by individual WMS GetMap requests can improve users' impression of your map, although it is not advisable when the layer being requested contains text labels, which may be duplicated on adjacent tiles many times over.
<mapml-viewer projection="CBMTILE" lat="60" lon="-95" zoom="2" controls>
<map-layer label="Tiled WMS GetMap" checked>
<map-extent units="CBMTILE" checked>
<!-- the units and axis attributes here appear at odds -->
<!-- however for rel="tile" and units="tilematrix" together tell the map that
the event being serialized is relative to a tile in a tilematrix coordinate
system (tcrs) -->
<map-input name="txmin" type="location" rel="tile" position="top-left" axis="easting" units="tilematrix" ></map-input>
<!-- in this case, position refers to a position on the tile that is to be fetched -->
<map-input name="tymin" type="location" rel="tile" position="bottom-left" axis="northing" units="tilematrix" ></map-input>
<map-input name="txmax" type="location" rel="tile" position="top-right" axis="easting" units="tilematrix" ></map-input>
<map-input name="tymax" type="location" rel="tile" position="top-left" axis="northing" units="tilematrix" ></map-input>
<map-link rel="tile" tref="https://datacube.services.geo.ca/ows/msi?SERVICE=WMS&REQUEST=GetMap&FORMAT=image/png&TRANSPARENT=TRUE&STYLES=msi-color&VERSION=1.3.0&LAYERS=msi&WIDTH=256&HEIGHT=256&CRS=EPSG:3978&BBOX={txmin},{tymin},{txmax},{tymax}" ></map-link>
<!-- a zoom input is necessary, but that's a bug:
https://github.com/Maps4HTML/MapML.js/issues/669 -->
<map-input name="z" type="zoom" value="25" min="0" max="25"></map-input>
</map-extent>
</map-layer>
</mapml-viewer>
Specifications
| Specification |
|---|
| MapML input element |
| HTML input element |