us.zuercher.gpx2map.source
Interface MapSource

All Known Implementing Classes:

AbstractCachedMapSource, AbstractTiledUrlMapSource, DummyMapSource, TerraserverUsaMapSource

public interface MapSource

MapSource represents a map source. MapSource instances are obtained from SourceFactory.

Once you have an instance of MapSource, you must take the following steps:

1. Query getProperties() and provide values for at least the required properties.
2. Call setCacheDir(File) to set a cache directory.
3. Call setBoundingBox(LatLon, LatLon) to set the map's boundaries.
4. Call downloadTiles(ProgressMeter) to download the map's tiles.
5. Call stitchTiles(File, ProgressMeter) to stitch the downloaded tiles together into a map.

After that, mapLocationToPixel(LatLon) and getImageSize(), can be used to manipulate the map.

Multiple concurrently existing maps can be achieved by creating multiple MapSource instances.

WARNING: MapSources are not guaranteed to be thread safe. In particular, multiple concurrently downloading MapSources may cause the cache to be corrupted. External synchronization is therefore necessary.

Author:

Stephan Zuercher

Method Summary

void	downloadTiles(ProgressMeter meter) Downloads the necessary map data.
Dimension	getImageSize()
double	getMapScale() Returns the map's scale in meters per pixel.
List<MapSourcePropertyDescriptor>	getProperties() Retrieve a list of MapSourcePropertyDescriptors for this map source.
Point	mapLocationToPixel(LatLon location) Compute the pixel coordinates of the given location in the output file generated by stitchTiles(File, ProgressMeter).
void	setBoundingBox(LatLon northWest, LatLon southEast) Configures the bounding box of latitude and longitude upon which map data will be drawn.
void	setCacheDir(File cacheDir) Configures the directory where this map source should place its cached data.
void	setProperty(String name, String value) Set the value of the given property.
void	stitchTiles(File outputFile, ProgressMeter meter) Stitch tiles together and write them as a PPM file to the given abstract file name.

Method Detail

getProperties

List<MapSourcePropertyDescriptor> getProperties()

Retrieve a list of MapSourcePropertyDescriptors for this map source.

Returns:

MapSourcePropertyDescriptors for this map source or an empty list if no properties exist.

setProperty

void setProperty(String name,
                 String value)

Set the value of the given property. It may be more expedient to use MapSourcePropertyDescriptor.set(MapSource, String).

Parameters:

name - property name

value - property value

setCacheDir

void setCacheDir(File cacheDir)

Configures the directory where this map source should place its cached data. Note that all map sources share this directory. Concrete implementations should create a sub-directory with an appropriately unique name.

Parameters:

cacheDir - map cache directory.

getMapScale

double getMapScale()

Returns the map's scale in meters per pixel.

Returns:

the map's scale in meters per pixel.

setBoundingBox

void setBoundingBox(LatLon northWest,
                    LatLon southEast)

Configures the bounding box of latitude and longitude upon which map data will be drawn.

Parameters:

northWest - northwest corner of the map

southEast - sourtheast corner of the map

downloadTiles

void downloadTiles(ProgressMeter meter)
                   throws IOException

Downloads the necessary map data. For most map sources this means converting the configured bounding box into map coordinates and using those coordinates to download the appropriate map tiles.

Implementations should cache map tiles in the cache directory.

Parameters:

meter - progress meter for indicating download progress

Throws:

IOException - if there's an error downloading map data

stitchTiles

void stitchTiles(File outputFile,
                 ProgressMeter meter)
                 throws IOException

Stitch tiles together and write them as a PPM file to the given abstract file name.

Parameters:

outputFile - name of output file.

meter - a progress meter

Throws:

IOException - on file error

See Also:

WritablePpmImage

mapLocationToPixel

Point mapLocationToPixel(LatLon location)

Compute the pixel coordinates of the given location in the output file generated by stitchTiles(File, ProgressMeter). Locations are from upper-left corner of the file, which is (0, 0).

Parameters:

location - location to compute

Returns:

pixel location of location, null if location is off map

getImageSize

Dimension getImageSize()

Returns:

stitched image dimensions