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 Classes: Version

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:



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/ogr/spatial_reference.rb', line 156

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.



144
145
146
 
# File 'lib/ogr/spatial_reference.rb', line 144

def c_pointer
  @c_pointer
end

Class Method Details

.axis_enum_to_name(orientation) ⇒ String

Parameters:

Returns:



100
101
102
 
# File 'lib/ogr/spatial_reference.rb', line 100

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

.cleanup ⇒ Object

Cleans up cached SRS-related memory.



105
106
107
 
# File 'lib/ogr/spatial_reference.rb', line 105

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) 


115
116
117
118
119
 
# File 'lib/ogr/spatial_reference.rb', line 115

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:



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

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}) 


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

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

.proj_version ⇒ Object 



130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/ogr/spatial_reference.rb', line 130

def self.proj_version
  major_ptr = FFI::MemoryPointer.new(:int)
  major_ptr.autorelease = false
  minor_ptr = FFI::MemoryPointer.new(:int)
  minor_ptr.autorelease = false
  patch_ptr = FFI::MemoryPointer.new(:int)
  patch_ptr.autorelease = false

  FFI::OGR::SRSAPI.OSRGetPROJVersion(major_ptr, minor_ptr, patch_ptr)

  Version.new(major_ptr.read_int, minor_ptr.read_int, patch_ptr.read_int)
end

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

Deprecated.

This was removed in GDAL 3.0.

Returns:



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

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) 


124
125
126
127
128
 
# File 'lib/ogr/spatial_reference.rb', line 124

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:



257
258
259
260
261
 
# File 'lib/ogr/spatial_reference.rb', line 257

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

#axis_mapping_strategy ⇒ FFI::OGR::SRSAPI::AxisMappingStrategy

Returns The axis mapping strategy.

Returns:

  • (FFI::OGR::SRSAPI::AxisMappingStrategy) —

    The axis mapping strategy.



286
287
288
 
# File 'lib/ogr/spatial_reference.rb', line 286

def axis_mapping_strategy
  FFI::OGR::SRSAPI.OSRGetAxisMappingStrategy(@c_pointer)
end

#axis_mapping_strategy=(strategy) ⇒ nil

Returns Sets the axis mapping strategy for this spatial reference.

Returns:

  • (nil) —

    Sets the axis mapping strategy for this spatial reference.



281
282
283
 
# File 'lib/ogr/spatial_reference.rb', line 281

def axis_mapping_strategy=(strategy)
  FFI::OGR::SRSAPI.OSRSetAxisMappingStrategy(@c_pointer, strategy)
end

#clone ⇒ OGR::SpatialReference

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

Returns:



197
198
199
200
201
 
# File 'lib/ogr/spatial_reference.rb', line 197

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:



206
207
208
209
210
 
# File 'lib/ogr/spatial_reference.rb', line 206

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:



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

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:



276
277
278
 
# File 'lib/ogr/spatial_reference.rb', line 276

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

#destroy! ⇒ Object 



188
189
190
191
192
 
# File 'lib/ogr/spatial_reference.rb', line 188

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.



265
266
267
 
# File 'lib/ogr/spatial_reference.rb', line 265

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.



271
272
273
 
# File 'lib/ogr/spatial_reference.rb', line 271

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

#fixup! ⇒ Object

Raises:



239
240
241
242
243
 
# File 'lib/ogr/spatial_reference.rb', line 239

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

#fixup_ordering! ⇒ Object

Raises:



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

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:



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

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:



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

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