Module: RGeo::Geos

Defined in:
lib/rgeo/geos.rb,
lib/rgeo/geos.rb,
lib/rgeo/geos/utils.rb,
lib/rgeo/geos/interface.rb,
lib/rgeo/geos/zm_factory.rb,
lib/rgeo/geos/ffi_factory.rb,
lib/rgeo/geos/capi_factory.rb,
lib/rgeo/geos/zm_feature_classes.rb,
lib/rgeo/geos/zm_feature_methods.rb,
lib/rgeo/geos/ffi_feature_classes.rb,
lib/rgeo/geos/ffi_feature_methods.rb,
lib/rgeo/geos/capi_feature_classes.rb

Overview

The Geos module provides general tools for creating and manipulating a GEOS-backed implementation of the SFS. This is a full implementation of the SFS using a Cartesian coordinate system. It uses the GEOS C++ library to perform most operations, and hence is available only if GEOS version 3.2 or later is installed and accessible when the rgeo gem is installed. RGeo feature calls are translated into appropriate GEOS calls and directed to the library’s C api. RGeo also corrects a few cases of missing or non-standard behavior in GEOS.

This module also provides a namespace for the implementation classes themselves; however, those classes are meant to be opaque and are therefore not documented.

To use the Geos implementation, first obtain a factory using the ::RGeo::Geos.factory method. You may then call any of the standard factory methods on the resulting object.

Defined Under Namespace

Modules: CAPIGeometryCollectionMethods, CAPIGeometryMethods, FFIGeometryCollectionMethods, FFIGeometryMethods, FFILineMethods, FFILineStringMethods, FFILinearRingMethods, FFIMultiLineStringMethods, FFIMultiPointMethods, FFIMultiPolygonMethods, FFIPointMethods, FFIPolygonMethods, Utils, ZMGeometryCollectionMethods, ZMGeometryMethods, ZMLineStringMethods, ZMMultiLineStringMethods, ZMMultiPolygonMethods, ZMPointMethods, ZMPolygonMethods Classes: CAPIFactory, CAPIGeometryCollectionImpl, CAPIGeometryImpl, CAPILineImpl, CAPILineStringImpl, CAPILinearRingImpl, CAPIMultiLineStringImpl, CAPIMultiPointImpl, CAPIMultiPolygonImpl, CAPIPointImpl, CAPIPolygonImpl, FFIFactory, FFIGeometryCollectionImpl, FFIGeometryImpl, FFILineImpl, FFILineStringImpl, FFILinearRingImpl, FFIMultiLineStringImpl, FFIMultiPointImpl, FFIMultiPolygonImpl, FFIPointImpl, FFIPolygonImpl, ZMFactory, ZMGeometryCollectionImpl, ZMGeometryImpl, ZMLineImpl, ZMLineStringImpl, ZMLinearRingImpl, ZMMultiLineStringImpl, ZMMultiPointImpl, ZMMultiPolygonImpl, ZMPointImpl, ZMPolygonImpl

Constant Summary collapse

CAPI_SUPPORTED = 
::RGeo::Geos.const_defined?(:CAPIGeometryMethods)
CAP_ROUND =

There is some trouble with END_CAP in GEOS In docs CAP_ROUND = 1, but it’s work properly with 0

0
CAP_FLAT = 
1
CAP_SQUARE = 
2
JOIN_ROUND = 
0
JOIN_MITRE = 
1
JOIN_BEVEL = 
2
Factory =

Deprecated alias of CAPIFactory. Defined primarily to support old YAML serializations.

CAPIFactory

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.preferred_native_interface ⇒ Object

The preferred native interface. This is the native interface used by default when a factory is created. Supported values are :capi and :ffi.

This is set automatically when RGeo loads, to :capi if the CAPI interface is available, otheriwse to :ffi if FFI is available, otherwise to nil if no GEOS interface is available. You can override this setting if you want to prefer FFI over CAPI.



84
85
86
 
# File 'lib/rgeo/geos/interface.rb', line 84

def preferred_native_interface
  @preferred_native_interface
end

Class Method Details

.capi_supported? ⇒ Boolean

Returns true if the CAPI GEOS implementation is supported.

Returns:

  • (Boolean) 


12
13
14
 
# File 'lib/rgeo/geos/interface.rb', line 12

def capi_supported?
  CAPI_SUPPORTED
end

.factory(opts_ = {}) ⇒ Object

Returns a factory for the GEOS implementation. Returns nil if the GEOS implementation is not supported.

Note that GEOS does not natively support 4-dimensional data (i.e. both z and m values). However, RGeo’s GEOS wrapper does provide a 4-dimensional factory that utilizes an extra native GEOS object to handle the extra coordinate. Hence, a factory configured with both Z and M support will work, but will be slower than a 2-dimensional or 3-dimensional factory.

Options include:

:native_interface

Specifies which native interface to use. Possible values are :capi and :ffi. The default is the value of the preferred_native_interface.

:uses_lenient_multi_polygon_assertions

If set to true, assertion checking on MultiPolygon is disabled. This may speed up creation of MultiPolygon objects, at the expense of not doing the proper checking for OGC MultiPolygon compliance. See RGeo::Feature::MultiPolygon for details on the MultiPolygon assertions. Default is false. Also called :lenient_multi_polygon_assertions.

:buffer_resolution

The resolution of buffers around geometries created by this factory. This controls the number of line segments used to approximate curves. The default is 1, which causes, for example, the buffer around a point to be approximated by a 4-sided polygon. A resolution of 2 would cause that buffer to be approximated by an 8-sided polygon. The exact behavior for different kinds of buffers is defined by GEOS.

:srid

Set the SRID returned by geometries created by this factory. Default is 0.

:proj4

The coordinate system in Proj4 format, either as a CoordSys::Proj4 object or as a string or hash representing the proj4 format. Optional.

:coord_sys

The coordinate system in OGC form, either as a subclass of CoordSys::CS::CoordinateSystem, or as a string in WKT format. Optional.

:srs_database

Optional. If provided, the value should be an implementation of CoordSys::SRSDatabase::Interface. If both this and an SRID are provided, they are used to look up the proj4 and coord_sys objects from a spatial reference system database.

:has_z_coordinate

Support z_coordinate. Default is false.

:has_m_coordinate

Support m_coordinate. Default is false.

:wkt_parser

Configure the parser for WKT. You may either pass a hash of configuration parameters for WKRep::WKTParser.new, or the special value :geos, indicating to use the native GEOS parser. Default is the empty hash, indicating the default configuration for WKRep::WKTParser. Note that the special :geos value is not supported for ZM factories, since GEOS currently can’t handle ZM natively.

:wkb_parser

Configure the parser for WKB. You may either pass a hash of configuration parameters for WKRep::WKBParser.new, or the special value :geos, indicating to use the native GEOS parser. Default is the empty hash, indicating the default configuration for WKRep::WKBParser. Note that the special :geos value is not supported for ZM factories, since GEOS currently can’t handle ZM natively.

:wkt_generator

Configure the generator for WKT. You may either pass a hash of configuration parameters for WKRep::WKTGenerator.new, or the special value :geos, indicating to use the native GEOS generator. Default is {:convert_case => :upper}. Note that the special :geos value is not supported for ZM factories, since GEOS currently can’t handle ZM natively.

:wkb_generator

Configure the generator for WKB. You may either pass a hash of configuration parameters for WKRep::WKBGenerator.new, or the special value :geos, indicating to use the native GEOS generator. Default is the empty hash, indicating the default configuration for WKRep::WKBGenerator. Note that the special :geos value is not supported for ZM factories, since GEOS currently can’t handle ZM natively.

:auto_prepare

Request an auto-prepare strategy. Supported values are :simple and :disabled. The former (which is the default) generates a prepared geometry the second time an operation that would benefit from it is called. The latter never automatically generates a prepared geometry (unless you generate one explicitly using the prepare! method).



176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/rgeo/geos/interface.rb', line 176

def factory(opts_ = {})
  if supported?
    native_interface_ = opts_[:native_interface] || Geos.preferred_native_interface
    if opts_[:has_z_coordinate] && opts_[:has_m_coordinate]
      ZMFactory.new(opts_)
    elsif native_interface_ == :ffi
      FFIFactory.new(opts_)
    else
      CAPIFactory.create(opts_)
    end
  end
end

.factory_generator(defaults_ = {}) ⇒ Object

Returns a Feature::FactoryGenerator that creates Geos-backed factories. The given options are used as the default options.

A common case for this is to provide the :srs_database as a default. Then, the factory generator need only be passed an SRID and it will automatically fetch the appropriate Proj4 and CoordSys objects.



197
198
199
 
# File 'lib/rgeo/geos/interface.rb', line 197

def factory_generator(defaults_ = {})
  ::Proc.new { |c_| factory(defaults_.merge(c_)) }
end

.ffi_supported? ⇒ Boolean

Returns true if the FFI GEOS implementation is supported.

Returns:

  • (Boolean) 


18
19
20
 
# File 'lib/rgeo/geos/interface.rb', line 18

def ffi_supported?
  FFI_SUPPORTED
end

.is_capi_geos?(object_) ⇒ Boolean

Returns true if the given feature is a CAPI GEOS feature, or if the given factory is a CAPI GEOS factory.

Returns:

  • (Boolean) 


32
33
34
35
36
37
 
# File 'lib/rgeo/geos/interface.rb', line 32

def is_capi_geos?(object_)
  CAPI_SUPPORTED &&
    (CAPIFactory === object_ || CAPIGeometryMethods === object_ ||
    ZMFactory === object_ && CAPIFactory === object_.z_factory ||
    ZMGeometryMethods === object_ && CAPIGeometryMethods === object_.z_geometry)
end

.is_ffi_geos?(object_) ⇒ Boolean

Returns true if the given feature is an FFI GEOS feature, or if the given factory is an FFI GEOS factory.

Returns:

  • (Boolean) 


42
43
44
45
46
47
 
# File 'lib/rgeo/geos/interface.rb', line 42

def is_ffi_geos?(object_)
  FFI_SUPPORTED &&
    (FFIFactory === object_ || FFIGeometryMethods === object_ ||
    ZMFactory === object_ && FFIFactory === object_.z_factory ||
    ZMGeometryMethods === object_ && FFIGeometryMethods === object_.z_geometry)
end

.is_geos?(object_) ⇒ Boolean

Returns true if the given feature is a GEOS feature, or if the given factory is a GEOS factory. Does not distinguish between CAPI and FFI.

Returns:

  • (Boolean) 


52
53
54
55
56
 
# File 'lib/rgeo/geos/interface.rb', line 52

def is_geos?(object_)
  CAPI_SUPPORTED && (CAPIFactory === object_ || CAPIGeometryMethods === object_) ||
    FFI_SUPPORTED && (FFIFactory === object_ || FFIGeometryMethods === object_) ||
    ZMFactory === object_ || ZMGeometryMethods === object_
end

.supported? ⇒ Boolean

Returns true if any GEOS implementation is supported. If this returns false, GEOS features are not available at all.

Returns:

  • (Boolean) 


25
26
27
 
# File 'lib/rgeo/geos/interface.rb', line 25

def supported?
  FFI_SUPPORTED || CAPI_SUPPORTED
end

.version ⇒ Object

Returns the GEOS library version as a string of the format “x.y.z”. Returns nil if GEOS is not available.



61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/rgeo/geos/interface.rb', line 61

def version
  unless defined?(@version)
    if ::RGeo::Geos::CAPI_SUPPORTED
      @version = ::RGeo::Geos::CAPIFactory._geos_version.freeze
    elsif ::RGeo::Geos::FFI_SUPPORTED
      @version = ::Geos::FFIGeos.GEOSversion.sub(/-CAPI-.*$/, "").freeze
    else
      @version = nil
    end
  end
  @version
end