deeptwins-engine-3d 0.1.69 → 0.1.71

package/dist/esm/tileLayer/CustomRasterLayer.js

@@ -0,0 +1,776 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+var _excluded = ["tilingScheme"];
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }
+function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
+function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
+function _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, _toPropertyKey(descriptor.key), descriptor); } }
+function _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); Object.defineProperty(Constructor, "prototype", { writable: false }); return Constructor; }
+function _inherits(subClass, superClass) { if (typeof superClass !== "function" && superClass !== null) { throw new TypeError("Super expression must either be null or a function"); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, writable: true, configurable: true } }); Object.defineProperty(subClass, "prototype", { writable: false }); if (superClass) _setPrototypeOf(subClass, superClass); }
+function _setPrototypeOf(o, p) { _setPrototypeOf = Object.setPrototypeOf ? Object.setPrototypeOf.bind() : function _setPrototypeOf(o, p) { o.__proto__ = p; return o; }; return _setPrototypeOf(o, p); }
+function _createSuper(Derived) { var hasNativeReflectConstruct = _isNativeReflectConstruct(); return function _createSuperInternal() { var Super = _getPrototypeOf(Derived), result; if (hasNativeReflectConstruct) { var NewTarget = _getPrototypeOf(this).constructor; result = Reflect.construct(Super, arguments, NewTarget); } else { result = Super.apply(this, arguments); } return _possibleConstructorReturn(this, result); }; }
+function _possibleConstructorReturn(self, call) { if (call && (_typeof(call) === "object" || typeof call === "function")) { return call; } else if (call !== void 0) { throw new TypeError("Derived constructors may only return object or undefined"); } return _assertThisInitialized(self); }
+function _assertThisInitialized(self) { if (self === void 0) { throw new ReferenceError("this hasn't been initialised - super() hasn't been called"); } return self; }
+function _isNativeReflectConstruct() { if (typeof Reflect === "undefined" || !Reflect.construct) return false; if (Reflect.construct.sham) return false; if (typeof Proxy === "function") return true; try { Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); return true; } catch (e) { return false; } }
+function _getPrototypeOf(o) { _getPrototypeOf = Object.setPrototypeOf ? Object.getPrototypeOf.bind() : function _getPrototypeOf(o) { return o.__proto__ || Object.getPrototypeOf(o); }; return _getPrototypeOf(o); }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _iterableToArray(iter) { if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter); }
+function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) return _arrayLikeToArray(arr); }
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+import * as turf from '@turf/turf';
+import * as Cesium from 'deeptwins-cesium';
+import proj4 from 'proj4';
+import ImageryLayer from "./ImageryLayer";
+
+/**
+ * CustomRasterLayer 是一个通用栅格瓦片图层：
+ * - 使用 Cesium.UrlTemplateImageryProvider 加载任意 URL 模板瓦片。
+ * - 使用 proj4 将瓦片范围和裁剪 GeoJSON 从 dataCrs 转到 renderCrs。
+ * - GCJ02 渲染时按 tileLayer/test 的瓦片坐标方案计算瓦片范围。
+ * - 可选按 GeoJSON 面要素裁剪瓦片。
+ * - 裁剪前先求瓦片 bbox 与裁剪面的交集，避免多面重叠时误裁。
+ * - 可选输出调试事件，便于排查范围、瓦片加载、裁剪和丢弃行为。
+ *
+ * @example 基础瓦片图层
+ * ```ts
+ * const layer = new DeepTwinsEngine3D.CustomRasterLayer({
+ *   id: 'base-raster',
+ *   source: {
+ *     url: 'https://example.com/tiles/{z}/{x}/{y}.png',
+ *     minimumLevel: 0,
+ *     maximumLevel: 18,
+ *   },
+ *   debug: true,
+ * });
+ * map.imageryLayers.add(layer);
+ * ```
+ *
+ * @example 带范围、坐标转换和裁剪的图层
+ * ```ts
+ * const layer = new DeepTwinsEngine3D.CustomRasterLayer({
+ *   id: 'project-raster',
+ *   source: {
+ *     url: 'https://example.com/project/{z}/{x}/{y}.png',
+ *     maximumLevel: 20,
+ *   },
+ *   // bounds 格式：[minX, minY, maxX, maxY]，这里表示 EPSG:3857 米制范围。
+ *   bounds: [13210000, 3520000, 13230000, 3540000],
+ *   dataCrs: 'EPSG:3857',
+ *   renderCrs: 'EPSG:4326',
+ *   clipFeature: geoJsonPolygon,
+ *   debug: (event) => console.debug(event),
+ * });
+ * map.imageryLayers.add(layer);
+ * ```
+ *
+ * @remarks API 文档
+ * - `source`：必填，Cesium.UrlTemplateImageryProvider 原生配置。
+ * - `layerOptions`：可选，Cesium.ImageryLayer 原生配置。
+ * - `bounds`：可选，瓦片范围 `[minX, minY, maxX, maxY]`。
+ * - `dataCrs`：可选，bounds 与 clipFeature 的原始坐标系，默认 `EPSG:4326`。
+ * - `renderCrs`：可选，bounds、clipFeature 和瓦片范围转换后的目标坐标系，默认 `EPSG:4326`。
+ * - `projectionDefs`：可选，自定义 proj4 坐标系定义。
+ * - `clipFeature`：可选，GeoJSON Polygon/MultiPolygon/Feature/FeatureCollection。
+ * - `autoFitBounds`：可选，创建后自动将相机定位到最终范围，需同时传入 `map`。
+ * - `debug`：可选，`true` 使用 console.debug，函数则接收结构化调试事件。
+ */
+
+/** 通用范围格式：[minX, minY, maxX, maxY]。 */
+
+/** 调试事件类型，覆盖范围初始化、瓦片加载和裁剪决策。 */
+
+/** debug 回调收到的结构化事件。 */
+
+/** debug 配置：关闭、console.debug 输出，或自定义事件处理函数。 */
+
+/** 内置切片方案名称，或 Cesium 原生 TilingScheme 实例。 */
+
+/** CustomRasterLayer 数据源配置，扩展 tilingScheme 字符串默认选项。 */
+
+/** CustomRasterLayer 构造配置。 */
+
+var DEFAULT_CRS = 'EPSG:4326';
+var GCJ02_CRS = 'GCJ02';
+var WEB_MERCATOR_DEFINITION = '+proj=merc +a=6378137 +b=6378137 +lat_ts=0 +lon_0=0 ' + '+x_0=0 +y_0=0 +k=1 +units=m +nadgrids=@null +wktext +no_defs +type=crs';
+var WGS84_DEFINITION = '+proj=longlat +datum=WGS84 +no_defs +type=crs';
+var GCJ02_A = 6378245.0;
+var GCJ02_EE = 0.006693421622965943;
+
+/** 从 EPSG:xxxx、EPSG/0/xxxx 或纯数字 CRS 中提取 EPSG code。 */
+var getEpsgCode = function getEpsgCode(crs) {
+  var match = crs.match(/EPSG(?::|\/0\/|::)(\d+)/i) || crs.match(/^(\d+)$/);
+  return match === null || match === void 0 ? void 0 : match[1];
+};
+
+/** 统一 CRS 名称。 */
+var normalizeCrs = function normalizeCrs() {
+  var crs = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : DEFAULT_CRS;
+  if (/^(gcj02|gcj-02)$/i.test(crs)) {
+    return GCJ02_CRS;
+  }
+  var code = getEpsgCode(crs);
+  return code ? "EPSG:".concat(code) : crs;
+};
+
+/** 注册调用方传入的 proj4 自定义坐标系定义。 */
+var registerProjectionDefs = function registerProjectionDefs(projectionDefs) {
+  Object.entries(projectionDefs || {}).forEach(function (_ref) {
+    var _ref2 = _slicedToArray(_ref, 2),
+      name = _ref2[0],
+      definition = _ref2[1];
+    proj4.defs(normalizeCrs(name), definition);
+  });
+};
+
+/** 确保常用 CRS 可被 proj4 识别，其他 CRS 由 projectionDefs 显式注册。 */
+var ensureProjDefinition = function ensureProjDefinition(crs) {
+  var projName = normalizeCrs(crs);
+  if (projName === GCJ02_CRS) {
+    return projName;
+  }
+  if (proj4.defs(projName)) {
+    return projName;
+  }
+  var code = getEpsgCode(projName);
+  if (code === '4326') {
+    proj4.defs(projName, WGS84_DEFINITION);
+    return projName;
+  }
+  if (code === '3857') {
+    proj4.defs(projName, WEB_MERCATOR_DEFINITION);
+    return projName;
+  }
+  if (code && /^326\d{2}$/.test(code)) {
+    var zone = Number(code.slice(3));
+    proj4.defs(projName, "+proj=utm +zone=".concat(zone, " +datum=WGS84 +units=m +no_defs +type=crs"));
+    return projName;
+  }
+  if (code && /^327\d{2}$/.test(code)) {
+    var _zone = Number(code.slice(3));
+    proj4.defs(projName, "+proj=utm +zone=".concat(_zone, " +south +datum=WGS84 +units=m +no_defs +type=crs"));
+    return projName;
+  }
+  throw new Error("Missing proj definition for CRS: ".concat(crs));
+};
+var isWgs84Crs = function isWgs84Crs(crs) {
+  return normalizeCrs(crs) === DEFAULT_CRS;
+};
+var isWgs84LikeCrs = function isWgs84LikeCrs(crs) {
+  return isWgs84Crs(crs);
+};
+var isOutOfChina = function isOutOfChina(lng, lat) {
+  return !(lng > 73.66 && lng < 135.05 && lat > 3.86 && lat < 53.55);
+};
+var transformGcj02Lat = function transformGcj02Lat(lng, lat) {
+  var ret = -100.0 + 2.0 * lng + 3.0 * lat + 0.2 * lat * lat + 0.1 * lng * lat + 0.2 * Math.sqrt(Math.abs(lng));
+  ret += (20.0 * Math.sin(6.0 * lng * Math.PI) + 20.0 * Math.sin(2.0 * lng * Math.PI)) * 2.0 / 3.0;
+  ret += (20.0 * Math.sin(lat * Math.PI) + 40.0 * Math.sin(lat / 3.0 * Math.PI)) * 2.0 / 3.0;
+  ret += (160.0 * Math.sin(lat / 12.0 * Math.PI) + 320 * Math.sin(lat * Math.PI / 30.0)) * 2.0 / 3.0;
+  return ret;
+};
+var transformGcj02Lng = function transformGcj02Lng(lng, lat) {
+  var ret = 300.0 + lng + 2.0 * lat + 0.1 * lng * lng + 0.1 * lng * lat + 0.1 * Math.sqrt(Math.abs(lng));
+  ret += (20.0 * Math.sin(6.0 * lng * Math.PI) + 20.0 * Math.sin(2.0 * lng * Math.PI)) * 2.0 / 3.0;
+  ret += (20.0 * Math.sin(lng * Math.PI) + 40.0 * Math.sin(lng / 3.0 * Math.PI)) * 2.0 / 3.0;
+  ret += (150.0 * Math.sin(lng / 12.0 * Math.PI) + 300.0 * Math.sin(lng / 30.0 * Math.PI)) * 2.0 / 3.0;
+  return ret;
+};
+var wgs84ToGcj02 = function wgs84ToGcj02(lng, lat) {
+  if (isOutOfChina(lng, lat)) {
+    return [lng, lat];
+  }
+  var dLat = transformGcj02Lat(lng - 105.0, lat - 35.0);
+  var dLng = transformGcj02Lng(lng - 105.0, lat - 35.0);
+  var radLat = lat / 180.0 * Math.PI;
+  var magic = Math.sin(radLat);
+  magic = 1 - GCJ02_EE * magic * magic;
+  var sqrtMagic = Math.sqrt(magic);
+  dLat = dLat * 180.0 / (GCJ02_A * (1 - GCJ02_EE) / (magic * sqrtMagic) * Math.PI);
+  dLng = dLng * 180.0 / (GCJ02_A / sqrtMagic * Math.cos(radLat) * Math.PI);
+  return [lng + dLng, lat + dLat];
+};
+var gcj02ToWgs84 = function gcj02ToWgs84(lng, lat) {
+  if (isOutOfChina(lng, lat)) {
+    return [lng, lat];
+  }
+  var _wgs84ToGcj = wgs84ToGcj02(lng, lat),
+    _wgs84ToGcj2 = _slicedToArray(_wgs84ToGcj, 2),
+    gcjLng = _wgs84ToGcj2[0],
+    gcjLat = _wgs84ToGcj2[1];
+  return [lng * 2 - gcjLng, lat * 2 - gcjLat];
+};
+
+/** 转换单个坐标点，保留第三维及后续附加值。 */
+var transformPoint = function transformPoint(point, sourceCrs, targetCrs) {
+  var normalizedSourceCrs = normalizeCrs(sourceCrs);
+  var normalizedTargetCrs = normalizeCrs(targetCrs);
+  if (normalizedSourceCrs === normalizedTargetCrs) {
+    return _toConsumableArray(point);
+  }
+  if (normalizedSourceCrs === GCJ02_CRS) {
+    var wgs84Point = gcj02ToWgs84(point[0], point[1]);
+    if (isWgs84LikeCrs(normalizedTargetCrs)) {
+      return [].concat(_toConsumableArray(wgs84Point), _toConsumableArray(point.slice(2)));
+    }
+    var _targetProj = ensureProjDefinition(normalizedTargetCrs);
+    var _proj = proj4(DEFAULT_CRS, _targetProj, wgs84Point),
+      _proj2 = _slicedToArray(_proj, 2),
+      _x = _proj2[0],
+      _y = _proj2[1];
+    return [_x, _y].concat(_toConsumableArray(point.slice(2)));
+  }
+  if (normalizedTargetCrs === GCJ02_CRS) {
+    var _wgs84Point = isWgs84LikeCrs(normalizedSourceCrs) ? [point[0], point[1]] : proj4(ensureProjDefinition(normalizedSourceCrs), DEFAULT_CRS, [point[0], point[1]]);
+    var _wgs84ToGcj3 = wgs84ToGcj02(_wgs84Point[0], _wgs84Point[1]),
+      _wgs84ToGcj4 = _slicedToArray(_wgs84ToGcj3, 2),
+      _x2 = _wgs84ToGcj4[0],
+      _y2 = _wgs84ToGcj4[1];
+    return [_x2, _y2].concat(_toConsumableArray(point.slice(2)));
+  }
+  var sourceProj = ensureProjDefinition(normalizedSourceCrs);
+  var targetProj = ensureProjDefinition(normalizedTargetCrs);
+  var _proj3 = proj4(sourceProj, targetProj, [point[0], point[1]]),
+    _proj4 = _slicedToArray(_proj3, 2),
+    x = _proj4[0],
+    y = _proj4[1];
+  return [x, y].concat(_toConsumableArray(point.slice(2)));
+};
+
+/** 转换 bbox 四角后重新计算外接范围，避免旋转/投影畸变导致范围不足。 */
+var transformBounds = function transformBounds(bounds, sourceCrs, targetCrs) {
+  var corners = [[bounds[0], bounds[1]], [bounds[0], bounds[3]], [bounds[2], bounds[1]], [bounds[2], bounds[3]]].map(function (point) {
+    return transformPoint(point, sourceCrs, targetCrs);
+  });
+  var xList = corners.map(function (_ref3) {
+    var _ref4 = _slicedToArray(_ref3, 1),
+      x = _ref4[0];
+    return x;
+  });
+  var yList = corners.map(function (_ref5) {
+    var _ref6 = _slicedToArray(_ref5, 2),
+      y = _ref6[1];
+    return y;
+  });
+  return [Math.min.apply(Math, _toConsumableArray(xList)), Math.min.apply(Math, _toConsumableArray(yList)), Math.max.apply(Math, _toConsumableArray(xList)), Math.max.apply(Math, _toConsumableArray(yList))];
+};
+
+/** Cesium.Rectangle 弧度范围转经纬度 bbox。 */
+var rectangleToBounds = function rectangleToBounds(rectangle) {
+  return [Cesium.Math.toDegrees(rectangle.west), Cesium.Math.toDegrees(rectangle.south), Cesium.Math.toDegrees(rectangle.east), Cesium.Math.toDegrees(rectangle.north)];
+};
+var boundsToRectangle = function boundsToRectangle(bounds, result) {
+  return Cesium.Rectangle.fromDegrees(bounds[0], bounds[1], bounds[2], bounds[3], result);
+};
+var normalizeBounds = function normalizeBounds(bounds) {
+  if (!bounds || bounds.length < 4 || bounds.slice(0, 4).some(function (value) {
+    return !Number.isFinite(value);
+  })) {
+    return undefined;
+  }
+  return [bounds[0], bounds[1], bounds[2], bounds[3]];
+};
+var transformRectangle = function transformRectangle(rectangle, sourceCrs, targetCrs, result) {
+  return boundsToRectangle(transformBounds(rectangleToBounds(rectangle), sourceCrs, targetCrs), result);
+};
+
+/** 将内置 tilingScheme 名称解析为 Cesium 原生切片方案实例。 */
+var createSourceTilingScheme = function createSourceTilingScheme(tilingScheme) {
+  if (!tilingScheme || tilingScheme === 'webMercator') {
+    return new Cesium.WebMercatorTilingScheme();
+  }
+  if (tilingScheme === 'geographic') {
+    return new Cesium.GeographicTilingScheme();
+  }
+  return tilingScheme;
+};
+
+/** 创建按目标坐标系渲染的瓦片坐标方案，逻辑对齐 tileLayer/test。 */
+var createRenderTilingScheme = function createRenderTilingScheme(tilingScheme, renderCrs) {
+  if (isWgs84Crs(renderCrs)) {
+    return tilingScheme;
+  }
+  return {
+    get ellipsoid() {
+      return tilingScheme.ellipsoid;
+    },
+    get rectangle() {
+      return transformRectangle(tilingScheme.rectangle, DEFAULT_CRS, renderCrs);
+    },
+    get projection() {
+      return tilingScheme.projection;
+    },
+    getNumberOfXTilesAtLevel: function getNumberOfXTilesAtLevel(level) {
+      return tilingScheme.getNumberOfXTilesAtLevel(level);
+    },
+    getNumberOfYTilesAtLevel: function getNumberOfYTilesAtLevel(level) {
+      return tilingScheme.getNumberOfYTilesAtLevel(level);
+    },
+    tileXYToNativeRectangle: function tileXYToNativeRectangle(x, y, level, result) {
+      return tilingScheme.tileXYToNativeRectangle(x, y, level, result);
+    },
+    rectangleToNativeRectangle: function rectangleToNativeRectangle(rectangle, result) {
+      return tilingScheme.rectangleToNativeRectangle(transformRectangle(rectangle, renderCrs, DEFAULT_CRS), result);
+    },
+    tileXYToRectangle: function tileXYToRectangle(x, y, level, result) {
+      return transformRectangle(tilingScheme.tileXYToRectangle(x, y, level), DEFAULT_CRS, renderCrs, result);
+    },
+    positionToTileXY: function positionToTileXY(position, level, result) {
+      var _transformPoint = transformPoint([Cesium.Math.toDegrees(position.longitude), Cesium.Math.toDegrees(position.latitude)], renderCrs, DEFAULT_CRS),
+        _transformPoint2 = _slicedToArray(_transformPoint, 2),
+        lng = _transformPoint2[0],
+        lat = _transformPoint2[1];
+      return tilingScheme.positionToTileXY(Cesium.Cartographic.fromDegrees(lng, lat), level, result);
+    }
+  };
+};
+
+/** 递归转换 GeoJSON coordinates，兼容点、线、面、多面等嵌套结构。 */
+var transformCoordinates = function transformCoordinates(coordinates, sourceCrs, targetCrs) {
+  if (!Array.isArray(coordinates)) {
+    return coordinates;
+  }
+  if (typeof coordinates[0] === 'number' && typeof coordinates[1] === 'number') {
+    return transformPoint(coordinates, sourceCrs, targetCrs);
+  }
+  return coordinates.map(function (item) {
+    return transformCoordinates(item, sourceCrs, targetCrs);
+  });
+};
+
+/** 转换 GeoJSON Geometry，包含 GeometryCollection。 */
+var transformGeometry = function transformGeometry(geometry, sourceCrs, targetCrs) {
+  if (!geometry) {
+    return;
+  }
+  if (geometry.type === 'GeometryCollection') {
+    var _geometry$geometries;
+    (_geometry$geometries = geometry.geometries) === null || _geometry$geometries === void 0 || _geometry$geometries.forEach(function (item) {
+      return transformGeometry(item, sourceCrs, targetCrs);
+    });
+    return;
+  }
+  if (geometry.coordinates) {
+    geometry.coordinates = transformCoordinates(geometry.coordinates, sourceCrs, targetCrs);
+  }
+};
+
+/** 深拷贝并转换 GeoJSON，避免修改调用方持有的原始对象。 */
+var transformGeoJson = function transformGeoJson(geoJson, sourceCrs, targetCrs) {
+  if (!geoJson) {
+    return geoJson;
+  }
+  var clonedGeoJson = JSON.parse(JSON.stringify(geoJson));
+  if (normalizeCrs(sourceCrs) === normalizeCrs(targetCrs)) {
+    return clonedGeoJson;
+  }
+  if (clonedGeoJson.type === 'FeatureCollection') {
+    var _clonedGeoJson$featur;
+    (_clonedGeoJson$featur = clonedGeoJson.features) === null || _clonedGeoJson$featur === void 0 || _clonedGeoJson$featur.forEach(function (feature) {
+      return transformGeometry(feature.geometry, sourceCrs, targetCrs);
+    });
+    return clonedGeoJson;
+  }
+  if (clonedGeoJson.type === 'Feature') {
+    transformGeometry(clonedGeoJson.geometry, sourceCrs, targetCrs);
+    return clonedGeoJson;
+  }
+  transformGeometry(clonedGeoJson, sourceCrs, targetCrs);
+  return clonedGeoJson;
+};
+
+/** 将 Geometry 包装为 Turf 可处理的 Feature。 */
+var createFeature = function createFeature(geometry) {
+  var properties = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  return {
+    type: 'Feature',
+    properties: properties,
+    geometry: geometry
+  };
+};
+
+/**
+ * 收集可裁剪的 Polygon，忽略点线等非面要素。
+ * MultiPolygon 会拆成多个 Polygon，避免重叠面在 canvas evenodd 填充时互相抵消。
+ */
+var collectPolygonFeatures = function collectPolygonFeatures(geoJson) {
+  var properties = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  if (!geoJson) {
+    return [];
+  }
+  if (geoJson.type === 'FeatureCollection') {
+    return geoJson.features.flatMap(function (feature) {
+      return collectPolygonFeatures(feature);
+    });
+  }
+  if (geoJson.type === 'Feature') {
+    return collectPolygonFeatures(geoJson.geometry, geoJson.properties || {});
+  }
+  if (geoJson.type === 'GeometryCollection') {
+    return geoJson.geometries.flatMap(function (geometry) {
+      return collectPolygonFeatures(geometry, properties);
+    });
+  }
+  if (geoJson.type === 'Polygon') {
+    return [createFeature(geoJson, properties)];
+  }
+  if (geoJson.type === 'MultiPolygon') {
+    return geoJson.coordinates.map(function (coordinates) {
+      return createFeature({
+        type: 'Polygon',
+        coordinates: coordinates
+      }, properties);
+    });
+  }
+  return [];
+};
+
+/** 使用 turf 计算裁剪面的 bbox，作为裁剪范围。 */
+var getClipFeatureBounds = function getClipFeatureBounds(clipFeatures) {
+  if (!clipFeatures.length) {
+    return undefined;
+  }
+  var bbox = turf.bbox(turf.featureCollection(clipFeatures));
+  if (bbox.length < 4 || bbox.some(function (value) {
+    return !Number.isFinite(value);
+  })) {
+    return undefined;
+  }
+  return normalizeBounds(bbox);
+};
+var getImageSize = function getImageSize(image) {
+  return {
+    width: image.width,
+    height: image.height
+  };
+};
+
+/**
+ * 通用自定义栅格图层。
+ *
+ * 继承项目现有 ImageryLayer 封装，内部使用 UrlTemplateImageryProvider。
+ * 若传入 clipFeature，会在 Cesium 创建纹理前用 canvas 对瓦片进行透明裁剪。
+ */
+var CustomRasterLayer = /*#__PURE__*/function (_ImageryLayer) {
+  _inherits(CustomRasterLayer, _ImageryLayer);
+  var _super = _createSuper(CustomRasterLayer);
+  /** 创建通用栅格图层。 */
+  function CustomRasterLayer(options) {
+    var _options$map;
+    var _this;
+    _classCallCheck(this, CustomRasterLayer);
+    if (!(options !== null && options !== void 0 && options.source)) {
+      throw new Error('CustomRasterLayer source is required.');
+    }
+    registerProjectionDefs(options.projectionDefs);
+    var dataCrs = normalizeCrs(options.dataCrs || DEFAULT_CRS);
+    var renderCrs = normalizeCrs(options.renderCrs || DEFAULT_CRS);
+    var transformedClipFeature = transformGeoJson(options.clipFeature, dataCrs, renderCrs);
+    var clipFeatures = collectPolygonFeatures(transformedClipFeature);
+    var _options$source = options.source,
+      sourceTilingSchemeOption = _options$source.tilingScheme,
+      sourceOptionsRest = _objectWithoutProperties(_options$source, _excluded);
+    var tileBounds = options.bounds ? transformBounds(options.bounds, dataCrs, renderCrs) : undefined;
+    var clipBounds = getClipFeatureBounds(clipFeatures);
+    var renderBounds = clipBounds || tileBounds;
+    var sourceRectangleBounds = sourceOptionsRest.rectangle ? rectangleToBounds(sourceOptionsRest.rectangle) : undefined;
+    var fitBounds = clipBounds || tileBounds || sourceRectangleBounds;
+    var tilingScheme = createRenderTilingScheme(createSourceTilingScheme(sourceTilingSchemeOption), renderCrs);
+    var sourceOptions = _objectSpread(_objectSpread({}, sourceOptionsRest), {}, {
+      tilingScheme: tilingScheme
+    }, renderBounds ? {
+      rectangle: boundsToRectangle(renderBounds)
+    } : {});
+    var imageProvider = new Cesium.UrlTemplateImageryProvider(sourceOptions);
+    _this = _super.call(this, imageProvider, options.layerOptions);
+    /** 图层 id，方便业务图层集合按 id 管理。 */
+    _defineProperty(_assertThisInitialized(_this), "id", void 0);
+    /** 图层层级，方便业务图层集合排序。 */
+    _defineProperty(_assertThisInitialized(_this), "zIndex", void 0);
+    /** Cesium 瓦片数据源实例。 */
+    _defineProperty(_assertThisInitialized(_this), "source", void 0);
+    _defineProperty(_assertThisInitialized(_this), "_debug", void 0);
+    _defineProperty(_assertThisInitialized(_this), "_clipFeatures", void 0);
+    _defineProperty(_assertThisInitialized(_this), "_fitBounds", void 0);
+    _defineProperty(_assertThisInitialized(_this), "_mapContext", void 0);
+    _this.id = options.id;
+    _this.zIndex = options.zIndex;
+    _this.source = imageProvider;
+    _this._debug = options.debug;
+    _this._clipFeatures = clipFeatures;
+    _this._fitBounds = fitBounds;
+    _this._mapContext = (_options$map = options.map) === null || _options$map === void 0 ? void 0 : _options$map._mapContext;
+    _this.logDebug({
+      type: 'range',
+      bounds: options.bounds,
+      tileBounds: tileBounds,
+      clipBounds: clipBounds,
+      renderBounds: renderBounds,
+      dataCrs: dataCrs,
+      renderCrs: renderCrs
+    });
+    if (options.autoFitBounds && normalizeBounds(fitBounds)) {
+      _this.fitToBounds(options.map, options.fitBoundsOptions);
+    }
+    return _this;
+  }
+  _createClass(CustomRasterLayer, [{
+    key: "getMap",
+    value: function getMap() {
+      return this._mapContext && this._mapContext.getMap();
+    }
+
+    /** 将相机定位到当前图层最终渲染范围。 */
+  }, {
+    key: "fitToBounds",
+    value: function fitToBounds() {
+      var _map$camera;
+      var map = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : this.getMap();
+      var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {
+        duration: 0
+      };
+      if (!map) {
+        throw new Error('CustomRasterLayer fitToBounds requires a map.');
+      }
+      var fitBounds = normalizeBounds(this._fitBounds);
+      if (!fitBounds) {
+        throw new Error('CustomRasterLayer fitToBounds requires valid bounds.');
+      }
+      var fitOptions = options || {
+        duration: 0
+      };
+      if (typeof map.setCameraViewByBbox === 'function') {
+        map.setCameraViewByBbox(fitBounds, fitOptions);
+        return this;
+      }
+      if ((_map$camera = map.camera) !== null && _map$camera !== void 0 && _map$camera.flyTo) {
+        map.camera.flyTo(_objectSpread({
+          destination: boundsToRectangle(fitBounds)
+        }, fitOptions));
+        return this;
+      }
+      throw new Error('CustomRasterLayer fitToBounds requires a map camera.');
+    }
+
+    /**
+     * Cesium 内部纹理创建钩子。
+     *
+     * 这里按 tileLayer/test 的 ClipLayer 逻辑处理裁剪：
+     * - 完全在裁剪面内：原图保留。
+     * - 完全不相交：替换为空透明 canvas。
+     * - 部分相交：按瓦片与裁剪面的交集裁剪 canvas。
+     */
+  }, {
+    key: "_createTexture",
+    value: function _createTexture(context, imagery) {
+      var _this2 = this;
+      var tileBbox = rectangleToBounds(imagery.rectangle);
+      this.logDebug({
+        type: 'tile-loaded',
+        x: imagery.x,
+        y: imagery.y,
+        level: imagery.level,
+        bbox: tileBbox,
+        imageSize: getImageSize(imagery.image)
+      });
+      if (!this._clipFeatures.length) {
+        return this.createTexture(context, imagery);
+      }
+      try {
+        var tileFeature = turf.bboxPolygon(tileBbox);
+        var isWithin = this._clipFeatures.some(function (feature) {
+          return turf.booleanWithin(tileFeature, feature);
+        });
+        if (isWithin) {
+          this.logDebug({
+            type: 'tile-kept',
+            x: imagery.x,
+            y: imagery.y,
+            level: imagery.level,
+            bbox: tileBbox,
+            reason: 'within-clip'
+          });
+          return this.createTexture(context, imagery);
+        }
+        var intersections = this.getClipIntersections(tileFeature);
+        if (!intersections.length) {
+          this.logDebug({
+            type: 'tile-discarded',
+            x: imagery.x,
+            y: imagery.y,
+            level: imagery.level,
+            bbox: tileBbox,
+            reason: 'outside-clip'
+          });
+          imagery.image = this.createTileCanvas(imagery);
+          return this.createTexture(context, imagery);
+        }
+        var canvas = this.createTileCanvas(imagery);
+        var canvasContext = canvas.getContext('2d');
+        if (!canvasContext) {
+          return this.createTexture(context, imagery);
+        }
+        canvasContext.drawImage(imagery.image, 0, 0, imagery.image.width, imagery.image.height);
+        this.clip(canvasContext, intersections.flatMap(function (intersection) {
+          return _this2.geometryToPathArray({
+            boundPolygon: intersection,
+            bbox: tileBbox,
+            width: imagery.image.width,
+            height: imagery.image.height
+          });
+        }));
+        this.logDebug({
+          type: 'tile-clipped',
+          x: imagery.x,
+          y: imagery.y,
+          level: imagery.level,
+          bbox: tileBbox,
+          reason: 'intersects-clip'
+        });
+        void createImageBitmap(canvas).then(function (image) {
+          imagery.image = image;
+          _this2.createTexture(context, imagery);
+        });
+        return undefined;
+      } catch (error) {
+        this.logDebug({
+          type: 'tile-error',
+          x: imagery.x,
+          y: imagery.y,
+          level: imagery.level,
+          bbox: tileBbox,
+          error: error
+        });
+        return this.createTexture(context, imagery);
+      }
+    }
+
+    /** 调用 Cesium 原始纹理创建逻辑。 */
+  }, {
+    key: "createTexture",
+    value: function createTexture(context, imagery) {
+      return ImageryLayer.prototype._createTexture.call(this, context, imagery);
+    }
+
+    /** 获取当前瓦片与所有裁剪面的交集，用交集路径裁剪当前瓦片。 */
+  }, {
+    key: "getClipIntersections",
+    value: function getClipIntersections(tileFeature) {
+      var intersections = [];
+      this._clipFeatures.forEach(function (feature) {
+        if (!turf.booleanIntersects(tileFeature, feature)) {
+          return;
+        }
+        var intersection = turf.intersect(tileFeature, feature);
+        if (intersection !== null && intersection !== void 0 && intersection.geometry) {
+          intersections.push(intersection);
+        }
+      });
+      return intersections;
+    }
+
+    /** 创建与当前瓦片同尺寸的透明 canvas。 */
+  }, {
+    key: "createTileCanvas",
+    value: function createTileCanvas(imagery) {
+      var canvas = document.createElement('canvas');
+      canvas.width = imagery.image.width;
+      canvas.height = imagery.image.height;
+      return canvas;
+    }
+
+    /** 将地理坐标转换为当前瓦片画布像素坐标。 */
+  }, {
+    key: "pointToPixel",
+    value: function pointToPixel(options) {
+      for (var i = 0; i < options.coors.length; i += 1) {
+        var coorTmp = options.coors[i];
+        var pointTmp = [];
+        for (var j = 0; j < coorTmp.length; j += 1) {
+          pointTmp.push([(coorTmp[j][0] - options.bbox[0]) / (options.bbox[2] - options.bbox[0]) * options.width, options.height - (options.bbox[3] - coorTmp[j][1]) / (options.bbox[3] - options.bbox[1]) * options.height]);
+        }
+        options.pointArr.push(pointTmp);
+      }
+    }
+
+    /** 将裁剪后的 geometry 转换为画布 path 坐标数组。 */
+  }, {
+    key: "geometryToPathArray",
+    value: function geometryToPathArray(options) {
+      var _this3 = this;
+      var featureType = options.boundPolygon.geometry.type;
+      var pointArr = [];
+      if (featureType === 'Polygon') {
+        this.pointToPixel({
+          pointArr: pointArr,
+          coors: options.boundPolygon.geometry.coordinates,
+          bbox: options.bbox,
+          width: options.width,
+          height: options.height
+        });
+      } else if (featureType === 'MultiPolygon') {
+        options.boundPolygon.geometry.coordinates.forEach(function (polygon) {
+          _this3.pointToPixel({
+            pointArr: pointArr,
+            coors: polygon,
+            bbox: options.bbox,
+            width: options.width,
+            height: options.height
+          });
+        });
+      }
+      return pointArr;
+    }
+
+    /** 按 path 坐标裁剪当前瓦片画布。 */
+  }, {
+    key: "clip",
+    value: function clip(context, pointArr) {
+      context.save();
+      context.globalCompositeOperation = 'destination-in';
+      context.beginPath();
+      for (var i = 0; i < pointArr.length; i += 1) {
+        var pointTmp = pointArr[i];
+        for (var j = 0; j < pointTmp.length; j += 1) {
+          if (j === 0) {
+            context.moveTo(pointTmp[j][0], pointTmp[j][1]);
+          } else {
+            context.lineTo(pointTmp[j][0], pointTmp[j][1]);
+          }
+        }
+      }
+      context.closePath();
+      context.fillStyle = '#000000';
+      context.fill();
+      context.restore();
+    }
+
+    /** 输出结构化 debug 事件。 */
+  }, {
+    key: "logDebug",
+    value: function logDebug(event) {
+      if (!this._debug) {
+        return;
+      }
+      var debugEvent = _objectSpread({
+        layerId: this.id
+      }, event);
+      if (typeof this._debug === 'function') {
+        this._debug(debugEvent);
+        return;
+      }
+      console.debug('[CustomRasterLayer]', debugEvent);
+    }
+  }]);
+  return CustomRasterLayer;
+}(ImageryLayer);
+export { CustomRasterLayer as default };