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 as displayed to the user. 066 * 067 * @return Name of the tile layer 068 */ 069 String getName(); 070 071 /** 072 * A unique id for this tile source. 073 * 074 * Unlike the name it has to be unique and has to consist only of characters 075 * valid for filenames. 076 * 077 * @return the id 078 */ 079 String getId(); 080 081 /** 082 * Constructs the tile url. 083 * 084 * @param zoom 085 * @param tilex 086 * @param tiley 087 * @return fully qualified url for downloading the specified tile image 088 */ 089 String getTileUrl(int zoom, int tilex, int tiley) throws IOException; 090 091 /** 092 * Specifies the tile image type. For tiles rendered by Mapnik or 093 * Osmarenderer this is usually <code>"png"</code>. 094 * 095 * @return file extension of the tile image type 096 */ 097 String getTileType(); 098 099 /** 100 * Specifies how large each tile is. 101 * @return The size of a single tile in pixels. 102 */ 103 int getTileSize(); 104 105 /** 106 * Gets the distance using Spherical law of cosines. 107 * @return the distance, m. 108 */ 109 double getDistance(double la1, double lo1, double la2, double lo2); 110 111 /** 112 * Transform longitude to pixelspace. 113 * @return [0..2^Zoomlevel*TILE_SIZE[ 114 */ 115 int LonToX(double aLongitude, int aZoomlevel); 116 117 /** 118 * Transforms latitude to pixelspace. 119 * @return [0..2^Zoomlevel*TILE_SIZE[ 120 */ 121 int LatToY(double aLat, int aZoomlevel); 122 123 /** 124 * Transforms pixel coordinate X to longitude 125 * @return ]-180..180[ 126 */ 127 double XToLon(int aX, int aZoomlevel); 128 129 /** 130 * Transforms pixel coordinate Y to latitude. 131 * @return [MIN_LAT..MAX_LAT] 132 */ 133 double YToLat(int aY, int aZoomlevel); 134 135 /** 136 * Transforms longitude to X tile coordinate. 137 * @return [0..2^Zoomlevel[ 138 */ 139 double lonToTileX(double lon, int zoom); 140 141 /** 142 * Transforms latitude to Y tile coordinate. 143 * @return [0..2^Zoomlevel[ 144 */ 145 double latToTileY(double lat, int zoom); 146 147 /** 148 * Transforms tile X coordinate to longitude. 149 * @return ]-180..180[ 150 */ 151 double tileXToLon(int x, int zoom); 152 153 /** 154 * Transforms tile Y coordinate to latitude. 155 * @return [MIN_LAT..MAX_LAT] 156 */ 157 double tileYToLat(int y, int zoom); 158}