GeoStream Tile Coordinates

A GeoStream client makes tile requests to the GeoStream server using a URL similar to:

http://localhost/GeoStream/tile.aspx?t=0,0,300,4,1

This topic describes the parameters passed to the server, using the above URL format, and how the GeoStream server generates tiles.

Note
You should never have to generate tiles using this URL, the JavaScript client automates the tile generation process. This topic is provided only for documentation completeness. The JavaScript API should be used to generate GeoStream maps.

The tile.aspx page is passed a string parameter t. This parameter consists of five comma-separated integer values. All five values must be explicitly specified. These five values are, in order:

• X (tile) coordinate

  No less than 0.5 * -(Zoom * TilesPerSuperTileEdge) and no greater than (0.5 * (Zoom * TilesPerSuperTileEdge)) - 1, where TilesPerSuperTileEdge is the fourth parameter.

  See the SuperTile section below for a detailed description.

  Note
  If the X (tile) coordinate exceeds minimum or maximum parameter values, the individual tile selection will wrap around the greater supertile.

• Y (tile) coordinate

  No less than 0.5 * -(Zoom * TilesPerSuperTileEdge) and no greater than (0.5 * (Zoom * TilesPerSuperTileEdge)) - 1, where TilesPerSuperTileEdge is the fourth parameter.

  See the SuperTile section below for a detailed description.

  Note
  If the Y (tile) coordinate exceeds minimum or maximum parameter values, a black tile will be displayed.

• Tile Size

  The height, in pixels, of the requested tile. Each tile is square, so the tile will also be Tile Size pixels wide.

  The supertile will also be square, with each side TileSize * TilesPerSuperTileEdge in length.

  Caution
  GeoStream will not render a map that is more than 16,000 pixels across. This means that the maximum width of a supertile is 16,000 pixels. To work around this limit, increase the Zoom value.

• Tiles Per Super Tile Edge

  The number of tiles across the width of the supertile. This value must be an even number (a multiple of two). This value is also equal to the height of the supertile (measured in tiles).

  See the SuperTile section below for a detailed description.

• Zoom

  The number of supertiles across the world. If this value increases by one the geographical area covered by each tile will decrease by a factor of four.

The GeoStream server draws tiles using the Mercator projection. The Mercator projection is a cylindrical projection of the earth's surface, where meridians are mapped to vertical lines. This results in some east-west distortion of the map. The map is also distorted north-south to match the east-west distortion.

Note
It is important to note that there is no distortion along the equator, but infinite distortion at each pole. It is for this reason that GeoStream maps do not render the top or bottom 2 degrees of the world.

Each supertile consists of Tiles Per Supertile Edge * Tiles Per SuperTile Edge tiles, arranged in a square grid.

When you request a tile from a GeoStream server, the corresponding supertile is generated. Only the tile you specifically requested (corresponding to the X and Y tile coordinates) will be selected from the supertile and returned. Note that tile coordinates reference the upper left corner of the tile and that the center of the supertile is always a coordinate of 0,0.

Individual tiles are cached on the GeoStream server, but supertiles are not cached.

Example

The supertile below was created using four tiles. The tiles were generated using the following four URLs:

1. http://localhost/GeoStream/tile.aspx?t=-1,-1,300,2,1
2. http://localhost/GeoStream/tile.aspx?t=0,-1,300,2,1
3. http://localhost/GeoStream/tile.aspx?t=-1,0,300,2,1
4. http://localhost/GeoStream/tile.aspx?t=0,0,300,2,1

Recall that the first two tile parameters specify which tile in the supertile to retrieve. The third parameter defines the size of the tile (in this case, 300 pixels square, which is the default unless you are using retina tiles, which are 600 pixels square). The fourth parameter defines the height and width of the supertile, measured in tiles (in this case the supertile is 2x2 tiles). The last parameter is used to calculate the zoom (in this case the entire world is spanned by 1 supertile).

To begin with define:

• TileSize (tile size in pixels)

• TilesPerSuperTileEdge (the number of tiles per super tile)

• Zoom (the number of supertiles across the world)

Next, calculate the number of pixels needed to represent the width of the world (worldWidthPixels) based on the given TileSize, TilesPerSuperTileEdge, and Zoom:

• worldWidthPixels = TileSize * Zoom * TilesPerSuperTileEdge

Using worldWidthPixels, calculate the radius:

• radius = worldWidthPixels / (2 * PI)

Convert the position of the known LatLon to a position on the world. The reference point is the upper left corner of the map - see figure below.

• worldx = (worldWidthPixels * (Longitude / 360)) + worldWidthPixels / 2

• worldy = (worldWidthPixels / 2) - (radius * Log (Tan (PI / 4 + (Latitude * PI) / 360)))

The worldx and worldy values point to a pixel within a tile. The location (or offset) of the point within the tile (the reference being the upper left corner of the tile), needs to be calculated. This can be calculated using the modulo operation:

Find the tile's x offset:

• tileoffsetx = worldx mod TileSize

Find the tile's y offset:

• tileoffsety = worldy mod TileSize

Finally, the x, y coordinates are calculated. Subtract the tile offset from the world position, to get the top left of the tile. Subtract worldWidthPixels / 2 to use the center of the world as a reference, and then divide by the tile size (in pixels) to get the tile coordinate:

• tilex = (worldx - tileoffsetx - worldWidthPixels / 2) / TileSize

• tiley = (worldy - tileoffsety - worldWidthPixels / 2) / TileSize

The coordinates tilex and tiley can now be used for the string parameter, t, outlined at the beginning of the GeoStream Tile Coordinates article. For example:

http://localhost/GeoStream/tile.aspx?t=tilex,tiley,TileSize,TilesPerSuperTile,Zoom