coordconver 0.1.3 → 1.1.0

data/exe/coordconver

@@ -0,0 +1,241 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 坐标转换命令行工具
+#
+#   coordconver wgs2gcj 121.468738 31.247138    # 单点坐标系转换
+#   coordconver dms 38.65777 104.08296          # 十进制度 -> 度分秒
+#   coordconver bearing 116.397 39.909 121.474 31.230  # 两点方位角(度)
+#   coordconver dest 116.397 39.909 153 1000    # 沿方位角偏移后的坐标
+#   coordconver gk 121.47 31.24 --zone3         # 高斯-克吕格正算
+#   cat points.txt | coordconver wgs2gcj        # 批量: 每行 "lng,lat" 或 "lng lat"
+
+require "optparse"
+require "csv"
+require "json"
+
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) if File.exist?(File.join(lib, "coordconver.rb"))
+require "coordconver"
+
+CONVERSION_ALIASES = {
+  "wgs" => "wgs", "wgs84" => "wgs",
+  "gcj" => "gcj", "gcj02" => "gcj",
+  "bd" => "bd", "bd09" => "bd"
+}.freeze
+
+METHOD_MAP = {
+  %w[wgs gcj] => "wgs_gcj", %w[gcj wgs] => "gcj_wgs",
+  %w[wgs bd] => "wgs_bd", %w[bd wgs] => "bd_wgs",
+  %w[gcj bd] => "gcj_bd", %w[bd gcj] => "bd_gcj"
+}.freeze
+
+def usage_and_exit(message = nil)
+  warn message if message
+  warn "用法: coordconver <命令> [参数] (--help 查看完整帮助)"
+  exit 1
+end
+
+def parse_conversion(name)
+  match = name.to_s.match(%r{\A(wgs84|wgs|gcj02|gcj|bd09|bd)\s*(?:2|to|->|=>|_)\s*(wgs84|wgs|gcj02|gcj|bd09|bd)\z}i)
+  usage_and_exit("无法识别的转换名称: #{name}") unless match
+
+  from = CONVERSION_ALIASES[match[1].downcase]
+  to = CONVERSION_ALIASES[match[2].downcase]
+  usage_and_exit("源坐标系与目标坐标系相同") if from == to
+
+  METHOD_MAP[[from, to]]
+end
+
+def parse_coords(args)
+  coords = args.flat_map { |a| a.to_s.split(/[,\s]+/).reject(&:empty?).map(&:to_f) }
+  usage_and_exit("坐标参数不足, 需要 <lng> <lat>") if coords.size < 2
+  coords
+end
+
+def line_coords(line, csv_mode)
+  if csv_mode
+    row = CSV.parse_line(line)
+    return [] unless row
+
+    nums = row.select { |c| c && c.match?(/\A[+-]?\d+(\.\d+)?\z/) }
+    nums.map(&:to_f)
+  else
+    line.split(/[,\s]+/).reject(&:empty?).map(&:to_f)
+  end
+end
+
+options = { round: 6, csv: false }
+parser = OptionParser.new do |opts|
+  opts.banner = "coordconver #{Coordconver::VERSION} — 坐标转换命令行工具"
+
+  opts.separator ""
+  opts.separator "坐标系转换 (WGS-84 地球 / GCJ-02 火星 / BD-09 百度):"
+  opts.separator "  coordconver <转换名> <lng> <lat>   转换名如 wgs2gcj, gcj2bd, wgs84togcj02"
+
+  opts.separator ""
+  opts.separator "其他命令:"
+  opts.separator "  dms  <lng> <lat>                     十进制度转度分秒"
+  opts.separator "  dec  <度分秒> <度分秒>               度分秒转十进制度"
+  opts.separator "  dist <lng1> <lat1> <lng2> <lat2>     两点球面距离(米)"
+  opts.separator "  bearing <lng1> <lat1> <lng2> <lat2>  两点初始方位角(度, 正北为0)"
+  opts.separator "  dest <lng> <lat> <方位角> <距离米>   沿方位角偏移后的坐标"
+  opts.separator "  gk <lng> <lat>                       高斯-克吕格正算 -> [东坐标, 北坐标]"
+  opts.separator "  invgk <x> <y> --cm 中央经线          高斯-克吕格反算"
+  opts.separator "  geo <地址> --baidu|--gaode|--tencent 地址转坐标(需 API key)"
+  opts.separator "  regeo <lng> <lat> --baidu|--gaode|--tencent  坐标转地址(需 API key)"
+  opts.separator ""
+  opts.separator "批量模式: 未给坐标参数时从 stdin 读取, 每行一条 \"lng,lat\" 或 \"lng lat\""
+
+  opts.separator ""
+  opts.separator "选项:"
+  opts.on("--baidu", "geo/regeo 使用百度地图 API") { options[:provider] = "baidu" }
+  opts.on("--gaode", "geo/regeo 使用高德地图 API (默认)") { options[:provider] = "gaode" }
+  opts.on("--tencent", "geo/regeo 使用腾讯地图 API") { options[:provider] = "tencent" }
+  opts.on("--cache", "geo/regeo 启用进程内结果缓存") { options[:cache] = true }
+  opts.on("--csv", "批量输入按 CSV 行解析(自动跳过表头)") { options[:csv] = true }
+  opts.on("-j", "--json", "以 JSON 数组输出") { options[:json] = true }
+  opts.on("--geojson", "转换结果以 GeoJSON 输出") { options[:geojson] = true }
+  opts.on("-r", "--round N", Integer, "小数位数, 默认 6") { |v| options[:round] = v }
+  opts.separator ""
+  opts.separator "高斯-克吕格选项:"
+  opts.on("--cm 度", Float, "中央经线(gk 可选, invgk 必填)") { |v| options[:cm] = v }
+  opts.on("--zone3", "按 3° 带推算中央经线(默认 6° 带)") { options[:zone_width] = 3 }
+  opts.on("--zone6", "按 6° 带推算中央经线") { options[:zone_width] = 6 }
+  opts.on("--ellipsoid 名称", "cgcs2000(默认)/wgs84/krassovsky/iag75") { |v| options[:ellipsoid] = v }
+  opts.on("-h", "--help", "显示帮助") { puts opts; exit 0 }
+  opts.on("-v", "--version", "显示版本") { puts "coordconver #{Coordconver::VERSION}"; exit 0 }
+end
+
+parser.parse!(ARGV)
+
+def configure_from_env(provider)
+  Coordconver.configure do |c|
+    if provider == "baidu" && ENV["COORDCONVER_BAIDU_AK"]
+      c.baidu_map_aks = ENV["COORDCONVER_BAIDU_AK"].split(",").map(&:strip)
+    elsif provider == "gaode" && ENV["COORDCONVER_GAODE_KEY"]
+      c.gaode_map_keys = ENV["COORDCONVER_GAODE_KEY"].split(",").map(&:strip)
+    elsif provider == "tencent" && ENV["COORDCONVER_TENCENT_KEY"]
+      c.tencent_map_keys = ENV["COORDCONVER_TENCENT_KEY"].split(",").map(&:strip)
+    end
+  end
+end
+
+def emit(result, options)
+  rounded = result.map { |v| v.is_a?(Numeric) ? v.round(options[:round]) : v }
+  options[:json] ? puts(JSON.generate(rounded)) : puts(rounded.join(","))
+end
+
+def emit_features(coords_list, options)
+  features = coords_list.map do |lng, lat|
+    { "type" => "Feature",
+      "geometry" => Coordconver.to_geojson(lng, lat),
+      "properties" => {} }
+  end
+  if features.size == 1
+    puts JSON.generate(features[0])
+  else
+    puts JSON.generate({ "type" => "FeatureCollection", "features" => features })
+  end
+end
+
+command = ARGV.shift
+usage_and_exit if command.nil?
+
+begin
+  case command.downcase
+  when "dms"
+    usage_and_exit("dms 需要 <lng> <lat> 两个参数") if ARGV.size < 2
+    emit(Coordconver.degree(Float(ARGV[0]), Float(ARGV[1])), options)
+  when "dec"
+    usage_and_exit("dec 需要 <度分秒> <度分秒> 两个参数") if ARGV.size < 2
+    emit(Coordconver.undegree(ARGV[0], ARGV[1]), options)
+  when "dist"
+    usage_and_exit("dist 需要 <lng1> <lat1> <lng2> <lat2> 四个参数") if ARGV.size < 4
+    puts Coordconver.distance(Float(ARGV[0]), Float(ARGV[1]), Float(ARGV[2]), Float(ARGV[3]))
+  when "bearing"
+    usage_and_exit("bearing 需要 <lng1> <lat1> <lng2> <lat2> 四个参数") if ARGV.size < 4
+    puts Coordconver.bearing(Float(ARGV[0]), Float(ARGV[1]), Float(ARGV[2]), Float(ARGV[3])).round(2)
+  when "dest"
+    usage_and_exit("dest 需要 <lng> <lat> <方位角> <距离米> 四个参数") if ARGV.size < 4
+    result = Coordconver.destination_point(Float(ARGV[0]), Float(ARGV[1]), Float(ARGV[2]), Float(ARGV[3]))
+    emit(result, options)
+  when "gk", "invgk"
+    if command.downcase == "gk"
+      usage_and_exit("gk 需要 <lng> <lat> 两个参数") if ARGV.size < 2
+      result = Coordconver.gauss_kruger(
+        Float(ARGV[0]), Float(ARGV[1]),
+        central_meridian: options[:cm],
+        zone_width: options[:zone_width] || 6,
+        ellipsoid: options[:ellipsoid] || :cgcs2000
+      )
+      emit(result, { round: 2 })
+    else
+      usage_and_exit("invgk 需要 <x> <y> 并指定 --cm 中央经线") if ARGV.size < 2 || options[:cm].nil?
+      result = Coordconver.inverse_gauss_kruger(
+        Float(ARGV[0]), Float(ARGV[1]),
+        central_meridian: options[:cm],
+        ellipsoid: options[:ellipsoid] || :cgcs2000
+      )
+      emit(result, options)
+    end
+  when "geo"
+    provider = options[:provider] || "gaode"
+    usage_and_exit("geo 需要 <地址> 参数") if ARGV.empty?
+    configure_from_env(provider)
+    Coordconver.configure { |c| c.cache = true } if options[:cache]
+    location = {
+      "baidu" => -> { Coordconver::Baidu.geo_location(ARGV[0]) },
+      "gaode" => -> { Coordconver::Gaode.geo_location(ARGV[0]) },
+      "tencent" => -> { Coordconver::Tencent.geo_location(ARGV[0]) }
+    }[provider].call
+    if location
+      emit(location, options)
+    else
+      warn "解析失败: #{ARGV[0].inspect}"
+      exit 2
+    end
+  when "regeo"
+    provider = options[:provider] || "gaode"
+    usage_and_exit("regeo 需要 <lng> <lat> 参数") if ARGV.size < 2
+    configure_from_env(provider)
+    Coordconver.configure { |c| c.cache = true } if options[:cache]
+    address = {
+      "baidu" => -> { Coordconver::Baidu.regeo_address(Float(ARGV[0]), Float(ARGV[1])) },
+      "gaode" => -> { Coordconver::Gaode.regeo_address(Float(ARGV[0]), Float(ARGV[1])) },
+      "tencent" => -> { Coordconver::Tencent.regeo_address(Float(ARGV[0]), Float(ARGV[1])) }
+    }[provider].call
+    if address
+      puts address
+    else
+      warn "解析失败: #{ARGV[0]},#{ARGV[1]}"
+      exit 2
+    end
+  else
+    method = parse_conversion(command)
+    if ARGV.empty?
+      usage_and_exit("需要 <lng> <lat> 参数, 或通过 stdin 管道输入批量坐标") if $stdin.tty?
+
+      converted = []
+      $stdin.each_line do |line|
+        coords = line_coords(line, options[:csv])
+        next if coords.size < 2
+
+        pair = Coordconver.public_send(method, coords[0], coords[1])
+        if options[:geojson]
+          converted << pair
+        else
+          emit(pair, options)
+        end
+      end
+      emit_features(converted, options) if options[:geojson]
+    else
+      coords = parse_coords(ARGV)
+      pair = Coordconver.public_send(method, coords[0], coords[1])
+      options[:geojson] ? emit_features([pair], options) : emit(pair, options)
+    end
+  end
+rescue Coordconver::Error, ArgumentError, TypeError, CSV::MalformedCSVError => e
+  warn "错误: #{e.message}"
+  exit 2
+end

data/lib/coordconver/coordconver.rb

@@ -1,106 +1,288 @@
+# frozen_string_literal: true
+
+# 坐标系互转核心算法(纯离线计算)。
+#
+# BD-09   百度坐标系, 百度地图使用
+# GCJ-02  火星坐标系(国测局), 高德/腾讯/谷歌中国使用
+# WGS-84  地球坐标系, GPS 设备原始坐标
 module Coordconver
-	module Coordconver
-
-		def self.included(base)
-			base.extend(ClassMethods)
-		end
-
-		# 定义一些常量
-		X_PI = 3.14159265358979324 * 3000.0 / 180.0
-		PI = 3.1415926535897932384626
-		AA = 6378245.0 #a
-		EE = 0.00669342162296594323 #e
-
-		module ClassMethods
-
-			def transformlat(lng, lat)
-				ret = -100.0 + 2.0 * lng + 3.0 * lat + 0.2 * lat * lat + 0.1 * lng * lat + 0.2 * Math.sqrt((lng).abs);
-				ret += (20.0 * Math.sin(6.0 * lng * PI) + 20.0 * Math.sin(2.0 * lng * PI)) * 2.0 / 3.0;
-				ret += (20.0 * Math.sin(lat * PI) + 40.0 * Math.sin(lat / 3.0 * PI)) * 2.0 / 3.0;
-				ret += (160.0 * Math.sin(lat / 12.0 * PI) + 320 * Math.sin(lat * PI / 30.0)) * 2.0 / 3.0;
-				return ret
-			end
-
-			def transformlng(lng, lat)
-				ret = 300.0 + lng + 2.0 * lat + 0.1 * lng * lng + 0.1 * lng * lat + 0.1 * Math.sqrt((lng).abs);
-				ret += (20.0 * Math.sin(6.0 * lng * PI) + 20.0 * Math.sin(2.0 * lng * PI)) * 2.0 / 3.0;
-				ret += (20.0 * Math.sin(lng * PI) + 40.0 * Math.sin(lng / 3.0 * PI)) * 2.0 / 3.0;
-				ret += (150.0 * Math.sin(lng / 12.0 * PI) + 300.0 * Math.sin(lng / 30.0 * PI)) * 2.0 / 3.0;
-			end
-
-			# 百度坐标系 (BD-09)  -> 火星坐标系 (GCJ-02)
-			# 即 百度  ->  谷歌、高德
-			# Coordconver.bd_gcj(lng, lat)
-			def bd_gcj(lng, lat)
-				x = lng - 0.0065;
-				y = lat - 0.006;
-				z = Math.sqrt(x * x + y * y) - 0.00002 * Math.sin(y * X_PI);
-				theta = Math.atan2(y, x) - 0.000003 * Math.cos(x * X_PI);
-				gg_lng = z * Math.cos(theta);
-				gg_lat = z * Math.sin(theta);
-				return [gg_lng, gg_lat]
-			end
-
-			# 百度坐标系 (BD-09)  -> 地球坐标 (WGS-84)
-			# 即 百度  -> 地球坐标
-			# Coordconver.bd_wgs(lng, lat)
-			def bd_wgs(lng, lat)
-				loca = wgs_gcj(lng, lat)
-				gcj_bd(loca[0], loca[1])
-			end
-
-			# 火星坐标系 (GCJ02)  -> 地球坐标 (WGS-84)
-			# 即  谷歌、高德 -> 地球坐标
-			# Coordconver.gcj_wgs(lng, lat)
-			def gcj_wgs(lng, lat)
-				dlat = transformlat(lng - 105.0, lat - 35.0);
-				dlng = transformlng(lng - 105.0, lat - 35.0);
-				radlat = lat / 180.0 * PI;
-				magic = Math.sin(radlat);
-				magic = 1 - EE * magic * magic;
-				sqrtmagic = Math.sqrt(magic);
-				dlat = (dlat * 180.0) / ((AA * (1 - EE)) / (magic * sqrtmagic) * PI);
-				dlng = (dlng * 180.0) / (AA / sqrtmagic * Math.cos(radlat) * PI);
-				mglat = lat + dlat;
-				mglng = lng + dlng;
-				return [lng * 2 - mglng, lat * 2 - mglat]
-			end
-
-			# 火星坐标系 (GCJ-02) 与百度坐标系 (BD-09)
-			# 即  谷歌、高德 -> 百度
-			# Coordconver.gcj_bd(lng, lat)
-			def gcj_bd(lng, lat)
-				z = Math.sqrt(lng * lng + lat * lat) + 0.00002 * Math.sin(lat * X_PI);
-				theta = Math.atan2(lat, lng) + 0.000003 * Math.cos(lng * X_PI);
-				bd_lng = z * Math.cos(theta) + 0.0065;
-				bd_lat = z * Math.sin(theta) + 0.006;
-				return [bd_lng, bd_lat]
-			end
-
-			# 地球坐标 ( WGS-84) 与百度坐标系 (BD-09)
-			# 即  地球坐标 -> 百度
-			# Coordconver.wgs_bd(lng, lat)
-			def wgs_bd(lng, lat)
-				loca = wgs_gcj(lng, lat)
-				gcj_bd(loca[0], loca[1])
-			end
-
-			# 地球坐标 ( WGS-84) 与火星坐标系 (GCJ-02)
-			# 即  地球坐标 -> 谷歌、高德
-			# Coordconver.wgs_gcj(lng, lat)
-			def wgs_gcj(lng, lat)
-				dlat = transformlat(lng - 105.0, lat - 35.0);
-				dlng = transformlng(lng - 105.0, lat - 35.0);
-				radlat = lat / 180.0 * PI;
-				magic = Math.sin(radlat);
-				magic = 1 - EE * magic * magic;
-				sqrtmagic = Math.sqrt(magic);
-				dlat = (dlat * 180.0) / ((AA * (1 - EE)) / (magic * sqrtmagic) * PI);
-				dlng = (dlng * 180.0) / (AA / sqrtmagic * Math.cos(radlat) * PI);
-				mglat = lat + dlat;
-				mglng = lng + dlng;
-				return [mglng, mglat]
-			end
-		end
-	end
+  X_PI = 3.14159265358979324 * 3000.0 / 180.0
+  PI = 3.1415926535897932384626
+  # 克拉索夫斯基椭球参数(GCJ-02 偏移算法使用)
+  SEMI_MAJOR_AXIS = 6378245.0
+  ECCENTRICITY_SQUARED = 0.00669342162296594323
+  # 平均地球半径(米), 球面距离/方位角计算使用
+  EARTH_RADIUS = 6_371_008.8
+  # 精确逆变换迭代次数
+  PRECISE_ITERATIONS = 5
+  # 中国区域大致边界。GCJ-02 加密仅在中国境内生效, 境外 WGS-84 与 GCJ-02 一致
+  CHINA_LNG_RANGE = [72.004, 137.8347].freeze
+  CHINA_LAT_RANGE = [0.8293, 55.8271].freeze
+
+  # 轻量坐标点结构, 可直接传给转换方法:
+  #   Coordconver.wgs_gcj(Coordconver.point(121.47, 31.25))
+  Point = Struct.new(:lng, :lat, keyword_init: true) do
+    def to_a
+      [lng, lat]
+    end
+
+    def to_h
+      { lng: lng, lat: lat }
+    end
+  end
+
+  class << self
+    # 构造 Point 结构
+    def point(lng, lat)
+      Point.new(lng: lng.to_f, lat: lat.to_f)
+    end
+
+    # 判断坐标是否在中国境外
+    # Coordconver.out_of_china?(121.47, 31.25) # => false
+    def out_of_china?(lng, lat)
+      lng < CHINA_LNG_RANGE[0] || lng > CHINA_LNG_RANGE[1] ||
+        lat < CHINA_LAT_RANGE[0] || lat > CHINA_LAT_RANGE[1]
+    end
+
+    # ---------- 坐标系转换 ----------
+    # 所有方法支持三种入参: (lng, lat) 双参 / Point / [lng, lat] / {lng:, lat:}
+    # 并支持 as: :hash 返回 {lng:, lat:}, as: :point 返回 Point, 默认 [lng, lat]
+
+    # 百度坐标系 (BD-09) -> 火星坐标系 (GCJ-02)
+    # 即 百度 -> 谷歌、高德、腾讯
+    # Coordconver.bd_gcj(121.47981626441, 31.251161076123) # => [121.47328, 31.24522]
+    def bd_gcj(lng, lat = nil, as: nil)
+      a, b = extract_pair(lng, lat)
+      x = a - 0.0065
+      y = b - 0.006
+      z = Math.sqrt(x * x + y * y) - 0.00002 * Math.sin(y * X_PI)
+      theta = Math.atan2(y, x) - 0.000003 * Math.cos(x * X_PI)
+      fmt([z * Math.cos(theta), z * Math.sin(theta)], as)
+    end
+
+    # 百度坐标系 (BD-09) -> 地球坐标 (WGS-84)
+    # 即 百度 -> 地球坐标 (近似, 误差米级)
+    def bd_wgs(lng, lat = nil, as: nil)
+      a, b = extract_pair(lng, lat)
+      fmt(gcj_wgs_raw(*bd_gcj_raw(a, b)), as)
+    end
+
+    # 百度坐标系 (BD-09) -> 地球坐标 (WGS-84), 迭代精确解, 厘米级
+    def bd_wgs_precise(lng, lat = nil, as: nil)
+      a, b = extract_pair(lng, lat)
+      fmt(gcj_wgs_iterate(*bd_gcj_raw(a, b)), as)
+    end
+
+    # 火星坐标系 (GCJ-02) -> 地球坐标 (WGS-84)
+    # 即 谷歌、高德、腾讯 -> 地球坐标。境外坐标原样返回。(近似, 误差米级)
+    def gcj_wgs(lng, lat = nil, as: nil)
+      a, b = extract_pair(lng, lat)
+      fmt(gcj_wgs_raw(a, b), as)
+    end
+
+    # 火星坐标系 (GCJ-02) -> 地球坐标 (WGS-84), 迭代精确解, 厘米级
+    # Coordconver.gcj_wgs_precise(*Coordconver.wgs_gcj(121.47, 31.24)) # => [121.47, 31.24]
+    def gcj_wgs_precise(lng, lat = nil, as: nil)
+      a, b = extract_pair(lng, lat)
+      fmt(gcj_wgs_iterate(a, b), as)
+    end
+
+    # 火星坐标系 (GCJ-02) -> 百度坐标系 (BD-09)
+    # 即 谷歌、高德、腾讯 -> 百度
+    def gcj_bd(lng, lat = nil, as: nil)
+      a, b = extract_pair(lng, lat)
+      z = Math.sqrt(a * a + b * b) + 0.00002 * Math.sin(b * X_PI)
+      theta = Math.atan2(b, a) + 0.000003 * Math.cos(a * X_PI)
+      fmt([z * Math.cos(theta) + 0.0065, z * Math.sin(theta) + 0.006], as)
+    end
+
+    # 地球坐标 (WGS-84) -> 百度坐标系 (BD-09)
+    # 即 地球坐标 -> 百度
+    def wgs_bd(lng, lat = nil, as: nil)
+      a, b = extract_pair(lng, lat)
+      fmt(gcj_bd_raw(*wgs_gcj_raw(a, b)), as)
+    end
+
+    # 地球坐标 (WGS-84) -> 火星坐标系 (GCJ-02)
+    # 即 地球坐标 -> 谷歌、高德、腾讯。境外坐标原样返回
+    def wgs_gcj(lng, lat = nil, as: nil)
+      a, b = extract_pair(lng, lat)
+      fmt(wgs_gcj_raw(a, b), as)
+    end
+
+    # ---------- 批量转换 ----------
+    # 支持数组/Point/Hash 混合输入:
+    #   Coordconver.transform([[121.46, 31.24], {lng: 116.39, lat: 39.90}], from: :wgs84, to: :gcj02)
+    # from/to 支持 :wgs84(wgs) :gcj02(gcj) :bd09(bd)
+    def transform(points, from:, to:, as: nil)
+      method = transform_method(from, to)
+      points.map do |pt|
+        a, b = extract_pair(pt)
+        fmt(public_send(method, a, b), as)
+      end
+    end
+
+    # ---------- 球面几何 ----------
+
+    # 两点球面距离(Haversine 公式), 返回米。两点需在同一坐标系下。
+    # Coordconver.distance(116.397428, 39.90923, 121.473701, 31.230416) # => 约 106.8 万米
+    def distance(lng1, lat1, lng2, lat2)
+      dlng = to_radian(lng2 - lng1)
+      dlat = to_radian(lat2 - lat1)
+      a = Math.sin(dlat / 2)**2 +
+          Math.cos(to_radian(lat1)) * Math.cos(to_radian(lat2)) * Math.sin(dlng / 2)**2
+      (2 * EARTH_RADIUS * Math.asin(Math.sqrt(a))).round(1)
+    end
+
+    # 起点到终点的初始方位角(以正北为 0°, 顺时针 0-360°)
+    # Coordconver.bearing(116.397428, 39.90923, 121.473701, 31.230416) # => 约 137.5
+    def bearing(lng1, lat1, lng2, lat2)
+      p1 = to_radian(lat1)
+      p2 = to_radian(lat2)
+      dl = to_radian(lng2 - lng1)
+      y = Math.sin(dl) * Math.cos(p2)
+      x = Math.cos(p1) * Math.sin(p2) - Math.sin(p1) * Math.cos(p2) * Math.cos(dl)
+      ((Math.atan2(y, x) * 180.0 / PI) + 360) % 360
+    end
+
+    # 从起点沿方位角移动指定距离(米)后的坐标
+    # Coordconver.destination_point(116.397428, 39.90923, 137.5, 1_068_000)
+    def destination_point(lng, lat, bearing_deg, distance_m, as: nil)
+      d = distance_m.to_f / EARTH_RADIUS
+      p1 = to_radian(lat)
+      b = to_radian(bearing_deg)
+      p2 = Math.asin(Math.sin(p1) * Math.cos(d) + Math.cos(p1) * Math.sin(d) * Math.cos(b))
+      l2 = to_radian(lng) + Math.atan2(
+        Math.sin(b) * Math.sin(d) * Math.cos(p1),
+        Math.cos(d) - Math.sin(p1) * Math.sin(p2)
+      )
+      lon = ((l2 * 180.0 / PI) + 540) % 360 - 180
+      fmt([lon, p2 * 180.0 / PI], as)
+    end
+
+    # ---------- 兼容旧式/语义化别名 ----------
+    alias wgs84_gcj02 wgs_gcj
+    alias gcj02_wgs84 gcj_wgs
+    alias gcj02_bd09 gcj_bd
+    alias bd09_gcj02 bd_gcj
+    alias wgs84_bd09 wgs_bd
+    alias bd09_wgs84 bd_wgs
+    alias gcj02_wgs84_precise gcj_wgs_precise
+    alias bd09_wgs84_precise bd_wgs_precise
+
+    # 归一化坐标入参: 支持 (lng, lat) 双参 / Point / [lng, lat] / {lng:, lat:}
+    def extract_pair(lng, lat = nil)
+      return [lng.to_f, lat.to_f] unless lat.nil?
+
+      case lng
+      when Point then [lng.lng.to_f, lng.lat.to_f]
+      when Hash
+        [float_of(lng[:lng] || lng["lng"]), float_of(lng[:lat] || lng["lat"])]
+      when Array then [float_of(lng[0]), float_of(lng[1])]
+      else raise ArgumentError, "无法解析的坐标: #{lng.inspect} (支持 (lng, lat) / Point / [lng, lat] / {lng:, lat:})"
+      end
+    end
+
+    private
+
+    def float_of(v)
+      raise ArgumentError, "坐标值无效: #{v.inspect}" if v.nil?
+
+      Float(v)
+    end
+
+    def fmt(pair, as)
+      case as
+      when nil then pair
+      when :hash then { lng: pair[0], lat: pair[1] }
+      when :point then Point.new(lng: pair[0], lat: pair[1])
+      else raise ArgumentError, "未知的返回格式: #{as.inspect} (支持 :hash / :point)"
+      end
+    end
+
+    def transform_method(from, to)
+      norm = ->(s) { s.to_s.downcase.gsub(/(84|02|09)\z/, "") }
+      map = {
+        %w[wgs gcj] => :wgs_gcj, %w[gcj wgs] => :gcj_wgs,
+        %w[wgs bd] => :wgs_bd, %w[bd wgs] => :bd_wgs,
+        %w[gcj bd] => :gcj_bd, %w[bd gcj] => :bd_gcj
+      }
+      m = map[[norm.call(from), norm.call(to)]]
+      raise ArgumentError, "不支持的转换: #{from} -> #{to}" unless m
+
+      m
+    end
+
+    def to_radian(deg)
+      deg * PI / 180.0
+    end
+
+    # gcj_wgs 迭代精确解: 解方程 wgs_gcj(w) = g
+    def gcj_wgs_iterate(lng, lat)
+      w = [lng, lat]
+      PRECISE_ITERATIONS.times do
+        cur = wgs_gcj_raw(w[0], w[1])
+        w = [w[0] + (lng - cur[0]), w[1] + (lat - cur[1])]
+      end
+      w
+    end
+
+    def gcj_wgs_raw(lng, lat)
+      return [lng, lat] if out_of_china?(lng, lat)
+
+      dlat = transformlat(lng - 105.0, lat - 35.0)
+      dlng = transformlng(lng - 105.0, lat - 35.0)
+      radlat = lat / 180.0 * PI
+      magic = 1 - ECCENTRICITY_SQUARED * Math.sin(radlat) * Math.sin(radlat)
+      sqrtmagic = Math.sqrt(magic)
+      dlat = (dlat * 180.0) / ((SEMI_MAJOR_AXIS * (1 - ECCENTRICITY_SQUARED)) / (magic * sqrtmagic) * PI)
+      dlng = (dlng * 180.0) / (SEMI_MAJOR_AXIS / sqrtmagic * Math.cos(radlat) * PI)
+      mglat = lat + dlat
+      mglng = lng + dlng
+      [lng * 2 - mglng, lat * 2 - mglat]
+    end
+
+    def wgs_gcj_raw(lng, lat)
+      return [lng, lat] if out_of_china?(lng, lat)
+
+      dlat = transformlat(lng - 105.0, lat - 35.0)
+      dlng = transformlng(lng - 105.0, lat - 35.0)
+      radlat = lat / 180.0 * PI
+      magic = 1 - ECCENTRICITY_SQUARED * Math.sin(radlat) * Math.sin(radlat)
+      sqrtmagic = Math.sqrt(magic)
+      dlat = (dlat * 180.0) / ((SEMI_MAJOR_AXIS * (1 - ECCENTRICITY_SQUARED)) / (magic * sqrtmagic) * PI)
+      dlng = (dlng * 180.0) / (SEMI_MAJOR_AXIS / sqrtmagic * Math.cos(radlat) * PI)
+      [lng + dlng, lat + dlat]
+    end
+
+    def gcj_bd_raw(lng, lat)
+      z = Math.sqrt(lng * lng + lat * lat) + 0.00002 * Math.sin(lat * X_PI)
+      theta = Math.atan2(lat, lng) + 0.000003 * Math.cos(lng * X_PI)
+      [z * Math.cos(theta) + 0.0065, z * Math.sin(theta) + 0.006]
+    end
+
+    def bd_gcj_raw(lng, lat)
+      x = lng - 0.0065
+      y = lat - 0.006
+      z = Math.sqrt(x * x + y * y) - 0.00002 * Math.sin(y * X_PI)
+      theta = Math.atan2(y, x) - 0.000003 * Math.cos(x * X_PI)
+      [z * Math.cos(theta), z * Math.sin(theta)]
+    end
+
+    def transformlat(lng, lat)
+      ret = -100.0 + 2.0 * lng + 3.0 * lat + 0.2 * lat * lat + 0.1 * lng * lat + 0.2 * Math.sqrt(lng.abs)
+      ret += (20.0 * Math.sin(6.0 * lng * PI) + 20.0 * Math.sin(2.0 * lng * PI)) * 2.0 / 3.0
+      ret += (20.0 * Math.sin(lat * PI) + 40.0 * Math.sin(lat / 3.0 * PI)) * 2.0 / 3.0
+      ret += (160.0 * Math.sin(lat / 12.0 * PI) + 320 * Math.sin(lat * PI / 30.0)) * 2.0 / 3.0
+      ret
+    end
+
+    def transformlng(lng, lat)
+      ret = 300.0 + lng + 2.0 * lat + 0.1 * lng * lng + 0.1 * lng * lat + 0.1 * Math.sqrt(lng.abs)
+      ret += (20.0 * Math.sin(6.0 * lng * PI) + 20.0 * Math.sin(2.0 * lng * PI)) * 2.0 / 3.0
+      ret += (20.0 * Math.sin(lng * PI) + 40.0 * Math.sin(lng / 3.0 * PI)) * 2.0 / 3.0
+      ret += (150.0 * Math.sin(lng / 12.0 * PI) + 300.0 * Math.sin(lng / 30.0 * PI)) * 2.0 / 3.0
+      ret
+    end
+  end
 end