Class Collection<C, I>

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.

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').hide('roads');

Type Parameters

C extends CesiumCollection
The type of Cesium collection (e.g., EntityCollection, PrimitiveCollection)
I extends CesiumCollectionItem
The type of items in the collection (e.g., Entity, Primitive)

Index

Constructors

constructor

new Collection<C extends CesiumCollection, I extends CesiumCollectionItem>(
options: { collection: C; tag?: Tag },
): Collection<C, I>
Creates a new Collection instance.
Type Parameters
- C extends CesiumCollection
- I extends CesiumCollectionItem
Parameters
- options: { collection: C; tag?: Tag }
 Configuration options
 - collection: C
 The Cesium collection to wrap
 - Optionaltag?: Tag
 The default tag to use for items (defaults to 'default')
Returns Collection<C, I>
- Defined in src/collection/collection.ts:91

Properties

`Private`_eventListeners

_eventListeners: Map<CollectionEventType, Set<EventHandler>> = ...

Event listeners

`Private`_tagMap

_tagMap: Map<Tag, Set> = ...

Tag to items map for faster lookups

`Private`_valuesCache

_valuesCache: null | I[] = null

Cache for values array to improve performance

`Protected`collection

collection: C

The underlying Cesium collection being wrapped.

`Protected`tag

tag: Tag

Default tag used when adding items without specifying a tag.

`Static` `Readonly`symbol

symbol: typeof symbol = ...

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.

Accessors

length

get length(): number
Gets the number of items in the collection.

Returns number
The item count
- Defined in src/collection/collection.ts:373

values

get values(): I[]
Gets all item instances in the collection. This array should not be modified directly.

Returns I[]
An array of all items in the collection
- Defined in src/collection/collection.ts:356

Methods

`Private`_addToTagMap

_addToTagMap(item: I, tag: Tag): void
Private
Adds an item to the internal tag map for quick lookups.
Parameters
- item: I
  The item to add
- tag: Tag
  The tag to associate with the item
Returns void
- Defined in src/collection/collection.ts:140

`Private`_emit

_emit(type: CollectionEventType, data?: { items?: I[]; tag?: Tag }): void
Private
Emits an event to all registered listeners.
Parameters
- type: CollectionEventType
  The event type
- Optionaldata: { items?: I[]; tag?: Tag }
  Additional event data
Returns void
- Defined in src/collection/collection.ts:122

`Private`_invalidateCache

_invalidateCache(): void
Private
Invalidates the values cache when collection changes.

Returns void
- Defined in src/collection/collection.ts:170

`Private`_removeFromTagMap

_removeFromTagMap(item: I & WithTag): void
Private
Removes an item from the internal tag map.
Parameters
- item: I & WithTag
  The item to remove
Returns void
- Defined in src/collection/collection.ts:153

[iterator]

"[iterator]"(): Iterator
Makes the collection directly iterable, allowing it to be used in for...of loops and with spread operators.

Returns Iterator
An iterator for the items in the collection
Example
```
// Iterate through all items in the collection
for (const entity of collection) {
 console.log(entity.id);
}

// Convert collection to array using spread syntax
const entitiesArray = [...collection];
```
- Defined in src/collection/collection.ts:111

add

add(item: I, tag?: Tag, index?: number): I
Adds a single item with a tag to the collection.
Parameters
- item: I
  The item to add to the collection
- Optionaltag: Tag
  Tag to associate with this item (defaults to the collection's default tag)
- Optionalindex: number
  The index to add the item at (if supported by the collection)
Returns I
The added item for chaining
Example
```
const entity = collection.add(new Entity({ ... }), 'landmarks');
```
- Defined in src/collection/collection.ts:215
add(items: I[], tag?: Tag): I[]
Adds multiple items with the same tag to the collection.
Parameters
- items: I[]
  The array of items to add to the collection
- Optionaltag: Tag
  Tag to associate with this item (defaults to the collection's default tag)
Returns I[]
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');
```
- Defined in src/collection/collection.ts:228

addEventListener

addEventListener(type: CollectionEventType, handler: EventHandler): this
Registers an event listener for collection events.
Parameters
- type: CollectionEventType
 The event type to listen for
- handler: EventHandler
 The callback function
Returns this
The collection instance for method chaining
- Defined in src/collection/collection.ts:181

contains

contains(item: I): boolean
Returns true if the provided item is in this collection, false otherwise.
Parameters
- item: I
  The item instance to check for
Returns boolean
True if the item is in the collection, false otherwise
- Defined in src/collection/collection.ts:257
contains(tag: Tag): boolean
Checks if the collection has any items with the specified tag.
Parameters
- tag: Tag
  The tag to check for
Returns boolean
True if items with the tag exist, false otherwise
Example
```
if (collection.contains('temporary')) {
  console.log('Temporary items exist');
}
```
- Defined in src/collection/collection.ts:269

filter

filter(predicate: (item: I) => boolean, by?: Tag): I[]
Filters items in the collection based on a predicate function. Optionally only filters items with a specific tag.
Parameters
- predicate: (item: I) => boolean
  Function that tests each item
- Optionalby: Tag
  Optional tag to filter by before applying the predicate
Returns I[]
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'
);
```
- Defined in src/collection/collection.ts:582

find

find(predicate: (value: I) => boolean, by?: Tag): undefined | I
Returns the first element in the collection that satisfies the provided testing function. Optionally filters by tag before searching.
Parameters
- predicate: (value: I) => boolean
  Function to test each element
- Optionalby: Tag
  Optional tag to filter items by before searching
Returns undefined | I
The first element that passes the test, or undefined if no elements pass
Example
```
// Find the first entity with a specific name
const namedEntity = collection.find(entity => entity.name === 'Target');

// Find the first building taller than 100 meters
const tallBuilding = collection.find(
  entity => entity.properties?.height?.getValue() > 100,
  'buildings'
);
```
- Defined in src/collection/collection.ts:648

first

first(by: Tag): undefined | I
Gets the first item matching the tag. More efficient than get when you only need one item, especially for large collections.
Parameters
- by: Tag
  The tag to search for
Returns undefined | I
The first matching item or undefined if none found
Example
```
// Get the first building
const firstBuilding = collection.first('buildings');
```
- Defined in src/collection/collection.ts:404

forEach

forEach(callback: (value: I, index: number) => void, by?: Tag): void
Executes a callback function for each item in the collection. Optionally filters items by tag before execution.
Parameters
- callback: (value: I, index: number) => void
  Function to execute for each item
- Optionalby: Tag
  Optional tag to filter items (if not provided, processes all items)
Returns void
Example
```
// Highlight all buildings
collection.forEach((entity) => {
  if (entity.polygon) {
    entity.polygon.material = new ColorMaterialProperty(Color.YELLOW);
  }
}, 'buildings');
```
- Defined in src/collection/collection.ts:602

get

get(by: Tag): I[]
Gets all items with the specified tag from the collection. Uses an optimized internal map for faster lookups.
Parameters
- by: Tag
  The tag to filter by
Returns I[]
An array of items with the specified tag, or an empty array if none found
Example
```
// Get all buildings
const buildings = collection.get('buildings');
```
- Defined in src/collection/collection.ts:388

hide

hide(by: Tag): this
Hides all items with the specified tag. Only affects items that have a 'show' property.
Parameters
- by: Tag
  The tag identifying which items to hide
Returns this
The collection itself.
Example
```
// Hide all buildings
collection.hide('buildings');
```
- Defined in src/collection/collection.ts:498

map

map<R>(callbackfn: (value: I, index: number) => R, by?: Tag): R[]
Creates a new array with the results of calling a provided function on every element in the collection. Optionally filters by tag before mapping.
Type Parameters
- R
Parameters
- callbackfn: (value: I, index: number) => R
 Function that produces an element of the new array
- Optionalby: Tag
 Optional tag to filter items by before mapping
Returns R[]
A new array with each element being the result of the callback function
Example
```
// Get all entity IDs
const entityIds = collection.map(entity => entity.id);

// Get positions of all buildings
const buildingPositions = collection.map(
 entity => entity.position.getValue(Cesium.JulianDate.now()),
 'buildings'
);
```
- Defined in src/collection/collection.ts:625

remove

remove(item: I): boolean
Removes an item from the collection.
Parameters
- item: I
  The item to remove
Returns boolean
True if the item was removed, false if it wasn't found
- Defined in src/collection/collection.ts:285
remove(by: Tag): boolean
Removes all items with the specified tag from the collection.
Parameters
- by: Tag
  The tag identifying which items to remove
Returns boolean
True if the item was removed, false if it wasn't found
- Defined in src/collection/collection.ts:292
remove(by: Tag[]): boolean
Removes all items with the array of tags from the collection.
Parameters
- by: Tag[]
  The tags identifying which items to remove
Returns boolean
True if the item was removed, false if it wasn't found
- Defined in src/collection/collection.ts:299

removeAll

removeAll(): void
Removes all items from the collection.

Returns void
- Defined in src/collection/collection.ts:343

removeEventListener

removeEventListener(type: CollectionEventType, handler: EventHandler): this
Removes an event listener.
Parameters
- type: CollectionEventType
 The event type
- handler: EventHandler
 The callback function to remove
Returns this
The collection instance for method chaining
- Defined in src/collection/collection.ts:196

setProperty

setProperty<K extends string | number | symbol, V>(
 property: K,
 value: V,
 by?: Tag,
): this
Sets a property value on all items with the specified tag.
Type Parameters
- K extends string | number | symbol
- V
Parameters
- property: K
 The property name to set
- value: V
 The value to set
- by: Tag = ...
 The tag identifying which items to update
Returns this
The number of items updated
Example
```
// Change color of all buildings to red
collection.setProperty('buildings', 'color', Color.RED);
```
- Defined in src/collection/collection.ts:545

show

show(by: Tag): this
Makes all items with the specified tag visible. Only affects items that have a 'show' property.
Parameters
- by: Tag
  The tag identifying which items to show
Returns this
The collection itself.
Example
```
// Show all buildings
collection.show('buildings');
```
- Defined in src/collection/collection.ts:475

toggle

toggle(by: Tag): this
Toggles visibility of all items with the specified tag. Only affects items that have a 'show' property.
Parameters
- by: Tag
  The tag identifying which items to toggle
Returns this
The collection itself.
Example
```
// Toggle visibility of all buildings
collection.toggle('buildings');
```
- Defined in src/collection/collection.ts:521

update

update(from: Tag, to: Tag): number
Updates the tag for all items with the specified tag.
Parameters
- from: Tag
  The tag to replace
- to: Tag
  The new tag to assign
Returns number
The number of items updated
Example
```
// Rename a tag
const count = collection.update('temp', 'temporary');
console.log(`Updated ${count} items`);
```
- Defined in src/collection/collection.ts:438

Class Collection<C, I>

Example

Type Parameters

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

collection: C

Optionaltag?: Tag

Returns Collection<C, I>

Properties

Private_eventListeners

Private_tagMap

Private_valuesCache

Protectedcollection

Protectedtag

Static Readonlysymbol

Accessors

length

Returns number

tags

Returns Tag[]

Example

values

Returns I[]

Methods

Private_addToTagMap

Parameters

Returns void

Private_emit

Parameters

Returns void

Private_invalidateCache

Returns void

Private_removeFromTagMap

Parameters

Returns void

[iterator]

Returns Iterator<I>

Example

add

Parameters

Returns I

Example

Parameters

Returns I[]

Example

addEventListener

Parameters

Returns this

contains

Parameters

Returns boolean

Parameters

Returns boolean

Example

filter

Parameters

Returns I[]

Example

find

Parameters

Returns undefined | I

Example

first

Parameters

Returns undefined | I

Example

forEach

Parameters

Returns void

Example

get

Parameters

Returns I[]

`Optional`tag?: Tag

`Private`_eventListeners

`Private`_tagMap

`Private`_valuesCache

`Protected`collection

`Protected`tag

`Static` `Readonly`symbol

`Private`_addToTagMap

`Private`_emit

`Private`_invalidateCache

`Private`_removeFromTagMap