<?php
/* vim: set expandtab wrap tabstop=4 shiftwidth=4 softtabstop=4:
+----------------------------------------------------------------------+
| PHP version 4                                                        |
+----------------------------------------------------------------------+
| Copyright (c) 2003-2004 Michal Migurski                              |
+----------------------------------------------------------------------+
| This source file is subject to version 3.0 of the PHP license,       |
| that is bundled with this package in the file LICENSE, and is        |
| available through the world-wide-web at the following url:           |
| http://www.php.net/license/3_0.txt.                                  |
| If you did not receive a copy of the PHP license and are unable to   |
| obtain it through the world-wide-web, please send a note to          |
| license@php.net so we can mail you a copy immediately.               |
+----------------------------------------------------------------------+
| Author: Michal Migurski <mike@teczno.com>                            |
+----------------------------------------------------------------------+

$Id: README-Map_Projection.php,v 1.1 2004/10/11 16:33:35 migurski Exp $

Map Projection is a collection of classes used to project GPS data points onto maps. When plotting large areas of a sphere's surface on a two dimensional map, a linear projection from latitude/longitude to x/y is often undesirable, due to to distortions that appear around the edges. Many projections exist that deal with these distortions: Mercator's projection was designed to aid navigation, while equal-area projections are intended to preserve a constant scaling factor from the sphere to the map. A list of projections and their properties can be found at http://mathworld.wolfram.com/topics/MapProjections.html.

This package can be used to convert GIS data to a few popular projections used in atlases and by map image providers, such as http://nationalatlas.gov or http://www.mapresources.com. If the specific parameters used to create a map are known, it is possible to use this package to plot geographical points to that map, or determine geographical position from map position.

Each class in this package implements a specific projection.

Linear_Projection is the base class, and is intended as an abstract class - no conversion is performed, and longitude/latitude are mapped directly to x/y.

The other classes (Albers_Conical_EqualArea_Projection, Lambert_Conformal_Conic_Projection, Lambert_Azimuthal_EqualArea_Projection, Mercator_Projection) extend Linear_Projection, and implement specific projections noted in the included comments.

Example of use:
*/

    // create a new instance of a Mercator projection
    
require_once('Mercator.php');
    
$mercator = new Mercator_Projection();
    
    
// create an array of city GPS locations
    // note that latitude/longitude should be in radians, not degrees
    
$cities = array(
        
'San Francisco' =>  array('lat' => deg2rad(37.78),
                                  
'lon' => deg2rad(-122.41)),
        
'Chicago' =>        array('lat' => deg2rad(41.81),
                                  
'lon' => deg2rad(-87.69)),
        
'New York City' =>  array('lat' => deg2rad(40.78),
                                  
'lon' => deg2rad(-73.98)),
        
'Miami' =>          array('lat' => deg2rad(25.56),
                                  
'lon' => deg2rad(-80.46)));
        
    
// project each point
    // after this step, each element in $cities will have x, y indeces defined
    
$mercator->project($cities);
    
print_r($cities);

/*
With x/y defined, it is possible to use PHP's image functions to draw the points on an existing map, or generate XML to be consumed by a flash front-end. It may be necessary to further transform the resulting points by rotating or scaling them, to fit a particular map.

Alternatively, the projection classes can be used to accept input from a map, for example from an image input element on an HTML page:
*/

    // create a new instance of a Mercator projection
    
require_once('Mercator.php');
    
$mercator = new Mercator_Projection();
    
    
// click x/y location
    
$click = array('x' => -2.1365'y' => 0.3097);
        
    
// unproject the point
    // after this step, $click will have lat, lon defined
    
$mercator->unproject($click);
    
print_r($click);

/*
With latitude/longitude defined, the click location can be compared to GPS coordinates.
*/
?>