001// License: GPL. For details, see Readme.txt file. 002package org.openstreetmap.gui.jmapviewer.interfaces; 003 004import java.io.IOException; 005 006import org.openstreetmap.gui.jmapviewer.JMapViewer; 007 008/** 009 * 010 * @author Jan Peter Stotz 011 */ 012public interface TileSource extends Attributed { 013 014 /** 015 * Specifies the different mechanisms for detecting updated tiles 016 * respectively only download newer tiles than those stored locally. 017 * 018 * <ul> 019 * <li>{@link #IfNoneMatch} Server provides ETag header entry for all tiles 020 * and <b>supports</b> conditional download via <code>If-None-Match</code> 021 * header entry.</li> 022 * <li>{@link #ETag} Server provides ETag header entry for all tiles but 023 * <b>does not support</b> conditional download via 024 * <code>If-None-Match</code> header entry.</li> 025 * <li>{@link #IfModifiedSince} Server provides Last-Modified header entry 026 * for all tiles and <b>supports</b> conditional download via 027 * <code>If-Modified-Since</code> header entry.</li> 028 * <li>{@link #LastModified} Server provides Last-Modified header entry for 029 * all tiles but <b>does not support</b> conditional download via 030 * <code>If-Modified-Since</code> header entry.</li> 031 * <li>{@link #None} The server does not support any of the listed 032 * mechanisms.</li> 033 * </ul> 034 * 035 */ 036 public enum TileUpdate { 037 IfNoneMatch, ETag, IfModifiedSince, LastModified, None 038 } 039 040 /** 041 * Specifies the maximum zoom value. The number of zoom levels is [0.. 042 * {@link #getMaxZoom()}]. 043 * 044 * @return maximum zoom value that has to be smaller or equal to 045 * {@link JMapViewer#MAX_ZOOM} 046 */ 047 int getMaxZoom(); 048 049 /** 050 * Specifies the minimum zoom value. This value is usually 0. 051 * Only for maps that cover a certain region up to a limited zoom level 052 * this method should return a value different than 0. 053 * 054 * @return minimum zoom value - usually 0 055 */ 056 int getMinZoom(); 057 058 /** 059 * @return The supported tile update mechanism 060 * @see TileUpdate 061 */ 062 TileUpdate getTileUpdate(); 063 064 /** 065 * A tile layer name has to be unique and has to consist only of characters 066 * valid for filenames. 067 * 068 * @return Name of the tile layer 069 */ 070 String getName(); 071 072 /** 073 * Constructs the tile url. 074 * 075 * @param zoom 076 * @param tilex 077 * @param tiley 078 * @return fully qualified url for downloading the specified tile image 079 */ 080 String getTileUrl(int zoom, int tilex, int tiley) throws IOException; 081 082 /** 083 * Specifies the tile image type. For tiles rendered by Mapnik or 084 * Osmarenderer this is usually <code>"png"</code>. 085 * 086 * @return file extension of the tile image type 087 */ 088 String getTileType(); 089 090 /** 091 * Specifies how large each tile is. 092 * @return The size of a single tile in pixels. 093 */ 094 int getTileSize(); 095 096 /** 097 * Gets the distance using Spherical law of cosines. 098 * @return the distance, m. 099 */ 100 double getDistance(double la1, double lo1, double la2, double lo2); 101 102 /** 103 * Transform longitude to pixelspace. 104 * @return [0..2^Zoomlevel*TILE_SIZE[ 105 */ 106 int LonToX(double aLongitude, int aZoomlevel); 107 108 /** 109 * Transforms latitude to pixelspace. 110 * @return [0..2^Zoomlevel*TILE_SIZE[ 111 */ 112 int LatToY(double aLat, int aZoomlevel); 113 114 /** 115 * Transforms pixel coordinate X to longitude 116 * @return ]-180..180[ 117 */ 118 double XToLon(int aX, int aZoomlevel); 119 120 /** 121 * Transforms pixel coordinate Y to latitude. 122 * @return [MIN_LAT..MAX_LAT] 123 */ 124 double YToLat(int aY, int aZoomlevel); 125 126 /** 127 * Transforms longitude to X tile coordinate. 128 * @return [0..2^Zoomlevel[ 129 */ 130 double lonToTileX(double lon, int zoom); 131 132 /** 133 * Transforms latitude to Y tile coordinate. 134 * @return [0..2^Zoomlevel[ 135 */ 136 double latToTileY(double lat, int zoom); 137 138 /** 139 * Transforms tile X coordinate to longitude. 140 * @return ]-180..180[ 141 */ 142 double tileXToLon(int x, int zoom); 143 144 /** 145 * Transforms tile Y coordinate to latitude. 146 * @return [MIN_LAT..MAX_LAT] 147 */ 148 double tileYToLat(int y, int zoom); 149}