/*
 * geoProj --
 *
 *	This header file defines constants and declares structures and
 *	functions that manage and apply cartographic projections.  See
 *	the GeoProj(3) man page for details.
 * 
 * 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.h,v 1.6 2007/06/22 22:40:49 tkgeomap Exp $
 *
 ********************************************
 *
 */

#ifndef _GEOPROJ_H_
#define _GEOPROJ_H_

/*
 * For C++ compilers, use extern "C"
 */

#ifdef __cplusplus
extern "C" {
#endif

#include "geography.h"

/*
 * The following constant identifies the currently recognized projection types.
 */

enum ProjType {
    CylEqDist, CylEqArea, Mercator, LambertConfConic,
    LambertEqArea, Orthographic, Stereographic
};

/*
 * Exported projection information.
 */

typedef struct GeoProjInfo {
    enum ProjType type;
    union {
	Angle refLon;	/* Reference longitude */
	GeoPt refPt;	/* Reference point */
    } prm;
    Angle rotation;
} GeoProjInfo;

/*
 * Length of a projection descriptor
 */

#define GEOPROJDESCRLEN 200

/*
 * Forward declaration of the GeoProj structure, needed for the function
 * declarations below.
 */

typedef struct GeoProj *GeoProj;

/*
 * Declarations of procedure types stored in a GeoProj structure.
 */

typedef GeoProjInfo	(GeoProjInfoProc) _ANSI_ARGS_((GeoProj proj));
typedef MapPt		(GeoProjLatLonToProjProc) _ANSI_ARGS_((GeoPt gpt,
				GeoProj proj));
typedef GeoPt		(GeoProjProjToLatLonProc) _ANSI_ARGS_((MapPt mpt,
				GeoProj proj));

/*
 * GeoProjParams pointers should point to structures that contain projection
 * specific information, such as reference points and computational constants.
 */

typedef void * GeoProjParams;

/*
 * This is the fundamental structure for this interface.  It stores parameters
 * and functions for making conversions between geographic and map coordinates.
 * It is normally accessed through the GeoProj type.
 * Clients should not refer to fields in this structure directly.  The
 * declaration is exported to help with debugging and to enable inheritance.
 */

struct GeoProj {
    enum ProjType type;				/* GeoProj type */
    char descriptor[GEOPROJDESCRLEN];		/* Text description */
    GeoProjInfoProc *infoProc;			/* Procedure to return
						 * information about the
						 * projection */
    GeoProjLatLonToProjProc *latLonToProjProc;	/* Procedure to convert a GeoPt
						 * to the corresponding MapPt */
    GeoProjProjToLatLonProc *projToLatLonProc;	/* Procedure to convert a MapPt
						 * to the corresponding GeoPt */
    GeoProjParams params;			/* Projection specific
						 * parameters */
    Angle rotation;				/* Rotation angle
						 * (clockwise degrees).
						 * This specifies the angle
						 * between geographic north
						 * and north on the map.
						 * It can also be regarded
						 * as the orientation of
						 * the surface onto which the
						 * Earth's surface is projected */
    double cosr, sinr;				/* Cosine and sine of rotation */
};

/*
 * The following structures are normally used in the params member of GeoProj
 * structures.
 */

typedef struct {
    GeoPt refPt;	/* Reference point */
    double cosRLat;	/* Cosine of reference latitude */
    double sinRLat;	/* Sine of reference latitude */
} GeoProjRefPtParams;

typedef struct {
    Angle refLat;	/* Reference latitude */
    double cosRLat;	/* Cosine of reference latitude */
    Angle refLon;	/* Reference longitude */
} GeoProjCylEqDistParams;

typedef struct {
    Angle refLat;	/* Reference latitude */
    Angle refLon;	/* Longitude of vertical meridian */
    double n;		/* See Snyder, p. 105 */
    double RF;		/* See Snyder, p. 105 */
    double rho0;	/* See Snyder, p. 105 */
} GeoProjLambertConfConicParams;

/*
 * Global function declarations.
 */

EXTERN GeoProj 		GeoProjAlloc _ANSI_ARGS_((void));
EXTERN void		GeoProjInit _ANSI_ARGS_((GeoProj proj));
EXTERN void		GeoProjFree _ANSI_ARGS_((GeoProj proj));
EXTERN void		GeoProjDestroy _ANSI_ARGS_((GeoProj proj));
EXTERN GeoProjInfo	GeoProjGetInfo _ANSI_ARGS_((GeoProj proj));
EXTERN enum		ProjType GeoProjGetType _ANSI_ARGS_((GeoProj proj));
EXTERN char *		GeoProjDescriptor _ANSI_ARGS_((GeoProj proj));
EXTERN GeoPt		ProjToLatLon _ANSI_ARGS_((MapPt projPt, GeoProj proj));
EXTERN MapPt		LatLonToProj _ANSI_ARGS_((GeoPt geoPt, GeoProj proj));
EXTERN void		SetCylEqDist _ANSI_ARGS_((GeoProj proj, Angle refLat,
			    Angle refLon));
EXTERN void		SetCylEqArea _ANSI_ARGS_((GeoProj proj, Angle refLon));
EXTERN void		SetMercator _ANSI_ARGS_((GeoProj proj, Angle refLon));
EXTERN void		SetLambertConfConic _ANSI_ARGS_((GeoProj proj,
				Angle refLat, Angle refLon));
EXTERN void		SetLambertEqArea _ANSI_ARGS_((GeoProj proj,
				GeoPt refPt));
EXTERN void		SetStereographic _ANSI_ARGS_((GeoProj proj,
				GeoPt refPt));
EXTERN void		SetOrthographic _ANSI_ARGS_((GeoProj proj,
				GeoPt refPt));
EXTERN void		GeoProjSetRotation _ANSI_ARGS_((GeoProj proj, Angle angle));

/*
 * end block for C++
 */
    
#ifdef __cplusplus
}
#endif

#endif