@juun-roh/cesium-utils 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +103 -22
  2. package/package.json +17 -12
package/README.md CHANGED
@@ -5,47 +5,128 @@
5
5
  [![Documentation](https://img.shields.io/badge/docs-typedoc-blue)](https://juunie-roh.github.io/cesium-utils/)
6
6
  [![Build Status](https://img.shields.io/github/actions/workflow/status/juunie-roh/cesium-utils/release-and-publish.yml)](https://github.com/juunie-roh/cesium-utils/actions)
7
7
 
8
- A utility library for Cesium.js that simplifies working with collections, terrain providers and highlights.
8
+ **Solve common Cesium.js development challenges** with utilities that provide hybrid terrain providers, entity collection tagging, and visual highlighting systems.
9
9
 
10
- [📚 API Documentation](https://juunie-roh.github.io/cesium-utils/) | [📦 NPM Package](https://www.npmjs.com/package/@juun-roh/cesium-utils) | [▶️ Demonstration](https://juun.vercel.app/cesium-utils)
10
+ ## 🚀 Common Problems This Library Solves
11
+
12
+ ### Multiple Terrain Sources (Hybrid Terrain Provider)
13
+
14
+ **Problem**: Cesium only supports one terrain provider at a time, but you need to combine multiple terrain sources.
15
+ **Solution**: `HybridTerrainProvider` seamlessly blends different terrain providers for different geographic regions.
16
+
17
+ ### Entity Collection Tagging and Filtering
18
+
19
+ **Problem**: Cesium's EntityCollection lacks built-in tagging and filtering capabilities for large datasets.
20
+ **Solution**: `Collection` class adds powerful tagging, filtering, and grouping to entity collections.
11
21
 
12
- ## Installation
22
+ ### Visual Entity Highlighting
13
23
 
14
- This library requires `cesium` to run.
24
+ **Problem**: No built-in way to highlight selected entities with silhouettes or surface effects.
25
+ **Solution**: `SilhouetteHighlight` and `SurfaceHighlight` provide professional visual highlighting systems.
26
+
27
+ [📚 API Documentation](https://juunie-roh.github.io/cesium-utils/) | [📦 NPM Package](https://www.npmjs.com/package/@juun-roh/cesium-utils) | [▶️ Demonstration](https://juun.vercel.app/cesium-utils)
28
+
29
+ ## Quick Start
15
30
 
16
31
  ```bash
17
- # npm
18
32
  npm install @juun-roh/cesium-utils cesium
33
+ ```
19
34
 
20
- # yarn
21
- yarn add @juun-roh/cesium-utils cesium
35
+ ### Hybrid Terrain Provider Example
22
36
 
23
- # pnpm
24
- pnpm add @juun-roh/cesium-utils cesium
37
+ Combine multiple terrain sources for different regions:
38
+
39
+ ```typescript
40
+ import { HybridTerrainProvider } from "@juun-roh/cesium-utils";
41
+
42
+ const terrainProvider = new HybridTerrainProvider({
43
+ regions: [
44
+ {
45
+ provider: highResProvider, // Your detailed terrain
46
+ rectangle: Rectangle.fromDegrees(-122.5, 37.7, -122.3, 37.8) // San Francisco
47
+ },
48
+ {
49
+ provider: globalProvider, // Fallback terrain
50
+ rectangle: Rectangle.MAX_VALUE
51
+ }
52
+ ]
53
+ });
54
+
55
+ viewer.terrainProvider = terrainProvider;
25
56
  ```
26
57
 
27
- ## Browser Compatibility
58
+ ### Entity Collection Tagging Example
28
59
 
29
- This library works in both modern browsers and Node.js environments. It supports:
60
+ Tag and filter entities efficiently:
30
61
 
31
- * ESM (ECMAScript modules)
32
- * CommonJS (via a bundled .cjs file)
62
+ ```typescript
63
+ import { Collection } from "@juun-roh/cesium-utils";
33
64
 
34
- ## Modular Exports
65
+ const buildings = new Collection(viewer.entities, "buildings");
66
+ const parks = new Collection(viewer.entities, "parks");
35
67
 
36
- This library supports modular exports, enabling you to import only the functionality you need rather than the entire package. This helps reduce bundle size and improves build performance by explicitly avoiding unused code.
68
+ // Add tagged entities
69
+ buildings.add({ position: coords, model: buildingModel });
70
+ parks.add({ position: coords, polygon: parkPolygon });
71
+
72
+ // Filter and manipulate by tag
73
+ buildings.show = false; // Hide all buildings
74
+ parks.forEach(entity => entity.polygon.material = Color.GREEN);
75
+ ```
76
+
77
+ ### Entity Highlighting Example
78
+
79
+ Add professional visual highlights:
37
80
 
38
81
  ```typescript
39
- // Import everything from the main package
40
- import { Collection, Highlight, HybridTerrainProvider } from "@juun-roh/cesium-utils";
82
+ import { SilhouetteHighlight } from "@juun-roh/cesium-utils";
41
83
 
42
- // Or import specific modules to minimize bundle size
43
- import { Collection } from "@juun-roh/cesium-utils/collection";
44
- import { Highlight } from "@juun-roh/cesium-utils/highlight";
84
+ const highlight = new SilhouetteHighlight(viewer, {
85
+ color: Color.YELLOW,
86
+ size: 2.0
87
+ });
88
+
89
+ // Highlight an entity
90
+ highlight.add(selectedEntity);
91
+ ```
92
+
93
+ ## API Overview
94
+
95
+ | Feature | Module | Use Case |
96
+ |---------|--------|----------|
97
+ | **HybridTerrainProvider** | `terrain` | Combine multiple terrain sources by region |
98
+ | **Collection** | `collection` | Tag, filter, and group entity collections |
99
+ | **SilhouetteHighlight** | `highlight` | Add silhouette effects to entities |
100
+ | **SurfaceHighlight** | `highlight` | Add surface glow effects to entities |
101
+ | **cloneViewer** | `viewer` | Duplicate viewer configurations |
102
+ | **syncCamera** | `viewer` | Synchronize camera positions between viewers |
103
+
104
+ ## Installation & Import Options
105
+
106
+ ```bash
107
+ npm install @juun-roh/cesium-utils cesium
108
+ yarn add @juun-roh/cesium-utils cesium
109
+ pnpm add @juun-roh/cesium-utils cesium
110
+ ```
111
+
112
+ **Tree-shakable imports** (recommended for smaller bundles):
113
+
114
+ ```typescript
115
+ // Import specific modules
45
116
  import { HybridTerrainProvider } from "@juun-roh/cesium-utils/terrain";
46
- import { cloneViewer, syncCamera } from "@juun-roh/cesium-utils/viewer";
117
+ import { Collection } from "@juun-roh/cesium-utils/collection";
118
+ import { SilhouetteHighlight } from "@juun-roh/cesium-utils/highlight";
47
119
  ```
48
120
 
121
+ **Convenience imports**:
122
+
123
+ ```typescript
124
+ // Import everything
125
+ import { Collection, HybridTerrainProvider, SilhouetteHighlight } from "@juun-roh/cesium-utils";
126
+ ```
127
+
128
+ **ESM and CommonJS support** - works in browsers and Node.js environments.
129
+
49
130
  ## Development Utilities
50
131
 
51
132
  For development and testing purposes, this library provides additional utilities through the `/utils` module. These utilities include deprecation warnings, terrain visualization helpers, and type checking functions.
@@ -57,7 +138,7 @@ import { Deprecate, TerrainVisualizer, isGetterOnly } from "@juun-roh/cesium-uti
57
138
 
58
139
  **Note**: These utilities are intentionally not exported from the main package as they are primarily intended for development, testing, and advanced terrain configuration.
59
140
 
60
- For detailed usage and examples, see [Development Utilities Documentation](src/utils/README.md).
141
+ For detailed usage and examples, see [Development Utilities Documentation](src/dev/README.md).
61
142
 
62
143
  ## Development
63
144
 
package/package.json CHANGED
@@ -1,22 +1,27 @@
1
1
  {
2
2
  "name": "@juun-roh/cesium-utils",
3
- "version": "0.2.2",
4
- "description": "Utilities to handle Cesium classes easier.",
3
+ "version": "0.2.3",
4
+ "description": "Solve common Cesium.js challenges: combine multiple terrain sources, tag and filter entity collections, and add visual highlights.",
5
5
  "keywords": [
6
- "3d",
7
- "3d-gis",
8
6
  "cesium",
9
7
  "cesiumjs",
10
- "collection",
8
+ "cesium-terrain-provider",
9
+ "cesium-entity-collection",
10
+ "cesium-highlight",
11
+ "cesium-utils",
12
+ "hybrid-terrain-provider",
13
+ "multiple-terrain-sources",
14
+ "entity-tagging",
15
+ "entity-filtering",
16
+ "cesium-collection-utilities",
17
+ "terrain-provider-hybrid",
18
+ "cesium-entity-tagging",
19
+ "cesium-terrain-hybrid",
20
+ "3d-gis",
11
21
  "geospatial",
12
- "gis",
13
- "highlight",
22
+ "webgl",
14
23
  "mapping",
15
- "tagged",
16
- "terrain",
17
- "terrain-provider",
18
- "utility",
19
- "webgl"
24
+ "3d-visualization"
20
25
  ],
21
26
  "repository": {
22
27
  "type": "git",