us.zuercher.gpx2map.source.terraserver_usa
Class TerraserverUsaMapSource

java.lang.Object
  us.zuercher.gpx2map.source.AbstractCachedMapSource
      us.zuercher.gpx2map.source.AbstractTiledUrlMapSource
          us.zuercher.gpx2map.source.terraserver_usa.TerraserverUsaMapSource

All Implemented Interfaces:

MapSource

public class TerraserverUsaMapSource
extends AbstractTiledUrlMapSource
implements MapSource

TerraserverUsaMapSource extends AbstractTiledUrlMapSource for the Terraserver USA map server.

The TerraserverUsaMapSource requires the following properties:

Name	Description	Values
type	Determines the map type.	Type 1: 1, USGS_DOQ, DOQ Type 2: 2, USGS_DRG, DRG Type 4: 4, USGS_Urban, USGS_Urban_Area, Urban
scale	Determines the map scale.	Desired scale in meters/pixel. Acceptable values run from 0.25 to 512, in powers of 2 (e.g., 0.25, 0.5, 1, 2, 4, ...).

The TerraserverUsaMapSource has no optional properties.

See the package description for links to details on how the Terraserver USA map server works.

Author:

Stephan Zuercher

Nested Class Summary

private static class

TerraserverUsaMapSource.StripeDescription StripeDescription describes the map tiles required from a particular UTM zone.

Field Summary

private LatLon	northWestLatLon Map boundary: northwest corner.
private static List<MapSourcePropertyDescriptor>	PROPERTIES
private static String	PROPERTY_SCALE Scale property name.
private static String	PROPERTY_TYPE Type property name.
private int	rowCount Number of rows of map tiles in the image.
private double	scale Map scale in meters per pixel.
private static MapSourcePropertyDescriptor	SCALE_PROPERTY_DESCRIPTOR Scale property descriptor.
private LatLon	southEastLatLon Map boundary: southeast corner.
private int	startRow Starting Y coordinate for all map tiles.
private int	terraserverScale Map scale converted to Terraserver scale value.
private int	totalColumnCount Total number of map tile columns in the image.
private String	type Map type.
private static String	TYPE_1 Type values.
private static String	TYPE_2
private static String	TYPE_4
private static MapSourcePropertyDescriptor	TYPE_PROPERTY_DESCRIPTOR Type property descriptor.
private static MapSourcePropertyChoice	TYPE_USGS_DOQ Type property descriptor DOQ choice.
private static MapSourcePropertyChoice	TYPE_USGS_DRG Type property descriptor DRG choice.
private static MapSourcePropertyChoice	TYPE_USGS_URBAN Type property descriptor Urban Area choice.
private int	typeId Map type id.
private static String	URL Map tile URL.
private TreeMap<Integer,TerraserverUsaMapSource.StripeDescription>	zoneStripeMap Map of UTM zone to stripe description.

Constructor Summary

TerraserverUsaMapSource()

Method Summary

private File	computeAddrTypeScaleZoneCacheDir(int xAddr, int zone) Computes the cache directory for a given Terraserver X coordinate and UTM zone.
private File	computeCacheFile(File addrTypeScaleCacheDir, int yAddr) Computes the cache file for a given X coordinate directory and the given Y coordinate.
private void	computeStripeCoords() Using the map boundaries, which tiles must be downloaded from which UTM zones.
Point	computeTerraServerTileAddress(UTM location) Computes the Terraserver X/Y coordinates for a given UTM coordinate.
private File	computeTerraserverUsaCacheDir() Computes the cache directory for this map source, relative to the application cache directory.
private File	computeTypeCacheDir() Computes the cache directory for the current map type, based on the Terraserver map source cache directory.
private File	computeTypeScaleCacheDir() Computes the cache directory for the current map scale, based on the current map type's cache directory.
private File	computeTypeScaleZoneCacheDir(int zone) Computes the cache directory for a given map zone, based on the current map scale's cache directory.
UTM	computeUtm(int xAddr, int yAddr, int zone, char letter) Computes the UTM coordinate of the southwest corner of the given Terraserver map tile.
void	downloadTiles(ProgressMeter meter) Downloads map tiles.
private static MapSourcePropertyChoice[]	generateScaleChoices() Creates map scale choices.
protected int	getColumnCount() Returns the total number of columns in the map.
Dimension	getImageSize() Returns the stitched image size.
double	getMapScale() Returns the number of meter per map pixel.
List<MapSourcePropertyDescriptor>	getProperties() Returns a list of all Terraserver USA map source property descriptors.
protected int	getRowCount() Returns the total number of rows in the map.
protected File	getTile(int col, int row) Returns the location of a given map tile in the cache.
Dimension	getTileSize() Returns the dimensions of a single map tile.
private int	getUtmMultiplier() Returns the multiplier used to convert UTM addresses to Terraserver tile addresses, based on the current map scale and type.
Point	mapLocationToPixel(LatLon location) Maps a location to a pixel on the stitched map.
Point	mapLocationToPixel(UTM location) Maps a location to a pixel on the stitched map.
private String	pad(int value, int digits) Converts the given integer value into a String that is at least the given number of digits long.
void	setBoundingBox(LatLon northWestLatLon, LatLon southEastLatLon) Configures the map's boundaries.
void	setProperty(String name, String value) Sets the given property to the given value.
void	setScale(double mpp) Configures the map scale in meters per pixel.
void	setType(String typeName) Configures the map type by name.

Methods inherited from class us.zuercher.gpx2map.source.AbstractTiledUrlMapSource

download, download, getCompressedCacheFileExtension, stitchTiles

Methods inherited from class us.zuercher.gpx2map.source.AbstractCachedMapSource

getCacheDir, setCacheDir

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface us.zuercher.gpx2map.source.MapSource

setCacheDir, stitchTiles

Field Detail

URL

private static final String URL

Map tile URL.

See Also:

Constant Field Values

PROPERTY_TYPE

private static final String PROPERTY_TYPE

Type property name.

See Also:

Constant Field Values

TYPE_USGS_DOQ

private static final MapSourcePropertyChoice TYPE_USGS_DOQ

Type property descriptor DOQ choice.

TYPE_USGS_DRG

private static final MapSourcePropertyChoice TYPE_USGS_DRG

Type property descriptor DRG choice.

TYPE_USGS_URBAN

private static final MapSourcePropertyChoice TYPE_USGS_URBAN

Type property descriptor Urban Area choice.

TYPE_PROPERTY_DESCRIPTOR

private static final MapSourcePropertyDescriptor TYPE_PROPERTY_DESCRIPTOR

Type property descriptor.

PROPERTY_SCALE

private static final String PROPERTY_SCALE

Scale property name.

See Also:

Constant Field Values

SCALE_PROPERTY_DESCRIPTOR

private static final MapSourcePropertyDescriptor SCALE_PROPERTY_DESCRIPTOR

Scale property descriptor.

TYPE_1

private static final String TYPE_1

Type values. The type property value is converted to one of these.

See Also:

Constant Field Values

TYPE_2

private static final String TYPE_2

See Also:

Constant Field Values

TYPE_4

private static final String TYPE_4

See Also:

Constant Field Values

PROPERTIES

private static final List<MapSourcePropertyDescriptor> PROPERTIES

northWestLatLon

private LatLon northWestLatLon

Map boundary: northwest corner.

southEastLatLon

private LatLon southEastLatLon

Map boundary: southeast corner.

type

private String type

Map type. See TYPE_1, TYPE_2, TYPE_4.

typeId

private int typeId

Map type id. One of 1, 2 or 4.

scale

private double scale

Map scale in meters per pixel.

terraserverScale

private int terraserverScale

Map scale converted to Terraserver scale value.

zoneStripeMap

private TreeMap<Integer,TerraserverUsaMapSource.StripeDescription> zoneStripeMap

Map of UTM zone to stripe description.

See Also:

computeStripeCoords()

totalColumnCount

private int totalColumnCount

Total number of map tile columns in the image.

startRow

private int startRow

Starting Y coordinate for all map tiles.

rowCount

private int rowCount

Number of rows of map tiles in the image.

Constructor Detail

TerraserverUsaMapSource

public TerraserverUsaMapSource()

Method Detail

setType

public void setType(String typeName)

Configures the map type by name.

Parameters:

typeName - one of the names given in TYPE_USGS_DOQ, TYPE_USGS_DRG, or TYPE_USGS_URBAN.

Throws:

IllegalMapSourcePropertyValueException - if typeName is not one of the legal values.

setScale

public void setScale(double mpp)

Configures the map scale in meters per pixel.

Parameters:

mpp - map scale in meters per pixel.

Throws:

IllegalMapSourcePropertyValueException - if the map scale is not a power of in range [0.25, 512].

setBoundingBox

public void setBoundingBox(LatLon northWestLatLon,
                           LatLon southEastLatLon)

Configures the map's boundaries.

Specified by:

setBoundingBox in interface MapSource

Parameters:

northWestLatLon - the northwest corner of the map

southEastLatLon - the southeast corner of the map

See Also:

MapSource.setBoundingBox(LatLon, LatLon)

downloadTiles

public void downloadTiles(ProgressMeter meter)
                   throws IOException

Downloads map tiles. Terraserver organizes map tiles within UTM zones. Tile x/y coordinates do not necessarily line up at zone boundaries because UTM eastings are based on the center of the zone, not the edge.

We first compute the tiles that we require from each zone and then download all necessary tiles for each zone in succession.

Specified by:

downloadTiles in interface MapSource

Parameters:

meter - a progress meter

Throws:

IOException - if there's an error downloading tiles

See Also:

MapSource.downloadTiles(ProgressMeter)

computeStripeCoords

private void computeStripeCoords()

Using the map boundaries, which tiles must be downloaded from which UTM zones. Initializes the zoneStripeMap with the results. In simple cases, data is only required from a single zone.

mapLocationToPixel

public Point mapLocationToPixel(LatLon location)

Maps a location to a pixel on the stitched map. Uses Conversions to convert the location to a UTM coordinate and calls mapLocationToPixel(UTM).

Specified by:

mapLocationToPixel in interface MapSource

Parameters:

location - location to determine on the map

Returns:

pixel location of location, null if location is off map

See Also:

MapSource.mapLocationToPixel(LatLon)

mapLocationToPixel

public Point mapLocationToPixel(UTM location)

Maps a location to a pixel on the stitched map.

Parameters:

location - the UTM coordinate to determine on the map

Returns:

the Point on the stitched map cooresponding to the given location.

See Also:

mapLocationToPixel(LatLon)

pad

private String pad(int value,
                   int digits)

Converts the given integer value into a String that is at least the given number of digits long. The value is padded with leading zeros, if necessary.

Parameters:

value - value to convert

digits - minimum number of digits

Returns:

a String digits or more characters in length.

computeTerraserverUsaCacheDir

private File computeTerraserverUsaCacheDir()

Computes the cache directory for this map source, relative to the application cache directory.

Returns:

cache directory specific to this map source

computeTypeCacheDir

private File computeTypeCacheDir()

Computes the cache directory for the current map type, based on the Terraserver map source cache directory.

Returns:

cache directory specific to the current map type.

See Also:

computeTerraserverUsaCacheDir()

computeTypeScaleCacheDir

private File computeTypeScaleCacheDir()

Computes the cache directory for the current map scale, based on the current map type's cache directory.

Returns:

cache directory specific to the current map scale

See Also:

computeTypeCacheDir()

computeTypeScaleZoneCacheDir

private File computeTypeScaleZoneCacheDir(int zone)

Computes the cache directory for a given map zone, based on the current map scale's cache directory.

Parameters:

zone - UTM zone

Returns:

cache directory specific to the UTM zone

See Also:

computeTypeScaleCacheDir()

computeAddrTypeScaleZoneCacheDir

private File computeAddrTypeScaleZoneCacheDir(int xAddr,
                                              int zone)

Computes the cache directory for a given Terraserver X coordinate and UTM zone.

Parameters:

xAddr - Terraserver X coordinate

zone - URM zone

Returns:

cache directory specific to the UTM zone and X-coordinate.

See Also:

computeTypeScaleZoneCacheDir(int)

computeCacheFile

private File computeCacheFile(File addrTypeScaleCacheDir,
                              int yAddr)

Computes the cache file for a given X coordinate directory and the given Y coordinate.

Parameters:

addrTypeScaleCacheDir - the cache directory for the X coordinate within which the Y coordinate map tile will be stored.

yAddr - the Y coordinate

Returns:

the cache file, with compression extension.

See Also:

computeAddrTypeScaleZoneCacheDir(int, int)

computeTerraServerTileAddress

public Point computeTerraServerTileAddress(UTM location)

Computes the Terraserver X/Y coordinates for a given UTM coordinate.

Parameters:

location - UTM coordinate to retrieve X/Y values for.

Returns:

a Point containing the Terraserver X/Y coordinates for the map tile that contains the given UTM coordinate.

computeUtm

public UTM computeUtm(int xAddr,
                      int yAddr,
                      int zone,
                      char letter)

Computes the UTM coordinate of the southwest corner of the given Terraserver map tile.

Parameters:

xAddr - Terraserver map tile X coordinate

yAddr - Terraserver map tile Y coordinate

zone - UTM zone

letter - UTM letter designator

Returns:

the UTM coordinate of the southwest corner of the given Terraserver map tile.

getUtmMultiplier

private int getUtmMultiplier()

Returns the multiplier used to convert UTM addresses to Terraserver tile addresses, based on the current map scale and type. Note that not all map types support all map scales values. If the current map scale is not supported by the current map type, a lower resolution scale will be used.

Returns:

the UTM multiplier for the current map scale and type.

getImageSize

public Dimension getImageSize()

Returns the stitched image size.

Specified by:

getImageSize in interface MapSource

Returns:

the dimensions of the final map image.

See Also:

MapSource.getImageSize()

getTileSize

public Dimension getTileSize()

Returns the dimensions of a single map tile. Terraserver USA map tiles are always 200x200.

Returns:

the dimensions of a single map tile.

getProperties

public List<MapSourcePropertyDescriptor> getProperties()

Returns a list of all Terraserver USA map source property descriptors.

Specified by:

getProperties in interface MapSource

Returns:

a List of MapSourcePropertyDescriptor

setProperty

public void setProperty(String name,
                        String value)

Sets the given property to the given value.

Specified by:

setProperty in interface MapSource

Parameters:

name - the property name

value - the property's value

Throws:

IllegalMapSourcePropertyNameException - if the property name is not known

IllegalMapSourcePropertyValueException - if the property value is illegal

getMapScale

public double getMapScale()

Returns the number of meter per map pixel.

Specified by:

getMapScale in interface MapSource

Returns:

the number of meter per map pixel.

getColumnCount

protected int getColumnCount()

Returns the total number of columns in the map.

Specified by:

getColumnCount in class AbstractTiledUrlMapSource

Returns:

the total number of columns in the map.

See Also:

AbstractTiledUrlMapSource.getColumnCount()

getRowCount

protected int getRowCount()

Returns the total number of rows in the map.

Specified by:

getRowCount in class AbstractTiledUrlMapSource

Returns:

the total number of rows in the map.

See Also:

AbstractTiledUrlMapSource.getRowCount()

getTile

protected File getTile(int col,
                       int row)

Returns the location of a given map tile in the cache.

Specified by:

getTile in class AbstractTiledUrlMapSource

Parameters:

col - 0-based column index

row - 0-based row index

Returns:

the location of a given map tile in the cache.

See Also:

AbstractTiledUrlMapSource.getTile(int, int)

generateScaleChoices

private static MapSourcePropertyChoice[] generateScaleChoices()

Creates map scale choices. Values are from -0.25 to 512 in powers of 2.

Returns:

map scale choices