Class: OGR::SpatialReference

Inherits:
Object
  • Object
show all
Includes:
GDAL::Logger, Extensions, OGR::SpatialReferenceMixins::CoordinateSystemGetterSetters, OGR::SpatialReferenceMixins::Exporters, OGR::SpatialReferenceMixins::Importers, OGR::SpatialReferenceMixins::Initializers, OGR::SpatialReferenceMixins::Morphers, OGR::SpatialReferenceMixins::ParameterGetterSetters, OGR::SpatialReferenceMixins::TypeChecks
Defined in:
lib/ogr/spatial_reference.rb,
lib/ogr/extensions/spatial_reference/extensions.rb

Overview

Represents a geographic coordinate system. There are two primary types:

1. "geographic", where positions are measured in long/lat.
2. "projected", where positions are measure in meters or feet.

Defined Under Namespace

Modules: Extensions

Constant Summary collapse

METER_TO_METER = 
1.0
RADIAN_TO_RADIAN = 
1.0

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from OGR::SpatialReferenceMixins::Initializers

included

Methods included from Extensions

#angular_units=, #linear_units=

Methods included from OGR::SpatialReferenceMixins::TypeChecks

#compound?, #geocentric?, #geog_cs_is_same?, #geographic?, #local?, #projected?, #same?, #vert_cs_is_same?, #vertical?

Methods included from OGR::SpatialReferenceMixins::ParameterGetterSetters

#angular_units, #attribute_value, #linear_units, #prime_meridian, #set_angular_units, #set_attribute_value, #set_linear_units, #set_linear_units_and_update_parameters, #set_target_linear_units, #target_linear_units

Methods included from OGR::SpatialReferenceMixins::Morphers

#morph_from_esri!, #morph_to_esri!

Methods included from OGR::SpatialReferenceMixins::Importers

#import_from_epsg, #import_from_epsga, #import_from_erm, #import_from_esri, #import_from_mapinfo, #import_from_pci, #import_from_proj4, #import_from_url, #import_from_usgs, #import_from_wkt, #import_from_xml, included

Methods included from OGR::SpatialReferenceMixins::Exporters

#to_erm, #to_mapinfo, #to_pci, #to_pretty_wkt, #to_proj4, #to_usgs, #to_wkt, #to_xml

Methods included from OGR::SpatialReferenceMixins::CoordinateSystemGetterSetters

#authority_code, #authority_name, #axis, #normalized_projection_parameter, #projection_parameter, #semi_major, #semi_minor, #set_ae, #set_albers_conic_equal_area, #set_authority, #set_bonne, #set_cea, #set_compound_cs, #set_cs, #set_ec, #set_eckert, #set_eckert_iv, #set_eckert_vi, #set_equirectangular, #set_equirectangular2, #set_from_user_input, #set_gauss_schreiber_transverse_mercator, #set_gc, #set_geoc_cs, #set_geog_cs, #set_geos, #set_gh, #set_gnomonic, #set_hom, #set_hom_2_pno, #set_igh, #set_iwm_polyconic, #set_krovak, #set_laea, #set_lcc, #set_lcc_1sp, #set_lccb, #set_local_cs, #set_mc, #set_mercator, #set_mollweide, #set_normalized_projection_parameter, #set_nzmg, #set_om, #set_orthographic, #set_os, #set_polyconic, #set_proj_cs, #set_projection, #set_projection_parameter, #set_ps, #set_qsc, #set_robinson, #set_sinusoidal, #set_soc, #set_state_plane, #set_stereographic, #set_tm_variant, #set_tmg, #set_tmso, #set_towgs84, #set_transverse_mercator, #set_utm, #set_vdg, #set_vert_cs, #set_wagner, #set_well_known_geog_cs, #spheroid_inverse_flattening, #towgs84, #utm_zone

Constructor Details

#initialize(spatial_reference_or_wkt = nil) ⇒ SpatialReference

Builds a spatial reference object using either the passed-in WKT string, OGR::SpatialReference object, or a pointer to an in-memory SpatialReference object. If nothing is passed in, an empty SpatialReference object is created, in which case you’ll need to populate relevant attributes.

If a OGR::SpatialReference is given, this clones that object so it can have it’s own object (relevant for cleaning up when garbage collecting).

Parameters:

Raises:



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/ogr/spatial_reference.rb', line 141

def initialize(spatial_reference_or_wkt = nil)
  pointer =
    case spatial_reference_or_wkt.class.name
    when "OGR::SpatialReference"
      # This is basically getting a reference to the SpatialReference that
      # was passed in, thus when this SpatialReference gets garbage-collected,
      # it shouldn't release anything.
      ptr = spatial_reference_or_wkt.c_pointer
      ptr.autorelease = false
    when "String", "NilClass"
      # FWIW, the docs say:
      # Note that newly created objects are given a reference count of one.
      #
      # ...which implies that we should use Release here instead of Destroy.
      ptr = FFI::OGR::SRSAPI.OSRNewSpatialReference(spatial_reference_or_wkt)
      ptr.autorelease = false

      # We're instantiating a new SR, so we can use .destroy.
      FFI::AutoPointer.new(ptr, SpatialReference.method(:release))
    when "FFI::AutoPointer", "FFI::Pointer", "FFI::MemoryPointer"
      # If we got a pointer, we don't know who owns the data, so don't
      # touch anything about autorelease/AutoPointer.
      spatial_reference_or_wkt
    else
      log "Dunno what to do with #{spatial_reference_or_wkt.inspect}"
    end

  raise OGR::CreateFailure, "Unable to create SpatialReference." if pointer.nil? || pointer.null?

  @c_pointer = pointer
end

Instance Attribute Details

#c_pointer ⇒ FFI::Pointer (readonly)

Returns C pointer to the C Spatial Reference.

Returns:

  • (FFI::Pointer) —

    C pointer to the C Spatial Reference.



129
130
131
 
# File 'lib/ogr/spatial_reference.rb', line 129

def c_pointer
  @c_pointer
end

Class Method Details

.axis_enum_to_name(orientation) ⇒ String

Parameters:

Returns:



98
99
100
 
# File 'lib/ogr/spatial_reference.rb', line 98

def self.axis_enum_to_name(orientation)
  FFI::OGR::SRSAPI::AxisEnumToName(orientation)
end

.cleanup ⇒ Object

Cleans up cached SRS-related memory.



103
104
105
 
# File 'lib/ogr/spatial_reference.rb', line 103

def self.cleanup
  FFI::OGR::SRSAPI.OSRCleanup
end

.destroy(pointer) ⇒ Object

This static method will destroy a OGRSpatialReference. It is equivalent to calling delete on the object, but it ensures that the deallocation is properly executed within the OGR libraries heap on platforms where this can matter (win32).

Parameters:

  • pointer (FFI::Pointer) 


113
114
115
116
117
 
# File 'lib/ogr/spatial_reference.rb', line 113

def self.destroy(pointer)
  return unless pointer && !pointer.null?

  FFI::OGR::SRSAPI.OSRDestroySpatialReference(pointer)
end

.parameter_info(projection_method, parameter_name) ⇒ Object

Deprecated.

This was removed in GDAL 3.0.

Fetch info about a single parameter of a projection method.

Parameters:



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/ogr/spatial_reference.rb', line 76

def self.parameter_info(projection_method, parameter_name)
  name_ptr_ptr = GDAL._pointer_pointer(:string)
  type_ptr_ptr = GDAL._pointer_pointer(:string)
  default_value_ptr = FFI::MemoryPointer.new(:double)

  result = FFI::OGR::SRSAPI.OPTGetParameterInfo(projection_method, parameter_name,
                                                name_ptr_ptr, type_ptr_ptr, default_value_ptr)

  return {} unless result

  name = GDAL._read_pointer_pointer_safely(name_ptr_ptr, :string)
  type = GDAL._read_pointer_pointer_safely(name_ptr_ptr, :string)

  {
    type: type,
    default_value: default_value_ptr.read_double,
    user_visible_name: name
  }
end

.parameter_list(projection_method) ⇒ Hash{parameter => Array<String>, user_visible_name => String}

Deprecated.

This was removed in GDAL 3.0.

Parameters:

  • projection_method (String) —

    One of OGR::SpatialReference.projection_methods.

Returns:

  • (Hash{parameter => Array<String>, user_visible_name => String}) 


56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/ogr/spatial_reference.rb', line 56

def self.parameter_list(projection_method)
  name_ptr_ptr = GDAL._pointer_pointer(:string)
  params_ptr_ptr = FFI::OGR::SRSAPI.OPTGetParameterList(projection_method, name_ptr_ptr)
  count = FFI::CPL::String.CSLCount(params_ptr_ptr)

  # For some reason #get_array_of_string leaves off the first 6.
  pointer_array = params_ptr_ptr.get_array_of_pointer(0, count)
  name = GDAL._read_pointer_pointer_safely(name_ptr_ptr, :string)

  {
    parameters: pointer_array.map(&:read_string).sort,
    user_visible_name: name
  }
end

.projection_methods(strip_underscores: false) ⇒ Array<String>

Deprecated.

This was removed in GDAL 3.0.

Returns:



40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/ogr/spatial_reference.rb', line 40

def self.projection_methods(strip_underscores: false)
  methods_ptr_ptr = FFI::OGR::SRSAPI.OPTGetProjectionMethods
  count = FFI::CPL::String.CSLCount(methods_ptr_ptr)

  # For some reason #get_array_of_string leaves off the first 6.
  pointer_array = methods_ptr_ptr.get_array_of_pointer(0, count)

  list = pointer_array.map(&:read_string).sort

  strip_underscores ? list.map! { |l| l.tr("_", " ") } : list
end

.release(pointer) ⇒ Object

Decrements the reference count by one, and destroy if zero.

Parameters:

  • pointer (FFI::Pointer) 


122
123
124
125
126
 
# File 'lib/ogr/spatial_reference.rb', line 122

def self.release(pointer)
  return unless pointer && !pointer.null?

  FFI::OGR::SRSAPI.OSRRelease(pointer)
end

Instance Method Details

#auto_identify_epsg! ⇒ Object

Sets the EPSG authority info if possible.

Raises:



242
243
244
245
246
 
# File 'lib/ogr/spatial_reference.rb', line 242

def auto_identify_epsg!
  OGR::ErrorHandling.handle_ogr_err("Unable to determine SRS from EPSG") do
    FFI::OGR::SRSAPI.OSRAutoIdentifyEPSG(@c_pointer)
  end
end

#clone ⇒ OGR::SpatialReference

Uses the C-API to clone this spatial reference object.

Returns:



182
183
184
185
186
 
# File 'lib/ogr/spatial_reference.rb', line 182

def clone
  new_spatial_ref_ptr = FFI::OGR::SRSAPI.OSRClone(@c_pointer)

  SpatialReference.new(new_spatial_ref_ptr)
end

#clone_geog_cs ⇒ OGR::SpatialReference

Makes a duplicate of the GEOGCS node of this spatial reference.

Returns:



191
192
193
194
195
 
# File 'lib/ogr/spatial_reference.rb', line 191

def clone_geog_cs
  new_spatial_ref_ptr = FFI::OGR::SRSAPI.OSRCloneGeogCS(@c_pointer)

  SpatialReference.new(new_spatial_ref_ptr)
end

#copy_geog_cs_from(other_spatial_ref) ⇒ Object

Parameters:

Raises:



200
201
202
203
204
205
206
207
 
# File 'lib/ogr/spatial_reference.rb', line 200

def copy_geog_cs_from(other_spatial_ref)
  other_spatial_ref_ptr = GDAL._pointer(OGR::SpatialReference, other_spatial_ref)
  raise OGR::InvalidSpatialReference if other_spatial_ref_ptr.nil? || other_spatial_ref_ptr.null?

  OGR::ErrorHandling.handle_ogr_err("Unable to copy GEOGCS") do
    FFI::OGR::SRSAPI.OSRCopyGeogCSFrom(@c_pointer, other_spatial_ref_ptr)
  end
end

#create_coordinate_transformation(destination_spatial_ref) ⇒ OGR::SpatialReference, FFI::Pointer

Returns Pointer to an OGR::SpatialReference.

Returns:



261
262
263
 
# File 'lib/ogr/spatial_reference.rb', line 261

def create_coordinate_transformation(destination_spatial_ref)
  OGR::CoordinateTransformation.new(@c_pointer, destination_spatial_ref)
end

#destroy! ⇒ Object 



173
174
175
176
177
 
# File 'lib/ogr/spatial_reference.rb', line 173

def destroy!
  SpatialReference.destroy(@c_pointer)

  @c_pointer = nil
end

#epsg_treats_as_lat_long? ⇒ Boolean

Returns true if this coordinate system should be treated as having lat/long coordinate ordering.

Returns:

  • (Boolean) —

    true if this coordinate system should be treated as having lat/long coordinate ordering.



250
251
252
 
# File 'lib/ogr/spatial_reference.rb', line 250

def epsg_treats_as_lat_long?
  FFI::OGR::SRSAPI.OSREPSGTreatsAsLatLong(@c_pointer)
end

#epsg_treats_as_northing_easting? ⇒ Boolean

Returns true if this coordinate system should be treated as having northing/easting coordinate ordering.

Returns:

  • (Boolean) —

    true if this coordinate system should be treated as having northing/easting coordinate ordering.



256
257
258
 
# File 'lib/ogr/spatial_reference.rb', line 256

def epsg_treats_as_northing_easting?
  FFI::OGR::SRSAPI.OSREPSGTreatsAsNorthingEasting(@c_pointer)
end

#fixup! ⇒ Object

Raises:



224
225
226
227
228
 
# File 'lib/ogr/spatial_reference.rb', line 224

def fixup!
  OGR::ErrorHandling.handle_ogr_err("Unable to fixup") do
    FFI::OGR::SRSAPI.OSRFixup(@c_pointer)
  end
end

#fixup_ordering! ⇒ Object

Raises:



217
218
219
220
221
 
# File 'lib/ogr/spatial_reference.rb', line 217

def fixup_ordering!
  OGR::ErrorHandling.handle_ogr_err("Unable to fixup ordering") do
    FFI::OGR::SRSAPI.OSRFixupOrdering(@c_pointer)
  end
end

#strip_ct_parameters! ⇒ Object

Strips all OGC coordinate transformation parameters.

Raises:



233
234
235
236
237
 
# File 'lib/ogr/spatial_reference.rb', line 233

def strip_ct_parameters!
  OGR::ErrorHandling.handle_ogr_err("Unable to strip coordinate transformation parameters") do
    FFI::OGR::SRSAPI.OSRStripCTParms(@c_pointer)
  end
end

#validate ⇒ Object

Raises:



210
211
212
213
214
 
# File 'lib/ogr/spatial_reference.rb', line 210

def validate
  OGR::ErrorHandling.handle_ogr_err("Unable to validate") do
    FFI::OGR::SRSAPI.OSRValidate(@c_pointer)
  end
end