pe_projection_new

Creates a map projection

Usage syntax

PE_PROJECTION pe_projection_new (const char *name, PE_PROJFUNC forward, PE_PROJFUNC inverse, PE_HORFUNC horizon);

Parameters

Description

Defines a new map projection with the specified attributes. To define a new map projection, you must write at least two functions. One function will implement the equations that convert from geographic to projected coordinates. The second will implement the equations that convert from projected to geographic coordinates. PE_PROJFUNC has the following format:

   typedef int (*PE_PROJFUNC) (
     double sph[2],
     double parm[PE_PARM_MAX],
     int    n,
     double coord[][2],
     int    iconst[],
     double dconst[]);

Pass null values for iconst and dconst. These arguments are used internally.

Optionally, you can implement a projection horizon. Each map projection has a certain limit. Many projections can map the entire world, but a few, like Transverse Mercator, are good for a limited area only. PE_HORFUNC has this structure.

   typedef PE_HORIZON (*PE_HORFUNC){
     double sph[2],
     double parm[PE_PARM_MAX];
} *PE_HORIZON;

The PE_HORIZON structure is:

   typedef struct pe_horizon_t {
     int nump;
     int kind;
     int inclusive;
     int replicate;
     int size;
     double *coord[2];
} *PE_HORIZON;

The nump argument is the number of parts in the horizon, while kind describes the shape type. The kind values are:

   PE_HORIZON_RECT
PE_HORIZON_POLY
PE_HORIZON_LINE
PE_HORIZON_POINT

Inclusive can have a value of 1 or 0. If 1, the horizon is inclusive. if 0, the horizon is exclusive. Horizons are returned in the units of the geographic coordinate system of the projected coordinate system. You can return one main horizon shape and tell a developer that he needs to shift the horizon by a full circle (if the geogcs units are degrees, the shift is 360 degrees) to catch other data with the replicate argument. The replicate values are:

   enum replicate_enum {
     PE_HORIZON_REPLICATE_NONE,
     PE_HORIZON_REPLICATE_LEFT,
     PE_HORIZON_REPLICATE_RIGHT,
     PE_HORIZON_REPLICATE_BOTH};

Size is the number of coordinates in the part, while coord is a pointer to the array of coordinate values.

Returns

On success, the new map projection with the attributes equal to the corresponding arguments. On failure, a null pointer.

Examples

PE_PROJECTION mercator =
   pe_projection_new("Mercator", mercator_f, mercator_i, merc_horz);