TileLayer / Renderer interface

[elemoine]

Tom and I have talked about the TileLayer/Renderer interface, which is currently a bit unclear and messy (the HTML renderer uses getTileForXYZ, while the WebGL uses getData).

Based on discussions with Tom, and Tim during the code sprint, the getTile way seems to be the way the go. We've also mentioned introducing the notion of TileMatrixSet (TilePyramid below).

Below is the list of types and interfaces we've come up with - comments welcome.

TileCoord
   z
   x
   y

TileBounds
   minX
   minY
   maxX (exclusive)
   maxY (exclusive)
   z
   contains(tileCoord) -> boolean
   overlaps(tileBounds) -> boolean
   touches(tileBounds) -> boolean
   isEmpty -> boolean
   include(tileCoord)

TileGrid
   id string
   origin Loc
   corner TOP_LEFT | BOTTOM_LEFT
   resolution number
   extent Bounds
   getTileCoord(Loc) -> tileCoord

TilePyramid
   projection Projection
   grids Array.<TileGrid>
   extent Bounds
   getResolutions -> Array.<number>
   getParents(tileCoord) -> Array.<TileCoord>
   getChildren(tileCoord) -> Bounds
   *getTileExtent(tileCoord) -> Bounds
   getTileBounds(Bounds, resolution) -> TileBounds

   (* find better name)

Tile
   tileCoord TileCoord
   url string

TileLayer
   tilePyramid
   extent Bounds
   getTile(tileCoord) -> Tile

[twpayne]

+1 from me :)

Key features of this architecture are:

• The ability to convert geographical coordinates to and from tile coordinates, without loading tiles. This allows renderers to work in whichever coordinate system is most convenient for them.
• Clean separation of how tiles are laid out vs. the actual data they contain. For example, this means that there only need be one instance of the OpenStreetMap tile layout (TilePyramid) which can be shared between multiple TileLayers.
• Common TilePyramids can be pre-supplied (e.g. for OSM), or equally computed when necessary, e.g. from the response to a WMTS GetCapabilities request. TilePyramids are flexible enough to represent WMTS, TMS, and OSM tile layouts.
• High-level convenience functions are easily implementable in terms of the more fundamental functions exposed above. For example, the original TileLayer.getData(Bounds, resolution) -> Array.<Array.<Tile>> function can be written in terms of TileLayer.getTilePyramid().getTileBounds(Bounds, resolution) and a nested loop of calls to TileLayer.getTile(tileCoord). Commonly used convenience functions can be implemented in the TileLayer base class and therefore shared between renderers.

[twpayne]

Minor update (this is nit picking).

In the above, both TilePyramid.getChildren and TilePyramid.getTileExtent have the same signature. What should happen is:

TilePyramid.getChildren should return a TileBounds of all the tiles at the next resolution which are overlapped by the parent tile.

TilePyramid.getTileExtent should return the geographical bounds of the passed tile.

[tschaub]

I agree with the ideas here and was headed toward the same.

There is some redundancy in the corner, extent, and origin properties of a TileGrid (assuming the TileGrid doesn't indicate data availability, only the grid structure - the layer extent indicates data availability). As I see it, there are four possible tile indexing schemes:

A:                         B:

*-----|-----|-----|        |-----|-----|-----*
| 0,0 | 1,0 | 2,0 |        | 2,0 | 1,0 | 0,0 |
|-----|-----|-----|        |-----|-----|-----|
| 0,0 | 1,0 | 2,0 |        | 2,1 | 1,1 | 0,1 |
|-----|-----|-----|        |-----|-----|-----|
| 0,2 | 1,2 | 2,2 |        | 2,2 | 1,2 | 0,2 |
|-----|-----|-----|        |-----|-----|-----|


C:                         D:

|-----|-----|-----|        |-----|-----|-----|
| 2,2 | 1,2 | 0,2 |        | 0,2 | 1,2 | 2,2 |
|-----|-----|-----|        |-----|-----|-----|
| 2,1 | 1,1 | 0,1 |        | 0,1 | 1,1 | 2,1 |
|-----|-----|-----|        |-----|-----|-----|
| 2,0 | 1,0 | 0,0 |        | 0,0 | 1,0 | 2,0 |
|-----|-----|-----*        *-----|-----|-----|

These can be represented by two properties (extent and corner) or three properties (extent, xRight, and yDown). I assume more people would find the first easier to understand. The second is what you need to determine the numbering scheme.

Since a tile source may support more than one tile pyramid, I'd like to talk a bit about how this can be represented on a layer.

Also, since the map should really be configured with a tile pyramid (I like the name TilePyramid), and nearly every pyramid we'll be dealing with will be "regular" (same origin/scheme for all grids), we'll either want to make a convenient factory for creating pyramids based on projection, numZoomLevels, opt_maxResolution (or same logic we currently use in map), or create a RegularTilePyramid constructor that provides the same.

[elemoine]

Thanks Tim. Good comments. I've started writing code for the TileGrid and TilePyramid constructors, and for a createRegular TilePyramid factory. See 1460be2.

[elemoine]

Done in the exp branch. Closing.