proj4rb 3.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d2946731ccd3cf4e96e214fce1e8e3c7fc46313f5f1d1fcc119c84e9b88f26f
-  data.tar.gz: 17ca8b08ed1b03be5d910ba77013b7028d88e45160b352764619799f7f156887
+  metadata.gz: dee29581eba9124621bcf04204e9d224e39bba0482caa174fc57014c49a37be7
+  data.tar.gz: 46529fe96f62f6a94cc26baf8f1a695e38ff9099b16c52c58b503380d8773594
 SHA512:
-  metadata.gz: 6a23e8938aa5d6289dabe4b1f0e5ad2aa204281f6ff2f0073fcbc20b6d404bc6b265120cb0c22561ad68338248a16959fd36873777cdbe7ebae4cbf86258ad2f
-  data.tar.gz: 78b42798c55214f7d73df85575b5d6a4a64283ab51583656a9441a725c369fde5a7b12c36944a8dd0a66c67bdf9ef6b48e189e34a3c6d280f11e0adca4116835
+  metadata.gz: 145525e768e261cc293be7ec9851c6e19590f40572de114262da5b4c94eb9baec8296131071eee3438de0df7a18e7ace0981f14c2b6b0079b37739d852879833
+  data.tar.gz: f79972d062f3ce4f3f03e8ba2d67b908a928407b5cec336cfc79c83dca745e310c06d339d78d506bf419eeec3a8bd6c3e543aba950c37f5537edfba625f9da84

data/ChangeLog

@@ -1,71 +1,88 @@
-3.0.0 (September 26, 2021)
+4.1.0 - March 12, 2023
+======================
+* Fix YARD warnings
+* Fix YARD types to match RBS types
+* Don't use type as attribute or method name to avoid conflicts with RBS
+
+4.0.0 - March 12, 2023
+======================
+* Support Proj 9
+* Add support for missing APIs - the gem now provides almost 100% coverage
+* Add support for Proj experimental APIs including the creation of projection conversions
+* Add/updated support for a number of ISO 19111 classes, including PrimeMeridian, Ellipsoid,
+ Datum, DatumEnsemble, CoordinateOperation and Parameters
+* Greatly improved documentation (https://rubydoc.info/github/cfis/proj4rb)
+* Remove old Proj 4.9 support
+* Note this release does have some API changes. These include the removal of Proj 4.9 Point and Coordinate classes, changes to the PrimeMeridian class and changes to the Ellipsoid class. These changes should not impact most users.
+
+3.0.0 - September 26, 2021
 =========================
 * Support Proj 8 which removes the old Proj API (Charlie Savage)
 * Support newer versions of FFI which remove support for returning strings from callbacks (Charlie Savage)
 
-2.2.2 (January 10, 2020)
+2.2.2 - January 10, 2020
 =========================
-* Move proj_context_set_autoclose_database to api 6.2 (Jan Klimke)
+* Move proj_context_set_autoclose_database to api 6.2 - Jan Klimke)
 * Improve search path generation code (Charlie Savage)
 
-2.2.1 (January 8, 2020)
+2.2.1 - January 8, 2020
 =========================
 * Move proj_as_projjson from version 6.0 to 6.2 api (Charlie Savage)
 * Improve search path generation code (Charlie Savage)
 
-2.2.0 (January 7, 2020)
+2.2.0 - January 7, 2020
 =========================
 * Fix broken gem - was not including all api files (Jan Klimke)
 * Add paths on MacOS when using Brew (Jan Klimke)
 * Various code cleanups (Charlie Savage)
 
-2.1.0 (January 5, 2020)
+2.1.0 - January 5, 2020
 =========================
 * Set Ruby 2.4.1 to be the minimum allowed version (Samuel Williams)
 * Fix incorrect use of context, reduce warnings when running tests (Samuel Williams)
 * Fix `bundle exec rake test` (Samuel Williams)
 * Add 2.4.1 to the travis test matrix  (Samuel Williams)
 
-2.0.0 (December 30, 2019)
+2.0.0 - December 30, 2019
 =========================
-- Full rewrite to support API changes in Proj versions 5 and 6 (Charlie Savage)
+- Full rewrite to support API changes in Proj versions 5 and 6 - Charlie Savage)
 - As part of rewrite switch bindings to use FFI versus a C extension (Charlie Savage)
 - Split Ruby code into multiple files based on classes (Charlie Savage)
 - Add in a bunch of new classes including Context, Crs, Coordinate, Ellipsoid, Prime Meridian and Transform (Charlie Savage)
 - Deprecate Projection and Point - these will stop working with Proj 7 since the use an older deprecated API (Charlie Savage)
 
-1.0.0 (December 14, 2014)
+1.0.0 - December 14, 2014
 =========================
 - Calling this 1.0.0 since its a very stable gem  (Charlie Savage)
 
-0.4.3 (August 30, 2011)
+0.4.3 - August 30, 2011
 =========================
 - Remove reference to now private projects.h header
 
-0.4.2 (August 15, 2011)
+0.4.2 - August 15, 2011
 =========================
 - Minor build tweak to support MSVC++
 
-0.4.1 (July 30, 2011)
+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)
+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)
+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)
+0.3.0 - August 14, 2008
 =========================
 - Removed Proj4::UV class which was previously deprecated
 - New build infrastructure for Windows (Charlie Savage)

data/README.rdoc

@@ -3,7 +3,9 @@ This gem provides Ruby bindings for the Proj Library (https://proj.org). The Pro
 between a number of different coordinate systems and projections.
 
 == Documentation
-Besides this readme file, reference documentation is available at https://rubydoc.info/github/cfis/proj4rb.
+Reference documentation is available at https://rubydoc.info/github/cfis/proj4rb.
+
+Examples can be found in this README file as well as in the Examples file. In addition, the test suite has exapmles of calling almost every API so when in doubt take a look at them!
 
 == Installation
 First install the gem in the usual manner:
@@ -23,9 +25,9 @@ If you are using the old Proj4 namespace, then you can do this:
 
   require 'proj4'
 
-=== Crs
-If you are using Proj 6, or newer, 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).
+=== CRS
+To create a coordinate system, you can use CRS codes, well-known text (WKT) strings
+ or old-style Proj strings (which are deprecated).
 
     crs1 = Proj::Crs.new('EPSG:4326')
 
@@ -64,14 +66,14 @@ After you have created two coordinate systems, you can then create a transformat
 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')
+    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')
+    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:
@@ -94,6 +96,25 @@ While the inverse transformation looks like this:
     assert_in_delta(0, to.z, 0.01)
     assert_in_delta(0, to.t, 0.01)
 
+=== Coordinate Operations
+Transformations are a type of Coordinate Operation. PROJ divides coordinate operations into three groups:
+
+* Conversions
+* Projections
+* Transformations
+
+Conversions are coordinate operations that do not exert a change in reference frame. The Ruby bindings support these via the Conversion class. See https://proj.org/operations/conversions/index.html for more information.
+
+Projections are cartographic mappings of the sphere onto the plane. Technically projections are conversions (according to ISO standards), but PROJ distinguishes them from conversions. The Ruby bindings support these
+ via the Projection module which has methods to create many common projections. A list can be found at https://proj.org/operations/projections/index.html.
+
+Transformations are coordinate operations that do cause a change in reference frames. The Ruby bindings support these via the Transformation class.
+
+For more information see https://proj.org/operations/index.html
+
+=== Operation Factory
+The OperationFactoryContext class can be used to build coordinate operations between two CRSes. This is done by first creating a factory and setting appropiate filters. These include spatial filters, accuracy filters, grid availability filters, etc. Once filters are set, then the factory can be queried for a list of possible conversions. For examples, please see the operation_factory_context_test.rb file.
+
 === 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
@@ -104,6 +125,21 @@ you will need to fill out at least the first two values:
 
 Lam is longitude and phi is latitude.
 
+=== Axis Order
+By default tranformations accept coordinates expressed in the units and axis order of the source CRS and return transformed coordinates in the units and axis order of the target CRS.
+
+For most geographic CRSes, the units will be in degrees. For geographic CRSes defined by the EPSG authority, the order of coordinates is latitude and then longitude.
+
+For projected CRSes, the units will vary (metre, us-foot, etc.). For projected CRS defined by the EPSG authority, and with EAST / NORTH directions, the order might may be east and then north or north and then east.
+
+If you prefer to work with a uniform axis order, regardless of the axis orders mandated by the source and target CRSes, then call the Context#normalize_for_visualization method:
+
+    normalized = transform.normalize_for_visualization
+
+The normalized transformation will return output coordinates in longitude, latitude order for geographic CRSes and easting, northing for most projected CRSes.
+
+For more information see https://proj.org/faq.html#why-is-the-axis-ordering-in-proj-not-consistent.
+
 === 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
@@ -112,48 +148,50 @@ 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 need to us Points and Projections.
-Those are deprecated classes but will continue to work with Proj version 7 and older.  Please refer to the documentation
-for more information.
+== Network Access
+Proj supports downloading grid files on demand if network access is enabled (it is disabled by default). To enable network use the method Context#network_enabled=. To specify the url endpoint use Context#url=. Advanced users can replace Proj's networking code, which uses libcurl, with their own implementation. To do this see the NetworkApi class.
+
+Downloaded grids are cached in a sqlite file named cache.db. To specify the location, size and other characteristics of the cache file refer to the GridCache class which is accessible via Context#cache. By default the cache size is 300MB. Caching is on by default but can be disabled via GridCache#enabled=.
 
 == 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)
+== Finding Proj Library (PROJ_LIB_PATH)
+proj4rb will search in a number of well-known locations for the libproj shared library. You
+can override this by specifying the full path to the library using the PROJ_LIB_PATH
+environmental variable.
+
+== Finding Proj Files (PROJ_DATA)
 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 but older functionality keeps working) depending on
-the version of Proj you are using.
-
-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 the underlying API
-they rely on was removed in Proj 8. So please port your code! But take note of the changes in Proj 6 described below.
-
-Proj 5 introduced 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 in Proj 5.
-
-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
+units, etc) in a sqlite file called proj.db. If Proj cannot find its database an exception will be
+raised. In this case, you can set the environmental variable PROJ_DATA to point to 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).
+
+For more information see https://proj.org/resource_files.html
+
+== Class Hierarchy
+The proj4rb class hierarchy is based on Proj's class hiearchy which, in turn, is derived from http://docs.opengeospatial.org/as/18-005r5/18-005r5.html. It is:
+
+   PjObject
+     CoordinateOperationMixin
+       Conversion
+       Transformation
+     CoordinateSystem
+     Crs
+     Datum
+     Ellipsoid
+     PrimeMerdian
+
+The PjObject class defines several methods to create new objects:
+
+* PjObject.create
+* PjObject.create_from_database
+* PjObject.create_from_name
+* PjObject.create_from_wkt
+
+The methods will return instances of the correct subclass.
 
 == Tests
 Proj4rb ships with a full test suite designed to work using Proj 6. If you are using an earlier version of Proj,
@@ -162,7 +200,7 @@ then expect *many* test failures.
 == License
 Proj4rb is released under the MIT license.
 
-==Authors
+== 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. Later, he rewrote the code to support

data/Rakefile

@@ -1,28 +1,28 @@
-#!/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.test_files = FileList['test/*_test.rb']
-  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.test_files = FileList['test/*_test.rb']
+  t.verbose = true
 end

data/lib/api/api.rb

@@ -1,118 +1,117 @@
-require 'rbconfig'
-require 'ffi'
-
-module Proj
-  module Api
-    extend FFI::Library
-
-    def self.library_versions
-      [22, # 8.0 and 8.1
-       19, # 7.x
-       17, # 6.2 *and* 6.1
-       15, # 6.0
-       14, # 5.2
-       13, # 5.0
-       12, # 4.9
-       11] # 4.9
-    end
-
-    def self.search_paths
-      result = case RbConfig::CONFIG['host_os']
-                 when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
-                   self.windows_search_paths
-                 when /darwin|mac os/
-                   self.macos_search_paths
-                 else
-                   self.linux_search_paths
-               end
-
-      result << 'libproj'
-      result
-    end
-
-    def self.windows_search_paths
-      self.library_versions.map do |version|
-        "libproj-#{version}"
-      end
-    end
-
-    def self.linux_search_paths
-      self.library_versions.map do |version|
-        "libproj.so.#{version}"
-      end
-    end
-
-    def self.macos_search_paths
-      # Mac Ports
-      paths1 = self.library_versions.map do |version|
-        case version
-          when 15..17
-            "/opt/local/lib/proj6/lib/libproj.#{version}.dylib"
-          when 13..14
-            "/opt/local/lib/proj5/lib/libproj.#{version}.dylib"
-          when 11..12
-            "/opt/local/lib/proj49/lib/libproj.#{version}.dylib"
-        end
-      end
-
-      # Mac HomeBrew
-      paths2 = self.library_versions.map do |version|
-        "/usr/local/lib/libproj.#{version}.dylib"
-      end
-
-      paths1 + paths2
-    end
-
-    ffi_lib self.search_paths
-
-    library = ffi_libraries.first
-
-    # proj_info was introduced in Proj 5
-    if library.find_function('proj_info')
-      require_relative './api_5_0'
-      PROJ_VERSION = Gem::Version.new(self.proj_info[:version])
-    else
-      # Load the old deprecated api
-      require_relative './api_4_9'
-
-      release = self.pj_get_release
-      version = release.match(/\d\.\d\.\d/)
-      PROJ_VERSION = Gem::Version.new(version)
-    end
-  end
-
-  if Api::PROJ_VERSION < Gem::Version.new('5.0.0')
-    def Api.proj_torad(value)
-      value * 0.017453292519943296
-    end
-
-    def Api.proj_todeg(value)
-      value * 57.295779513082321
-    end
-  end
-
-  # Load the old deprecated API for versions before version 8
-  if Api::PROJ_VERSION < Gem::Version.new('8.0.0')
-    require_relative './api_4_9'
-  end
-
-  if Api::PROJ_VERSION >= Gem::Version.new('5.1.0')
-    require_relative './api_5_1'
-  end
-
-  if Api::PROJ_VERSION >= Gem::Version.new('5.2.0')
-    require_relative './api_5_2'
-  end
-
-  if Api::PROJ_VERSION >= Gem::Version.new('6.0.0')
-    require_relative './api_6_0'
-  end
-
-  if Api::PROJ_VERSION >= Gem::Version.new('6.1.0')
-    require_relative './api_6_1'
-  end
-
-  if Api::PROJ_VERSION >= Gem::Version.new('6.2.0')
-    require_relative './api_6_2'
-  end
-end
+require 'rbconfig'
+require 'ffi'
+
+module Proj
+  module Api
+    extend FFI::Library
+
+    # List of knows PROJ library versions
+    #
+    # @return [Array<String>]
+    def self.library_versions
+      ["25", # 9.2
+       "9_1", # 9.1
+       "22", # 8.0 and 8.1
+       "19", # 7.x
+       "17", # 6.1 *and* 6.2
+       "15", # 6.0
+       "14", # 5.2
+       "13", # 5.0
+       "12", # 4.9
+       "11"] # 4.9
+    end
+
+    # Search paths to use when looking for PROJ library
+    #
+    # @return [Array<String>]
+    def self.search_paths
+      result = case RbConfig::CONFIG['host_os']
+                 when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+                   self.windows_search_paths
+                 when /darwin|mac os/
+                   self.macos_search_paths
+                 else
+                   self.linux_search_paths
+               end
+
+       # Try libproj as catch all
+      result << 'libproj'
+      result
+    end
+
+    # Windows search paths for PROJ library
+    #
+    # @return [Array<String>]
+    def self.windows_search_paths
+      self.library_versions.map do |version|
+        ["libproj-#{version}", "libproj_#{version}"]
+      end.flatten
+    end
+
+    # Linux search paths for PROJ library
+    #
+    # @return [Array<String>]
+    def self.linux_search_paths
+      self.library_versions.map do |version|
+        "libproj.so.#{version}"
+      end
+    end
+
+    # MacOS search paths for PROJ library
+    #
+    # @return [Array<String>]
+    def self.macos_search_paths
+      # On MacOS only support HomeBrew since the MacPort is unsupported and ancient (5.2).
+      self.library_versions.map do |version|
+        "libproj.#{version}.dylib"
+      end
+    end
+
+    # Load PROJ library
+    #
+    # @return [FFI::DynamicLibrary]
+    def self.load_library
+      if ENV["PROJ_LIB_PATH"]
+        ffi_lib ENV["PROJ_LIB_PATH"]
+      else
+        ffi_lib self.search_paths
+      end
+
+      ffi_libraries.first
+    end
+
+    # Load API files based on PROJ version
+    #
+    # @return [nil]
+    def self.load_api
+      # First load the base 5.0 api so we can determine the Proj Version
+      require_relative './api_5_0'
+      Api.const_set('PROJ_VERSION', Gem::Version.new(self.proj_info[:version]))
+
+      # Now load the rest of the apis based on the proj version
+      versions = ['5.1.0', '5.2.0',
+                  '6.0.0', '6.1.0', '6.2.0', '6.3.0',
+                  '7.0.0', '7.1.0', '7.2.0',
+                  '8.0.0', '8.1.0', '8.2.0',
+                  '9.1.0', '9.2.0']
+
+      versions.each do |version|
+        api_version = Gem::Version.new(version)
+
+        if PROJ_VERSION >= api_version
+          require_relative "./api_#{api_version.segments[0]}_#{api_version.segments[1]}"
+        end
+      end
+
+      # Add in the experimental api
+      require_relative "./api_experimental"
+    end
+
+    # Load the library
+    load_library
+
+    # Load the api
+    load_api
+  end
+end
+