Module: Proj::CoordinateOperationMixin

Included in:
Conversion, Transformation
Defined in:
lib/proj/coordinate_operation_mixin.rb

Overview

Coordinate Operations convert coordinates to a new value. In Proj they are can either by conversions that do not exert a change in reference frame or transformations which do.

Instance Method Summary collapse

Instance Method Details

#accuracy ⇒ Float

Returns the accuracy (in meters) of a coordinate operation.

Returns:

  • (Float) —

    The accuracy, or a negative value if unknown or in case of error.

See Also:



371
372
373
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 371

def accuracy
  Api.proj_coordoperation_get_accuracy(self.context, self)
end

#angular_input?(direction) ⇒ Boolean

Returns if an operation expects input in radians

Parameters:

  • direction (PjDirection) —

    Direction of transformation

Returns:

  • (Boolean)

See Also:



18
19
20
21
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 18

def angular_input?(direction)
  result = Api.proj_angular_input(self, direction)
  result == 1 ? true : false
end

#angular_output?(direction) ⇒ Boolean

Check if an operation returns output in radians

Parameters:

  • direction (PjDirection) —

    Direction of transformation

Returns:

  • (Boolean)

See Also:



28
29
30
31
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 28

def angular_output?(direction)
  result = Api.proj_angular_output(self, direction)
  result == 1 ? true : false
end

#ballpark_transformation? ⇒ Boolean

Return whether a coordinate operation has a “ballpark” transformation

Returns:

  • (Boolean)

See Also:



351
352
353
354
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 351

def ballpark_transformation?
  result = Api.proj_coordoperation_has_ballpark_transformation(self.context, self)
  result == 1 ? true : false
end

#create_inverse ⇒ Conversion, Transformation

Returns a coordinate operation that represents the inverse operation of this operation

Returns:



66
67
68
69
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 66

def create_inverse
  ptr = Api.proj_coordoperation_create_inverse(self.context, self)
  self.class.create_object(ptr, self.context)
end

#degree_input?(direction) ⇒ Boolean

Returns if an operation expects input in degrees

Parameters:

  • direction (PjDirection) —

    Direction of transformation

Returns:

  • (Boolean)

See Also:



38
39
40
41
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 38

def degree_input?(direction)
  result = Api.proj_degree_input(self, direction)
  result == 1 ? true : false
end

#degree_output?(direction) ⇒ Boolean

Check if an operation returns output in degrees

Parameters:

  • direction (PjDirection) —

    Direction of transformation

Returns:

  • (Boolean)

See Also:



48
49
50
51
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 48

def degree_output?(direction)
  result = Api.proj_degree_output(self, direction)
  result == 1 ? true : false
end

#forward(coord) ⇒ Coordinate

Transforms a Proj::Coordinate from the source Proj::Crs to the target Proj::Crs. Coordinates should be expressed in the units and axis order of the definition of the source CRS. The returned transformed coordinate will be in the units and axis order of the definition of the target CRS.

Parameters:

Returns:

See Also:



194
195
196
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 194

def forward(coord)
  self.transform(coord, :PJ_FWD)
end

#grid(index) ⇒ Integer

Returns information about a Grid

Parameters:

  • index (Integer) —

    Grid index

Returns:

  • (Integer)

See Also:



391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 391

def grid(index)
  out_short_name = FFI::MemoryPointer.new(:string)
  out_full_name = FFI::MemoryPointer.new(:string)
  out_package_name = FFI::MemoryPointer.new(:string)
  out_url = FFI::MemoryPointer.new(:string)
  out_direct_download  = FFI::MemoryPointer.new(:int)
  out_open_license = FFI::MemoryPointer.new(:int)
  out_available = FFI::MemoryPointer.new(:int)

  result = Api.proj_coordoperation_get_grid_used(self.context, self, index,
                                                 out_short_name, out_full_name, out_package_name,
                                                 out_url, out_direct_download ,
                                                 out_open_license, out_available)

  if result != 1
    Error.check_object(self)
  end

  name_ptr = out_short_name.read_pointer
  full_name_ptr = out_full_name.read_pointer
  package_name_ptr = out_package_name.read_pointer
  url_ptr = out_url.read_pointer
  downloadable_ptr = out_direct_download 
  open_license_ptr = out_open_license
  available_ptr = out_available

  unless name_ptr.null?
    Grid.new(name_ptr.read_string_to_null, self.context,
             full_name: full_name_ptr.null? ? nil : full_name_ptr.read_string_to_null,
             package_name: package_name_ptr.null? ? nil : package_name_ptr.read_string_to_null,
             url: url_ptr.null? ? nil : url_ptr.read_string_to_null,
             downloadable: downloadable_ptr.null? ? nil : downloadable_ptr.read_int == 1 ? true : false,
             open_license: open_license_ptr.null? ? nil : open_license_ptr.read_int == 1 ? true : false,
             available: available_ptr.null? ? nil : available_ptr.read_int == 1 ? true : false)
  end
end

#grid_count ⇒ Integer

Returns the number of grids used by a CoordinateOperation

Returns:

  • (Integer)

See Also:



380
381
382
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 380

def grid_count
  Api.proj_coordoperation_get_grid_used_count(self.context, self)
end

#instantiable? ⇒ Boolean

Return whether a coordinate operation can be instantiated as a PROJ pipeline, checking in particular that referenced grids are available.

Returns:

  • (Boolean)

See Also:



58
59
60
61
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 58

def instantiable?
  result = Api.proj_coordoperation_is_instantiable(self.context, self)
  result == 1 ? true : false
end

#inverse(coord) ⇒ Coordinate

Transforms a Proj::Coordinate from the target Proj::Crs to the source Proj::Crs. Coordinates should be expressed in the units and axis order of the definition of the source CRS. The returned transformed coordinate will be in the units and axis order of the definition of the target CRS.

Parameters:

Returns:

See Also:



207
208
209
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 207

def inverse(coord)
  self.transform(coord, :PJ_INV)
end

#last_used_operation ⇒ CoordinateOperationMixin

Return the operation used during the last invocation of Transformation#forward or Transformation#inverse

Returns:

See Also:



341
342
343
344
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 341

def last_used_operation
  ptr = Api.proj_trans_get_last_used_operation(self)
  self.class.create_object(ptr, self.context)
end

#method_auth_name ⇒ String

Returns the operation authority name

Returns:

  • (String)

See Also:



102
103
104
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 102

def method_auth_name
  method_info[:method_auth_name]
end

#method_code ⇒ String

Returns the operation code

Returns:

  • (String)

See Also:



111
112
113
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 111

def method_code
  method_info[:method_code]
end

#method_name ⇒ String

Returns the operation name

Returns:

  • (String)

See Also:



93
94
95
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 93

def method_name
  method_info[:method_name]
end

#normalize_for_visualization ⇒ CoordinateOperationMixin

Returns a new PJ object whose axis order is the one expected for visualization purposes

Returns:

See Also:



331
332
333
334
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 331

def normalize_for_visualization
  ptr = Api.proj_normalize_for_visualization(self.context, self)
  self.class.create_object(ptr, self.context)
end

#param(index) ⇒ Param

Returns a parameter of a SingleOperation

Parameters:

  • index (Integer) —

    Parameter index

Returns:

See Also:



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
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 142

def param(index)
  out_name = FFI::MemoryPointer.new(:string)
  out_auth_name = FFI::MemoryPointer.new(:string)
  out_code = FFI::MemoryPointer.new(:string)
  out_value = FFI::MemoryPointer.new(:double)
  out_value_string = FFI::MemoryPointer.new(:string)
  out_unit_conv_factor = FFI::MemoryPointer.new(:double)
  out_unit_name = FFI::MemoryPointer.new(:string)
  out_unit_auth_name = FFI::MemoryPointer.new(:string)
  out_unit_code = FFI::MemoryPointer.new(:string)
  out_unit_category = FFI::MemoryPointer.new(:string)

  result = Api.proj_coordoperation_get_param(self.context, self, index,
                                             out_name, out_auth_name, out_code,
                                             out_value, out_value_string,
                                             out_unit_conv_factor,
                                             out_unit_name, out_unit_auth_name,out_unit_code,
                                             out_unit_category)
  if result != 1
    Error.check_object(self)
  end

  name_ptr = out_name.read_pointer
  auth_name_ptr = out_auth_name.read_pointer
  code_ptr = out_code.read_pointer
  value_string_ptr = out_value_string.read_pointer
  unit_name_ptr = out_unit_name.read_pointer
  unit_auth_name_ptr = out_unit_auth_name.read_pointer
  unit_code_ptr = out_unit_code.read_pointer
  unit_category_ptr = out_unit_category.read_pointer

  Param.new(name: name_ptr.null? ? nil : name_ptr.read_string_to_null,
            auth_name: auth_name_ptr.null? ? nil : auth_name_ptr.read_string_to_null,
            code: code_ptr.null? ? nil : code_ptr.read_string_to_null,
            value: out_value.null? ? nil : out_value.read_double,
            value_string: value_string_ptr.null? ? nil : value_string_ptr.read_string_to_null,
            unit_conv_factor: out_unit_conv_factor.null? ? nil : out_unit_conv_factor.read_double,
            unit_name: unit_name_ptr.null? ? nil : unit_name_ptr.read_string_to_null,
            unit_auth_name: unit_auth_name_ptr.null? ? nil : unit_auth_name_ptr.read_string_to_null,
            unit_code: unit_code_ptr.null? ? nil : unit_code_ptr.read_string_to_null,
            unit_category: unit_category_ptr.null? ? nil : unit_category_ptr.read_string_to_null)
end

#param_count ⇒ Integer

Returns the number of parameters of a SingleOperation

Returns:

  • (Integer)

See Also:



120
121
122
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 120

def param_count
  Api.proj_coordoperation_get_param_count(self.context, self)
end

#param_index(name) ⇒ Integer

Returns the index of a parameter of a SingleOperation

Parameters:

  • name (String) —

    Name of the parameter. Must not be nil

Returns:

  • (Integer) —

    Index of the parameter or -1 in case of error.

See Also:



131
132
133
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 131

def param_index(name)
  Api.proj_coordoperation_get_param_index(self.context, self, name)
end

#requires_per_coordinate_input_time? ⇒ Boolean

Return whether a coordinate operation requires time as an input for each coordinate.

Returns:

  • (Boolean)

See Also:



361
362
363
364
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 361

def requires_per_coordinate_input_time?
  result = Api.proj_coordoperation_requires_per_coordinate_input_time(self.context, self)
  result == 1 ? true : false
end

#roundtrip(direction, iterations, coordinate) ⇒ Float

Measure the internal consistency of a given transformation. The function performs n round trip transformations starting in either the forward or reverse direction.

Parameters:

  • direction (PjDirection) —

    The starting direction of transformation

  • iterations (Integer) —

    The number of roundtrip transformations

  • coordinate (Coordinate) —

    The input coordinate

Returns:

  • (Float) —

    The euclidean distance of the starting point coordinate and the last coordinate after n iterations back and forth.

See Also:



322
323
324
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 322

def roundtrip(direction, iterations, coordinate)
  Api.proj_roundtrip(self, direction, iterations, coordinate.pj_coord)
end

#step(index) ⇒ PjObject

Returns a step of a concatenated operation

Parameters:

  • index (Integer) —

    Index of the step

Returns:

See Also:



459
460
461
462
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 459

def step(index)
  ptr = Api.proj_concatoperation_get_step(self.context, self, index)
  self.class.create_object(ptr, self.context)
end

#step_count ⇒ Integer

Returns the number of steps in a concatenated operation

Returns:

  • (Integer) —

    The number of steps

See Also:



448
449
450
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 448

def step_count
  Api.proj_concatoperation_get_step_count(self.context, self)
end

#to_wgs84(error_if_incompatible = false) ⇒ Array<Float>

Return the parameters of a Helmert transformation as WKT1 TOWGS84 values

Parameters:

  • error_if_incompatible (Boolean) (defaults to: false) —

    If true an exception is thrown if the coordinate operation is not compatible with a WKT1 TOWGS84 representation

Returns:

  • (Array<Float>) —

    ] Array of 7 numbers that represent translation, rotation and scale parameters. Rotation and scale difference terms might be zero if the transformation only includes translation parameters

See Also:



436
437
438
439
440
441
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 436

def to_wgs84(error_if_incompatible = false)
  parameter_count = 7
  out_values = FFI::MemoryPointer.new(:double, parameter_count)
  Api.proj_coordoperation_get_towgs84_values(self.context, self, out_values, parameter_count, error_if_incompatible ? 1 : 0)
  out_values.read_array_of_double(parameter_count)
end

#transform(coord, direction) ⇒ Coordinate

Transforms a Proj::Coordinate in the specified direction. See forward and inverse

Parameters:

  • direction (PjDirection) —

    Direction of transformation (:PJ_FWD or :PJ_INV)

  • coord (Coordinate)

Returns:

See Also:



220
221
222
223
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 220

def transform(coord, direction)
  struct = Api.proj_trans(self, direction, coord)
  Coordinate.from_coord(struct)
end

#transform_array(coordinates, direction) ⇒ Array<Coordinate>

Transforms an array of coordinates. Individual points that fail to transform will have their components set to Infinity.

Parameters:

  • coordinates (Array<Coordinate>) —

    Coordinates to transform

  • direction (PjDirection) —

    The direction of the transformation

Returns:

  • (Array<Coordinate>) —

    Array of transformed coordinates



292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 292

def transform_array(coordinates, direction)
  coords_ptr = FFI::MemoryPointer.new(Api::PjCoord, coordinates.size)
  coordinates.each_with_index do |coordinate, i|
    pj_coord = Api::PjCoord.new(coords_ptr[i])
    pj_coord.to_ptr.__copy_from__(coordinate.to_ptr, Api::PjCoord.size)
  end

  int = Api.proj_trans_array(self, direction, coordinates.size, coords_ptr)
  unless int == 0
    Error.check_object(self)
  end

  result = Array.new(coordinates.size)
  coordinates.size.times do |i|
    pj_coord = Api::PjCoord.new(coords_ptr[i])
    result[i] = Coordinate.from_coord(pj_coord)
  end
  result
end

#transform_bounds(bounds, direction, densify_points = 21) ⇒ Bounds

Transform boundary densifying the edges to account for nonlinear transformations along these edges and extracting the outermost bounds.

Parameters:

  • bounds (Bounds) —

    Bounding box in source CRS (target CRS if direction is inverse).

  • direction (PjDirection) —

    The direction of the transformation.

  • densify_points (Integer) (defaults to: 21) —

    Recommended to use 21. This is the number of points to use to densify the bounding polygon in the transformation.

Returns:

  • (Bounds) —

    Bounding box in target CRS (target CRS if direction is inverse).

See Also:



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 235

def transform_bounds(bounds, direction, densify_points = 21)
  out_xmin = FFI::MemoryPointer.new(:double)
  out_ymin = FFI::MemoryPointer.new(:double)
  out_xmax = FFI::MemoryPointer.new(:double)
  out_ymax = FFI::MemoryPointer.new(:double)

  result = Api.proj_trans_bounds(self.context, self, direction,
                                 bounds.xmin, bounds.ymin, bounds.xmax, bounds.ymax,
                                 out_xmin, out_ymin, out_xmax, out_ymax, densify_points)

  unless result == 0
    Error.check_object(self)
  end

  Bounds.new(out_xmin.read_double, out_ymin.read_double, out_xmax.read_double, out_ymax.read_double)
end

#transform_bounds_3d(bounds, direction, densify_points = 21) ⇒ Bounds3d

Transform 3D boundary densifying the edges to account for nonlinear transformations and extracting the outermost bounds.

Parameters:

  • bounds (Bounds3d) —

    Bounding box in source CRS (target CRS if direction is inverse).

  • direction (PjDirection) —

    The direction of the transformation.

  • densify_points (Integer) (defaults to: 21) —

    Number of points to use to densify the bounding polygon in the transformation.

Returns:

  • (Bounds3d) —

    Bounding box in target CRS (target CRS if direction is inverse).

See Also:



262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/proj/coordinate_operation_mixin.rb', line 262

def transform_bounds_3d(bounds, direction, densify_points = 21)
  out_xmin = FFI::MemoryPointer.new(:double)
  out_ymin = FFI::MemoryPointer.new(:double)
  out_zmin = FFI::MemoryPointer.new(:double)
  out_xmax = FFI::MemoryPointer.new(:double)
  out_ymax = FFI::MemoryPointer.new(:double)
  out_zmax = FFI::MemoryPointer.new(:double)

  result = Api.proj_trans_bounds_3d(self.context, self, direction,
                                    bounds.xmin, bounds.ymin, bounds.zmin,
                                    bounds.xmax, bounds.ymax, bounds.zmax,
                                    out_xmin, out_ymin, out_zmin,
                                    out_xmax, out_ymax, out_zmax,
                                    densify_points)

  unless result == 0
    Error.check_object(self)
  end

  Bounds3d.new(out_xmin.read_double, out_ymin.read_double, out_zmin.read_double,
               out_xmax.read_double, out_ymax.read_double, out_zmax.read_double)
end