coordconver 0.1.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 547a5de94434f34a523968d850e7f857135e819b
-  data.tar.gz: c2b74b48ddaa5a2f581fb3791ab28791c4ca3070
+SHA256:
+  metadata.gz: 9889fff6fe699d7d248aa42661f59029249f3ca929de12bb0cb81953faa71c8b
+  data.tar.gz: 988c47e1827785c21359bb6af7c0658d8f3985a397d351ff297f378359242c1c
 SHA512:
-  metadata.gz: 751b6f920215846deb3aafbc7392755e7dc6f75602c1c7d66fbf6c92123049e69207647d17f6cf62ec0df05f47098271470fb4b5d1550e64a4c1b6fe31d67a98
-  data.tar.gz: 092f9da7b7177e74b7993bd6720739abc727f1d4f32e1cf90bdb107b88da886f29a4d55b6b4e7ad38839d83920ff81ed85ee8e65158a16674fe10258dcc12f5c
+  metadata.gz: 24c92c16f253e8da20a14a5f26335f4782222ad8d15f78177e24b82f207033861d490dbb52613ebc0164f2f6a38d0ea769199b0534d0b46430d05210078cf3d5
+  data.tar.gz: 51db680c343e5451aaf1401345c5a6fc02b375dabcb46371449772d62cf45f5453f6c5645f4ee259e1516818009042595393e909e263b18502c061e0e028d264

data/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    name: Ruby ${{ matrix.ruby }}
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['2.7', '3.0', '3.1', '3.2', '3.3', '3.4']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake test
+      - name: CLI smoke test
+        run: |
+          exe/coordconver wgs2gcj 121.468738 31.247138
+          exe/coordconver wgs2gcj 121.468738 31.247138 --json
+          exe/coordconver wgs2gcj 121.468738 31.247138 --geojson
+          echo "121.468738,31.247138" | exe/coordconver gcj2wgs
+          printf "lng,lat\n121.468738,31.247138\n" | exe/coordconver wgs2gcj --csv
+          exe/coordconver dms 38.65777 104.08296
+          exe/coordconver dist 116.397428 39.90923 121.473701 31.230416
+          exe/coordconver bearing 116.397428 39.90923 121.473701 31.230416
+          exe/coordconver dest 116.397428 39.90923 153 100000
+          exe/coordconver gk 121.47 31.24 --zone3
+          exe/coordconver invgk 640045.58 3458515.34 --cm 120

data/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+## 1.1.0 (2026-10-25)
+
+### 新增
+
+- **厘米级精确逆变换**：`gcj_wgs_precise` / `bd_wgs_precise`（迭代法，误差 < 1e-7 度），原 `gcj_wgs`/`bd_wgs` 保留为近似版本（米级）。
+- **球面几何**：`bearing`（初始方位角）、`destination_point`（沿方位角偏移点），与 `distance` 配套。
+- **灵活的入参/出参**：所有转换方法支持 `Point` 结构 / `[lng, lat]` / `{lng:, lat:}` 单参调用，以及 `as: :hash` / `as: :point` 返回格式；新增 `Coordconver.point` 与 `Coordconver::Point`。
+- **批量转换**：`Coordconver.transform(points, from:, to:, as:)`。
+- **WKT / GeoJSON 支持**：`parse_wkt` / `to_wkt` / `parse_geojson` / `to_geojson`，可与坐标转换自由组合。
+- **高斯-克吕格投影**：`gauss_kruger` / `inverse_gauss_kruger` 正反算（CGCS2000/WGS-84/北京54/西安80 椭球，往返精度优于 1cm），`zone_meridian` 3°/6° 带号与中央经线换算。
+- **腾讯位置服务支持**：`Coordconver::Tencent` 的 `geo` / `regeo` / `ip` 及便捷方法，与百度/高德同等的多 key 轮询能力。
+- **多 key 智能轮询**：从随机取样改为线程安全的 round-robin；识别配额超限/无效 key（百度 401/402/200/201/210，高德 10001/10003/10009/10044/20003，腾讯 110/112/120/121/199）后自动摘除并在冷却 5 分钟后恢复；全部 key 耗尽时抛出 `ApiError`。
+- **进程内 LRU 缓存**：`config.cache = true` 开启（可配 `cache_ttl`/`cache_size`），重复的地理编码请求不再消耗配额。
+- **高德官方坐标转换 API**：`Gaode.convert` / `convert_location`（GPS/百度 -> GCJ-02，单次最多 40 点）。
+- **CLI 增强**：新增 `bearing` / `dest` / `gk` / `invgk` 子命令；`--csv`（表头自动跳过）、`--geojson`、`--cache`、`--tencent` 选项。
+- **在线试用页**：`docs/` 目录新增纯前端 demo（GitHub Pages 托管），坐标转换/度分秒/距离方位角/高斯-克吕格算法的 JS 移植与 gem 数值一致，无需安装即可体验。
+- 英文文档 `README.en.md`。
+
+### 变更
+
+- 百度/高德/腾讯 API 请求统一经 `Geo::Api` 调度层（缓存 + key 轮换），行为对调用方透明。
+- `Configuration.reset!` 现在会同时重置 key 轮询状态与缓存。
+
+## 1.0.0 (2026-10-25)
+
+### 修复
+
+- **`bd_wgs` 方向 bug**：0.x 版本的 `bd_wgs` 复用了 `wgs_bd` 的逻辑，返回结果方向完全错误。现已改为 `gcj_wgs(bd_gcj(...))` 并增加回归测试。
+- `transformlng` 遗漏 return 导致结果依赖实现细节的问题。
+
+### 变更（不兼容）
+
+- 百度地理编码升级至 [Geocoding API v3](https://lbsyun.baidu.com/index.php?title=webapi/guide/webservice-geocoding)（旧 v2 接口已下线），默认走 HTTPS；`regeo` 使用 Reverse Geocoding API v3。
+- 调用百度/高德 API 前必须先配置 key（`Coordconver.configure` 或 `Coordconver::Client.new`），未配置时抛出 `Coordconver::ConfigurationError`；移除了源码中硬编码的测试 key。
+- `Coordconver.cal_degree` 默认输出保留两位小数秒（`"38°39′27.97″"`）；需要旧版整数秒输出时使用 `Coordconver.cal_degree(n, 0)`。
+- `undegree`/`cal_undegree` 精度由 5 位小数提升至 6 位小数。
+- 最低 Ruby 版本要求提升至 2.7。
+- 移除 `Coordconver::Coordconver` 嵌套模块，转换方法直接定义在 `Coordconver` 单例上（原调用方式 `Coordconver.bd_gcj` 等不受影响）。
+- 要求 RubyGems 发布启用 MFA。
+
+### 新增
+
+- `Coordconver.distance`：两点球面距离（Haversine，米）。
+- `Coordconver.out_of_china?`：境外坐标判断，境外坐标 `wgs_gcj`/`gcj_wgs` 原样返回。
+- 语义化别名：`wgs84_gcj02`、`gcj02_wgs84`、`gcj02_bd09`、`bd09_gcj02`、`wgs84_bd09`、`bd09_wgs84`。
+- 度分秒解析支持多种写法（`38°39′27.97″` / `38d39m27.97s` / `38:39:27.97`）与负值（西经/南纬）。
+- 命令行工具 `coordconver`：坐标系转换、度分秒互转、距离计算、stdin 批量转换、JSON 输出。
+- 百度 SN 校验支持（`baidu_sn` 配置项）。
+- 便捷方法：`Baidu.geo_location`、`Baidu.regeo_address`、`Gaode.geo_location`、`Gaode.regeo_address`。
+- 统一错误体系：`Coordconver::Error` / `ConfigurationError` / `NetworkError` / `ApiError`。
+- `Coordconver.configure` 全局配置块；`open_timeout` / `read_timeout` 可配置。
+- HTTP 层：指数退避自动重试、非 2xx 判定、JSON 解析容错、请求头规范化。
+- 测试全面离线化（stub 网络层），另提供 `COORDCONVER_LIVE_TEST=1` 门控的真实 API 联调测试；CI 由 Travis 迁移至 GitHub Actions（Ruby 2.7 ~ 3.4 矩阵）。
+
+## 0.1.4
+
+- 最后一个 0.x 版本。

data/README.en.md

@@ -0,0 +1,177 @@
+# Coordconver
+
+[![CI](https://github.com/cheenwe/coordconver/actions/workflows/ci.yml/badge.svg)](https://github.com/cheenwe/coordconver/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/coordconver.svg)](https://badge.fury.io/rb/coordconver)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A zero-dependency Ruby toolkit for Chinese map coordinates ([中文文档](README.md)):
+
+1. **Offline coordinate conversion** between BD-09 (Baidu), GCJ-02 (Mars, used by Amap/Tencent/Google China) and WGS-84 (GPS), with a **centimeter-accurate iterative inverse**
+2. **Spherical geometry**: distance, initial bearing, destination point
+3. **Decimal degrees ⇄ DMS**, **WKT / GeoJSON** parsing and generation
+4. **Gauss-Krüger projection** (CGCS2000 / Beijing54 / Xi'an80 / WGS-84, 3°/6° zones)
+5. **Geocoding** via Baidu / Amap (Gaode) / Tencent Web APIs, plus Amap's official coordinate conversion API
+6. **Production-ready**: automatic key rotation with quota failover, in-process LRU cache, unified error hierarchy, thread-safe
+7. **CLI** for one-off and batch (CSV/GeoJSON) conversions
+
+Requires Ruby >= 2.7. No runtime dependencies — standard library only.
+
+> **Try it online** (no install needed): https://cheenwe.github.io/coordconver/ — a pure front-end demo with results identical to the gem.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'coordconver'
+```
+
+then `bundle`, or install directly:
+
+    $ gem install coordconver
+
+## Coordinate conversion
+
+```ruby
+require 'coordconver'
+
+wgs = [121.468738, 31.247138]
+Coordconver.wgs_gcj(*wgs)  # => [121.47327833883615, 31.2452165865549]
+Coordconver.wgs_bd(*wgs)   # => [121.47980789007566, 31.251157822142243]
+```
+
+| Conversion | Method | Alias |
+| ----- | ----- | ----- |
+| BD-09 -> GCJ-02 | `Coordconver.bd_gcj(lng, lat)` | `bd09_gcj02` |
+| GCJ-02 -> BD-09 | `Coordconver.gcj_bd(lng, lat)` | `gcj02_bd09` |
+| GCJ-02 -> WGS-84 | `Coordconver.gcj_wgs(lng, lat)` | `gcj02_wgs84` |
+| WGS-84 -> GCJ-02 | `Coordconver.wgs_gcj(lng, lat)` | `wgs84_gcj02` |
+| BD-09 -> WGS-84 | `Coordconver.bd_wgs(lng, lat)` | `bd09_wgs84` |
+| WGS-84 -> BD-09 | `Coordconver.wgs_bd(lng, lat)` | `wgs84_bd09` |
+
+Every method accepts `(lng, lat)`, a `Coordconver.point(lng, lat)` struct, `[lng, lat]` or `{lng:, lat:}`, and returns `[lng, lat]` by default — pass `as: :hash` or `as: :point` for other shapes:
+
+```ruby
+Coordconver.wgs_gcj(121.468738, 31.247138, as: :hash)
+# => {lng: 121.47327833883615, lat: 31.2452165865549}
+```
+
+### Precise inverse
+
+The standard `gcj_wgs` is an approximate inverse (meter-level error). The iterative `gcj_wgs_precise` is accurate to ~1 cm:
+
+```ruby
+g = Coordconver.wgs_gcj(121.468738, 31.247138)
+Coordconver.gcj_wgs_precise(*g)  # => [121.468738, 31.247138]
+Coordconver.bd_wgs_precise(*bd)  # same for Baidu coordinates
+```
+
+### Batch conversion
+
+```ruby
+points = [[121.468738, 31.247138], Coordconver.point(116.481499, 39.990475), { lng: 104.08, lat: 30.65 }]
+Coordconver.transform(points, from: :wgs84, to: :gcj02, as: :hash)
+```
+
+## Spherical geometry
+
+```ruby
+Coordconver.distance(116.397428, 39.90923, 121.473701, 31.230416) # => 1068194.1 (meters)
+Coordconver.bearing(116.397428, 39.90923, 121.473701, 31.230416)  # => 153.04 (degrees from north)
+Coordconver.destination_point(116.397428, 39.90923, 153.0, 100_000)
+Coordconver.out_of_china?(121.47, 31.25) # => false
+```
+
+## DMS / WKT / GeoJSON
+
+```ruby
+Coordconver.degree(38.65777, 104.08296)         # => ["38°39′27.97″", "104°4′58.66″"]
+Coordconver.undegree("38°39′27.97″", "104°4′58.66″")
+Coordconver.cal_undegree("38:39:27.97")         # also 38d39m27.97s, negatives supported
+
+Coordconver.parse_wkt("POINT (121.47 31.25)")   # => [121.47, 31.25]
+Coordconver.to_wkt(121.47, 31.25)               # => "POINT (121.47 31.25)"
+Coordconver.parse_geojson(geojson_hash_or_string)
+Coordconver.to_geojson(121.47, 31.25)           # => {"type"=>"Point", "coordinates"=>[121.47, 31.25]}
+```
+
+## Gauss-Krüger projection
+
+Forward/inverse Gauss-Krüger (transverse Mercator) for surveying workflows:
+
+```ruby
+Coordconver.gauss_kruger(121.47, 31.24, zone_width: 3)
+# => [640045.58, 3458515.34]
+Coordconver.gauss_kruger(121.47, 31.24, central_meridian: 120, ellipsoid: :krassovsky) # Beijing54
+Coordconver.inverse_gauss_kruger(640045.58, 3458515.34, central_meridian: 120)
+Coordconver.zone_meridian(121.47, width: 3)     # => [40, 120]
+```
+
+Ellipsoids: `:cgcs2000` (default), `:wgs84`, `:krassovsky` (Beijing54), `:iag75` (Xi'an80).
+
+## Geocoding (Baidu / Amap / Tencent)
+
+Get API keys from [Baidu](https://lbsyun.baidu.com/apiconsole/key) (server-side AK), [Amap](https://console.amap.com/dev/key/app) (Web service) or [Tencent LBS](https://lbs.qq.com/dev/console/application/mine). Pass multiple keys and the library rotates them automatically, skipping keys that hit quota limits (they recover after a 5-minute cooldown).
+
+```ruby
+Coordconver.configure do |config|
+  config.baidu_map_aks = ["baidu-ak-1", "baidu-ak-2"]
+  config.gaode_map_keys = ["amap-key-1"]
+  config.tencent_map_keys = ["tencent-key-1"]
+  # config.baidu_sn = "sn-secret"  # only for SN-signed AKs
+  # config.cache = true            # in-process LRU cache to save quota
+end
+
+Coordconver::Baidu.geo_location("百度大厦")            # => [lng, lat] (BD-09)
+Coordconver::Gaode.regeo_address(116.480881, 39.989410) # => "北京市朝阳区..." (GCJ-02 in)
+Coordconver::Tencent.geo_location("北京市海淀区...")     # => [lng, lat] (GCJ-02)
+Coordconver::Baidu.ip("8.8.8.8")
+
+# Official Amap conversion API (up to 40 points per call)
+Coordconver::Gaode.convert_location([121.468738, 31.247138], from: :gps)
+```
+
+Raw methods (`geo`/`regeo`) return the provider's full parsed JSON. Business errors are not raised — check `status` in the response (`0` for Baidu/Tencent, `"1"` for Amap).
+
+### Error handling
+
+```ruby
+begin
+  Coordconver::Gaode.regeo_address(116.48, 39.98)
+rescue Coordconver::ConfigurationError # no key configured
+rescue Coordconver::ApiError           # all keys exhausted/invalid (e.raw has the last response)
+rescue Coordconver::NetworkError       # timeouts/HTTP failures (retried 3x internally)
+rescue Coordconver::Error              # base class
+end
+```
+
+## CLI
+
+```bash
+coordconver wgs2gcj 121.468738 31.247138     # => 121.473278,31.245217
+coordconver dms 38.65777 104.08296
+coordconver dist 116.397 39.909 121.474 31.230
+coordconver bearing 116.397 39.909 121.474 31.230
+coordconver dest 116.397 39.909 153 100000
+coordconver gk 121.47 31.24 --zone3
+cat points.txt | coordconver wgs2gcj --csv   # batch, header skipped
+coordconver wgs2gcj 121.46 31.24 --geojson
+coordconver geo --gaode "北京方恒国际中心A座"   # needs COORDCONVER_GAODE_KEY env var
+coordconver regeo --baidu 116.322987 39.983424
+```
+
+Environment variables: `COORDCONVER_BAIDU_AK`, `COORDCONVER_GAODE_KEY`, `COORDCONVER_TENCENT_KEY` (comma-separated for multiple keys).
+
+## Development
+
+`bin/setup` to install dependencies, `rake test` to run the offline test suite. Live API tests are gated behind `COORDCONVER_LIVE_TEST=1` plus real keys. Install locally with `bundle exec rake install`; release with `bundle exec rake release`.
+
+The online demo is served by GitHub Pages from the `docs/` directory. To enable it once: repo Settings -> Pages -> Source `Deploy from a branch`, branch `master`, folder `/docs`.
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/cheenwe/coordconver.
+
+## License
+
+MIT License.