cesium-near-view-rectangle 0.0.1

package/README.md

@@ -0,0 +1,93 @@
+# cesium-near-view-rectangle
+
+Compute the **near-end visible rectangle** of a Cesium camera by screen-space ray sampling.
+
+When the camera is tilted (e.g. pitched at −30°), the built-in `camera.computeViewRectangle()` often returns an oversized rectangle that includes the far horizon. This package focuses the rectangle on the **near-end ground** that is actually close to the camera, giving a much tighter and more useful bounding box.
+
+## Installation
+
+```bash
+npm install cesium-near-view-rectangle
+```
+
+## Usage
+
+```js
+import { computeNearViewRectangle, computeAutoMaxDistKm } from 'cesium-near-view-rectangle';
+
+// Cesium is whatever you already have — window.Cesium (CDN) or `import * as Cesium from 'cesium'`
+
+// Basic usage
+const result = computeNearViewRectangle(Cesium, viewer);
+
+if (result) {
+  const { rect, hitCount, missCount, total } = result;
+  console.log('west:',  Cesium.Math.toDegrees(rect.west));
+  console.log('east:',  Cesium.Math.toDegrees(rect.east));
+  console.log('south:', Cesium.Math.toDegrees(rect.south));
+  console.log('north:', Cesium.Math.toDegrees(rect.north));
+} else {
+  console.warn('Camera may be pointing at the sky — no valid ground found.');
+}
+
+// Recommended: auto distance filter based on camera height
+const result2 = computeNearViewRectangle(Cesium, viewer, {
+  rows: 14,
+  cols: 14,
+  nearRatio: 0.3,
+  maxDistKm: computeAutoMaxDistKm(Cesium, viewer),
+});
+```
+
+## API
+
+### `computeNearViewRectangle(Cesium, viewer, options?)`
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `Cesium` | `object` | — | Cesium namespace (`window.Cesium` or `import * as Cesium from 'cesium'`) |
+| `viewer` | `Cesium.Viewer` | — | Cesium Viewer instance |
+| `options.rows` | `number` | `12` | Number of sample rows |
+| `options.cols` | `number` | `12` | Number of sample columns |
+| `options.nearRatio` | `number` | `0.35` | Start row as a fraction of screen height (0 = top, 1 = bottom). Higher values sample closer to the camera. |
+| `options.maxDistKm` | `number \| null` | `null` | Distance filter threshold in km. Points farther than this are discarded. Use `computeAutoMaxDistKm(Cesium, viewer)` for automatic tuning. |
+
+**Returns** `{ rect, hitCount, missCount, total } | null`
+
+| Field | Type | Description |
+|---|---|---|
+| `rect` | `Cesium.Rectangle` | Computed bounding rectangle (radians) |
+| `hitCount` | `number` | Number of screen samples that hit the ground |
+| `missCount` | `number` | Number of samples that missed (sky, too far, etc.) |
+| `total` | `number` | Total number of sample points tried |
+
+Returns `null` when fewer than 3 valid ground hits were found (e.g. camera pointing at sky).
+
+---
+
+### `computeAutoMaxDistKm(Cesium, viewer)`
+
+Returns a recommended `maxDistKm` value derived from the current camera height:
+
+```
+maxDistKm = max(cameraHeightKm × 3, 200)
+```
+
+## How it works
+
+1. A grid of screen-space points is generated covering the lower portion of the viewport (controlled by `nearRatio`).
+2. For each point, a ray is cast from the camera through that pixel:
+   - First tries `globe.pick()` (terrain-aware).
+   - Falls back to ray–ellipsoid intersection if terrain pick fails.
+3. Ground positions are filtered by distance and elevation sanity checks.
+4. `Cesium.Rectangle.fromCartographicArray()` wraps all valid hits into the final rectangle.
+
+## Compatibility
+
+- Works with any CesiumJS version that provides `IntersectionTests.rayEllipsoid` (≥ 1.107)
+- No runtime dependencies — bring your own Cesium
+- ESM only
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "cesium-near-view-rectangle",
+  "version": "0.0.1",
+  "description": "Compute the near-end visible rectangle of a Cesium camera by screen-space ray sampling. More accurate than camera.computeViewRectangle() when the view is tilted.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "cesium",
+    "cesiumjs",
+    "camera",
+    "viewport",
+    "rectangle",
+    "visible-area",
+    "near-view",
+    "gis",
+    "3d-map"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}

package/src/index.js

@@ -0,0 +1,152 @@
+/**
+ * 射线与 WGS84 椭球体求交（Cesium 1.107+ 兼容）
+ * @param {object} Cesium  Cesium 命名空间对象
+ * @param {object} ray
+ * @returns {object | null}
+ */
+function rayEllipsoidIntersect(Cesium, ray) {
+  const ellipsoid = Cesium.Ellipsoid.WGS84;
+  const intersection = Cesium.IntersectionTests.rayEllipsoid(ray, ellipsoid);
+  if (!intersection) return null;
+  const t = intersection.start >= 0 ? intersection.start : intersection.stop;
+  if (t < 0) return null;
+  return Cesium.Ray.getPoint(ray, t);
+}
+
+/**
+ * 从屏幕坐标拾取地面交点
+ * 优先 globe.pick（含地形），失败则退回椭球体求交
+ * @param {object} Cesium
+ * @param {object} screenPos
+ * @param {object} camera
+ * @param {object} globe
+ * @param {object} scene
+ * @returns {object | null}
+ */
+function pickGroundPoint(Cesium, screenPos, camera, globe, scene) {
+  const ray = camera.getPickRay(screenPos);
+  if (!ray) return null;
+  const cart3 = globe.pick(ray, scene);
+  if (cart3) return cart3;
+  return rayEllipsoidIntersect(Cesium, ray);
+}
+
+/**
+ * 生成屏幕采样点网格
+ * nearRatio：只采样屏幕 [nearRatio*H, H] 高度范围（下方 = 近端地面）
+ * @param {object} Cesium
+ * @param {number} rows
+ * @param {number} cols
+ * @param {number} nearRatio
+ * @param {HTMLCanvasElement} canvas
+ * @returns {object[]}
+ */
+function buildSamplePoints(Cesium, rows, cols, nearRatio, canvas) {
+  const W = canvas.width;
+  const H = canvas.height;
+  const yStart = Math.floor(H * nearRatio);
+  const points = [];
+
+  for (let r = 0; r <= rows; r++) {
+    const y = yStart + (H - yStart) * (r / rows);
+    for (let c = 0; c <= cols; c++) {
+      points.push(new Cesium.Cartesian2(W * (c / cols), y));
+    }
+  }
+  // 强制补四角和中心点
+  points.push(new Cesium.Cartesian2(0, 0));
+  points.push(new Cesium.Cartesian2(W, 0));
+  points.push(new Cesium.Cartesian2(0, H));
+  points.push(new Cesium.Cartesian2(W, H));
+  points.push(new Cesium.Cartesian2(W / 2, H / 2));
+  return points;
+}
+
+/**
+ * 根据相机高度自动推算合理的最大距离（km）
+ *
+ * @param {object} Cesium  Cesium 命名空间对象（window.Cesium 或 import * as Cesium）
+ * @param {object} viewer  Cesium Viewer 实例
+ * @returns {number}
+ */
+export function computeAutoMaxDistKm(Cesium, viewer) {
+  const carto = Cesium.Ellipsoid.WGS84.cartesianToCartographic(
+    viewer.camera.position,
+  );
+  if (!carto) return 200;
+  return Math.max((carto.height / 1000) * 3, 200);
+}
+
+/**
+ * 计算相机近端可视矩形区域
+ *
+ * @param {object} Cesium  Cesium 命名空间对象（window.Cesium 或 import * as Cesium）
+ * @param {object} viewer  Cesium Viewer 实例
+ * @param {object}   [options]
+ * @param {number}   [options.rows=12]           采样行数
+ * @param {number}   [options.cols=12]           采样列数
+ * @param {number}   [options.nearRatio=0.35]    采样起始行比例（0=顶部，1=底部），
+ *                                              值越大越靠近相机近端
+ * @param {number|null} [options.maxDistKm=null] 距离过滤阈值（km），null 表示不过滤；
+ *                                              推荐使用 computeAutoMaxDistKm(Cesium, viewer)
+ * @returns {{ rect: object, hitCount: number, missCount: number, total: number } | null}
+ *   成功时返回矩形结果，视角朝向天空等无效情况返回 null
+ */
+export function computeNearViewRectangle(Cesium, viewer, options) {
+  options = options || {};
+  const rows = options.rows !== undefined ? options.rows : 12;
+  const cols = options.cols !== undefined ? options.cols : 12;
+  const nearRatio = options.nearRatio !== undefined ? options.nearRatio : 0.35;
+  const maxDistKm = options.maxDistKm !== undefined ? options.maxDistKm : null;
+
+  const camera = viewer.camera;
+  const scene = viewer.scene;
+  const globe = scene.globe;
+  const canvas = viewer.canvas;
+
+  const samplePts = buildSamplePoints(Cesium, rows, cols, nearRatio, canvas);
+  const cartoList = [];
+  let hitCount = 0;
+  let missCount = 0;
+
+  for (const sp of samplePts) {
+    const cart3 = pickGroundPoint(Cesium, sp, camera, globe, scene);
+    if (!cart3) {
+      missCount++;
+      continue;
+    }
+
+    const carto = Cesium.Ellipsoid.WGS84.cartesianToCartographic(cart3);
+    if (!carto) {
+      missCount++;
+      continue;
+    }
+
+    // 距离过滤：剔除地平线附近的远端点
+    if (maxDistKm !== null) {
+      const distM = Math.sqrt(
+        Math.pow(cart3.x - camera.position.x, 2) +
+          Math.pow(cart3.y - camera.position.y, 2) +
+          Math.pow(cart3.z - camera.position.z, 2),
+      );
+      if (distM > maxDistKm * 1000) {
+        missCount++;
+        continue;
+      }
+    }
+
+    // 高度合理性过滤
+    if (carto.height > 15000 || carto.height < -500) {
+      missCount++;
+      continue;
+    }
+
+    cartoList.push(carto);
+    hitCount++;
+  }
+
+  if (cartoList.length < 3) return null;
+
+  const rect = Cesium.Rectangle.fromCartographicArray(cartoList);
+  return { rect, hitCount, missCount, total: samplePts.length };
+}