Class: Proj::Transformation

Inherits:
PjObject show all
Includes:
CoordinateOperationMixin
Defined in:
lib/proj/transformation.rb

Overview

Transformations are coordinate operations that convert coordinates from one Crs to another. In Proj they are defined as operations that exert a change in reference frame while {Conversion conversions } do not.

Class Method Summary collapse

Instance Method Summary collapse

Methods included from CoordinateOperationMixin

#accuracy, #ballpark_transformation?, #create_inverse, #forward, #grid, #grid_count, #instantiable?, #inverse, #last_used_operation, #method_auth_name, #method_code, #method_name, #normalize_for_visualization, #param, #param_count, #param_index, #roundtrip, #step, #step_count, #to_wgs84, #transform, #transform_array, #transform_bounds

Methods inherited from PjObject

#accuracy, #angular_input?, #angular_output?, #area_of_use, #auth, #auth_name, #context, #context=, create_from_database, create_from_name, create_from_wkt, #definition, #degree_input?, #degree_output?, #deprecated?, #description, #equivalent_to?, #errno, #errorno, #factors, #geod_distance, #has_inverse?, #id, #id_code, #info, #initialize_copy, #lp_distance, #lpz_distance, #name, #non_deprecated, #proj_type, #remarks, #scope, #source_crs, #target_crs, #to_json, #to_proj_string, #to_ptr, #to_s, #to_wkt, #xy_distance, #xyz_distance

Constructor Details

#initialize(source, target, context = nil, area: nil, authority: nil, accuracy: nil, allow_ballpark: nil, only_best: nil, force_over: nil) ⇒ Transformation

Transforms a Coordinate from the source Crs to the target 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.

For most geographic Crses, the units will be in degrees. For geographic CRS defined by the EPSG authority, the order of coordinates is latitude first, longitude second. When using a PROJ initialization string, on contrary, the order will be longitude first, latitude second.

For projected CRS, the units may vary (metre, us-foot, etc..).

For projected CRS defined by the EPSG authority, and with EAST / NORTH directions, the axis order might be easting first, northing second, or the reverse. When using a PROJ string, the order will be easting first, northing second, except if the +axis parameter modifies it.

Parameters:

  • source (Crs, String)

    The source Crs. See the Crs documentation for the string format

  • target (Crs, String)

    The target Crs. See the Crs documentation for the string format

  • area (Area) (defaults to: nil)

    If an area is specified a more accurate transformation between two given systems can be chosen

  • context (Context) (defaults to: nil)
  • authority (String) (defaults to: nil)

    Restricts the authority of coordinate operations looked up in the database

  • accuracy (Float) (defaults to: nil)

    Sets the minimum desired accuracy (in metres) of the candidate coordinate operations

  • allow_ballpark (Boolean) (defaults to: nil)

    Set to false to disallow the use of Ballpark transformation in the candidate coordinate operations.

  • only_best (Boolean) (defaults to: nil)

    Set to true to cause PROJ to error out if the best transformation cannot be used. Requires Proj 9.2 and higher

See Also:



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
# File 'lib/proj/transformation.rb', line 71

def initialize(source, target, context=nil,
               area: nil, authority: nil, accuracy: nil, allow_ballpark: nil, only_best: nil, force_over: nil)

  context ||= Context.current

  options = {"AUTHORITY": authority,
             "ACCURACY": accuracy.nil? ? nil : accuracy.to_s,
             "ALLOW_BALLPARK": allow_ballpark.nil? ? nil : (allow_ballpark ? "YES" : "NO"),
             "ONLY_BEST": only_best.nil? ? nil : (only_best ? "YES" : "NO"),
             "FORCE_OVER": force_over.nil? ? nil : (force_over ? "YES" : "NO")}
  options_ptr = create_options_pointer(options)

  ptr = if source.is_a?(Crs) && target.is_a?(Crs)
          if Api.method_defined?(:proj_create_crs_to_crs_from_pj)
            Api.proj_create_crs_to_crs_from_pj(context, source, target, area, options_ptr)
          else
            Api.proj_create_crs_to_crs(context, source.definition, target.definition, area)
          end
        else
          Api.proj_create_crs_to_crs(context, source, target, nil)
        end

  if ptr.null?
    Error.check_context(context)
    # If that does not raise an error then no operation was found
    raise(Error, "No operation found matching criteria")
  end

  super(ptr, context)
end

Class Method Details

.create(context, name: nil, auth_name: nil, code: nil, source_crs:, target_crs:, interpolation_crs: nil, method_name: nil, method_auth_name: nil, method_code: nil, params:, accuracy:) ⇒ Transformation

Create a Transformation

Parameters:

  • context (Context)

    Context

  • name (String) (defaults to: nil)

    Name of the transformation. Default is nil.

  • auth_name (String) (defaults to: nil)

    Transformation authority name. Default is nil.

  • code (String) (defaults to: nil)

    Transformation code. Default is nil.

  • source_crs (CoordinateSystem)

    Source CRS

  • target_crs (CoordinateSystem)

    Target CRS

  • interpolation_crs (CoordinateSystem) (defaults to: nil)

    Interpolation. Default is nil

  • method_name (String) (defaults to: nil)

    Method name. Default is nil.

  • method_auth_name (String) (defaults to: nil)

    Method authority name. Default is nil.

  • method_code (String) (defaults to: nil)

    Method code. Default is nil.

  • params (Array<Parameter>)

    Parameter descriptions

  • accuracy (Float)

    Accuracy of the transformation in meters. A negative value means unknown.

Returns:



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# File 'lib/proj/transformation.rb', line 25

def self.create(context, name: nil, auth_name: nil, code: nil,
                source_crs:, target_crs:, interpolation_crs: nil,
                method_name: nil, method_auth_name: nil, method_code: nil,
                params:, accuracy:)

  params_ptr = FFI::MemoryPointer.new(Api::PJ_PARAM_DESCRIPTION, params.size)
  params.each_with_index do |param, i|
    param_description_target = Api::PJ_PARAM_DESCRIPTION.new(params_ptr[i])
    param_description_source = param.to_description
    param_description_target.to_ptr.__copy_from__(param_description_source.to_ptr, Api::PJ_PARAM_DESCRIPTION.size)
  end

  ptr = Api.proj_create_transformation(context, name, auth_name, code,
                                       source_crs, target_crs, interpolation_crs,
                                       method_name, method_auth_name, method_code,
                                       params.count, params_ptr, accuracy)
  self.create_object(ptr, context)
end