proj4rb 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 99cd1a356cd839962a71f2c48333e7441cbec03d
-  data.tar.gz: 65f2ba67386c2daea17fe2e22d5f8b50de1bb697
+SHA256:
+  metadata.gz: bdd77e892a3126bb4c0b4c984356e9ba6a32e73811813c2d5dcc5a2eb36a02ae
+  data.tar.gz: 0217052b386be354cd4b48c5bc0536c179336c5c73026a3cb544e9630ad66810
 SHA512:
-  metadata.gz: 334bc98a7beb383a5fe66435a258c72985859f8bbd0ac4cff59e106b6bcfc383b447d50c346f1a000adccee1460747b5513904a9e785c3f08dee23fe3d0b21cb
-  data.tar.gz: f4e8df9f338f337bfb784bfb7388e22213ed29fe4d01e5d73478146032b1a36c5e5f8158bd1889f653b4964b351e1afef9f9267f663099f6385127db4949d0cd
+  metadata.gz: 9d0e577ede5260d24da9b474e10c52700f9179fe9a42e61728fba85f051be1b152af847c6c45c8df9ef9ad9f5b5ea71ca82ecbef977056b2361dfb2de3be7dac
+  data.tar.gz: 050366cf1ce478ee809a4d82af9a9ed0a9e54e3fd28d4fd58d4fac4b22c0ddbb431969a61581c8a5e3990525e567f2fb7f03b1f9a010b734867c67c9795f7369

data/ChangeLog

@@ -0,0 +1,46 @@
+2.0.0 (December 30, 2019)
+=========================
+- Full rewrite to support API changes in Proj versions 5 and 6
+- As part of rewrite switch bindings to use FFI versus a C extension
+- Split Ruby code into multiple files based on classes
+- Add in a bunch of new classes including Context, Crs, Coordinate, Ellipsoid, Prime Meridian and Transform
+- Deprecate Projection and Point - these will stop working with Proj 7 since the use an older deprecated API
+
+- Calling this 1.0.0 since its a very stable gem
+
+1.0.0 (December 14, 2014)
+=========================
+- Calling this 1.0.0 since its a very stable gem
+
+0.4.3 (August 30, 2011)
+=========================
+- Remove reference to now private projects.h header
+
+0.4.2 (August 15, 2011)
+=========================
+- Minor build tweak to support MSVC++
+
+0.4.1 (July 30, 2011)
+=========================
+- Search first for binaries when using windows gems
+- Add # encoding to test files
+- Reformat tests files to use standard ruby 2 space indenting
+
+0.4.0 (July 30, 2011)
+=========================
+- Update to compile on Ruby 1.9.* (Fabio Renzo Panettieri)
+- Add in gemspec file (Charlie Savage)
+- Add rake-compiler as development dependency, remove older MinGW build system (Charlie Savage)
+- Move to GitHub (Charlie Savage)
+
+0.3.1 (December 23, 2009)
+=========================
+- Update extconf.conf file to be more flexible to make it easier to build
+    on OS X when using MacPorts
+- Updated windows binary to link against proj4.7
+
+0.3.0 (August 14, 2008)
+=========================
+- Removed Proj4::UV class which was previously deprecated
+- New build infrastructure for Windows (Charlie Savage)
+- Fixed memory leaks in forward() and inverse() methods (Charlie Savage)

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in tensorflow-ruby.gemspec
+gemspec

data/README.rdoc

@@ -1,160 +1,170 @@
 =Proj4rb
+This gem provides Ruby bindings for the Proj Library (https://proj.org). The Proj Library supports converting coordinates
+between a number of different coordinate systems and projections.
 
-This is a Ruby binding for the Proj.4 Carthographic Projection library
-(http://trac.osgeo.org/proj/), that supports conversions between a large
-number of geographic coordinate systems and datums.
+== Installation
+First install the gem in the usual manner:
 
-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.
+    gem install proj4rb
+
+Next install the Proj Library. This of course varies per system, but you want to install the latest version Proj
+possible. Once installed, you'll need to make sure that libproj is installed on your operating system's
+load path.
+
+== Usage
+To get started first require the gem:
+
+  require 'proj'
+
+If you are using the old Proj4 namespace, then you can do this:
 
-== Operations
-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 <tt>proj</tt> /
-<tt>proj.exe</tt> 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: <tt>forward!</tt>, <tt>inverse!</tt>, and <tt>transform!</tt>
-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 <tt>forward_all!</tt>, <tt>inverse_all!</tt>, and
-<tt>transform_all!</tt> 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
-<tt><<</tt> 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+
- 
-==Error handling
-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 <tt>list-errors.rb</tt> program from the examples for a list.
-
-==Definition lists
-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 <i>list-*</i> files in the <i>example</i> directory for code
-examples.
-
-Note that these lists rquire version 449 or later of the Proj.4 C library.
-
-==Installation
-To install the gem simply type:
-    gem install proj4rb
+=== Crs
+If you are using Proj 6 create a coordinate system. To create a coordinate system, you can use CRS codes, well-known text (WKT) strings
+or old-style Proj4 strings (which are deprecated).
 
-==Compiling
-===Linux
-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 <i>ext</i> directory and create
-a Makefile:
-    cd ext
-    ruby extconf.rb
-If there are any problems consult the <i>mkmf.log</i> log file.
-Then compile with
-    make
-The result is the file <i>proj4_ruby.so</i>.
-
-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 <tt>proj4rb-<i>version</i>-i486-linux.gem</tt>
-or similar in the <i>pkg</i> directory.
-
-===Mac OS X
-To compile the proj4rb Ruby bindings from source you'll need the
-Proj.4 C library installed. Enter the <i>ext</i> directory and create
-a Makefile:
-    cd ext
-    ruby extconf.rb
-If there are any problems consult the <i>mkmf.log</i> log file.
-Then compile with
-    make
-The result is the file <i>projrb.bundle</i> which you need to copy into
-the <i>lib</i> directory:
-    cp projrb.bundle ../lib/
-
-If you want to, you can now create a gem with
-    rake gem
-
-This will create a file <tt>proj4rb-<i>version</i>-universal-darwin8.0.gem</tt>
-or similar in the <i>pkg</i> directory.
-
-===Windows
-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:
-
-1.  Open a msys prompt (a DOS prompt may also work)
-2.  Change diretories to ext/MingW
-3.  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.
-
-==License
-Proj4rb is released under the MIT license.
+    crs1 = Proj::Crs.new('EPSG:4326')
+
+    crs2 = Proj::Crs.new('urn:ogc:def:crs:EPSG::4326')
+
+    crs3 = Proj::Crs.new('+proj=longlat +datum=WGS84 +no_defs +type=crs')
+
+    crs4 = Proj::Crs.new(<<~EOS)
+      GEOGCRS["WGS 84",
+      DATUM["World Geodetic System 1984",
+            ELLIPSOID["WGS 84",6378137,298.257223563,
+                      LENGTHUNIT["metre",1]]],
+      PRIMEM["Greenwich",0,
+             ANGLEUNIT["degree",0.0174532925199433]],
+      CS[ellipsoidal,2],
+      AXIS["geodetic latitude (Lat)",north,
+           ORDER[1],
+           ANGLEUNIT["degree",0.0174532925199433]],
+      AXIS["geodetic longitude (Lon)",east,
+           ORDER[2],
+           ANGLEUNIT["degree",0.0174532925199433]],
+      USAGE[
+          SCOPE["unknown"],
+              AREA["World"],
+          BBOX[-90,-180,90,180]],
+      ID["EPSG",4326]]
+    EOS
+
+Notice when using the old-style Proj4 string, the addition of the "+type=crs" value.
+
+If you are using Proj 5, then you should create a transformation using epsg strings (see below). If you are using Proj 4,
+you need to use the deprecated Projection class (see documentation).
+
+=== Transformation
+After you have created two coordinate systems, you can then create a transformation. For example, if you want to
+convert coordinates from the "3-degree Gauss-Kruger zone 3" coordinate system to WGS84 (one version of lat-long)
+first create a transformation:
+
+    crs_gk  = Proj::Crs.new('epsg:31467')
+    crs_wgs84 = Proj::Crs.new('epsg:4326')
+    transform = Proj::Transformation.new(crs_gk, crs_wgs84)
+
+Alternatively, or if you are using Proj 5, you can create a transformation without first
+creating Crs instances. Instead, pass the EPSG information directly to the transformation:
+
+    transform = Proj::Transformation.new('epsg:31467', 'epsg:4326')
+
+Once you've created the transformation, you can tranform coordinates using either
+the +forward+ or +inverse+ methods. The forward transformation looks like this:
+
+    from = Proj::Coordinate.new(x: 5428192.0, y: 3458305.0, z: -5.1790915237)
+    to = transform.forward(from)
+
+    assert_in_delta(48.98963932450735, to.x, PRECISION)
+    assert_in_delta(8.429263044355544, to.y, PRECISION)
+    assert_in_delta(-5.1790915237, to.z, PRECISION)
+    assert_in_delta(0, to.t, PRECISION)
+
+While the inverse transformation looks like this:
 
+    from = Proj::Coordinate.new(lam: 48.9906726079, phi: 8.4302123334)
+    to = transform.inverse(from)
+
+    assert_in_delta(5428306.389495558, to.x, PRECISION)
+    assert_in_delta(3458375.3367194114, to.y, PRECISION)
+    assert_in_delta(0, to.z, PRECISION)
+    assert_in_delta(0, to.t, PRECISION)
+
+Transformation objects can also be created directly like this:
+
+    transform = Proj::Transformation.new('epsg:31467', 'epsg:4326')
+
+=== Coordinate
+Notice the examples above transform Coordinate objects. A Coordinate consists
+of up to four double values to represent three directions plus time. In general
+you will need to fill out at least the first two values:
+
+    from = Proj::Coordinate.new(x: 5428192.0, y: 3458305.0, z: -5.1790915237)
+    from = Proj::Coordinate.new(lam: 48.9906726079, phi: 8.4302123334)
+
+Lam is longitude and phi is latitude.
+
+=== Context
+Contexts are used to support multi-threaded programs. The bindings expose this object via Context.current
+and store it using thread local storage. Use the context object to access error codes, set proj4
+compatability settings, set the logging level and to install custom logging code.
+
+Both Crs and Transformation objects take a context object in their constructors. If none is passed, they default
+to using Context.current
+
+=== Projection
+If you are using Proj 4, then instead of using Coordinates, Crses and Tranformations you use Points and Projections. Those
+are deprecated classes but will continue to work until the release of Proj 7.  Please refer to the documentation
+for more information.
+
+== Error handling
+When an error occurs, a Proj::Error instance will be thrown with the underlying message provided
+from the Proj library.
+
+== Finding Proj Files (LIB_PROJ)
+Starting with version 6, Proj stores its information (datums, ellipsoids, prime meridians, coordinate systems,
+units, etc) in a sqlite file called proj.db. If Proj cannot find its database, then the Ruby bindings will
+search for it in some well-known locations. Failing that, the Ruby bindings will raise an exception.
+In this case, set the environmental variable PROJ_LIB to point at the folder that contains the proj.db file.
+Note PROJ_LIB must be set by whatever launches your Ruby program. The Ruby program itself cannot set this
+variable and have it work correctly (at least not on windows).
+
+== Backwards Compatibility
+Proj versions 5 and 6 are *very* different than Proj version 4. Changes are documented at
+https://proj.org/development/migration.html. Note that the gem should gracefully degrade
+(as in newer functionality stops working) depending on if you are using Proj 6, Proj 5 or Proj 4.
+
+To ensure backwards compatiblity, the Ruby bindings still include the older Point and Projection
+classes. However, these classes are no longer documented in this Readme because they will be
+removed upon the release of Proj 7 which will remove the underlying API's they are dependent upon.
+So please port your code! But take note of the changes in Proj 6 described below.
+
+Proj 5 introduced the the Coordinate, Crs and Tranformation apis. However, it wasn't until Proj 6 that additional
+metadata APIs were added, so the amount of information about each object is somewhat limited.
+
+Proj 6 makes a big change compared to previous releases that is not well documented (see
+https://github.com/OSGeo/PROJ/pull/1182). When creating tranformations with EPSG values Proj 6
+will assume EPSG axis order and units (typically lat-long degree for geodetic CRS). First,
+this means that lat-long should usually be specified in degrees and not radians (breaking change one).
+Second, the axis order is likely different than what your previous code assumed (breaking change two).
+Note if creating transformations with the deprecated "+init=epsg:XXXX" values, Proj 6 will assume the traditional
+axis order and units (long-lat radians for geodetic CRS).
+
+Bottom line - when porting your code to the new Proj 6 APIs generally:
+
+* Use degrees, not radians
+* Swap the order of the lat and long values
+
+== Tests
+Proj4rb ships with a full test suite designed to work using Proj 6. If you are using an earlier version of Proj,
+then expect *many* test failures.
+
+== License
+Proj4rb is released under the MIT license.
 
 ==Authors
 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.
-
+the Windows build infrastructure. Later, he updated the code to support
+Proj version 5 and 6 and ported the code to use FFI.

data/Rakefile

@@ -1,42 +1,27 @@
-#!/usr/bin/env ruby
-
-require "rubygems"
-require "rake/extensiontask"
-require "rake/testtask"
-require "rubygems/package_task"
-require "rdoc/task"
-require "yaml"
-
-# Read the spec file
-GEM_NAME = "proj4rb"
-SO_NAME = "proj4_ruby"
-spec = Gem::Specification.load("#{GEM_NAME}.gemspec")
-
-# Setup generic gem
-Gem::PackageTask.new(spec) do |pkg|
-  pkg.package_dir = 'pkg'
-  pkg.need_tar    = false
-end
-
-# RDoc Task
-desc "Generate rdoc documentation"
-RDoc::Task.new("rdoc") do |rdoc|
-  rdoc.rdoc_dir = 'doc'
-  rdoc.title    = "Proj4rb"
-  # Show source inline with line numbers
-  rdoc.options << "--line-numbers"
-  # Make the readme file the start page for the generated html
-  rdoc.main = 'README.rdoc'
-  rdoc.rdoc_files.include('doc/*.rdoc',
-                          'ext/projrb.c',
-                          'README',
-                          'proj4rb.gemspec',
-                          'Changelog',
-                          'MIT-LICENSE')
-end
-
-# Test Task
-Rake::TestTask.new do |t|
-  t.libs << "test"
-  t.verbose = true
+#!/usr/bin/env ruby
+
+require "rubygems"
+require "rake/testtask"
+require "rubygems/package_task"
+require "yard"
+require "yaml"
+
+# Read the spec file
+GEM_NAME = "proj4rb"
+spec = Gem::Specification.load("#{GEM_NAME}.gemspec")
+
+# Setup generic gem
+Gem::PackageTask.new(spec) do |pkg|
+  pkg.package_dir = 'pkg'
+  pkg.need_tar    = false
+end
+
+# Yard Task
+desc "Generate documentation"
+YARD::Rake::YardocTask.new
+
+# Test Task
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.verbose = true
 end