.\" .\" Copyright (c) 2004 Gordon D. Carrie. All rights reserved. .\" .\" Licensed under the Open Software License version 2.1 .\" .\" Please address questions and feedback to user0@tkgeomap.org .\" .\" @(#) $Id: geoProj.3,v 1.7 2007/06/22 22:30:08 tkgeomap Exp $ .so man.macros .TH geoProj 3 2 Geography "Geography C functions" .SH NAME GeoProj, GeoProjAlloc, GeoProjInit, GeoProjFree, GeoProjDestroy, GeoProjGetInfo, GeoProjGetType, GeoProjDescriptor, ProjToLatLon, LatLonToProj, SetCylEqDist, SetCylEqArea, SetMercator, SetLambertConfConic, SetLambertEqArea, SetStereographic, SetOrthographic, GeoProjSetRotation \- apply cartographic projections to geographic and map coordinates. .SH SYNOPSIS .nf \fB#include \fR \fBGeoProj GeoProjAlloc(\fIvoid\fB);\fR \fBvoid GeoProjInit(GeoProj \fIproj\fB);\fR \fBvoid GeoProjFree(GeoProj \fIproj\fB);\fR \fBvoid GeoProjDestroy(GeoProj \fIproj\fB);\fR \fBGeoProjInfo GeoProjGetInfo(GeoProj \fIproj\fB);\fR \fBenum ProjType GeoProjGetType(GeoProj \fIproj\fB);\fR \fBchar * GeoProjDescriptor(GeoProj \fIproj\fB);\fR \fBGeoPt ProjToLatLon(MapPt \fImapPt\fB, GeoProj \fIproj\fB);\fR \fBMapPt LatLonToProj(GeoPt \fIgeoPt\fB, GeoProj \fIproj\fB);\fR \fBvoid SetCylEqDist(GeoProj \fIproj\fB, Angle \fIrefLat\fB, Angle \fIrefLon\fB);\fR \fBvoid SetCylEqArea(GeoProj \fIproj\fB, Angle \fIrefLon\fB);\fR \fBvoid SetMercator(GeoProj \fIproj\fB, Angle \fIrefLon\fB);\fR \fBvoid SetLambertConfConic(GeoProj \fIproj\fB, Angle \fIrefLat\fB, Angle \fIrefLon\fB);\fR \fBvoid SetLambertEqArea(GeoProj \fIproj\fB, GeoPt \fIrefPt\fB);\fR \fBvoid SetStereographic(GeoProj \fIproj\fB, GeoPt \fIrefPt\fB);\fR \fBvoid SetOrthographic(GeoProj \fIproj\fB, GeoPt \fIrefPt\fB);\fR \fBvoid GeoProjSetRotation\fR(\fBGeoProj\fR \fIproj\fR, \fBAngle\fR \fIangle\fR); .fi .SH DESCRIPTION These functions convert geographic points to and from projection coordinates. Projection information is stored in objects of type \fBGeoProj\fR. .TP \fBGeoProjAlloc\fR creates a new projection. It returns the projection or \fBNULL\fR on failure. When no longer needed, the projection should be destroyed with a call to \fBGeoProjDestroy\fR. .TP \fBGeoProjInit\fR initializes internal members of new projection \fIproj\fR. It assumes the previous contents of \fIproj\fR are garbage. Initializing a \fBGeoProj\fR object may involve memory allocations, which should eventually be freed with a call to \fBGeoProjFree\fR. .TP \fBGeoProjFree\fR frees internal memory associated with \fIproj\fR that was allocated during a call to \fBGeoProjInit\fR. \fIproj\fR remains allocated. .TP \fBGeoProjDestroy\fR frees all memory associated with \fIproj\fR, during a call to \fBGeoProjAlloc\fR, and it frees \fIproj\fR. .TP \fBGeoProjGetInfo\fR returns a \fBGeoProjInfo\fR structure for \fIproj\fR. \fBGeoProjInfo\fR structures store publicly visible members of a \fBGeoProj\fR object. The \fBGeoProjInfo\fR structure is declared as follows: .CS typedef struct GeoProjInfo { enum ProjType type; union { Angle rLon; GeoPt refPt; } prm; } GeoProjInfo; .CE where \fItype\fR is the projection type, \fIrLon\fR is a reference longitude in microdegrees, and \fIrefPt\fR is a reference point. The projection type determines which union member applies. .TP The currently defined types are: .CS enum ProjType { CylEqDist, CylEqArea, Mercator, LambertConfConic, Stereographic, Orthographic }; .CE .TP \fBGeoProjGetType\fR returns the type of \fIproj\fR. .TP \fBGeoProjDescriptor\fR returns the descriptor from \fIproj\fR. The returned value should not be modified by the user. .TP \fBProjToLatLon\fR returns the geographic point corresponding to \fImapPt\fR in projection \fIproj\fR. Returns \fBGeoPtNowhere()\fR if \fImapPt\fR cannot be transformed by \fIproj\fR. See the \fBgeography\fR (3) man page for more information on \fBMapPt\fR objects. .TP \fBLatLonToProj\fR returns the map point corresponding to \fIgeoPt\fR in projection \fIproj\fR. Returns \fBMapPtNowhere()\fR if \fIgeoPt\fR cannot be transformed by \fIproj\fR. .TP \fBSetCylEqDist\fR sets \fIproj\fR to Cylindrical Equidistant projection referenced to \fIrefLat\fR and \fIrefLon\fR. \fIproj\fR should have been already allocated. Upon return \fIproj\fR will have a descriptor of form \fB"CylEqDist with reference point {\fIrefLat refLon\fB} global."\fR .TP \fBSetCylEqArea\fR sets \fIproj\fR to Cylindrical Equal Area projection referenced to \fIrefLon\fR. \fIproj\fR should have been already allocated. Upon return \fIproj\fR will have a descriptor of form \fB"CylEqArea with reference longitude \fIrefLon\fB global."\fR .TP \fBSetMercator\fR sets \fIproj\fR to Mercator projection referenced to \fIrefLon\fR. \fIproj\fR should have been already allocated. Upon return \fIproj\fR will have a descriptor of form \fB"Mercator with reference longitude \fIrefLon\fB global."\fR .TP \fBSetLambertConfConic\fR sets \fIproj\fR to Lambert Conformal Conic projection referenced to \fIrefLat\fR and \fIrefLon\fR. \fIproj\fR should have been already allocated. Upon return \fIproj\fR will have a descriptor of form \fB"LambertConfConic reference point {\fIrefLat refLon\fB} global."\fR .TP \fBSetLambertEqArea\fR sets \fIproj\fR to Lambert Azimuthal Equal Area projection referenced to \fIrefPt\fR. \fIproj\fR should have been already allocated. Upon return \fIproj\fR will have a descriptor of form \fB"LambertEqArea with reference point \fIrefPt\fB hemispheric."\fR .TP \fBSetStereographic\fR sets \fIproj\fR to Stereographic projection referenced to \fIrefPt\fR. \fIproj\fR should have been already allocated. Upon return \fIproj\fR will have a descriptor of form \fB"Stereographic with reference point \fIrefPt\fB hemispheric."\fR .TP \fBSetOrthographic\fR sets \fIproj\fR to Orthographic projection referenced to \fIrefPt\fR. \fIproj\fR should have been already allocated. Upon return \fIproj\fR will have a descriptor of form \fB"Orthographic with reference point \fIrefPt\fB hemispheric."\fR .TP \fBGeoProjSetRotation\fR sets the projection rotation to \fIangle\fR. This is the orientation of the map surface onto which the Earth's surface is projected. The \fIangle\fR is clockwise from the unrotated projection. .SH KEYWORDS geography, projections .SH SEE ALSO geography .SH AUTHOR Gordon Carrie (user0@tkgeomap.org)