this namespace hold structures and code written by Scott Morris. More...

Classes
class	AutoLayer
	RAII approach to the old TopoFusion Layer data structure. More...

class	Tile_manager
	RAII tool for opening and closing the DOQ master index. More...

class	DOrthoQuad
	Digital orthoquad buffer. More...

struct	tile_entry
	data structure for downloaded UTM tiles, like a pt More...

struct	Ellipsoid
	a TopoFusion data structure used to represent an ellipsoid earth More...

struct	pt
	definition for a TopoFusion pt More...

struct	seg
	old TopoFusion data structure for a sequence of pt structures More...

struct	track
	old TopoFusion data structure: metadata for a seg More...

struct	waypoint
	definition used for waypoint More...

struct	layer
	definition used for layer More...

Functions
Int_matrix	get_aerial_image (const pt &nw_corner, size_t width, size_t height)
	return a matrix (like a monochrome image) of aerial imagery More...

Image	get_topographic_map_detail (const pt &nw_corner, size_t width, size_t height)
	return an image of a chunk of topographic map More...

int	download_tile (const tile_entry entry, char buffer, int bufsize)
	download a 200x200 terraserver tile using the internet. More...

int	validate_ellipsoid_table ()
	verify that ellipsoid ids correspond to positions in ellipsoid list More...

void	LLtoUTM (int ReferenceEllipsoid, const double Lat, const double Long, pt &utm)
	convert Latitude and Longitude to Universal Transverse Mercator coordinates More...

void	utm_to_lat_long (int ReferenceEllipsoid, const pt &utm, double &Lat, double &Long)
	convert Universal Transverse Mercator coordinates to Latitude and Longitude More...

void	utm_to_lat_long (int ReferenceEllipsoid, const std::vector< pt > &utm_in, std::vector< double > latitude_out, std::vector< double > longitude_out)
	this is a fast, vectorized (bulk) version of the single-pt function. More...

void	UTMtoGPXLL (int ReferenceEllipsoid, const pt &utm, double &Lat, double &Long)
	converts Universal Transverse Mercator coordinates coords to Latitude and Longitude. More...

double	getNewEasting (const pt &utm, int new_zone)
	return an easting coordinate (from zone) relative to new_zone More...

char	zone_of (int ReferenceEllipsoid, const pt &p)
	return the proper zone number for the given point More...

double	dist (const pt a, const pt b)
	compute approx. Great Circle distance between two UTM points More...

double	segmentLength (const seg *s)
	computes the length of a segment More...

void	initLayer (layer *l)
	clear all the fields of a layer (pointers assumed to be dangling) More...

void	destroyLayer (layer *l)
	release memory in the layer's tracks and waypoints arrays More...

void	initTrack (track *t)
	clear the fields of a track (like a default constructor) More...

void	initWaypoint (waypoint *w)
	clear the point.ele field of a waypoint (and that's all). More...

pt	make_pt (double eee, double nnn, char zzz, double elev=NO_ELEV)
	construct a point from its parameters but not as a ctor. More...

int	readTrack_GPX (const std::string &filename, layer *l)
	read a track from a named file into the pointed-to layer More...

int	writeTrack_GPX (const std::string &filename, const layer &l)
	write a track (stored in the indicated layer) into a named file More...

Variables
const char *	IVILAB_DOQ_TILE_CACHE_DIRECTORY ="/net/v04/data_3/trails/doq_cache"
	intentionally-long pathname to where we cache DOQ tiles at the lab. More...

const size_t	MAX_TRACKSTRING = 255
	max len of string field in track, etc More...

const int	NO_ELEV = -1
	sentinel value for "blank" pt::ele More...

const size_t	LAYER_FN_SIZE = 2048
	max length of a layer's filename field More...

Detailed Description

this namespace hold structures and code written by Scott Morris.

Enumeration Type Documentation

enum kjb::TopoFusion::ELLIPSOID_ID

Enumerator
ELLIPSOID_Airy
ELLIPSOID_Australian_National
ELLIPSOID_Bessel_1841
ELLIPSOID_Bessel_1841_Nambia
ELLIPSOID_Clarke_1866	standard for UTM coordinates
ELLIPSOID_Clarke_1880
ELLIPSOID_Everest
ELLIPSOID_Fischer_1960_Mercury
ELLIPSOID_Fischer_1968
ELLIPSOID_GRS_1967
ELLIPSOID_GRS_1980	also fairly common
ELLIPSOID_Helmert_1906
ELLIPSOID_Hough
ELLIPSOID_International
ELLIPSOID_Krassovsky
ELLIPSOID_Modified_Airy
ELLIPSOID_Modified_Everest
ELLIPSOID_Modified_Fischer_1960
ELLIPSOID_South_American_1969
ELLIPSOID_WGS_60
ELLIPSOID_WGS_66
ELLIPSOID_WGS_72
ELLIPSOID_WGS_84	this is the most popular choice
ELLIPSOID_END_OF_LIST
ELLIPSOID_START_OF_LIST

Function Documentation

void kjb::TopoFusion::destroyLayer ( layer * l )

release memory in the layer's tracks and waypoints arrays

double kjb::TopoFusion::dist	(	const pt	a,
		const pt	b
	)

compute approx. Great Circle distance between two UTM points

Parameters

a	UTM location of first point. Easting and northing in meters.
b	UTM location of second point. Easting and northing in meters.

Returns: approx. distance in meters between the two points

If the points are in the same UTM zone (i.e., similar longitudes) then we approximate the Earth as a cylinder, i.e., we use Euclidean distance with the northing and easting differences. If the UTM zones differ, then we do likewise but we use a more sophisticated approximation to account for the difference in easting. In any case, the points have to be fairly close to each other because this does not compute true geodesics.

int kjb::TopoFusion::download_tile	(	const tile_entry *	entry,
		char *	buffer,
		int	bufsize
	)

download a 200x200 terraserver tile using the internet.

Parameters

[in]	entry	UTM-style location, and database-number, to fetch
[out]	buffer	region of bytes where your tile will be written.
[in]	bufsize	size of buffer – around 500000 should be enough.

Returns: If successful, result is positive, equal to the number of characters written to buffer. If unsuccessful, result is negative, indicating the type of problem (see source for details).

Warning: This function is not thread-safe; it uses lots of static data.

A typical tile is somewhat less than 10 kilobytes, but why be stingy? Scott chose a safety factor of 50 in the trails code. That means buffer is 500000 chars in size, and bufsize contains the value 500000, in the trails code.

Int_matrix kjb::TopoFusion::get_aerial_image	(	const pt &	nw_corner,
		size_t	width,
		size_t	height
	)

return a matrix (like a monochrome image) of aerial imagery

Parameters

nw_corner	Northwest corner location of the image
width	Width of the image, in meters (one meter per pixel)
height	Height of the image, in meters (one meter per pixel)

Returns: an integer matrix with pixel intensities (north at top, east right)

Image kjb::TopoFusion::get_topographic_map_detail	(	const pt &	nw_corner,
		size_t	width,
		size_t	height
	)

return an image of a chunk of topographic map

Parameters

nw_corner	Northwest corner location of the image
width	Width of the image, in pixels (two meters per pixel)
height	Height of the image, in pixels (two meters per pixel)

Returns: a pixel matrix showing a detail of a USGS topographic orthoquad

This works by instantiating a DOrthoQuad object (possibly preceded by a Tile_manager object too, if necessary), setting the theme to TOPO_2M, and extracting a chunk of the selected size.

double kjb::TopoFusion::getNewEasting	(	const pt &	utm,
		int	new_zone
	)

return an easting coordinate (from zone) relative to new_zone

void kjb::TopoFusion::initLayer ( layer * l )

clear all the fields of a layer (pointers assumed to be dangling)

void kjb::TopoFusion::initTrack ( track * t )

clear the fields of a track (like a default constructor)

void kjb::TopoFusion::initWaypoint ( waypoint * w )

clear the point.ele field of a waypoint (and that's all).

void kjb::TopoFusion::LLtoUTM	(	int	ReferenceEllipsoid,
		const double	Lat,
		const double	Long,
		pt &	utm
	)

convert Latitude and Longitude to Universal Transverse Mercator coordinates

Author: Chuck Gantz- chuck.nosp@m..gan.nosp@m.tz@gl.nosp@m.obal.nosp@m.star..nosp@m.com

Parameters

[in]	ReferenceEllipsoid	spheroid used to model the earth's shape
[in]	Lat	Latitude in dec. degrees, north positive and south negative
[in]	Long	Longitude in dec. degrees, east positive and west negative.
[out]	UTMNorthing	UTM northing in meters from the equator.
[out]	UTMEasting	UTM easting in meters from west edge of zone
[out]	UTMZone	UTM zone (band of similar longitudes)

converts lat/long to UTM coords. Equations from USGS Bulletin 1532 East Longitudes are positive, West longitudes are negative. North latitudes are positive, South latitudes are negative Lat and Long are in decimal degrees

pt kjb::TopoFusion::make_pt	(	double	eee,
		double	nnn,
		char	zzz,
		double	elev = `NO_ELEV`
	)

inline

construct a point from its parameters but not as a ctor.

int kjb::TopoFusion::readTrack_GPX	(	const std::string &	filename,
		layer *	l
	)

read a track from a named file into the pointed-to layer

Parameters

[in]	filename	name of the file to read
[out]	l	pointer to layer into which to write the track

Returns: kjb_c::NO_ERROR or ERROR as appropriate

double kjb::TopoFusion::segmentLength ( const seg * s )

computes the length of a segment

void kjb::TopoFusion::utm_to_lat_long	(	int	ReferenceEllipsoid,
		const pt &	utm,
		double &	Lat,
		double &	Long
	)

convert Universal Transverse Mercator coordinates to Latitude and Longitude

Parameters

ReferenceEllipsoid	index of the ellipsoid used to model Earth
i]	utm Universal Transverse Mercator coordinates coordinates of a point
o]	Lat Latitude in decimal degrees (see Latitude and Longitude)
o]	Long Longitude in decimal degrees (see Latitude and Longitude)

Author: Chuck Gantz- chuck.nosp@m..gan.nosp@m.tz@gl.nosp@m.obal.nosp@m.star..nosp@m.com; Scott Morris; Andrew Predoehl

Equations from USGS Bulletin 1532 East Longitudes are positive, West longitudes are negative. North latitudes are positive, South latitudes are negative Lat and Long are in decimal degrees.

void kjb::TopoFusion::utm_to_lat_long	(	int	ReferenceEllipsoid,
		const std::vector< pt > &	utm_in,
		std::vector< double > *	latitude_out,
		std::vector< double > *	longitude_out
	)

this is a fast, vectorized (bulk) version of the single-pt function.

Parameters

ReferenceEllipsoid	index of the ellipsoid used to model Earth
i]	utm array of Universal Transverse Mercator coordinates coordinates of points to convert
o]	Lat array storing converted decimal latitudes (see Latitude and Longitude)
o]	Long array storing converted decimal longitudes (see Latitude and Longitude)

Author: Chuck Gantz; Scott Morris; Andrew Predoehl

Equations from USGS Bulletin 1532. East Longitudes are positive, West longitudes are negative. North latitudes are positive, South latitudes are negative Lat and Long are in decimal degrees. This code was vectorized by hand by Andrew Predoehl based on the single-input version. Empirical tests suggest it produces indistinguishable results, and it is much faster (by a factor of over 100, for big inputs).

void kjb::TopoFusion::UTMtoGPXLL	(	int	ReferenceEllipsoid,
		const pt &	utm,
		double &	Lat,
		double &	Long
	)

converts Universal Transverse Mercator coordinates coords to Latitude and Longitude.

Parameters

ReferenceEllipsoid	index into array ellipsoid[] in constants.h
UTMNorthing	northing coordinate in meters
UTMEasting	easting coordinate in meters
UTMZone	zone number
Lat	latitude in decimal degrees.
Long	longitude in decimal degrees.

Author: Chuck Gantz- chuck.nosp@m..gan.nosp@m.tz@gl.nosp@m.obal.nosp@m.star..nosp@m.com

Equations from USGS Bulletin 1532 East Longitudes are positive, West longitudes are negative. North latitudes are positive, South latitudes are negative. Lat and Long are in decimal degrees.

int kjb::TopoFusion::validate_ellipsoid_table ( )

verify that ellipsoid ids correspond to positions in ellipsoid list

Returns: ERROR or NO_ERROR as appropriate. Does not throw.

You should probably call this early in the run of any important GIS program.

int kjb::TopoFusion::writeTrack_GPX	(	const std::string &	filename,
		const layer &	l
	)

write a track (stored in the indicated layer) into a named file

Parameters

filename	name of the file to write to
l	layer containing the tracks to be written

Returns: kjb_c::NO_ERROR or ERROR as appropriate

Exceptions

kjb::IO_error for certain error conditions.

char kjb::TopoFusion::zone_of	(	int	ReferenceEllipsoid,
		const pt &	p
	)

return the proper zone number for the given point

Parameters

ReferenceEllipsoid	index of r.e. to use for utm-to-lat/long conv.
p	query point, possibly with an "improper" zone number due to overlap

This does NOT just fetch the zone field of the input point! The input point is allowed to have the "wrong" zone, and this will try to return the proper zone.

Zones cover six degrees of longitude, aligned to integer six-degree multiples of meridian number. UTM supports overlapping zones (i.e., you can modestly stray by a handful of kilometers across the 6-degree bands, yet retain pretty good accuracy) but the system works best when your UTM coordinates are in the proper zone. This function will return the proper zone for the given input point. Accuracy has not been quantified, but it would be best if the input point does not ask the zones to overlap more than about 40 km (according to Wikipedia).

Example: if query point p is near the east end of Lake Mead on the Colorado River, barely in zone 11, you can get fairly accurate coordinates for upriver points by adding to the "easting" of p and retaining zone 11. But you'll get better accuracy if you switch to zone 12 (the proper zone for most upriver points in Arizona) and use a new easting value appropriate to zone 12.

See Also: getNewEasting()

Variable Documentation

const char * kjb::TopoFusion::IVILAB_DOQ_TILE_CACHE_DIRECTORY ="/net/v04/data_3/trails/doq_cache"

intentionally-long pathname to where we cache DOQ tiles at the lab.

hardcoded filesystem path to the /data_3 directory storing DEM tiles

const size_t kjb::TopoFusion::LAYER_FN_SIZE = 2048

max length of a layer's filename field

const size_t kjb::TopoFusion::MAX_TRACKSTRING = 255

max len of string field in track, etc

const int kjb::TopoFusion::NO_ELEV = -1

sentinel value for "blank" pt::ele

Enumerations
enum	ELLIPSOID_ID { ELLIPSOID_Airy = 1, ELLIPSOID_Australian_National, ELLIPSOID_Bessel_1841, ELLIPSOID_Bessel_1841_Nambia, ELLIPSOID_Clarke_1866, ELLIPSOID_Clarke_1880, ELLIPSOID_Everest, ELLIPSOID_Fischer_1960_Mercury, ELLIPSOID_Fischer_1968, ELLIPSOID_GRS_1967, ELLIPSOID_GRS_1980, ELLIPSOID_Helmert_1906, ELLIPSOID_Hough, ELLIPSOID_International, ELLIPSOID_Krassovsky, ELLIPSOID_Modified_Airy, ELLIPSOID_Modified_Everest, ELLIPSOID_Modified_Fischer_1960, ELLIPSOID_South_American_1969, ELLIPSOID_WGS_60, ELLIPSOID_WGS_66, ELLIPSOID_WGS_72, ELLIPSOID_WGS_84, ELLIPSOID_END_OF_LIST, ELLIPSOID_START_OF_LIST = ELLIPSOID_Airy }

Classes

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

Function Documentation

Variable Documentation