class RGeo::CoordSys::Proj4

This is a Ruby wrapper around a Proj4 coordinate system. It represents a single geographic coordinate system, which may be a flat projection, a geocentric (3-dimensional) coordinate system, or a geographic (latitude-longitude) coordinate system.

Generally, these are used to define the projection for a Feature::Factory. You can then convert between coordinate systems by casting geometries between such factories using the :project option. You may also use this object directly to perform low-level coordinate transformations.

Public Class Methods

create(defn_, opts_={}) click to toggle source

Create a new Proj4 object, given a definition, which may be either a string or a hash. Returns nil if the given definition is invalid or Proj4 is not supported.

Recognized options include:

:radians: If set to true, then this proj4 will represent geographic (latitude/longitude) coordinates in radians rather than degrees. If this is a geographic coordinate system, then its units will be in radians. If this is a projected coordinate system, then its units will be unchanged, but any geographic coordinate system obtained using #get_geographic will use radians as its units. If this is a geocentric or other type of coordinate system, this has no effect. Default is false. (That is all coordinates are in degrees by default.)

# File lib/rgeo/coord_sys/proj4.rb, line 241
def create(defn_, opts_={})
  result_ = nil
  if supported?
    if defn_.kind_of?(::Hash)
      defn_ = defn_.map{ |k_, v_| v_ ? "+#{k_}=#{v_}" : "+#{k_}" }.join(' ')
    end
    unless defn_ =~ %r^\s*\+/
      defn_ = defn_.sub(%r^(\s*)/, '\1+').gsub(%r(\s+)([^+\s])/, '\1+\2')
    end
    result_ = _create(defn_, opts_[:radians])
    result_ = nil unless result_._valid?
  end
  result_
end

new(defn_, opts_={}) click to toggle source

Create a new Proj4 object, given a definition, which may be either a string or a hash. Raises Error::UnsupportedOperation if the given definition is invalid or Proj4 is not supported.

Recognized options include:

:radians: If set to true, then this proj4 will represent geographic (latitude/longitude) coordinates in radians rather than degrees. If this is a geographic coordinate system, then its units will be in radians. If this is a projected coordinate system, then its units will be unchanged, but any geographic coordinate system obtained using #get_geographic will use radians as its units. If this is a geocentric or other type of coordinate system, this has no effect. Default is false. (That is all coordinates are in degrees by default.)

# File lib/rgeo/coord_sys/proj4.rb, line 274
def new(defn_, opts_={})
  result_ = create(defn_, opts_)
  unless result_
    raise Error::UnsupportedOperation, "Proj4 not supported in this installation"
  end
  result_
end

supported?() click to toggle source

Returns true if Proj4 is supported in this installation. If this returns false, the other methods such as create will not work.

# File lib/rgeo/coord_sys/proj4.rb, line 194
def supported?
  respond_to?(:_create)
end

transform(from_proj_, from_geometry_, to_proj_, to_factory_) click to toggle source

Low-level geometry transform method. Transforms the given geometry between the given two projections. The resulting geometry is constructed using the to_factory. Any projections associated with the factories themselves are ignored.

# File lib/rgeo/coord_sys/proj4.rb, line 308
def transform(from_proj_, from_geometry_, to_proj_, to_factory_)
  case from_geometry_
  when Feature::Point
    _transform_point(from_proj_, from_geometry_, to_proj_, to_factory_)
  when Feature::Line
    to_factory_.line(from_geometry_.points.map{ |p_| _transform_point(from_proj_, p_, to_proj_, to_factory_) })
  when Feature::LinearRing
    _transform_linear_ring(from_proj_, from_geometry_, to_proj_, to_factory_)
  when Feature::LineString
    to_factory_.line_string(from_geometry_.points.map{ |p_| _transform_point(from_proj_, p_, to_proj_, to_factory_) })
  when Feature::Polygon
    _transform_polygon(from_proj_, from_geometry_, to_proj_, to_factory_)
  when Feature::MultiPoint
    to_factory_.multi_point(from_geometry_.map{ |p_| _transform_point(from_proj_, p_, to_proj_, to_factory_) })
  when Feature::MultiLineString
    to_factory_.multi_line_string(from_geometry_.map{ |g_| transform(from_proj_, g_, to_proj_, to_factory_) })
  when Feature::MultiPolygon
    to_factory_.multi_polygon(from_geometry_.map{ |p_| _transform_polygon(from_proj_, p_, to_proj_, to_factory_) })
  when Feature::GeometryCollection
    to_factory_.collection(from_geometry_.map{ |g_| transform(from_proj_, g_, to_proj_, to_factory_) })
  end
end

transform_coords(from_proj_, to_proj_, x_, y_, z_=nil) click to toggle source

Low-level coordinate transform method. Transforms the given coordinate (x, y, [z]) from one proj4 coordinate system to another. Returns an array with either two or three elements.

# File lib/rgeo/coord_sys/proj4.rb, line 288
def transform_coords(from_proj_, to_proj_, x_, y_, z_=nil)
  if !from_proj_._radians? && from_proj_._geographic?
    x_ *= ImplHelper::Math::RADIANS_PER_DEGREE
    y_ *= ImplHelper::Math::RADIANS_PER_DEGREE
  end
  result_ = _transform_coords(from_proj_, to_proj_, x_, y_, z_)
  if result_ && !to_proj_._radians? && to_proj_._geographic?
    result_[0] *= ImplHelper::Math::DEGREES_PER_RADIAN
    result_[1] *= ImplHelper::Math::DEGREES_PER_RADIAN
  end
  result_
end

version() click to toggle source

Returns the Proj4 library version as a Versionomy object if the Versionomy library is available; otherwise as a string of the format “x.y.z”. Returns nil if Proj4 is not available.

# File lib/rgeo/coord_sys/proj4.rb, line 215
def version
  unless defined?(@version)
    str_ = version_string
    @version = str_ && defined?(::Versionomy) ? ::Versionomy.parse(str_) : str_
  end
  @version
end

version_string() click to toggle source

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

# File lib/rgeo/coord_sys/proj4.rb, line 202
def version_string
  unless defined?(@version_string)
    @version_string = respond_to?(:_proj_version) ? _proj_version.to_s.split('').join('.') : nil
  end
  @version_string
end

Public Instance Methods

==(rhs_) click to toggle source

Alias for: eql?

canonical_hash() click to toggle source

Returns the “canonical” hash definition for this coordinate system, as reported by Proj4. This may be slightly different from the definition used to construct this object.

# File lib/rgeo/coord_sys/proj4.rb, line 132
def canonical_hash
  unless defined?(@canonical_hash)
    @canonical_hash = {}
    canonical_str.strip.split(%r\s+/).each do |elem_|
      if elem_ =~ %r^\+(\w+)(=(\S+))?$/
        @canonical_hash[$1] = $3
      end
    end
  end
  @canonical_hash
end

canonical_str() click to toggle source

Returns the “canonical” string definition for this coordinate system, as reported by Proj4. This may be slightly different from the definition used to construct this object.

# File lib/rgeo/coord_sys/proj4.rb, line 117
def canonical_str
  unless defined?(@canonical_str)
    @canonical_str = _canonical_str
    if @canonical_str.respond_to?(:force_encoding)
      @canonical_str.force_encoding('US-ASCII')
    end
  end
  @canonical_str
end

eql?(rhs_) click to toggle source

Returns true if this Proj4 is equivalent to the given Proj4.

Note: this tests for equivalence by comparing only the hash definitions of the Proj4 objects, and returning true if those definitions are equivalent. In some cases, this may still return false even if the actual coordinate systems are identical, since there are sometimes multiple ways to express a given coordinate system.

# File lib/rgeo/coord_sys/proj4.rb, line 80
def eql?(rhs_)
  rhs_.class == self.class && rhs_.canonical_hash == canonical_hash && rhs_._radians? == _radians?
end

Also aliased as: ==

geocentric?() click to toggle source

Returns true if this Proj4 object is a geocentric (3dz) coordinate system.

# File lib/rgeo/coord_sys/proj4.rb, line 165
def geocentric?
  _geocentric?
end

geographic?() click to toggle source

Returns true if this Proj4 object is a geographic (lat-long) coordinate system.

# File lib/rgeo/coord_sys/proj4.rb, line 157
def geographic?
  _geographic?
end

get_geographic() click to toggle source

Get the geographic (unprojected lat-long) coordinate system corresponding to this coordinate system; i.e. the one that uses the same ellipsoid and datum.

# File lib/rgeo/coord_sys/proj4.rb, line 182
def get_geographic
  _get_geographic
end

original_str() click to toggle source

Returns the string definition originally used to construct this object. Returns nil if this object wasn’t created by a string definition; i.e. if it was created using get_geographic.

# File lib/rgeo/coord_sys/proj4.rb, line 149
def original_str
  _original_str
end

radians?() click to toggle source

Returns true if this Proj4 object uses radians rather than degrees if it is a geographic coordinate system.

# File lib/rgeo/coord_sys/proj4.rb, line 173
def radians?
  _radians?
end