@juun-roh/cesium-utils 0.0.2 → 0.0.4

package/README.md

@@ -13,13 +13,13 @@ A utility library for Cesium.js that simplifies working with collections and ter
 
 ```bash
 # npm
-npm install @juun_roh/cesium-utils
+npm install @juun-roh/cesium-utils
 
 # yarn
-yarn add @juun_roh/cesium-utils
+yarn add @juun-roh/cesium-utils
 
 # pnpm
-pnpm add @juun_roh/cesium-utils
+pnpm add @juun-roh/cesium-utils
 ```
 
 ## Browser Compatibility

package/dist/chunk-4XCQZPKH.js

@@ -0,0 +1 @@
+import{defined as r,EntityCollection as g}from"cesium";var l=class n{static symbol=Symbol("cesium-item-tag");tag;collection;_valuesCache=null;_tagMap=new Map;_eventListeners=new Map;constructor({collection:t,tag:e}){this.tag=e||"default",this.collection=t}_emit(t,e){let i=this._eventListeners.get(t);if(i){let a={type:t,...e};i.forEach(s=>s(a))}}_addToTagMap(t,e){this._tagMap.has(e)||this._tagMap.set(e,new Set),this._tagMap.get(e)?.add(t)}_removeFromTagMap(t){let e=t[n.symbol],i=this._tagMap.get(e);i&&(i.delete(t),i.size===0&&this._tagMap.delete(e))}_invalidateCache(){this._valuesCache=null}addEventListener(t,e){return this._eventListeners.has(t)||this._eventListeners.set(t,new Set),this._eventListeners.get(t)?.add(e),this}removeEventListener(t,e){return this._eventListeners.get(t)?.delete(e),this}add(t,e=this.tag,i){return Array.isArray(t)?t.forEach(a=>{this.add(a)}):(Object.defineProperty(t,n.symbol,{value:e,enumerable:!1,writable:!0,configurable:!0}),this.collection.add(t,i),this._addToTagMap(t,e),this._invalidateCache(),this._emit("add",{items:[t],tag:e})),t}contains(t){return this.collection.contains(t)}remove(t){let e=this.collection.remove(t);return e&&(this._removeFromTagMap(t),this._invalidateCache(),this._emit("remove",{items:[t]})),e}removeAll(){this._tagMap.clear(),this.collection.removeAll(),this._invalidateCache(),this._emit("clear")}get values(){if(this._valuesCache)return this._valuesCache;if(this.collection instanceof g)this._valuesCache=this.collection.values||[];else{let t=[];for(let e=0;e<this.collection.length;e++)t.push(this.collection.get(e));this._valuesCache=t}return this._valuesCache}get length(){return this.values?.length||0}getByTag(t){let e=this._tagMap.get(t);return e?Array.from(e):[]}getFirstByTag(t){let e=this._tagMap.get(t);if(e&&e.size>0)return e.values().next().value}getTags(){return Array.from(this._tagMap.keys())}hasTag(t){let e=this._tagMap.get(t);return!!e&&e.size>0}updateTag(t,e){let i=this.getByTag(t);for(let a of i)this._removeFromTagMap(a),Object.defineProperty(a,n.symbol,e),this._addToTagMap(a,e);return i.length>0&&this._emit("update",{items:i,tag:e}),i.length}removeByTag(t){let e=0;return Array.isArray(t)?t.forEach(i=>{this.removeByTag(i)}):this.getByTag(t).forEach(i=>{this.remove(i)&&e++}),e}show(t){let e=this.getByTag(t),i=0;for(let a of e)r(a.show)&&(a.show=!0,i++);return i}hide(t){let e=this.getByTag(t),i=0;for(let a of e)r(a.show)&&(a.show=!1,i++);return i}toggle(t){let e=this.getByTag(t),i=0;for(let a of e)r(a.show)&&(a.show=!a.show,i++);return i}setProperty(t,e,i){let a=this.getByTag(t),s=0;for(let o of a)e in o?(o[e]=i,s++):console.warn(`${e} does not exists in ${o}`);return s}filter(t,e){return(e?this.getByTag(e):this.values).filter(t)}forEach(t,e){(e?this.getByTag(e):this.values).forEach((a,s)=>t(a,s))}},c=l;export{c as a};

package/dist/chunk-C52KJ2WP.js

@@ -0,0 +1 @@
+import{GeographicTilingScheme as h,Rectangle as c}from"cesium";var o=class{_rectangle;_tilingScheme;_tileRanges;_levels;constructor(e,r){if(this._tilingScheme=r||new h,this._rectangle=new c,this._tileRanges=new Map,this._levels=new Set,e.type==="rectangle"&&e.rectangle)this._rectangle=c.clone(e.rectangle);else if(e.type==="tileRange"&&e.tileRanges)e.tileRanges instanceof Map?this._tileRanges=new Map(e.tileRanges):this._tileRanges=new Map(Object.entries(e.tileRanges).map(([t,i])=>[parseInt(t),i])),this._calculateRectangleFromTileRanges();else throw new Error("Either rectangle or tileRanges must be provided.");this._levels=new Set(Array.from(this._tileRanges.keys()))}contains(e,r,t){if(this._tileRanges.has(t)){let a=this._tileRanges.get(t);return e>=a.start.x&&e<=a.end.x&&r>=a.start.y&&r<=a.end.y}let i=this._tilingScheme.tileXYToRectangle(e,r,t);return c.intersection(i,this._rectangle)!==void 0}configureAvailability(e){if(e.availability){e.availability._tilingScheme&&(e.availability._tilingScheme=this._tilingScheme);for(let[r,t]of this._tileRanges.entries())e.availability.addAvailableTileRange(r,t.start.x,t.start.y,t.end.x,t.end.y)}}get rectangle(){return this._rectangle}get tilingScheme(){return this._tilingScheme}get tileRanges(){return this._tileRanges}get levels(){return this._levels}_calculateRectangleFromTileRanges(){let e=Number.POSITIVE_INFINITY,r=Number.POSITIVE_INFINITY,t=Number.NEGATIVE_INFINITY,i=Number.NEGATIVE_INFINITY,a=Array.from(this._tileRanges.keys());if(a.length===0){this._rectangle=c.MAX_VALUE;return}let n=Math.min(...a),u=this._tileRanges.get(n);if(u){let{start:m,end:v}=u,b=this._tilingScheme.tileXYToRectangle(m.x,m.y,n),T=this._tilingScheme.tileXYToRectangle(v.x,v.y,n);e=Math.min(b.west,e),r=Math.min(T.south,r),t=Math.max(T.east,t),i=Math.max(b.north,i)}this._rectangle=new c(e,r,t,i)}};(r=>{function l(t,i,a,n=new h){let u=new Map;return u.set(a,{start:{x:t,y:i},end:{x:t,y:i}}),new r({type:"tileRange",tileRanges:u},n)}r.fromTile=l;function e(t,i=new h){return new r({type:"rectangle",rectangle:c.clone(t)},i)}r.fromRectangle=e})(o||={});import{CesiumTerrainProvider as p}from"cesium";var s=class l{_provider;_bounds;_levels;_ready=!1;_credit;_isCustom;constructor(e,r){this._bounds=e.bounds instanceof o?e.bounds:new o(e.bounds),this._levels=new Set(e.levels||[]),this._credit=e.credit||"custom",this._isCustom=e.isCustom!==void 0?e.isCustom:!0,this._provider=r,this._ready=!0,this._bounds.configureAvailability(this._provider)}static async create(e){let r;return typeof e.provider=="string"?r=await p.fromUrl(e.provider,{requestVertexNormals:!0,credit:e.credit||"custom"}):r=e.provider,new l(e,r)}contains(e,r,t){return this._levels.size>0&&!this._levels.has(t)?!1:this._bounds.contains(e,r,t)}requestTileGeometry(e,r,t,i){if(!(!this._ready||!this.contains(e,r,t)||!this._provider?.getTileDataAvailable(e,r,t)))return this._provider.requestTileGeometry(e,r,t,i)}getTileDataAvailable(e,r,t){return!this.contains(e,r,t)||!this._ready?!1:this._provider?.getTileDataAvailable(e,r,t)??!1}get isCustom(){return this._isCustom}get credit(){return this._credit}get provider(){return this._provider}get bounds(){return this._bounds}get levels(){return this._levels}get ready(){return this._ready}};(e=>{async function l(r,t,i,a="custom"){let n=new o({type:"tileRange",tileRanges:t});return await e.create({provider:r,bounds:n,levels:i||Object.keys(t).map(m=>parseInt(m)),credit:a})}e.fromUrl=l})(s||={});var d=class extends Array{async add(e){let r;return e instanceof s?r=e:r=await s.create(e),this.push(r)}remove(e){let r=this.indexOf(e);return r>=0?(this.splice(r,1),!0):!1}clear(){this.length=0}};import{CesiumTerrainProvider as _,EllipsoidTerrainProvider as f,GeographicTilingScheme as P}from"cesium";var g=class l{_terrainAreas=new d;_terrainProvider;_fallbackProvider;_tilingScheme;_ready=!1;_availability;constructor(e,r,t){this._terrainProvider=e,this._fallbackProvider=r,this._tilingScheme=e.tilingScheme||new P,this._terrainAreas=new d(...t),this._availability=e.availability,this._ready=!0}static async create(e){try{let r;typeof e.terrainProvider=="string"?r=await _.fromUrl(e.terrainProvider,{requestVertexNormals:!0}):r=e.terrainProvider;let t;e.fallbackProvider?typeof e.fallbackProvider=="string"?t=await _.fromUrl(e.fallbackProvider,{requestVertexNormals:!0}):t=e.fallbackProvider:t=new f;let i=[];for(let a of e.terrainAreas){let n=await s.create(a);i.push(n)}return new l(r,t,i)}catch(r){throw console.error("Failed to initialize HybridTerrainProvider:",r),r}}get ready(){return this._ready}get tilingScheme(){return this._tilingScheme}get availability(){return this._availability}get terrainAreas(){return[...this._terrainAreas]}get defaultProvider(){return this._terrainProvider}get fallbackProvider(){return this._fallbackProvider}get credit(){return this._terrainProvider?.credit}get errorEvent(){return this._terrainProvider.errorEvent}get hasWaterMask(){return this._terrainProvider.hasWaterMask}get hasVertexNormals(){return this._terrainProvider.hasVertexNormals}loadTileDataAvailability(e,r,t){return this._terrainProvider.loadTileDataAvailability(e,r,t)}getLevelMaximumGeometricError(e){return this._terrainProvider.getLevelMaximumGeometricError(e)}requestTileGeometry(e,r,t,i){if(this._ready){for(let a of this._terrainAreas)if(a.contains(e,r,t))return a.requestTileGeometry(e,r,t,i);return this._terrainProvider.getTileDataAvailable(e,r,t)?this._terrainProvider.requestTileGeometry(e,r,t,i):this._fallbackProvider.requestTileGeometry(e,r,t,i)}}getTileDataAvailable(e,r,t){return this._terrainAreas.forEach(i=>{if(i.contains(e,r,t)&&i.getTileDataAvailable(e,r,t))return!0}),this._terrainProvider.getTileDataAvailable(e,r,t)||!0}};(e=>{async function l(r,t,i,a){return e.create({terrainAreas:[{provider:r,bounds:{type:"tileRange",tileRanges:i},levels:a||Object.keys(i).map(n=>parseInt(n)),credit:"custom"}],terrainProvider:t,fallbackProvider:new f})}e.createOverlay=l})(g||={});export{o as a,s as b,d as c,g as d};

package/dist/chunk-H3FSQZZE.js

@@ -0,0 +1 @@
+import{a as w}from"./chunk-4XCQZPKH.js";import{Color as l,Entity as P,HeightReference as V,Rectangle as E,TileCoordinatesImageryProvider as O}from"cesium";var b=class u{_viewer;_collection;_hybridTerrain;_visible=!1;_level=15;_tileCoordinatesLayer;_colors=new Map([["custom",l.RED],["default",l.BLUE],["fallback",l.GRAY],["grid",l.YELLOW]]);constructor(i,t){this._viewer=i,this._collection=new w({collection:i.entities,tag:u.tag.default}),t&&(t.colors&&Object.entries(t.colors).forEach(([o,r])=>{this._colors.set(o,r)}),t.tile!==void 0&&(this._visible=t.tile),t.activeLevel!==void 0&&(this._level=t.activeLevel),t.terrainProvider&&this.setTerrainProvider(t.terrainProvider))}setTerrainProvider(i){this._hybridTerrain=i,this.update()}update(){this.clear(),this._visible&&this.show(this._level)}clear(){this._collection.removeByTag(this._collection.getTags())}show(i=15){if(!this._hybridTerrain)return;this._collection.removeByTag(u.tag.grid),this._level=i;let t=this._hybridTerrain.tilingScheme;this._tileCoordinatesLayer||(this._tileCoordinatesLayer=this._viewer.imageryLayers.addImageryProvider(new O({tilingScheme:t,color:l.YELLOW})));let o=(e,n,d)=>{if(this._hybridTerrain){for(let h of this._hybridTerrain.terrainAreas)if(h.contains(e,n,d))return h.isCustom?this._colors.get("custom")||l.RED:this._colors.get("default")||l.BLUE;if(this._hybridTerrain.getTileDataAvailable(e,n,d))return this._colors.get("default")||l.BLUE}return this._colors.get("fallback")||l.TRANSPARENT},r=this._getVisibleRectangle();if(!r)return;function g(e){return e&&Number.isFinite(e.west)&&Number.isFinite(e.south)&&Number.isFinite(e.east)&&Number.isFinite(e.north)&&e.west<=e.east&&e.south<=e.north}if(!g(r)){console.warn("Invalid visible rectangle detected, skipping grid display");return}try{let e=t.positionToTileXY(E.northwest(r),i),n=t.positionToTileXY(E.southeast(r),i);if(!e||!n)return;let d=100,h=Math.min(n.x-e.x+1,d),m=Math.min(n.y-e.y+1,d);for(let s=e.x;s<=e.x+h-1;s++)for(let c=e.y;c<=e.y+m-1;c++)try{let a=t.tileXYToRectangle(s,c,i);if(!g(a)){console.warn(`Invalid rectangle for tile (${s}, ${c}, ${i}), skipping`);continue}let y=o(s,c,i),v=u.createRectangle(a,y.withAlpha(.3));v.properties?.addProperty("tileX",s),v.properties?.addProperty("tileY",c),v.properties?.addProperty("tileLevel",i),this._collection.add(v,u.tag.grid)}catch(a){console.warn(`Error creating tile (${s}, ${c}, ${i}): ${a.message}`);continue}console.log("\u{1F680} ~ TerrainVisualizer ~ showGrid ~ collection:",this._collection),this._visible=!0}catch(e){console.error("Error displaying tile grid:",e)}}hide(){this._collection.removeByTag(u.tag.grid),this._tileCoordinatesLayer&&(this._viewer.imageryLayers.remove(this._tileCoordinatesLayer),this._tileCoordinatesLayer=void 0),this._visible=!1}setColors(i){Object.entries(i).forEach(([t,o])=>{this._colors.set(t,o)}),this.update()}flyTo(i,t){let{rectangle:o}=i.bounds;this._viewer.camera.flyTo({destination:o,...t,complete:()=>{this._visible&&this.update()}})}_getVisibleRectangle(){return this._viewer.camera.computeViewRectangle()}get level(){return this._level}set level(i){this._level=i,this._visible&&this.update()}get visible(){return this._visible}get collection(){return this._collection}get viewer(){return this._viewer}};(o=>{o.tag={default:"Terrain Visualizer",boundary:"Terrain Visualizer Boundary",grid:"Terrain Visualizer Tile Grid"};function i(r,g){return new P({rectangle:{coordinates:r,material:g,heightReference:V.CLAMP_TO_GROUND}})}o.createRectangle=i;function t(r,g,e){let n=e?.tag||"terrain_area_visualization",d=e?.color||l.RED,h=e?.maxTilesToShow||100,m=e?.show??!0,s=e?.alpha||.7,c=e?.tileAlpha||.2,a="provider"in r?r.bounds:r,y=new w({collection:g.entities,tag:n}),{rectangle:v}=a;if(y.add(o.createRectangle(v,d.withAlpha(s)),n),m&&a.levels.size>0){let{tilingScheme:R}=a;a.levels.forEach(C=>{let _=0,{tileRanges:L}=a;for(let[x,f]of L.entries())if(x===C)for(let p=f.start.x;p<=f.end.x&&_<h;p++)for(let T=f.start.y;T<=f.end.y&&_<h;T++){let A=R.tileXYToRectangle(p,T,C);y.add(i(A,d.withAlpha(c)),`${n}_tile`),_++}})}return y}o.visualize=t})(b||={});export{b as a};

package/dist/chunk-STARYORM.js

@@ -0,0 +1 @@
+import{a as r}from"./chunk-YZ7AUGIO.js";import{Viewer as d}from"cesium";function f(e,a,c){let m={baseLayerPicker:e.baseLayerPicker!==void 0,geocoder:e.geocoder!==void 0,homeButton:e.homeButton!==void 0,sceneModePicker:e.sceneModePicker!==void 0,timeline:e.timeline!==void 0,navigationHelpButton:e.navigationHelpButton!==void 0,animation:e.animation!==void 0,fullscreenButton:e.fullscreenButton!==void 0,shouldAnimate:e.clock.shouldAnimate,terrainProvider:e.terrainProvider,requestRenderMode:e.scene.requestRenderMode,infoBox:e.infoBox!==void 0},n=new d(a,{...m,...c});r(e,n);let l=e.imageryLayers;n.imageryLayers.removeAll();for(let o=0;o<l.length;o++){let s=l.get(o);n.imageryLayers.addImageryProvider(s.imageryProvider,o)}n.clock.startTime=e.clock.startTime.clone(),n.clock.stopTime=e.clock.stopTime.clone(),n.clock.currentTime=e.clock.currentTime.clone(),n.clock.multiplier=e.clock.multiplier,n.clock.clockStep=e.clock.clockStep,n.clock.clockRange=e.clock.clockRange,n.clock.shouldAnimate=e.clock.shouldAnimate,n.scene.globe.enableLighting=e.scene.globe.enableLighting,n.scene.globe.depthTestAgainstTerrain=e.scene.globe.depthTestAgainstTerrain,n.scene.screenSpaceCameraController.enableCollisionDetection=e.scene.screenSpaceCameraController.enableCollisionDetection;let t=e.scene.screenSpaceCameraController.tiltEventTypes;t&&(n.scene.screenSpaceCameraController.tiltEventTypes=Array.isArray(t)?[...t]:t);let i=e.scene.screenSpaceCameraController.zoomEventTypes;return i&&(n.scene.screenSpaceCameraController.zoomEventTypes=Array.isArray(i)?[...i]:i),n}export{f as a};

package/dist/chunk-YZ7AUGIO.js

@@ -0,0 +1 @@
+import{defined as n}from"cesium";function a(o,e){if(n(o)&&n(e)){let{camera:i}=o;e.camera.position=i.positionWC.clone(),e.camera.direction=i.directionWC.clone(),e.camera.up=i.upWC.clone()}}export{a};

package/dist/collection/index.cjs

@@ -0,0 +1 @@
+"use strict";var l=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var d=(s,e)=>{for(var t in e)l(s,t,{get:e[t],enumerable:!0})},v=(s,e,t,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let a of m(e))!u.call(s,a)&&a!==t&&l(s,a,{get:()=>e[a],enumerable:!(i=c(e,a))||i.enumerable});return s};var T=s=>v(l({},"__esModule",{value:!0}),s);var f={};d(f,{Collection:()=>h});module.exports=T(f);var n=require("cesium"),g=class s{static symbol=Symbol("cesium-item-tag");tag;collection;_valuesCache=null;_tagMap=new Map;_eventListeners=new Map;constructor({collection:e,tag:t}){this.tag=t||"default",this.collection=e}_emit(e,t){let i=this._eventListeners.get(e);if(i){let a={type:e,...t};i.forEach(o=>o(a))}}_addToTagMap(e,t){this._tagMap.has(t)||this._tagMap.set(t,new Set),this._tagMap.get(t)?.add(e)}_removeFromTagMap(e){let t=e[s.symbol],i=this._tagMap.get(t);i&&(i.delete(e),i.size===0&&this._tagMap.delete(t))}_invalidateCache(){this._valuesCache=null}addEventListener(e,t){return this._eventListeners.has(e)||this._eventListeners.set(e,new Set),this._eventListeners.get(e)?.add(t),this}removeEventListener(e,t){return this._eventListeners.get(e)?.delete(t),this}add(e,t=this.tag,i){return Array.isArray(e)?e.forEach(a=>{this.add(a)}):(Object.defineProperty(e,s.symbol,{value:t,enumerable:!1,writable:!0,configurable:!0}),this.collection.add(e,i),this._addToTagMap(e,t),this._invalidateCache(),this._emit("add",{items:[e],tag:t})),e}contains(e){return this.collection.contains(e)}remove(e){let t=this.collection.remove(e);return t&&(this._removeFromTagMap(e),this._invalidateCache(),this._emit("remove",{items:[e]})),t}removeAll(){this._tagMap.clear(),this.collection.removeAll(),this._invalidateCache(),this._emit("clear")}get values(){if(this._valuesCache)return this._valuesCache;if(this.collection instanceof n.EntityCollection)this._valuesCache=this.collection.values||[];else{let e=[];for(let t=0;t<this.collection.length;t++)e.push(this.collection.get(t));this._valuesCache=e}return this._valuesCache}get length(){return this.values?.length||0}getByTag(e){let t=this._tagMap.get(e);return t?Array.from(t):[]}getFirstByTag(e){let t=this._tagMap.get(e);if(t&&t.size>0)return t.values().next().value}getTags(){return Array.from(this._tagMap.keys())}hasTag(e){let t=this._tagMap.get(e);return!!t&&t.size>0}updateTag(e,t){let i=this.getByTag(e);for(let a of i)this._removeFromTagMap(a),Object.defineProperty(a,s.symbol,t),this._addToTagMap(a,t);return i.length>0&&this._emit("update",{items:i,tag:t}),i.length}removeByTag(e){let t=0;return Array.isArray(e)?e.forEach(i=>{this.removeByTag(i)}):this.getByTag(e).forEach(i=>{this.remove(i)&&t++}),t}show(e){let t=this.getByTag(e),i=0;for(let a of t)(0,n.defined)(a.show)&&(a.show=!0,i++);return i}hide(e){let t=this.getByTag(e),i=0;for(let a of t)(0,n.defined)(a.show)&&(a.show=!1,i++);return i}toggle(e){let t=this.getByTag(e),i=0;for(let a of t)(0,n.defined)(a.show)&&(a.show=!a.show,i++);return i}setProperty(e,t,i){let a=this.getByTag(e),o=0;for(let r of a)t in r?(r[t]=i,o++):console.warn(`${t} does not exists in ${r}`);return o}filter(e,t){return(t?this.getByTag(t):this.values).filter(e)}forEach(e,t){(t?this.getByTag(t):this.values).forEach((a,o)=>e(a,o))}},h=g;

package/dist/collection/index.d.cts

@@ -0,0 +1,363 @@
+import { BillboardCollection, DataSourceCollection, EntityCollection, ImageryLayerCollection, LabelCollection, PointPrimitiveCollection, PolylineCollection, PrimitiveCollection, Billboard, DataSource, Entity, ImageryLayer, Label, PointPrimitive, Polyline, Primitive, Cesium3DTileset, GroundPrimitive } from 'cesium';
+
+type CesiumCollection = BillboardCollection | DataSourceCollection | EntityCollection | ImageryLayerCollection | LabelCollection | PointPrimitiveCollection | PolylineCollection | PrimitiveCollection;
+type Primitives = Primitive | Cesium3DTileset | GroundPrimitive;
+type CesiumCollectionItem = Billboard | DataSource | Entity | ImageryLayer | Label | PointPrimitive | Polyline | Primitives;
+type Tag = string | number;
+interface WithTag {
+    [key: symbol]: Tag;
+}
+/**
+ * Collection event types
+ */
+type CollectionEventType = 'add' | 'remove' | 'update' | 'clear';
+/**
+ * Event handler function type
+ */
+type EventHandler<I> = (event: {
+    type: CollectionEventType;
+    items?: I[];
+    tag?: Tag;
+}) => void;
+
+/**
+ * @class
+ * Abstract class that enhances Cesium collection objects with tagging functionality.
+ * This class provides a consistent API for working with different types of Cesium collections
+ * and allows grouping and manipulating collection items by custom tags.
+ *
+ * @template C - The type of Cesium collection (e.g., EntityCollection, PrimitiveCollection)
+ * @template I - The type of items in the collection (e.g., Entity, Primitive)
+ *
+ * @example
+ * // Creating a specialized collection for entities
+ * class MyEntities extends Collection<EntityCollection, Entity> {
+ *   constructor(viewer) {
+ *     super({ collection: viewer.entities, tag: 'myEntities' });
+ *   }
+ *
+ *   get values() {
+ *     return this.collection.values;
+ *   }
+ * }
+ *
+ * const entities = new MyEntities(viewer);
+ * entities.add(new Entity({ ... }), 'buildings');
+ * entities.add(new Entity({ ... }), 'roads');
+ *
+ * // Later, show only buildings
+ * entities.show('buildings');
+ * entities.hide('roads');
+ */
+declare class Collection<C extends CesiumCollection, I extends CesiumCollectionItem> {
+    /**
+     * Symbol used as a property key to store tags on collection items.
+     * Using a Symbol ensures no property naming conflicts with the item's own properties.
+     * @readonly
+     */
+    static readonly symbol: unique symbol;
+    /**
+     * Default tag used when adding items without specifying a tag.
+     * @protected
+     */
+    protected tag: Tag;
+    /**
+     * The underlying Cesium collection being wrapped.
+     * @protected
+     */
+    protected collection: C;
+    /**
+     * Cache for values array to improve performance
+     * @private
+     */
+    private _valuesCache;
+    /**
+     * Tag to items map for faster lookups
+     * @private
+     */
+    private _tagMap;
+    /**
+     * Event listeners
+     * @private
+     */
+    private _eventListeners;
+    /**
+     * Creates a new Collection instance.
+     *
+     * @param options - Configuration options
+     * @param options.collection - The Cesium collection to wrap
+     * @param options.tag - The default tag to use for items (defaults to 'default')
+     */
+    constructor({ collection, tag }: {
+        collection: C;
+        tag?: Tag;
+    });
+    /**
+     * Emits an event to all registered listeners.
+     *
+     * @private
+     * @param type - The event type
+     * @param data - Additional event data
+     */
+    private _emit;
+    /**
+     * Adds an item to the internal tag map for quick lookups.
+     *
+     * @private
+     * @param item - The item to add
+     * @param tag - The tag to associate with the item
+     */
+    private _addToTagMap;
+    /**
+     * Removes an item from the internal tag map.
+     *
+     * @private
+     * @param item - The item to remove
+     */
+    private _removeFromTagMap;
+    /**
+     * Invalidates the values cache when collection changes.
+     *
+     * @private
+     */
+    private _invalidateCache;
+    /**
+     * Registers an event listener for collection events.
+     *
+     * @param type - The event type to listen for
+     * @param handler - The callback function
+     * @returns The collection instance for method chaining
+     */
+    addEventListener(type: CollectionEventType, handler: EventHandler<I>): this;
+    /**
+     * Removes an event listener.
+     *
+     * @param type - The event type
+     * @param handler - The callback function to remove
+     * @returns The collection instance for method chaining
+     */
+    removeEventListener(type: CollectionEventType, handler: EventHandler<I>): this;
+    /**
+     * Adds a single item with a tag to the collection.
+     *
+     * @param item - The item to add to the collection
+     * @param tag - Tag to associate with this item (defaults to the collection's default tag)
+     * @param index - The index to add the item at (if supported by the collection)
+     * @returns The added item for chaining
+     *
+     * @example
+     * const entity = collection.add(new Entity({ ... }), 'landmarks');
+     */
+    add(item: I, tag?: Tag, index?: number): I;
+    /**
+     * Adds multiple items with the same tag to the collection.
+     *
+     * @param items - The array of items to add to the collection
+     * @param tag - Tag to associate with this item (defaults to the collection's default tag)
+     * @returns The array of added items
+     *
+     * @example
+     * // Add multiple entities with the same tag
+     * const entities = [new Entity({ ... }), new Entity({ ... })];
+     * const addedEntities = collection.add(entities, 'buildings');
+     */
+    add(items: I[], tag?: Tag): I[];
+    /**
+     * Returns true if the provided item is in this collection, false otherwise.
+     *
+     * @param item - The item to check for
+     * @returns True if the item is in the collection, false otherwise
+     */
+    contains(item: I): boolean;
+    /**
+     * Removes an item from the collection.
+     *
+     * @param item - The item to remove
+     * @returns True if the item was removed, false if it wasn't found
+     */
+    remove(item: I & WithTag): boolean;
+    /**
+     * Removes all items from the collection.
+     */
+    removeAll(): void;
+    /**
+     * Gets all item instances in the collection.
+     * This array should not be modified directly.
+     *
+     * @returns An array of all items in the collection
+     */
+    get values(): I[];
+    /**
+     * Gets the number of items in the collection.
+     *
+     * @returns The item count
+     */
+    get length(): number;
+    /**
+     * Gets all items with the specified tag from the collection.
+     * Uses an optimized internal map for faster lookups.
+     *
+     * @param tag - The tag to filter by
+     * @returns An array of items with the specified tag, or an empty array if none found
+     *
+     * @example
+     * // Get all buildings
+     * const buildings = collection.getByTag('buildings');
+     */
+    getByTag(tag: Tag): I[];
+    /**
+     * Gets the first item matching the tag. More efficient than getByTag when
+     * you only need one item, especially for large collections.
+     *
+     * @param tag - The tag to search for
+     * @returns The first matching item or undefined if none found
+     *
+     * @example
+     * // Get the first building
+     * const firstBuilding = collection.getFirstByTag('buildings');
+     */
+    getFirstByTag(tag: Tag): I | undefined;
+    /**
+     * Gets all unique tags currently in use in the collection.
+     *
+     * @returns An array of all unique tags
+     *
+     * @example
+     * // Get all tags
+     * const tags = collection.getTags();
+     * console.log(`Collection has these tags: ${tags.join(', ')}`);
+     */
+    getTags(): Tag[];
+    /**
+     * Checks if the collection has any items with the specified tag.
+     *
+     * @param tag - The tag to check for
+     * @returns True if items with the tag exist, false otherwise
+     *
+     * @example
+     * if (collection.hasTag('temporary')) {
+     *   console.log('Temporary items exist');
+     * }
+     */
+    hasTag(tag: Tag): boolean;
+    /**
+     * Updates the tag for all items with the specified tag.
+     *
+     * @param oldTag - The tag to replace
+     * @param newTag - The new tag to assign
+     * @returns The number of items updated
+     *
+     * @example
+     * // Rename a tag
+     * const count = collection.updateTag('temp', 'temporary');
+     * console.log(`Updated ${count} items`);
+     */
+    updateTag(oldTag: Tag, newTag: Tag): number;
+    /**
+     * Removes all items with the specified tag from the collection.
+     *
+     * @param tag - The tag identifying which items to remove
+     * @returns The number of items removed
+     *
+     * @example
+     * // Remove all temporary markers
+     * const count = collection.removeByTag('temporary');
+     * console.log(`Removed ${count} items`);
+     */
+    removeByTag(tag: Tag): number;
+    /**
+     * Removes all items with the array of tags from the collection.
+     *
+     * @param tag - The tags identifying which items to remove
+     * @returns The number of items removed
+     *
+     * @example
+     * // Remove all items containing tags
+     * const count = collection.removeByTag('temporary', 'default', 'tag');
+     * console.log(`Removed ${count} items`);
+     */
+    removeByTag(tag: Tag[]): number;
+    /**
+     * Makes all items with the specified tag visible.
+     * Only affects items that have a 'show' property.
+     *
+     * @param tag - The tag identifying which items to show
+     * @returns The number of items affected
+     *
+     * @example
+     * // Show all buildings
+     * collection.show('buildings');
+     */
+    show(tag: Tag): number;
+    /**
+     * Hides all items with the specified tag.
+     * Only affects items that have a 'show' property.
+     *
+     * @param tag - The tag identifying which items to hide
+     * @returns The number of items affected
+     *
+     * @example
+     * // Hide all buildings
+     * collection.hide('buildings');
+     */
+    hide(tag: Tag): number;
+    /**
+     * Toggles visibility of all items with the specified tag.
+     * Only affects items that have a 'show' property.
+     *
+     * @param tag - The tag identifying which items to toggle
+     * @returns The number of items affected
+     *
+     * @example
+     * // Toggle visibility of all buildings
+     * collection.toggle('buildings');
+     */
+    toggle(tag: Tag): number;
+    /**
+     * Sets a property value on all items with the specified tag.
+     *
+     * @param tag - The tag identifying which items to update
+     * @param property - The property name to set
+     * @param value - The value to set
+     * @returns The number of items updated
+     *
+     * @example
+     * // Change color of all buildings to red
+     * collection.setProperty('buildings', 'color', Color.RED);
+     */
+    setProperty<K extends string, V>(tag: Tag, property: K, value: V): number;
+    /**
+     * Filters items in the collection based on a predicate function.
+     * Optionally only filters items with a specific tag.
+     *
+     * @param predicate - Function that tests each item
+     * @param tag - Optional tag to filter by before applying the predicate
+     * @returns Array of items that pass the test
+     *
+     * @example
+     * // Get all buildings taller than 100 meters
+     * const tallBuildings = collection.filter(
+     *   entity => entity.properties?.height?.getValue() > 100,
+     *   'buildings'
+     * );
+     */
+    filter(predicate: (item: I) => boolean, tag?: Tag): I[];
+    /**
+     * Executes a callback function for each item in the collection.
+     * Optionally filters items by tag before execution.
+     *
+     * @param callback - Function to execute for each item
+     * @param tag - Optional tag to filter items (if not provided, processes all items)
+     *
+     * @example
+     * // Highlight all buildings
+     * collection.forEach((entity) => {
+     *   if (entity.polygon) {
+     *     entity.polygon.material = new ColorMaterialProperty(Color.YELLOW);
+     *   }
+     * }, 'buildings');
+     */
+    forEach(callback: (item: I, index: number) => void, tag?: Tag): void;
+}
+
+export { type CesiumCollection, type CesiumCollectionItem, Collection, type CollectionEventType, type EventHandler, type Primitives, type Tag, type WithTag };