Proj4rb
This is a Ruby binding for the Proj.4 Carthographic Projection library (proj.maptools.org), that supports conversions between a very large number of geographic coordinate systems and datums.
Most functions of the C library are implemented in the Ruby binding. Where there is a direct equivalent between C and Ruby, identifiers (like names of functions and constants) are the same. But the usage has been changed to take advantage of Rubys object-oriented features.
Operations
The library can be loaded this way:
require 'proj4'
The classes are in the Proj4 module:
include Proj4
First you have to create a projection like this:
proj = Projection.new( :proj => "utm", :zone => "21", :units => "m" )
(There are several alternative ways of specifying the arguments, see the documentation for Proj4::Projection.new for details.)
This defines a UTM21 North projection in WGS84. Note that the proj
/ proj.exe
initialization arguments equivalent to the one above would be:
+proj=utm +zone=21 +units=m
To use the projection, you have 2 operations: forward
and inverse
. forward
transforms the point in WGS84 lon/lat (in radians) to the coordinate system defined during the creation of the Projection object. inverse
does the opposite. For example:
projected_point = proj.forward(lonlat_point)
lonlat_point = proj.inverse(projected_point)
There is also a transform
function which can transform between any two projections including datum conversions:
point_in_projB = projA.transform(projB, point_in_projA)
The forward
, inverse
, and transform
methods all have an in-place equivalent: forward!
, inverse!
, and transform!
which projects the given point in place. There are also forwardDeg
and inverseDeg
methods which work with longitudes and latitudes in degrees rather than radians.
For the points you can use an object of the Proj4::Point class. It has properties: x
, y
, and z
, which can be set and retrieved. Aliases lon
and lat
for x
and y
, respectively, are available. (For backwards compatibility there is also an UV class, but this will go away in future versions.) Instead of the Proj4::Point object you can use any other objects which responds to the methods x
and y
(and z
for 3D datum transformations with the transform
method).
The methods forward_all
, inverse_all
, and transform_all
(and their in-place versions forward_all!
, inverse_all!
, and transform_all!
work just like their simple counterparts, but instead of a single point they convert a collection of points in one go. They take an array as an argument or any object responding to the each
method (for the in-place versions) or each
, clear
, and <<
methods (for the normal version).
You are also given 2 constants to convert between degrees and radians: DEG_TO_RAD
and RAD_TO_DEG
Error handling
The projection initialization (Proj4::Projection.new) and all projection functions (Proj4::Projection#forward/inverse/transform) in their different versions throw an exception when there is a problem. There is a catch-all exception Proj4::Error and many subclasses of it for all the different errors that the Proj.4 C library can return. See Proj4::Error for more information or use the list-errors.rb
program from the examples for a list.
Definition lists
Proj.4 knows about many different datums, ellipsoids, prime meridians, projection types and length units. The Proj4::Datum, Proj4::Ellipsoid, Proj4::PrimeMeridian, Proj4::ProjectionType, and Proj4::Unit classes can be used to access those lists and get details about each definition. See the list-* files in the example directory for some code examples.
Note that these lists are only available since the version 449 of the Proj.4 C library.
Installation
Just install the gem with
gem install proj4rb
Compiling
Linux
To compile the proj4rb Ruby bindings from source you’ll need the Proj.4 C library installed. Enter the src directory and create a Makefile:
cd src
ruby extconf.rb
If there are any problems consult the mkmf.log log file. Then compile with
make
The result is the file projrb.so which you need to copy into the lib directory:
cp projrb.so ../lib/
If you want to, you can now create a gem with
rake gem
This will create a file proj4rb-version-i486-linux.gem
or similar in the pkg directory.
Mac OS X
To compile the proj4rb Ruby bindings from source you’ll need the Proj.4 C library installed. Enter the src directory and create a Makefile:
cd src
ruby extconf.rb
If there are any problems consult the mkmf.log log file. Then compile with
make
The result is the file projrb.bundle which you need to copy into the lib directory:
cp projrb.bundle ../lib/
If you want to, you can now create a gem with
rake gem
This will create a file proj4rb-version-universal-darwin8.0.gem
or similar in the pkg directory.
Windows
The result is the file proj.dll which you need to copy into the lib directory:
cp proj.dll ../lib/
TODO
-
Completely cross-platform build system (mkrf?)
Changes since the last version
-
Added most functions supported by C library and many tests.
-
Added support for Linux builds.
-
Improved error handling. On error the methods throw exceptions now.
License
Proj4rb is released under the MIT license.
Support
Any questions, enhancement proposals, bug notifications or corrections can be sent to [email protected] or [email protected].
Authors
The proj4rb Ruby bindings were created by Guilhelm Vellut with many additions by Jochen Topf.