Module: RGeo::Geographic

Defined in:
lib/rgeo/geographic/factory.rb,
lib/rgeo/geographic/interface.rb,
lib/rgeo/geographic/projector.rb,
lib/rgeo/geographic/spherical_math.rb,
lib/rgeo/geographic/projected_window.rb,
lib/rgeo/geographic/projected_feature_classes.rb,
lib/rgeo/geographic/projected_feature_methods.rb,
lib/rgeo/geographic/simple_mercator_projector.rb,
lib/rgeo/geographic/spherical_feature_classes.rb,
lib/rgeo/geographic/spherical_feature_methods.rb

Defined Under Namespace

Modules: ProjectedGeometryMethods, ProjectedLineStringMethods, ProjectedLinearRingMethods, ProjectedMultiPolygonMethods, ProjectedNCurveMethods, ProjectedNSurfaceMethods, ProjectedPointMethods, ProjectedPolygonMethods, SphericalGeometryMethods, SphericalLineStringMethods, SphericalMath, SphericalMultiLineStringMethods, SphericalPointMethods, SphericalPolygonMethods Classes: Factory, ProjectedGeometryCollectionImpl, ProjectedLineImpl, ProjectedLineStringImpl, ProjectedLinearRingImpl, ProjectedMultiLineStringImpl, ProjectedMultiPointImpl, ProjectedMultiPolygonImpl, ProjectedPointImpl, ProjectedPolygonImpl, ProjectedWindow, Projector, SimpleMercatorProjector, SphericalGeometryCollectionImpl, SphericalLineImpl, SphericalLineStringImpl, SphericalLinearRingImpl, SphericalMultiLineStringImpl, SphericalMultiPointImpl, SphericalMultiPolygonImpl, SphericalPointImpl, SphericalPolygonImpl

Class Method Summary collapse

Class Method Details

.projected_factory(opts = {}) ⇒ Object

Creates and returns a geographic factory that includes a projection specified by a coordinate system. Like all geographic factories, this one creates features using latitude- longitude values. However, calculations such as intersections are done in the projected coordinate system, and size and distance calculations report results in the projected units. Thus, this factory actually includes two factories representing different coordinate systems: the main factory representing the geographic lat-long coordinate system, and an auxiliary “projection factory” representing the projected coordinate system.

This implementation is intended for advanced GIS applications requiring greater control over the projection being used.

Options

When creating a projected implementation, you must provide enough information to construct a CoordinateSystem specification for the projection. Generally, this means you will provide either the projection’s factory itself (via the :projection_factory option), in which case the factory must include a coord_sys; or, alternatively, you should provide the coordinate system and let this method construct a projection factory for you (which it will do using the preferred Cartesian factory generator). If you choose this second method, you may provide the coord_sys via the :projection_coord_sys or <option or :projection_srid.

Following are detailed descriptions of the various options you can pass to this method.

:projection_factory

Specify an existing Cartesian factory to use for the projection. This factory must have a non-nil coord_sys. If this is provided, any :projection_coord_sys and :projection_srid are ignored.

:projection_coord_sys

Specify a OGC coordinate system for the projection. This may be specified as an RGeo::CoordSys::CS::GeographicCoordinateSystem object, or as a String in OGC WKT format. Optional.

:projection_srid

The SRID value to use for the projection factory. Defaults to the given projection coordinate system’s authority code, or to 0 if no projection coordinate system is known. If this is provided without a projection_coord_sys, one will be instansiated from the default_coord_sys_class or projection_coord_sys_class if given.

:projection_coord_sys_class

Class to create the projection_coord_sys from if only a projection_srid is provided.

:coord_sys

An OGC coordinate system for the geographic (lat-lon) factory, which may be an RGeo::CoordSys::CS::GeographicCoordinateSystem object or a string in OGC WKT format. It defaults to the geographic system embedded in the projection coordinate system. Generally, you should leave it at the default unless you want the geographic coordinate system to be based on a different horizontal datum than the projection.

:srid

The SRID value to use for the main geographic factory. Defaults to the given geographic coordinate system’s authority code, or to 0 if no geographic coordinate system is known.

:has_z_coordinate

Support a Z coordinate. Default is false. Note: this is ignored if a :projection_factory is provided; in that case, the geographic factory’s z-coordinate availability will match the projection factory’s setting.

:has_m_coordinate

Support an M coordinate. Default is false. Note: this is ignored if a :projection_factory is provided; in that case, the geographic factory’s m-coordinate availability will match the projection factory’s setting.

:wkt_parser

Configure the parser for WKT. The value is a hash of configuration parameters for WKRep::WKTParser.new. Default is the empty hash, indicating the default configuration for WKRep::WKTParser.

:wkb_parser

Configure the parser for WKB. The value is a hash of configuration parameters for WKRep::WKBParser.new. Default is the empty hash, indicating the default configuration for WKRep::WKBParser.

:wkt_generator

Configure the generator for WKT. The value is a hash of configuration parameters for WKRep::WKTGenerator.new. Default is {:convert_case => :upper}.

:wkb_generator

Configure the generator for WKT. The value is a hash of configuration parameters for WKRep::WKTGenerator.new. Default is the empty hash, indicating the default configuration for WKRep::WKBGenerator.

If a :projection_factory is not provided, you may also provide options for configuring the projected Cartesian factory. For example, if GEOS is used for the projected factory, you may also set the :buffer_resolution option. See RGeo::Geos.factory for more details.



307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
 
# File 'lib/rgeo/geographic/interface.rb', line 307

def projected_factory(opts = {})
  if (projection_factory = opts[:projection_factory])
    # Get the projection coordinate systems from the given factory
    projection_coord_sys = projection_factory.coord_sys

    if projection_coord_sys && !projection_coord_sys.projected?
      raise ArgumentError, "The :projection_factory's coord_sys is not a ProjectedCoordinateSystem."
    end

    # Determine geographic coordinate system. First check parameters.
    coord_sys = opts[:coord_sys]
    srid = opts[:srid]
    # Fall back to getting the values from the projection.
    coord_sys ||= projection_coord_sys.geographic_coordinate_system if projection_coord_sys
    srid ||= coord_sys.authority_code if coord_sys
    srid ||= 4326
    # Now we should have all the coordinate system info.
    factory = Geographic::Factory.new(
      "Projected",
      coord_sys: coord_sys,
      srid: srid.to_i,
      has_z_coordinate: projection_factory.property(:has_z_coordinate),
      has_m_coordinate: projection_factory.property(:has_m_coordinate),
      wkt_parser: opts[:wkt_parser], wkt_generator: opts[:wkt_generator],
      wkb_parser: opts[:wkb_parser], wkb_generator: opts[:wkb_generator]
    )
    projector = Geographic::Projector.create_from_existing_factory(
      factory,
      projection_factory
    )
  else
    # Determine projection coordinate system. First check the parameters.
    projection_coord_sys_info = ImplHelper::Utils.setup_coord_sys(
      opts[:projection_srid],
      opts[:projection_coord_sys],
      opts[:projection_coord_sys_class]
    )
    projection_coord_sys = projection_coord_sys_info[:coord_sys]
    projection_srid = projection_coord_sys_info[:srid]

    # Determine geographic coordinate system. First check parameters.
    coord_sys = opts[:coord_sys]
    srid = opts[:srid]

    # Fall back to getting the values from the projection.
    coord_sys ||= projection_coord_sys.geographic_coordinate_system if projection_coord_sys
    srid ||= coord_sys.authority_code if coord_sys
    srid ||= 4326
    # Now we should have all the coordinate system info.
    factory = Geographic::Factory.new(
      "Projected",
      coord_sys: coord_sys,
      srid: srid.to_i,
      has_z_coordinate: opts[:has_z_coordinate],
      has_m_coordinate: opts[:has_m_coordinate],
      wkt_parser: opts[:wkt_parser], wkt_generator: opts[:wkt_generator],
      wkb_parser: opts[:wkb_parser], wkb_generator: opts[:wkb_generator]
    )
    projector = Geographic::Projector.create_from_opts(
      factory,
      srid: projection_srid,
      coord_sys: projection_coord_sys,
      buffer_resolution: opts[:buffer_resolution],
      has_z_coordinate: opts[:has_z_coordinate],
      has_m_coordinate: opts[:has_m_coordinate],
      wkt_parser: opts[:wkt_parser], wkt_generator: opts[:wkt_generator],
      wkb_parser: opts[:wkb_parser], wkb_generator: opts[:wkb_generator]
    )
  end
  factory.projector = projector
  factory
end

.simple_mercator_factory(opts = {}) ⇒ Object

Creates and returns a geographic factory that is designed for visualization applications that use Google or Bing maps, or any other visualization systems that use the same projection. It includes a projection factory that matches the projection used by those mapping systems.

Like all geographic factories, this one creates features using latitude-longitude values. However, calculations such as intersections are done in the projected coordinate system, and size and distance calculations report results in the projected units.

The behavior of the simple_mercator factory could also be obtained using a projected_factory with appropriate Proj4 specifications. However, the simple_mercator implementation is done without actually requiring the Proj4 library. The projections are simple enough to be implemented in pure ruby.

About the coordinate system

Many popular visualization technologies, such as Google and Bing maps, actually use two coordinate systems. The first is the standard WSG84 lat-long system used by the GPS and represented by EPSG 4326. Most API calls and input-output in these mapping technologies utilize this coordinate system. The second is a Mercator projection based on a “sphericalization” of the WGS84 lat-long system. This projection is the basis of the map’s screen and tiling coordinates, and has been assigned EPSG 3857.

This factory represents both coordinate systems. The main factory produces data in the lat-long system and reports SRID 4326, and the projected factory produces data in the projection and reports SRID 3857. Latitudes are restricted to the range (-85.05112877980659, 85.05112877980659), which conveniently results in a square projected domain.

Options

You may use the following options when creating a simple_mercator factory:

:has_z_coordinate

Support a Z coordinate. Default is false.

:has_m_coordinate

Support an M coordinate. Default is false.

:wkt_parser

Configure the parser for WKT. The value is a hash of configuration parameters for WKRep::WKTParser.new. Default is the empty hash, indicating the default configuration for WKRep::WKTParser.

:wkb_parser

Configure the parser for WKB. The value is a hash of configuration parameters for WKRep::WKBParser.new. Default is the empty hash, indicating the default configuration for WKRep::WKBParser.

:wkt_generator

Configure the generator for WKT. The value is a hash of configuration parameters for WKRep::WKTGenerator.new. Default is {:convert_case => :upper}.

:wkb_generator

Configure the generator for WKT. The value is a hash of configuration parameters for WKRep::WKTGenerator.new. Default is the empty hash, indicating the default configuration for WKRep::WKBGenerator.

You may also provide options understood by the underlying projected Cartesian factory. For example, if GEOS is used for the projected factory, you may also set the :buffer_resolution options. See RGeo::Geos.factory for more details.



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/rgeo/geographic/interface.rb', line 189

def simple_mercator_factory(opts = {})
  factory = Geographic::Factory.new(
    "Projected",
    coord_sys: coord_sys4326,
    srid: 4326,
    wkt_parser: opts[:wkt_parser],
    wkb_parser: opts[:wkb_parser],
    wkt_generator: opts[:wkt_generator],
    wkb_generator: opts[:wkb_generator],
    has_z_coordinate: opts[:has_z_coordinate],
    has_m_coordinate: opts[:has_m_coordinate]
  )
  projector = Geographic::SimpleMercatorProjector.new(
    factory,
    buffer_resolution: opts[:buffer_resolution],
    has_z_coordinate: opts[:has_z_coordinate],
    has_m_coordinate: opts[:has_m_coordinate]
  )
  factory.projector = projector
  factory
end

.spherical_factory(opts = {}) ⇒ Object

Creates and returns a geographic factory that does not include a a projection, and which performs calculations assuming a spherical earth. In other words, geodesics are treated as great circle arcs, and geometric calculations are handled accordingly. Size and distance calculations report results in meters. This implementation is thus ideal for everyday calculations on the globe in which good accuracy is desired, but in which it is not deemed necessary to perform the complex ellipsoidal calculations needed for greater precision.

The maximum error is about 0.5 percent, for objects and calculations that span a significant percentage of the globe, due to distortion caused by rotational flattening of the earth. For calculations that span a much smaller area, the error can drop to a few meters or less.

Limitations

This implementation does not implement some of the more advanced geometric operations. In particular:

  • Relational operators such as Feature::Geometry#intersects? are not implemented for most types.

  • Relational constructors such as Feature::Geometry#union are not implemented for most types.

  • Buffer, convex hull, and envelope calculations are not implemented for most types. Boundaries are available except for GeometryCollection.

  • Length calculations are available, but areas are not. Distances are available only between points.

  • Equality and simplicity evaluation are implemented for some but not all types.

  • Assertions for polygons and multipolygons are not implemented.

Unimplemented operations will return nil if invoked.

Options

You may use the following options when creating a spherical factory:

:has_z_coordinate

Support a Z coordinate. Default is false.

:has_m_coordinate

Support an M coordinate. Default is false.

: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 not specified precisely, but in general the value is taken as the number of segments per 90-degree curve.

:coord_sys

Provide a coordinate system in OGC format, either as an object (one of the CoordSys::CS classes) or as a string in WKT format. This coordinate system must be a GeographicCoordinateSystem. The default is the “popular visualization CRS” (EPSG 4055).

:coord_sys_class

CoordSys::CS::CoordinateSystem implementation used to instansiate a coord_sys based on the :srid given.

:srid

The SRID that should be returned by features from this factory. Default is 4055, indicating EPSG 4055, the “popular visualization crs”. You may alternatively wish to set the srid to 4326, indicating the WGS84 crs, but note that that value implies an ellipsoidal datum, not a spherical datum.

:wkt_parser

Configure the parser for WKT. The value is a hash of configuration parameters for WKRep::WKTParser.new. Default is the empty hash, indicating the default configuration for WKRep::WKTParser.

:wkb_parser

Configure the parser for WKB. The value is a hash of configuration parameters for WKRep::WKBParser.new. Default is the empty hash, indicating the default configuration for WKRep::WKBParser.

:wkt_generator

Configure the generator for WKT. The value is a hash of configuration parameters for WKRep::WKTGenerator.new. Default is {:convert_case => :upper}.

:wkb_generator

Configure the generator for WKT. The value is a hash of configuration parameters for WKRep::WKTGenerator.new. Default is the empty hash, indicating the default configuration for WKRep::WKBGenerator.



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/rgeo/geographic/interface.rb', line 101

def spherical_factory(opts = {})
  coord_sys = opts[:coord_sys]
  srid = opts[:srid]
  srid ||= coord_sys.authority_code if coord_sys
  Geographic::Factory.new(
    "Spherical",
    has_z_coordinate: opts[:has_z_coordinate],
    has_m_coordinate: opts[:has_m_coordinate],
    coord_sys: coord_sys || coord_sys4055,
    buffer_resolution: opts[:buffer_resolution],
    wkt_parser: opts[:wkt_parser],
    wkb_parser: opts[:wkb_parser],
    wkt_generator: opts[:wkt_generator],
    wkb_generator: opts[:wkb_generator],
    srid: (srid || 4055).to_i
  )
end