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}