001// License: GPL. For details, see Readme.txt file. 002package org.openstreetmap.gui.jmapviewer.interfaces; 003 004import java.awt.Point; 005import java.io.IOException; 006import java.util.List; 007import java.util.Map; 008 009import org.openstreetmap.gui.jmapviewer.JMapViewer; 010import org.openstreetmap.gui.jmapviewer.Tile; 011import org.openstreetmap.gui.jmapviewer.TileXY; 012 013/** 014 * 015 * @author Jan Peter Stotz 016 */ 017public interface TileSource extends Attributed { 018 019 /** 020 * Specifies the maximum zoom value. The number of zoom levels is [0.. 021 * {@link #getMaxZoom()}]. 022 * 023 * @return maximum zoom value that has to be smaller or equal to 024 * {@link JMapViewer#MAX_ZOOM} 025 */ 026 int getMaxZoom(); 027 028 /** 029 * Specifies the minimum zoom value. This value is usually 0. 030 * Only for maps that cover a certain region up to a limited zoom level 031 * this method should return a value different than 0. 032 * 033 * @return minimum zoom value - usually 0 034 */ 035 int getMinZoom(); 036 037 /** 038 * A tile layer name as displayed to the user. 039 * 040 * @return Name of the tile layer 041 */ 042 String getName(); 043 044 /** 045 * A unique id for this tile source. 046 * 047 * Unlike the name it has to be unique and has to consist only of characters 048 * valid for filenames. 049 * 050 * @return the id 051 */ 052 String getId(); 053 054 /** 055 * Constructs the tile url. 056 * 057 * @param zoom zoom level 058 * @param tilex X coordinate 059 * @param tiley Y coordinate 060 * @return fully qualified url for downloading the specified tile image 061 * @throws IOException if any I/O error occurs 062 */ 063 String getTileUrl(int zoom, int tilex, int tiley) throws IOException; 064 065 /** 066 * Creates tile identifier that is unique among all tile sources, but the same tile will always 067 * get the same identifier. Used for creation of cache key. 068 * 069 * @param zoom zoom level 070 * @param tilex X coordinate 071 * @param tiley Y coordinate 072 * @return tile identifier 073 */ 074 String getTileId(int zoom, int tilex, int tiley); 075 076 /** 077 * Specifies how large each tile is. 078 * @return The size of a single tile in pixels. -1 if default size should be used 079 */ 080 int getTileSize(); 081 082 /** 083 * @return default tile size, for this tile source 084 * TODO: @since 085 */ 086 int getDefaultTileSize(); 087 088 /** 089 * Gets the distance using Spherical law of cosines. 090 * @param la1 latitude of first point 091 * @param lo1 longitude of first point 092 * @param la2 latitude of second point 093 * @param lo2 longitude of second point 094 * @return the distance betwen first and second point, in m. 095 */ 096 double getDistance(double la1, double lo1, double la2, double lo2); 097 098 /** 099 * @param lon longitude 100 * @param lat latitude 101 * @param zoom zoom level 102 * @return transforms longitude and latitude to pixel space (as if all tiles at specified zoom level where joined) 103 */ 104 Point latLonToXY(double lat, double lon, int zoom); 105 106 /** 107 * @param point point 108 * @param zoom zoom level 109 * @return transforms longitude and latitude to pixel space (as if all tiles at specified zoom level where joined) 110 */ 111 Point latLonToXY(ICoordinate point, int zoom); 112 113 /** 114 * @param point point 115 * @param zoom zoom level 116 * @return WGS84 Coordinates of given point 117 */ 118 ICoordinate xyToLatLon(Point point, int zoom); 119 120 /** 121 * 122 * @param x X coordinate 123 * @param y Y coordinate 124 * @param zoom zoom level 125 * @return WGS84 Coordinates of given point 126 */ 127 ICoordinate xyToLatLon(int x, int y, int zoom); 128 129 /** 130 * @param lon longitude 131 * @param lat latitude 132 * @param zoom zoom level 133 * @return x and y tile indices 134 */ 135 TileXY latLonToTileXY(double lat, double lon, int zoom); 136 137 /** 138 * 139 * @param point point 140 * @param zoom zoom level 141 * @return x and y tile indices 142 */ 143 TileXY latLonToTileXY(ICoordinate point, int zoom); 144 145 /** 146 * @param xy X/Y coordinates 147 * @param zoom zoom level 148 * @return WGS84 coordinates of given tile 149 */ 150 ICoordinate tileXYToLatLon(TileXY xy, int zoom); 151 152 /** 153 * 154 * @param tile Tile 155 * @return WGS84 coordinates of given tile 156 */ 157 ICoordinate tileXYToLatLon(Tile tile); 158 159 /** 160 * 161 * @param x X coordinate 162 * @param y Y coordinate 163 * @param zoom zoom level 164 * @return WGS84 coordinates of given tile 165 */ 166 ICoordinate tileXYToLatLon(int x, int y, int zoom); 167 168 /** 169 * @param zoom zoom level 170 * @return maximum X index of tile for specified zoom level 171 */ 172 int getTileXMax(int zoom); 173 174 /** 175 * 176 * @param zoom zoom level 177 * @return minimum X index of tile for specified zoom level 178 */ 179 int getTileXMin(int zoom); 180 181 /** 182 * 183 * @param zoom zoom level 184 * @return maximum Y index of tile for specified zoom level 185 */ 186 int getTileYMax(int zoom); 187 188 /** 189 * @param zoom zoom level 190 * @return minimum Y index of tile for specified zoom level 191 */ 192 int getTileYMin(int zoom); 193 194 /** 195 * Determines, if the returned data from TileSource represent "no tile at this zoom level" situation. Detection 196 * algorithms differ per TileSource, so each TileSource should implement each own specific way. 197 * 198 * @param headers HTTP headers from response from TileSource server 199 * @param statusCode HTTP status code 200 * @param content byte array representing the data returned from the server 201 * @return true, if "no tile at this zoom level" situation detected 202 */ 203 boolean isNoTileAtZoom(Map<String, List<String>> headers, int statusCode, byte[] content); 204 205 /** 206 * Extracts metadata about the tile based on HTTP headers 207 * 208 * @param headers HTTP headers from Tile Source server 209 * @return tile metadata 210 */ 211 Map<String, String> getMetadata(Map<String, List<String>> headers); 212}