nmeasim::app::map¶

namespace nmeasim::app::map · Applications

The slippy-map view of the desktop application, part of nmeasim::app.

It holds MapWidget, which paints raster tiles with the vessel, its track and the navigation overlays; TileCache, which serves the tiles from memory, from a disk cache or from a tile server over the network; and the Web Mercator (EPSG:3857) tile arithmetic both rely on. Positions are WGS 84 latitudes and longitudes in degrees; widget and world coordinates are pixels with x to the right and y downwards; zoom levels follow the slippy map scheme, in which each level doubles the scale and a tile is 256 pixels square.

See also

https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames

Types¶

Type	Description
`MapWidget`	A slippy map: raster tiles from a `TileCache`, the vessel with its heading and a vector of its course and speed, the track it has sailed, and mouse, touchpad and keyboard navigation.
`ScaleBar`	Length and caption of the scale bar.
`TileCache`	Serves map tiles from memory, then from a directory on disk, and finally by downloading them from a tile server.
`TileKey`	Address of one tile: its zoom level and its column and row at that level.

Summary¶

Functions

Name	Description
`default_attribution()`	Returns the attribution the map shows for a tile server when none is configured.
`scale_bar()`	Returns the longest round distance whose bar fits in a maximum length.
`tiles_at()`	Returns the number of tiles along one axis at a zoom level, 2^`zoom`.
`tile_coordinates()`	Returns the fractional tile coordinates of a position at a zoom level.
`pixel_coordinates()`	Returns the pixel coordinates of a position at a zoom level.
`position_of_tile()`	Returns the position at fractional tile coordinates at a zoom level, the inverse of `tile_coordinates`.
`position_of_pixel()`	Returns the position at pixel coordinates at a zoom level, the inverse of `pixel_coordinates`.
`tile_at()`	Returns the tile containing fractional tile coordinates, with x wrapped around the antimeridian.
`parent_of()`	Returns the tile one zoom level up (one level less detailed) that contains a tile.
`wrap_longitude()`	Wraps a longitude into [-180, 180), as the world repeats east and west.
`metres_per_pixel()`	Returns the ground distance one pixel covers at a latitude and zoom level.

Variables

Name	Description
`kTileSize`	Edge length of a square raster tile in pixels, as served by OpenStreetMap-style servers.
`kMinZoom`	Lowest zoom level the map widget allows; at level 1 the world is 2 by 2 tiles.
`kMaxZoom`	Highest zoom level the map widget allows, the deepest level the OpenStreetMap standard tile layer serves.
`kMaxLatitudeDeg`	Northern and southern limit of Web Mercator in degrees, `atan(sinh(pi))`.

Functions¶

default_attribution()¶

QString default_attribution(const QString& url_template)

Returns the attribution the map shows for a tile server when none is configured.

The OpenStreetMap tile servers require the credit © OpenStreetMap contributors; for any other server the map cannot know the terms, so it shows none unless one is configured with MapWidget::set_attribution.

Parameters

Name	Type	Description
`url_template`	`const QString&`	Tile URL template, as `TileCache::url_template` returns it.

Returns QString: © OpenStreetMap contributors when the host of the URL is openstreetmap.org or one of its sub-domains, such as tile.openstreetmap.org; empty otherwise.

Declared in src/app/map/map_widget.hpp:70 · defined in src/app/map/map_widget.cpp:114

scale_bar()¶

ScaleBar scale_bar(double metres_per_pixel, double max_length_px)

Returns the longest round distance whose bar fits in a maximum length.

Nautical miles are preferred, in steps of 1, 2 and 5 from 0.1 nm to 5000 nm; when not even 0.1 nm fits, the bar shows 10, 20, 50 or 100 m instead.

Parameters

Name	Type	Description
`metres_per_pixel`	`double`	Ground distance one pixel covers at the map centre, in metres; must be positive.
`max_length_px`	`double`	Longest bar that fits, in pixels; must be positive.

Returns ScaleBar: The bar, with its length in pixels and its caption. It is empty (zero length, no label) when an argument is not positive or NaN, or when not even 10 m fits.

Declared in src/app/map/map_widget.hpp:59 · defined in src/app/map/map_widget.cpp:127

tiles_at()¶

int tiles_at(int zoom) noexcept

Returns the number of tiles along one axis at a zoom level, 2^zoom.

Parameters

Name	Type	Description
`zoom`	`int`	Whole zoom level; clamped to [0, 30] so that the result fits in an `int`.

Returns int: The number of tiles per axis, from 1 to 2^30.

Declared in src/app/map/tile_math.hpp:56 · defined in src/app/map/tile_math.cpp:42

tile_coordinates()¶

QPointF tile_coordinates(core::geo::Position position, int zoom) noexcept

Returns the fractional tile coordinates of a position at a zoom level.

Parameters

Name	Type	Description
`position`	`core::geo::Position`	`Position` to project. The latitude is clamped to [-`kMaxLatitudeDeg`, `kMaxLatitudeDeg`]; the longitude is not wrapped, so one outside [-180, 180] gives an x outside [0, 2^`zoom`].
`zoom`	`int`	Whole zoom level, clamped as `tiles_at` does.

Returns QPointF: Tile coordinates, x eastwards and y southwards, both in [0, 2^zoom] for positions in range.

Declared in src/app/map/tile_math.hpp:66 · defined in src/app/map/tile_math.cpp:47

pixel_coordinates()¶

QPointF pixel_coordinates(core::geo::Position position, int zoom) noexcept

Returns the pixel coordinates of a position at a zoom level.

Parameters

Name	Type	Description
`position`	`core::geo::Position`	`Position` to project, treated as `tile_coordinates` treats it.
`zoom`	`int`	Whole zoom level, clamped as `tiles_at` does.

Returns QPointF: Pixel coordinates in the world image, which is 2^zoom times kTileSize pixels square: the tile coordinates times kTileSize.

Declared in src/app/map/tile_math.hpp:74 · defined in src/app/map/tile_math.cpp:58

position_of_tile()¶

core::geo::Position position_of_tile(QPointF tile, int zoom) noexcept

Returns the position at fractional tile coordinates at a zoom level, the inverse of tile_coordinates.

Parameters

Name	Type	Description
`tile`	`QPointF`	Tile coordinates, x eastwards and y southwards. Values outside [0, 2^`zoom`] are neither wrapped nor clamped: they give longitudes outside [-180, 180] and latitudes beyond `kMaxLatitudeDeg`.
`zoom`	`int`	Whole zoom level, clamped as `tiles_at` does.

Returns core::geo::Position: The position in degrees.

Declared in src/app/map/tile_math.hpp:84 · defined in src/app/map/tile_math.cpp:62

position_of_pixel()¶

core::geo::Position position_of_pixel(QPointF pixel, int zoom) noexcept

Returns the position at pixel coordinates at a zoom level, the inverse of pixel_coordinates.

Parameters

Name	Type	Description
`pixel`	`QPointF`	Pixel coordinates in the world image, treated as `position_of_tile` treats tile coordinates.
`zoom`	`int`	Whole zoom level, clamped as `tiles_at` does.

Returns core::geo::Position: The position in degrees.

Declared in src/app/map/tile_math.hpp:93 · defined in src/app/map/tile_math.cpp:70

tile_at()¶

TileKey tile_at(QPointF tile, int zoom) noexcept

Returns the tile containing fractional tile coordinates, with x wrapped around the antimeridian.

Parameters

Name	Type	Description
`tile`	`QPointF`	Tile coordinates. The x may lie outside [0, 2^`zoom`) and is wrapped into it, as the world repeats east and west.
`zoom`	`int`	Whole zoom level, stored in the key as given.

Returns TileKey: The key of the tile. Its y is the floor of tile.y() clamped to [0, 2^zoom), so a point north or south of the projected world gives the first or last row.

Declared in src/app/map/tile_math.hpp:103 · defined in src/app/map/tile_math.cpp:74

parent_of()¶

TileKey parent_of(TileKey key) noexcept

Returns the tile one zoom level up (one level less detailed) that contains a tile.

Parameters

Name	Type	Description
`key`	`TileKey`	Tile whose parent is wanted.

Returns TileKey: The key at key.zoom - 1 whose area covers key and three sibling tiles. A key at zoom 0 or below has no parent and yields the whole-world tile (0, 0) at zoom 0.

Declared in src/app/map/tile_math.hpp:110 · defined in src/app/map/tile_math.cpp:84

wrap_longitude()¶

double wrap_longitude(double longitude_deg) noexcept

Wraps a longitude into [-180, 180), as the world repeats east and west.

Parameters

Name	Type	Description
`longitude_deg`	`double`	Longitude in degrees, positive east; any finite value.

Returns double: The same meridian in [-180, 180): 180 gives -180 and 190 gives -170.

Declared in src/app/map/tile_math.hpp:116 · defined in src/app/map/tile_math.cpp:91

metres_per_pixel()¶

double metres_per_pixel(double latitude_deg, int zoom) noexcept

Returns the ground distance one pixel covers at a latitude and zoom level.

This is the Web Mercator ground resolution: the equatorial circumference of WGS 84 divided by the world width in pixels and multiplied by the cosine of the latitude. It holds along both axes at that latitude.

Parameters

Name	Type	Description
`latitude_deg`	`double`	Latitude in degrees, positive north; clamped to [-`kMaxLatitudeDeg`, `kMaxLatitudeDeg`].
`zoom`	`int`	Whole zoom level, clamped as `tiles_at` does.

Returns double: Metres per pixel, for example about 156543 at zoom 0 on the equator.

Declared in src/app/map/tile_math.hpp:128 · defined in src/app/map/tile_math.cpp:100

Variables¶

kTileSize¶

int kTileSize{256}

Edge length of a square raster tile in pixels, as served by OpenStreetMap-style servers.

Declared in src/app/map/tile_math.hpp:25

kMinZoom¶

int kMinZoom{1}

Lowest zoom level the map widget allows; at level 1 the world is 2 by 2 tiles.

Declared in src/app/map/tile_math.hpp:27

kMaxZoom¶

int kMaxZoom{19}

Highest zoom level the map widget allows, the deepest level the OpenStreetMap standard tile layer serves.

Declared in src/app/map/tile_math.hpp:30

kMaxLatitudeDeg¶

double kMaxLatitudeDeg{85.05112878}

Northern and southern limit of Web Mercator in degrees, atan(sinh(pi)).

The projection is undefined at the poles; this latitude makes the projected world square. Positions beyond it are clamped to it.

Declared in src/app/map/tile_math.hpp:35