Table of Contents

Class TileGrid

Namespace
SpatialNET.IO
Assembly
SpatialNET.IO.dll

A tile grid in any coordinate reference system: origin, origin corner, tile size in pixels and one resolution (world units per pixel) per level. The grid only does arithmetic; it never projects.

public sealed class TileGrid

Inheritance

Inherited Members

Constructors

TileGrid(double, double, IEnumerable<double>, int, int, TileOrigin)

Creates a grid.

public TileGrid(double originX, double originY, IEnumerable<double> resolutions, int tileWidth = 256, int tileHeight = 256, TileOrigin origin = TileOrigin.UpperLeft)

Parameters

originX double

The X coordinate of the origin.

originY double

The Y coordinate of the origin.

resolutions IEnumerable<double>

World units per pixel per level, level 0 first.

tileWidth int

The tile width in pixels; default 256.

tileHeight int

The tile height in pixels; default 256.

origin TileOrigin

The origin corner; default SpatialNET.IO.TileOrigin.UpperLeft.

Exceptions

ArgumentNullException

resolutions is null.

ArgumentOutOfRangeException

The origin is not finite, a resolution is not finite and positive, or a tile size is not positive.

Fields

MetersPerInch

The meters per inch used to convert between scale and resolution (OGC: 0.0254).

public const double MetersPerInch = 0.0254

Field Value

double

WebMercatorHalfExtent

The half extent of the WebMercator (EPSG:3857) world: 20037508.342789244 m.

public const double WebMercatorHalfExtent = 20037508.342789244

Field Value

double

Properties

LevelCount

The number of levels.

public int LevelCount { get; }

Property Value

int

Origin

The origin corner.

public TileOrigin Origin { get; }

Property Value

TileOrigin

OriginX

The X coordinate of the origin.

public double OriginX { get; }

Property Value

double

OriginY

The Y coordinate of the origin.

public double OriginY { get; }

Property Value

double

Resolutions

The resolutions (world units per pixel) per level.

public IReadOnlyList<double> Resolutions { get; }

Property Value

IReadOnlyList<double>

TileHeight

The tile height in pixels.

public int TileHeight { get; }

Property Value

int

TileWidth

The tile width in pixels.

public int TileWidth { get; }

Property Value

int

Methods

FromScales(double, double, IEnumerable<double>, double, int, int, TileOrigin)

Creates a grid from map scales (as tile service metadata usually lists them).

public static TileGrid FromScales(double originX, double originY, IEnumerable<double> scales, double dpi = 96, int tileWidth = 256, int tileHeight = 256, TileOrigin origin = TileOrigin.UpperLeft)

Parameters

originX double

The X coordinate of the origin.

originY double

The Y coordinate of the origin.

scales IEnumerable<double>

The scale denominators per level, level 0 first.

dpi double

The dots per inch the scales refer to; default 96.

tileWidth int

The tile width in pixels; default 256.

tileHeight int

The tile height in pixels; default 256.

origin TileOrigin

The origin corner; default SpatialNET.IO.TileOrigin.UpperLeft.

Returns

TileGrid

Exceptions

ArgumentNullException

scales is null.

ArgumentOutOfRangeException

A value is out of range (see the constructor), or dpi is not finite and positive.

Resolution(int)

The resolution of a level.

public double Resolution(int level)

Parameters

level int

The level.

Returns

double

Exceptions

ArgumentOutOfRangeException

level is not a level of the grid.

ResolutionToScale(double, double)

Converts a resolution into a scale denominator: resolution · dpi / 0.0254.

public static double ResolutionToScale(double resolution, double dpi = 96)

Parameters

resolution double

The resolution in world units (meters) per pixel.

dpi double

The dots per inch; default 96.

Returns

double

Exceptions

ArgumentOutOfRangeException

dpi is not finite and positive.

Scale(int, double)

The scale denominator of a level.

public double Scale(int level, double dpi = 96)

Parameters

level int

The level.

dpi double

The dots per inch; default 96.

Returns

double

Exceptions

ArgumentOutOfRangeException

level is not a level of the grid, or dpi is invalid.

ScaleToResolution(double, double)

Converts a scale denominator into a resolution: scale · 0.0254 / dpi.

public static double ScaleToResolution(double scale, double dpi = 96)

Parameters

scale double

The scale denominator.

dpi double

The dots per inch; default 96.

Returns

double

Exceptions

ArgumentOutOfRangeException

dpi is not finite and positive.

TileAt(int, double, double)

The tile that contains a world coordinate; a point on a tile border belongs to the tile right of / away from the origin.

public (long Row, long Column) TileAt(int level, double x, double y)

Parameters

level int

The level.

x double

The X coordinate.

y double

The Y coordinate.

Returns

(long Row, long Column)

Exceptions

ArgumentOutOfRangeException

level is not a level of the grid.

TileEnvelope(int, long, long)

The world envelope of a tile.

public Envelope2D TileEnvelope(int level, long row, long column)

Parameters

level int

The level.

row long

The row, counted from the origin corner.

column long

The column, counted from the origin to the right.

Returns

Envelope2D

Exceptions

ArgumentOutOfRangeException

level is not a level of the grid.

TileRange(int, Envelope2D)

The inclusive row and column range of the tiles that meet a world envelope.

public (long MinRow, long MinColumn, long MaxRow, long MaxColumn) TileRange(int level, Envelope2D envelope)

Parameters

level int

The level.

envelope Envelope2D

The envelope; must not be empty.

Returns

(long MinRow, long MinColumn, long MaxRow, long MaxColumn)

Exceptions

ArgumentOutOfRangeException

level is not a level of the grid, or the envelope is empty.

TryGetWebMercatorZoom(int, out int, double)

Whether a level of this grid is a standard WebMercator zoom level: same origin (upper left), 256 px tiles and the resolution of zoom zoom. Tiles of such a level can be served under that z/x/y unchanged.

public bool TryGetWebMercatorZoom(int level, out int zoom, double relativeTolerance = 1E-06)

Parameters

level int

The level.

zoom int

The WebMercator zoom, or -1.

relativeTolerance double

The allowed relative difference of origin and resolution; default 1e-6.

Returns

bool

Exceptions

ArgumentOutOfRangeException

level is not a level of the grid.

TryGetWebMercatorZoom(double, out int, double, double)

Whether a map scale matches a WebMercator zoom level (0..30). The scale is that of the projected plane (as tile services state it, e.g. 1:591657527.59 for zoom 0 at 96 dpi), not the true scale at a latitude.

public static bool TryGetWebMercatorZoom(double scale, out int zoom, double dpi = 96, double relativeTolerance = 1E-06)

Parameters

scale double

The scale denominator.

zoom int

The zoom level, or -1.

dpi double

The dots per inch; default 96.

relativeTolerance double

The allowed relative difference; default 1e-6. Use a larger one for rounded scales.

Returns

bool

Exceptions

ArgumentOutOfRangeException

dpi is not finite and positive.

TryGetWebMercatorZoomForResolution(double, out int, double)

Whether a resolution matches a WebMercator zoom level (0..30).

public static bool TryGetWebMercatorZoomForResolution(double resolution, out int zoom, double relativeTolerance = 1E-06)

Parameters

resolution double

The resolution in meters per pixel.

zoom int

The zoom level, or -1.

relativeTolerance double

The allowed relative difference; default 1e-6.

Returns

bool

WebMercator(int)

The standard WebMercator grid (EPSG:3857, Google/OSM/Mapbox XYZ): origin (-20037508.342789244, 20037508.342789244) upper left, 256 px tiles, level z has 2^z × 2^z tiles. Level = zoom, row = y, column = x.

public static TileGrid WebMercator(int maxZoom = 24)

Parameters

maxZoom int

The highest zoom level; default 24.

Returns

TileGrid

Exceptions

ArgumentOutOfRangeException

maxZoom is not in 0..30.

WebMercatorResolution(int)

The resolution of a WebMercator zoom level: 2 · 20037508.342789244 / 256 / 2^zoom.

public static double WebMercatorResolution(int zoom)

Parameters

zoom int

The zoom level, ≥ 0.

Returns

double

Exceptions

ArgumentOutOfRangeException

zoom is negative.