coordconver 0.1.3 → 1.1.0

data/lib/coordconver/geo/key_pool.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Coordconver
+  module Geo
+    # 多 key 智能轮询: round-robin 取 key, 请求失败(配额超限/无效)时摘除该 key,
+    # 冷却时间过后自动恢复。线程安全。
+    class KeyPool
+      # 被摘除 key 的冷却时长(秒), 覆盖"每秒/每日配额超限"两类场景
+      COOLDOWN = 300
+
+      def initialize
+        @mutex = Mutex.new
+        @index = {}
+        @disabled_at = {}
+      end
+
+      # 轮询取下一个可用 key; 全部处于冷却期时抛出 ApiError
+      def next_key(provider, keys)
+        @mutex.synchronize do
+          purge_expired(Time.now)
+          enabled = keys.reject { |k| @disabled_at[[provider, k]] }
+          if enabled.empty?
+            raise ApiError, "所有 #{provider} key 均不可用(配额超限或无效), 请更换或补充 key"
+          end
+
+          @index[provider] = (@index[provider] ||= -1) + 1
+          enabled[@index[provider] % enabled.size]
+        end
+      end
+
+      def mark_bad(provider, key)
+        @mutex.synchronize { @disabled_at[[provider, key]] = Time.now }
+      end
+
+      def disabled?(provider, key)
+        @mutex.synchronize do
+          purge_expired(Time.now)
+          !@disabled_at[[provider, key]].nil?
+        end
+      end
+
+      def reset!
+        @mutex.synchronize do
+          @index.clear
+          @disabled_at.clear
+        end
+      end
+
+      private
+
+      def purge_expired(now)
+        @disabled_at.reject! { |_, t| now - t > COOLDOWN }
+      end
+
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        def next_key(provider, keys)
+          instance.next_key(provider, keys)
+        end
+
+        def mark_bad(provider, key)
+          instance.mark_bad(provider, key)
+        end
+
+        def disabled?(provider, key)
+          instance.disabled?(provider, key)
+        end
+
+        def reset!
+          instance.reset!
+        end
+      end
+    end
+  end
+end

data/lib/coordconver/geo/tencent.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Coordconver
+  module Geo
+    # 腾讯位置服务 WebService API
+    # 申请 key: https://lbs.qq.com/dev/console/application/mine (启用 WebServiceAPI)
+    # 坐标为 GCJ-02; 逆地理编码 location 参数为 "lat,lng" 顺序
+    module Tencent
+      extend self
+
+      # 视为"key 无效/配额超限"的状态码, 触发自动轮换下一个 key
+      # 110 请求来源未被授权 112 IP未被授权 120 每秒调用量超限 121 日调用量超限 199 key结构错误
+      KEY_ERROR_STATUSES = [110, 112, 120, 121, 199].freeze
+
+      # 地理编码: 结构化地址 -> 坐标 (GCJ-02)
+      # Coordconver::Tencent.geo("北京市海淀区彩和坊路海淀西大街74号")["result"]["location"]
+      # 支持可选参数: region(城市), get_poi, ...
+      def geo(address, options = {})
+        params = { address: address }.merge(options)
+        request("/geocoder/v1/", params)
+      end
+
+      # 逆地理编码: 坐标 (GCJ-02) -> 结构化地址
+      # Coordconver::Tencent.regeo(116.322987, 39.983424)["result"]["address"]
+      def regeo(lng, lat, options = {})
+        params = {
+          location: "#{lat},#{lng}", # 腾讯接口为 lat,lng 顺序
+          get_poi: 0
+        }.merge(options)
+        request("/geocoder/v1/", params)
+      end
+
+      # IP 定位: IP -> 城市 + 坐标 (GCJ-02)
+      def ip(ip = nil)
+        params = {}
+        params[:ip] = ip unless ip.nil? || ip.empty?
+        request("/location/v1/ip", params)
+      end
+
+      # 便捷方法: 地址 -> [lng, lat] (GCJ-02), 解析失败返回 nil
+      def geo_location(address, options = {})
+        loc = geo(address, options).dig("result", "location")
+        loc && [loc["lng"], loc["lat"]]
+      end
+
+      # 便捷方法: 坐标 -> 地址字符串 (GCJ-02), 解析失败返回 nil
+      def regeo_address(lng, lat, options = {})
+        result = regeo(lng, lat, options).dig("result") || {}
+        result.dig("formatted_addresses", "recommend") || result["address"]
+      end
+
+      private
+
+      def request(path, params)
+        Api.call(
+          provider: :tencent,
+          url: base_url + path,
+          params: params,
+          key_param: :key,
+          bad_result: ->(r) { KEY_ERROR_STATUSES.include?(r["status"].to_i) }
+        )
+      end
+
+      def base_url
+        Configuration.settings[:tencent_base_url].sub(%r{/\z}, "")
+      end
+    end
+  end
+end

data/lib/coordconver/projection.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# 高斯-克吕格投影(横轴墨卡托)正反算, 以及 3°/6° 带号与中央经线换算。
+# 适用于 CGCS2000 / 北京54 / 西安80 / WGS-84 椭球, 精度毫米级。
+#
+# 经 Coordconver.extend(Projection) 挂载:
+#   Coordconver.gauss_kruger(121.47, 31.24)                      # => [x东坐标, y北坐标]
+#   Coordconver.inverse_gauss_kruger(543_000, 3_456_000, central_meridian: 120)
+#   Coordconver.zone_meridian(121.47, width: 3)                  # => [40, 120]
+module Coordconver
+  module Projection
+    extend self
+
+    # 椭球参数: a 长半轴(米), rf 扁率倒数
+    ELLIPSOIDS = {
+      cgcs2000: [6_378_137.0, 298.257_222_101],
+      wgs84: [6_378_137.0, 298.257_223_563],
+      krassovsky: [6_378_245.0, 298.3],       # 北京54
+      iag75: [6_378_140.0, 298.257]           # 西安80
+    }.freeze
+
+    # 高斯-克吕格正算: 经纬度 -> 平面坐标 [东坐标 x, 北坐标 y] (米)
+    # central_meridian: 中央经线(度), 缺省按 zone_width 自动推算
+    # zone_width: 3 或 6 (度), 仅在未指定 central_meridian 时使用
+    # false_easting: 东坐标偏移(米), 默认 500_000 (测绘惯例, 保证 x 为正)
+    # ellipsoid: :cgcs2000 / :wgs84 / :krassovsky(北京54) / :iag75(西安80)
+    def gauss_kruger(lng, lat, central_meridian: nil, zone_width: 6,
+                     ellipsoid: :cgcs2000, false_easting: 500_000, false_northing: 0)
+      a, f = ellipsoid_params(ellipsoid)
+      cm = central_meridian || zone_meridian(lng, width: zone_width)[1]
+      e2 = f * (2 - f)
+      ep2 = e2 / (1 - e2)
+
+      p = deg2rad(lat)
+      dl = deg2rad(lng - cm)
+      sin_p = Math.sin(p)
+      cos_p = Math.cos(p)
+      tan_p = Math.tan(p)
+
+      n = a / Math.sqrt(1 - e2 * sin_p * sin_p)
+      t = tan_p * tan_p
+      c = ep2 * cos_p * cos_p
+      aa = dl * cos_p
+      m = meridional_arc(p, a, e2)
+
+      x = false_easting + n * (aa +
+            (1 - t + c) * aa**3 / 6 +
+            (5 - 18 * t + t * t + 72 * c - 58 * ep2) * aa**5 / 120)
+      y = false_northing + m + n * tan_p * (aa**2 / 2 +
+            (5 - t + 9 * c + 4 * c * c) * aa**4 / 24 +
+            (61 - 58 * t + t * t + 600 * c - 330 * ep2) * aa**6 / 720)
+      [x.round(4), y.round(4)]
+    end
+
+    # 高斯-克吕格反算: 平面坐标 -> 经纬度 [lng, lat]
+    # central_meridian 必填(反算无法从 x, y 推出投影带)
+    def inverse_gauss_kruger(x, y, central_meridian:, ellipsoid: :cgcs2000,
+                             false_easting: 500_000, false_northing: 0)
+      a, f = ellipsoid_params(ellipsoid)
+      e2 = f * (2 - f)
+      ep2 = e2 / (1 - e2)
+
+      m = y - false_northing
+      mu = m / (a * (1 - e2 / 4 - 3 * e2**2 / 64 - 5 * e2**3 / 256))
+      e1 = (1 - Math.sqrt(1 - e2)) / (1 + Math.sqrt(1 - e2))
+
+      p1 = footpoint_latitude(mu, e1)
+      sin_p1 = Math.sin(p1)
+      cos_p1 = Math.cos(p1)
+      tan_p1 = Math.tan(p1)
+
+      c1 = ep2 * cos_p1 * cos_p1
+      t1 = tan_p1 * tan_p1
+      n1 = a / Math.sqrt(1 - e2 * sin_p1 * sin_p1)
+      r1 = a * (1 - e2) / (1 - e2 * sin_p1 * sin_p1)**1.5
+      d = (x - false_easting) / n1
+
+      p = p1 - (n1 * tan_p1 / r1) * (d**2 / 2 -
+            (5 + 3 * t1 + 10 * c1 - 4 * c1 * c1 - 9 * ep2) * d**4 / 24 +
+            (61 + 90 * t1 + 298 * c1 + 45 * t1 * t1 - 252 * ep2 - 3 * c1 * c1) * d**6 / 720)
+      l = (d -
+            (1 + 2 * t1 + c1) * d**3 / 6 +
+            (5 - 2 * c1 + 28 * t1 - 3 * c1 * c1 + 8 * ep2 + 24 * t1 * t1) * d**5 / 120) / cos_p1
+
+      [rad2deg(l + deg2rad(central_meridian)), rad2deg(p)].map { |v| v.round(9) }
+    end
+
+    # 带号与中央经线: zone_meridian(121.47) => [21, 123], zone_meridian(121.47, width: 3) => [40, 120]
+    def zone_meridian(lng, width: 6)
+      raise ArgumentError, "带宽仅支持 3 或 6 度" unless [3, 6].include?(width)
+
+      zone = width == 6 ? (lng / 6).floor + 1 : (lng / 3).round
+      [zone, width == 6 ? zone * 6 - 3 : zone * 3]
+    end
+
+    private
+
+    def ellipsoid_params(name)
+      params = ELLIPSOIDS[name.to_s.downcase.to_sym]
+      raise ArgumentError, "未知椭球: #{name.inspect} (支持 #{ELLIPSOIDS.keys.join(', ')})" unless params
+
+      [params[0], 1.0 / params[1]]
+    end
+
+    # 子午线弧长
+    def meridional_arc(p, a, e2)
+      a * ((1 - e2 / 4 - 3 * e2**2 / 64 - 5 * e2**3 / 256) * p -
+        (3 * e2 / 8 + 3 * e2**2 / 32 + 45 * e2**3 / 1024) * Math.sin(2 * p) +
+        (15 * e2**2 / 256 + 45 * e2**3 / 1024) * Math.sin(4 * p) -
+        (35 * e2**3 / 3072) * Math.sin(6 * p))
+    end
+
+    # 底点纬度迭代
+    def footpoint_latitude(mu, e1)
+      mu + (3 * e1 / 2 - 27 * e1**3 / 32) * Math.sin(2 * mu) +
+        (21 * e1**2 / 16 - 55 * e1**4 / 32) * Math.sin(4 * mu) +
+        (151 * e1**3 / 96) * Math.sin(6 * mu) +
+        (1097 * e1**4 / 512) * Math.sin(8 * mu)
+    end
+
+    def deg2rad(deg)
+      deg * Math::PI / 180.0
+    end
+
+    def rad2deg(rad)
+      rad * 180.0 / Math::PI
+    end
+  end
+end

data/lib/coordconver/utils/http.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Coordconver
+  module Utils
+    # 轻量 HTTP 客户端, 仅依赖标准库。
+    # 网络层失败(超时/连接错误/非 2xx)会自动重试, 重试耗尽后抛出 Coordconver::NetworkError。
+    class Http
+      DEFAULT_OPEN_TIMEOUT = 5
+      DEFAULT_READ_TIMEOUT = 10
+      DEFAULT_RETRY_TIMES = 3
+      RETRY_BASE_SLEEP = 0.5
+
+      HTTP_VERB_MAP = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
+        delete: Net::HTTP::Delete
+      }.freeze
+
+      DEFAULT_HEADERS = {
+        "user-agent" => "coordconver/#{Coordconver::VERSION} (+https://github.com/cheenwe/coordconver)",
+        "accept" => "application/json"
+      }.freeze
+
+      RETRYABLE_ERRORS = [
+        Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET,
+        Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError, EOFError
+      ].freeze
+
+      def initialize(method, url, params: nil, body: nil, headers: {})
+        method = method.to_s.downcase.to_sym
+        raise ArgumentError, "不支持的 HTTP method: #{method}" unless HTTP_VERB_MAP.key?(method)
+
+        @uri = URI(url)
+        @uri.query = build_query(params) if params && !params.empty?
+        @method = method
+        @body = body
+        @headers = headers
+      end
+
+      def send_request
+        attempts = 0
+        begin
+          attempts += 1
+          perform
+        rescue *RETRYABLE_ERRORS => e
+          raise NetworkError, "#{@uri.host} 请求失败: #{e.class}: #{e.message}" if attempts >= DEFAULT_RETRY_TIMES
+
+          sleep(RETRY_BASE_SLEEP * (2**(attempts - 1)))
+          retry
+        end
+      end
+
+      private
+
+      def perform
+        opts = {
+          use_ssl: @uri.scheme == "https",
+          open_timeout: open_timeout,
+          read_timeout: read_timeout
+        }
+        Net::HTTP.start(@uri.host, @uri.port, **opts) do |http|
+          response = http.request(build_request)
+          unless response.is_a?(Net::HTTPSuccess)
+            raise NetworkError, "#{@uri.host} 返回 HTTP #{response.code}"
+          end
+
+          response
+        end
+      end
+
+      def build_request
+        request = HTTP_VERB_MAP[@method].new(@uri)
+        request.initialize_http_header(DEFAULT_HEADERS.merge(@headers))
+        request.body = @body.to_json if @body
+        request
+      end
+
+      def build_query(params)
+        URI.encode_www_form(params)
+      end
+
+      def open_timeout
+        configured = Coordconver::Geo::Configuration.configured? && Coordconver::Geo::Configuration.settings[:open_timeout]
+        configured || DEFAULT_OPEN_TIMEOUT
+      end
+
+      def read_timeout
+        configured = Coordconver::Geo::Configuration.configured? && Coordconver::Geo::Configuration.settings[:read_timeout]
+        configured || DEFAULT_READ_TIMEOUT
+      end
+    end
+  end
+end

data/lib/coordconver/utils/request.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Coordconver
+  module Utils
+    module Request
+      extend self
+
+      def get(url, params: nil, headers: {})
+        send_request(:get, url, params: params, headers: headers)
+      end
+
+      def post(url, body: nil, headers: {})
+        send_request(:post, url, body: body, headers: headers)
+      end
+
+      def put(url, body: nil, headers: {})
+        send_request(:put, url, body: body, headers: headers)
+      end
+
+      def delete(url, params: nil, headers: {})
+        send_request(:delete, url, params: params, headers: headers)
+      end
+
+      def send_request(method, url, params: nil, body: nil, headers: {})
+        raw_response = Http.new(
+          method.to_sym,
+          url,
+          params: params,
+          body: body,
+          headers: headers
+        ).send_request
+
+        parse_body(raw_response.body)
+      rescue JSON::ParserError => e
+        raise NetworkError, "响应不是合法 JSON: #{e.message}"
+      end
+
+      def parse_body(body)
+        JSON.parse(body)
+      end
+    end
+  end
+end

data/lib/coordconver/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Coordconver
-  VERSION = "0.1.3"
+  VERSION = "1.1.0"
 end

data/lib/coordconver.rb

@@ -1,8 +1,33 @@
+# frozen_string_literal: true
+
 require "coordconver/version"
+require "coordconver/errors"
 require "coordconver/coordconver"
 require "coordconver/degree"
+require "coordconver/formats"
+require "coordconver/projection"
+require "coordconver/geo/configuration"
+require "coordconver/geo/key_pool"
+require "coordconver/geo/cache"
+require "coordconver/geo/api"
+require "coordconver/geo/client"
+require "coordconver/geo/baidu"
+require "coordconver/geo/gaode"
+require "coordconver/geo/tencent"
+require "coordconver/utils/http"
+require "coordconver/utils/request"
 
 module Coordconver
-  include Coordconver
-  include Degree
+  # 坐标系转换/距离/方位角等方法已直接定义在 Coordconver 单例上,
+  # 如 Coordconver.wgs_gcj(lng, lat) / Coordconver.distance(...) / Coordconver.bearing(...)
+  extend Degree
+  extend Formats
+  extend Projection
+
+  # 便捷常量别名, 兼容 Coordconver::Baidu / Coordconver::Gaode 等用法
+  Baidu = Geo::Baidu
+  Gaode = Geo::Gaode
+  Tencent = Geo::Tencent
+  Client = Geo::Client
+  Configuration = Geo::Configuration
 end

metadata

@@ -1,43 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: coordconver
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 1.1.0
 platform: ruby
 authors:
 - chenwei
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2016-12-12 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.12'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.12'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -52,33 +38,59 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-description: 1.提供了百度坐标（BD09）、国测局坐标（火星坐标，GCJ02）、和WGS84坐标系之间的转换. 2.坐标点到经纬度的相互转换.
+description: 纯离线实现百度坐标(BD-09)、国测局坐标(GCJ-02)、地球坐标(WGS-84)互转(含厘米级精确逆变换), 两点距离/方位角/偏移点,
+  经纬度与度分秒互转, WKT/GeoJSON 互转, 高斯-克吕格投影正反算; 并封装百度/高德/腾讯 Web 服务 API 实现地址与坐标互转, 支持多 key
+  自动轮询与进程内缓存。附带命令行工具。
 email:
 - cheenwe@gmail.com
-executables: []
+executables:
+- coordconver
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".gitignore"
-- ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
+- README.en.md
 - README.md
 - Rakefile
 - bin/console
-- bin/coordconver
 - bin/setup
 - coordconver.gemspec
+- docs/cc-algorithms.js
+- docs/index.html
+- exe/coordconver
 - lib/coordconver.rb
 - lib/coordconver/coordconver.rb
 - lib/coordconver/degree.rb
+- lib/coordconver/errors.rb
+- lib/coordconver/formats.rb
+- lib/coordconver/geo/api.rb
+- lib/coordconver/geo/baidu.rb
+- lib/coordconver/geo/cache.rb
+- lib/coordconver/geo/client.rb
+- lib/coordconver/geo/configuration.rb
+- lib/coordconver/geo/gaode.rb
+- lib/coordconver/geo/key_pool.rb
+- lib/coordconver/geo/tencent.rb
+- lib/coordconver/projection.rb
+- lib/coordconver/utils/http.rb
+- lib/coordconver/utils/request.rb
 - lib/coordconver/version.rb
 homepage: https://github.com/cheenwe/coordconver
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/cheenwe/coordconver
+  source_code_uri: https://github.com/cheenwe/coordconver
+  changelog_uri: https://github.com/cheenwe/coordconver/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/cheenwe/coordconver/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -86,16 +98,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.1
-signing_key: 
+rubygems_version: 3.1.6
+signing_key:
 specification_version: 4
-summary: 坐标转换/Coordconver
+summary: 百度(BD-09)/火星(GCJ-02)/地球(WGS-84)坐标系互转、球面几何、高斯-克吕格投影, 以及百度/高德/腾讯地理编码
 test_files: []

data/.travis.yml

@@ -1,8 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.3.1
-before_install: gem install bundler -v 1.12.5
-
-script:
-  - bundle exec rake test

data/bin/coordconver

@@ -1,4 +0,0 @@
-#!/usr/bin/env ruby
-require "coordconver"
-
-puts Coordconver.wgs84_bd09(ARGV[0],ARGV[1] )