深度解析 S2 Geometry：在 Node.js 中構建高效能地理空間索引與範圍查詢

npm install s2geometry-node
# 或者純 JS 版本的
npm install nodes2

const s2 = require('s2geometry-node');

// 1. 建立台北 101 座標 (25.033976, 121.564538)
const latLng = s2.S2LatLng.fromDegrees(25.033976, 121.564538);

// 2. 獲取該點在 Level 16 (約 100m 精度) 的 S2CellId
const cellId = s2.S2CellId.fromLatLng(latLng).parent(16);

// 輸出 Token (Hex 字串) 與 64 位元整數 ID
console.log('Level 16 Token:', cellId.toToken());     // e.g. "3442abb..."
console.log('Level 16 ID (String):', cellId.id().toString());
console.log('當前 Level:', cellId.level());          // 16

// 取得當前 Cell 在同層級的所有相鄰 Cell (包含角點共有 8 個鄰居)
const neighbors = [];
cellId.getEdgeNeighbors(neighbors);

console.log('鄰近的 Cell 數量:', neighbors.length);
neighbors.forEach((neighbor, idx) => {
  console.log(`鄰居 ${idx + 1} Token:`, neighbor.toToken());
});

const s2 = require('s2geometry-node');

/**
 * 給定矩形經緯度，生成用於資料庫查詢的 Cell 區間
 * @param {number} minLat 最小緯度 (南)
 * @param {number} minLng 最小經度 (西)
 * @param {number} maxLat 最大緯度 (北)
 * @param {number} maxLng 最大經度 (東)
 */
function getBoundingBoxQueryRanges(minLat, minLng, maxLat, maxLng) {
  // 1. 建立矩形範圍 (S2LatLngRect)
  const pLo = s2.S2LatLng.fromDegrees(minLat, minLng);
  const pHi = s2.S2LatLng.fromDegrees(maxLat, maxLng);
  const rect = s2.S2LatLngRect.fromPointPair(pLo, pHi);

  // 2. 配置 RegionCoverer 參數
  const coverer = new s2.S2RegionCoverer();
  coverer.setMinLevel(8);    // 最小 Cell 層級 (避免覆蓋塊過大造成過多 False Positives)
  coverer.setMaxLevel(16);   // 最大 Cell 層級 (避免切太碎造成過多 SQL 條件)
  coverer.setMaxCells(20);   // 最多產生的 Cell 數量 (建議 8~30 之間平衡查詢效能)

  // 3. 獲取覆蓋該矩形的 S2CellUnion
  const cellUnion = coverer.getCovering(rect);

  // 4. 將每個 S2CellId 轉換為查詢區間 [rangeMin, rangeMax]
  const ranges = [];
  const cellIds = cellUnion.cellIds();

  for (let i = 0; i < cellIds.length; i++) {
    const cid = cellIds[i];
    ranges.push({
      cellId: cid.id().toString(),
      token: cid.toToken(),
      level: cid.level(),
      // 區間起點：該 Cell 樹狀結構下的最底層第一個葉子節點
      rangeMin: cid.rangeMin().id().toString(),
      // 區間終點：該 Cell 樹狀結構下的最底層最後一個葉子節點
      rangeMax: cid.rangeMax().id().toString()
    });
  }

  return ranges;
}

// 範例：查詢台北大安森林公園周邊矩形
const queryRanges = getBoundingBoxQueryRanges(
  25.0260, 121.5320, // 南西 (SW)
  25.0360, 121.5400  // 北東 (NE)
);

console.log(`成功將矩形分解為 ${queryRanges.length} 個 S2 區間：`);
console.dir(queryRanges, { depth: null });

-- 寫入時計算的 S2 索引欄位 (使用 BIGINT UNSIGNED 或 DECIMAL)
CREATE TABLE places (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255),
    lat DOUBLE,
    lng DOUBLE,
    s2_id BIGINT UNSIGNED NOT NULL,
    INDEX idx_s2_id (s2_id)
);

-- 透過 S2RegionCoverer 產生的多個區間快速篩選
SELECT id, name, lat, lng FROM places 
WHERE 
   (s2_id BETWEEN 4935105234527715328 AND 4935105238822682623)
OR (s2_id BETWEEN 4935105243117649920 AND 4935105247412617215)
OR (s2_id BETWEEN 4935105251707584512 AND 4935105256002551807);