@lijuhong1981/cesium.utils 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# cesium-utils
 
-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.
+Cesium 公共工具库。从 `pci-map-3d` 抽取的、与业务解耦的 Cesium 工具代码。
+
+## 目录结构
+
+```
+src/
+├── index.js          # 库入口
+├── revisions/        # Cesium 类的扩展/补丁（monkey-patch）
+├── parses/           # 值解析工具（字符串/数字 → Cesium 类型）
+├── additions/        # 坐标/矩阵变换族 + Geographic/PropertyType 类型
+└── utils/            # Scratch 缓存 + 通用工具函数
+```
+
+## 使用
+
+本库是 ES Module，`cesium` 作为 peerDependency 由使用方提供（确保扩展与使用方共享同一个 Cesium 实例，monkey-patch 才能全局生效）。
+
+```bash
+npm install @lijuhong1981/cesium.utils cesium
+```
+
+```js
+import * as CesiumUtils from '@lijuhong1981/cesium.utils';
+// 或按需引入
+import { Geographic, parseToCartesian3 } from '@lijuhong1981/cesium.utils';
+```
+
+## 依赖
+
+- `cesium`（peer，`>=1.107.0 <2.0.0`）
+- `@lijuhong1981/jslibs`（伞包，内含 `jsmath` / `jscheck` / `jslib` / `jsdestroy` 等公共包）
+
+## API 文档
+
+文档使用 [JSDoc](https://jsdoc.app/) + [docdash](https://github.com/clenemt/docdash) 生成：
+
+```bash
+npm install
+npm run docs   # 生成到 docs/ 目录
+```
+
+打开 `docs/index.html` 查看。文档覆盖：
+
+- **revisions/**：Cesium 类扩展（`@class` + `@memberof` 归到对应 Cesium 类下）
+- **parses/**：解析函数
+- **additions/**：变换类与 `Geographic` 类型
+- **utils/**：工具函数（`Scratch` 缓存已排除）
+
+## 模块说明
+
+- **revisions/**：25 个 Cesium 类扩展（BoundingSphere、Camera、Cartesian、Matrix、Rectangle 等）。
+- **parses/**：45 个解析函数。
+- **additions/**：`Geographic`、`GeographicTransform`、`ModelMatrixTransforms`、`StTransforms`、`TranslationRotationScaleTransform`、`PropertyChangedListener`、`GeometryInstanceAttributes`、`PropertyType`。
+- **utils/**：`Scratch` + 12 个通用函数。
+
+## 暂未迁入
+
+- `revisions/IntersectionTests.revise.js`：依赖第四层 `PCI3DTileset`，且引用了未定义的 `Check`/`PCI3MXTileset`/`InnerWorker`/`WorkerMessageType`。
+- `revisions/` 中 4 个未导出文件：`Model` / `ModelNode` / `ParticleSystem` / `ScreenSpaceCameraController`。
+- `materials/`、`tiles/`、`defines/` 其余、`draws/`、`primitives/`、`domUI/`、`additions/` 中的业务类。
+- `utils/` 中与媒体播放 / DOM / 部署地址相关的工具。

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@lijuhong1981/cesium.utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Cesium 公共工具库：Cesium 类扩展（revisions）、值解析（parses）、坐标/矩阵变换、通用工具函数",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "docs": "jsdoc -c jsdoc.json"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "cesium",
+    "3d",
+    "gis",
+    "map",
+    "utils"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "cesium": ">=1.107.0 <2.0.0"
+  },
+  "dependencies": {
+    "@lijuhong1981/jslibs": "^1.4.30"
+  },
+  "devDependencies": {
+    "docdash": "^2.0.2",
+    "jsdoc": "^4.0.5"
+  }
+}