@cn-map/gaode-extra-shared 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Jungzl.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @cn-map/gaode-extra-shared
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+高德地图 Three.js 扩展包（`@cn-map/gaode-*-extra`）共用的底层工具。
+
+## 安装
+
+```bash
+npm install @cn-map/gaode-extra-shared
+```
+
+```bash
+yarn add @cn-map/gaode-extra-shared
+```
+
+```bash
+pnpm add @cn-map/gaode-extra-shared
+```
+
+```bash
+bun add @cn-map/gaode-extra-shared
+```
+
+## 模块
+
+### Canvas 占用
+
+同一张地图的 GL canvas 只允许一个 3D 图层占用，避免多个 Three.js 渲染器争用同一 WebGL 上下文。
+
+```typescript
+import { releaseCanvas, tryAcquireCanvas } from '@cn-map/gaode-extra-shared'
+
+const owner = Symbol('layer')
+
+if (tryAcquireCanvas(map.getGL().canvas, owner)) {
+  // 挂载渲染器
+  releaseCanvas(map.getGL().canvas, owner)
+}
+```
+
+### 地图坐标转换
+
+把经纬度转换为 Three.js 场景坐标，转换使用的 origin 与图层相机保持一致。
+
+```typescript
+import { createMapCoordinates } from '@cn-map/gaode-extra-shared'
+
+const coordinates = createMapCoordinates(map, map.getCenter())
+
+const position = coordinates.lngLatToScene([120.1, 30.1], 12)
+const positions = coordinates.lngLatsToScene([
+  [120.1, 30.1],
+  [120.2, 30.2, 20],
+])
+```
+
+### 相机同步
+
+把 AMap 当前帧的相机参数同步到 Three.js 相机。`2D` 视图必须使用 `OrthographicCamera`，`3D` 视图必须使用 `PerspectiveCamera`；类型不匹配时不写入参数，由调用方决定如何提示。
+
+```typescript
+import { syncMapCamera } from '@cn-map/gaode-extra-shared'
+
+const result = syncMapCamera({
+  map,
+  camera: activeCamera,
+  viewMode: '2D',
+  origin: map.getCenter(),
+})
+
+if (!result.synced) {
+  console.warn(`${result.viewMode} view requires a ${result.expected}`)
+}
+```
+
+## 许可证
+
+[MIT](https://github.com/Jungzl/amap/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import { Camera, OrthographicCamera, PerspectiveCamera } from "three";
+/**
+ * 尝试占用一个共享 canvas（通常是一个 map 的 GL canvas）。
+ * 同一 canvas 只允许一个 3D 图层占用；同一 owner 可以重复占用（例如 HMR）。
+ */
+export declare function tryAcquireCanvas(canvas: object, owner: symbol): boolean;
+/**
+ * 释放 canvas 占用；只有当前 owner 才能释放，避免误删其他图层的占用。
+ */
+export declare function releaseCanvas(canvas: object, owner: symbol): void;
+export declare function getCanvasOwner(canvas: object): symbol | undefined;
+export declare function isPerspectiveCamera(camera: Camera): camera is PerspectiveCamera;
+export declare function isOrthographicCamera(camera: Camera): camera is OrthographicCamera;
+type MapCameraSyncResult = {
+  synced: true;
+} | {
+  synced: false;
+  viewMode: AMap.ViewMode;
+  expected: "PerspectiveCamera" | "OrthographicCamera";
+};
+interface SyncMapCameraOptions {
+  map: AMap.Map;
+  camera: Camera;
+  viewMode: AMap.ViewMode;
+  /**
+   * 图层坐标原点。
+   */
+  origin: AMap.LngLatLike;
+  /**
+   * 默认使用 `map.customCoords`。
+   */
+  customCoords?: AMap.CustomCoords;
+}
+/**
+ * 把 AMap 当前帧的相机参数同步到 Three.js 相机。
+ *
+ * 相机类型必须和 viewMode 匹配：`2D` 使用 `OrthographicCamera`，`3D` 使用 `PerspectiveCamera`。
+ * 类型不匹配时不写入任何参数，返回 `synced: false`，由调用方决定是否提示。
+ */
+export declare function syncMapCamera({ map, camera, viewMode, origin, customCoords }: SyncMapCameraOptions): MapCameraSyncResult;
+type ScenePosition = [number, number, number];
+interface MapCoordinates {
+  /**
+   * The geographic origin used by all conversions.
+   */
+  readonly origin: AMap.LngLatLike;
+  /**
+   * Convert a geographic coordinate to a Three.js scene position.
+   *
+   * `altitude` is mapped to the scene's Z axis. When omitted, a third tuple
+   * element such as `[lng, lat, altitude]` is used.
+   */
+  lngLatToScene: (lnglat: AMap.LngLatLike, altitude?: number) => ScenePosition;
+  /**
+   * Batch convert geographic coordinates to Three.js scene positions.
+   *
+   * When `altitude` is omitted, each tuple's third element is used.
+   */
+  lngLatsToScene: (lnglats: AMap.LngLatLike[], altitude?: number) => ScenePosition[];
+}
+/**
+ * Create a coordinate converter backed by AMap's custom coordinates.
+ *
+ * The converter keeps the same origin as the layer renderer, so scene objects
+ * stay aligned with the map across 2D/3D views, pan, zoom and rotation.
+ */
+export declare function createMapCoordinates(map: AMap.Map, origin: AMap.LngLatLike): MapCoordinates;
+export type { MapCameraSyncResult, MapCoordinates, ScenePosition, SyncMapCameraOptions };

package/dist/index.js

@@ -0,0 +1,116 @@
+import { MathUtils } from "three";
+// src/canvas-ownership.ts
+const canvasOwners = /* @__PURE__ */ new WeakMap();
+/**
+* 尝试占用一个共享 canvas（通常是一个 map 的 GL canvas）。
+* 同一 canvas 只允许一个 3D 图层占用；同一 owner 可以重复占用（例如 HMR）。
+*/
+function tryAcquireCanvas(canvas, owner) {
+	const currentOwner = canvasOwners.get(canvas);
+	if (currentOwner !== void 0 && currentOwner !== owner) return false;
+	canvasOwners.set(canvas, owner);
+	return true;
+}
+/**
+* 释放 canvas 占用；只有当前 owner 才能释放，避免误删其他图层的占用。
+*/
+function releaseCanvas(canvas, owner) {
+	if (canvasOwners.get(canvas) === owner) canvasOwners.delete(canvas);
+}
+function getCanvasOwner(canvas) {
+	return canvasOwners.get(canvas);
+}
+// src/map-camera.ts
+function isPerspectiveCamera(camera) {
+	return camera.isPerspectiveCamera === true;
+}
+function isOrthographicCamera(camera) {
+	return camera.isOrthographicCamera === true;
+}
+/**
+* 把 AMap 当前帧的相机参数同步到 Three.js 相机。
+*
+* 相机类型必须和 viewMode 匹配：`2D` 使用 `OrthographicCamera`，`3D` 使用 `PerspectiveCamera`。
+* 类型不匹配时不写入任何参数，返回 `synced: false`，由调用方决定是否提示。
+*/
+function syncMapCamera({ map, camera, viewMode, origin, customCoords = map.customCoords }) {
+	customCoords.setCenter(origin);
+	if (viewMode === "3D") {
+		if (!isPerspectiveCamera(camera)) return {
+			synced: false,
+			viewMode,
+			expected: "PerspectiveCamera"
+		};
+		const { near, far, fov, up, lookAt, position } = customCoords.getCameraParams();
+		camera.near = near;
+		camera.far = far;
+		camera.fov = fov;
+		camera.position.set(...position);
+		camera.up.set(up[0], up[1], up[2]);
+		camera.lookAt(...lookAt);
+		camera.updateProjectionMatrix();
+		camera.updateMatrixWorld();
+		return { synced: true };
+	}
+	if (!isOrthographicCamera(camera)) return {
+		synced: false,
+		viewMode,
+		expected: "OrthographicCamera"
+	};
+	const { near, far, top, bottom, left, right, position, rotation } = customCoords.getCameraParams();
+	camera.near = near;
+	camera.far = far;
+	camera.top = top;
+	camera.bottom = bottom;
+	camera.left = left;
+	camera.right = right;
+	const [centerX, centerY] = customCoords.lngLatToCoord(map.getCenter());
+	camera.position.set(centerX, centerY, position[2]);
+	camera.up.set(0, 1, 0);
+	camera.lookAt(centerX, centerY, 0);
+	camera.rotation.z = MathUtils.degToRad(rotation);
+	camera.updateProjectionMatrix();
+	camera.updateMatrixWorld();
+	return { synced: true };
+}
+// src/map-coordinates.ts
+function tupleAltitude(lnglat) {
+	if (!Array.isArray(lnglat) || lnglat.length < 3) return void 0;
+	return lnglat[2];
+}
+function resolveAltitude(lnglat, altitude) {
+	return altitude ?? tupleAltitude(lnglat) ?? 0;
+}
+/**
+* Create a coordinate converter backed by AMap's custom coordinates.
+*
+* The converter keeps the same origin as the layer renderer, so scene objects
+* stay aligned with the map across 2D/3D views, pan, zoom and rotation.
+*/
+function createMapCoordinates(map, origin) {
+	const customCoords = map.customCoords;
+	const applyOrigin = () => customCoords.setCenter(origin);
+	return {
+		origin,
+		lngLatToScene(lnglat, altitude) {
+			applyOrigin();
+			const [x, y] = customCoords.lngLatToCoord(lnglat);
+			return [
+				x,
+				y,
+				resolveAltitude(lnglat, altitude)
+			];
+		},
+		lngLatsToScene(lnglats, altitude) {
+			applyOrigin();
+			return customCoords.lngLatsToCoords(lnglats).map(([x, y], index) => {
+				return [
+					x,
+					y,
+					resolveAltitude(lnglats[index], altitude)
+				];
+			});
+		}
+	};
+}
+export { createMapCoordinates, getCanvasOwner, isOrthographicCamera, isPerspectiveCamera, releaseCanvas, syncMapCamera, tryAcquireCanvas };

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@cn-map/gaode-extra-shared",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "高德地图 Three.js 扩展包共享代码",
+  "keywords": [
+    "amap",
+    "three",
+    "高德",
+    "高德地图"
+  ],
+  "bugs": {
+    "url": "https://gtihub.com/Jungzl/amap/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jungzl/amap.git",
+    "directory": "packages/extra-shared"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@cn-map/gaode-types": "^2.1.0",
+    "@types/three": "0.162.0",
+    "three": "0.162.0",
+    "vitest": "^5.1.0"
+  },
+  "peerDependencies": {
+    "@cn-map/gaode-types": "^2.0.0",
+    "@types/three": "<=0.162.0",
+    "three": "<=0.162.0"
+  },
+  "peerDependenciesMeta": {
+    "@cn-map/gaode-types": {
+      "optional": true
+    },
+    "@types/three": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "check:type": "tsc",
+    "test": "vitest run",
+    "test:unit": "vitest run -p unit",
+    "test:coverage": "vitest run --coverage --bail=1"
+  }
 }