This project exists to provide a Ruby 1.9 compatible version of Proj4rb. Only minor changes have been made in the source code to make this happen. The bulk of the changes have been the inclusion of Jeweler for easily packaging. It’s not really nice to bump the version number, so I’ve left it at 0.3.1.
This is a Ruby binding for the Proj.4 Carthographic Projection library (trac.osgeo.org/proj/), that supports conversions between a large number of geographic coordinate systems and datums.
Most functions of the C library are exposed to Ruby. In cases where there is a direct equivalent between C and Ruby, identifiers (such as names of functions and constants) are the same. But the usage has been changed to take advantage of Ruby’s object-oriented features.
To load the library:
require 'proj4'
The classes are in the Proj4 module so you may wish to include it:
include Proj4
Next, you need to create a projection:
proj = Projection.new( :proj => "utm", :zone => "21", :units => "m" )
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
Note there are several alternative ways of specifying the arguments, see the documentation for Proj4::Projection.new for details.
Once you’ve created the projection, you can tranform coordinates using either the forward or inverse methods. 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 also available. (There used to be a UV class, but this has been removed in version 0.3.0.)
Instead of using the Proj4::Point object, you may use another class as long as it 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 transforming a single point they transform a collection of points in a single call. They take an array as an argument or any object that responds to the each method (for the in-place versions) or each, clear, and << methods (for the normal version).
The library also defines two constants to make it easy to convert between degrees and radians: DEG_TO_RAD and RAD_TO_DEG
Projection initialization (Proj4::Projection.new) and transformation functions (Proj4::Projection#forward/inverse/transform) all throw exceptions when they encounter an error. This is done by mapping proj4’s C error codes to Ruby specific exception classes. See Proj4::Error for more information or use the list-errors.rb program from the examples for a list.
Proj.4 supports many different datums, ellipsoids, prime meridians, projection types and length units. Use the Proj4::Datum, Proj4::Ellipsoid, Proj4::PrimeMeridian, Proj4::ProjectionType, and Proj4::Unit classes to access this information and get detailed information about each definition. See the list-* files in the example directory for code examples.
Note that these lists rquire version 449 or later of the Proj.4 C library.
To install the gem simply type:
gem install proj4rb
To compile the proj4rb Ruby bindings from source you’ll need the Proj.4 C library installed. Then simply call:
rake build
If there is a problem, you can perform this step manually: Enter the ext directory and create a Makefile:
cd ext ruby extconf.rb
If there are any problems consult the mkmf.log log file. Then compile with
make
The result is the file proj4_ruby.so.
If you want to run the tests call
rake test
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.
To compile the proj4rb Ruby bindings from source you’ll need the Proj.4 C library installed. Enter the ext directory and create a Makefile:
cd ext 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.
To build the library on Windows requires a working installation of Visual Studio or MingW/msys. You of course also need to have proj4 installed.
If you are using Visual Studio, you’ll find a Visual Studio 2008 project file in ext/vc. You’ll have to edit the various include and library paths to fit your specific environment.
If you are using MingW/msys, then:
-
Open a msys prompt (a DOS prompt may also work)
-
Change diretories to ext/MingW
-
Type in rake
The result is a proj4_ruby.so file which can be package into a GEM or copied to the ruby/site-lib directory.
Proj4rb is released under the MIT license.
Any questions, enhancement proposals, bug notifications or corrections can be sent to jochen@topf.org.
The proj4rb Ruby bindings were started by Guilhem Vellut with most of the code written by Jochen Topf. Charlie Savage ported the code to Windows and added the Windows build infrastructure.