@juun-roh/cesium-utils 0.4.3 → 0.4.5

package/dist/index.d.cts

@@ -1,6 +1,1329 @@
-export { Collection } from './collection/index.cjs';
-export { Highlight, SilhouetteHighlight, SurfaceHighlight } from './highlight/index.cjs';
-export { TerrainOptions, TerrainRegion, TerrainTiles } from './terrain/index.cjs';
-export { cloneViewer, syncCamera } from './viewer/index.cjs';
-export { H as HybridTerrainProvider } from './hybrid-terrain-provider-Th8n2hZ1.cjs';
-import 'cesium';
+import { DataSourceCollection, EntityCollection, ImageryLayerCollection, PrimitiveCollection, Billboard, Cesium3DTileset, GroundPrimitive, Label, PointPrimitive, Polyline, Primitive, DataSource, Entity, ImageryLayer, Color, Viewer, Model, Cesium3DTileFeature, TerrainProvider, TilingScheme, TileAvailability, Credit, Event, Request, TerrainData, Cartesian3, JulianDate, Rectangle } from 'cesium';
+
+/**
+ * Represents a path to any nested property in an object, using dot notation.
+ *
+ * The `(keyof T & string)` portion provides top-level key hints in autocomplete,
+ * while `(string & {})` allows any string input to pass through.
+ *
+ * Actual path validation is delegated to {@link NestedValueOf}, which returns `never`
+ * for invalid paths — causing a type error on the corresponding value parameter.
+ *
+ * @example
+ * ```ts
+ * function f<Path extends NestedKeyOf<Obj>>(
+ *   key: Path,
+ *   value: NestedValueOf<Obj, Path> // ← validation happens here
+ * ) {}
+ *
+ * f("a.b.c", 123);       // ✅ valid path, correct value type
+ * f("invalid.path", 1);  // ❌ NestedValueOf returns never
+ * ```
+ */
+type NestedKeyOf<T extends object> = (keyof T & string) | (string & {});
+/**
+ * Extracts the type of a nested property from a property path string.
+ *
+ * @template ObjectType - The object type to extract the value type from
+ * @template Path - The property path string (e.g., "a.b.c")
+ *
+ * @example
+ * type Value = NestedValueOf<{ a: { b: number } }, "a.b">
+ * // Result: number
+ */
+type NestedValueOf<ObjectType, Path extends string> = Path extends `${infer Cur}.${infer Rest}` ? Cur extends keyof ObjectType ? NonNullable<ObjectType[Cur]> extends Function | ((...args: any[]) => any) ? never : NestedValueOf<NonNullable<ObjectType[Cur]>, Rest> : never : Path extends keyof ObjectType ? NonNullable<ObjectType[Path]> extends Function | ((...args: any[]) => any) ? never : ObjectType[Path] : never;
+
+/**
+ * @class
+ * A wrapper 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)
+ *
+ * @see [Collection Demo](https://juun.vercel.app/cesium-utils/collection)
+ *
+ * @example
+ * // Example 1: Managing Complex Scene with Multiple Object Types
+ * class SceneOrganizer {
+ *   private entities: Collection<EntityCollection, Entity>;
+ *   private billboards: Collection<BillboardCollection, Billboard>;
+ *   private primitives: Collection<PrimitiveCollection, Primitive>;
+ *
+ *   constructor(viewer: Viewer) {
+ *     this.entities = new Collection({ collection: viewer.entities });
+ *     this.billboards = new Collection({
+ *       collection: viewer.scene.primitives.add(new BillboardCollection())
+ *     });
+ *     this.primitives = new Collection({
+ *       collection: viewer.scene.primitives
+ *     });
+ *   }
+ *
+ *   // Unified API across different collection types!
+ *   showLayer(layerName: string) {
+ *     this.entities.show(layerName);
+ *     this.billboards.show(layerName);
+ *     this.primitives.show(layerName);
+ *   }
+ *
+ *   hideLayer(layerName: string) {
+ *     this.entities.hide(layerName);
+ *     this.billboards.hide(layerName);
+ *     this.primitives.hide(layerName);
+ *   }
+ *
+ *   removeLayer(layerName: string) {
+ *     this.entities.remove(layerName);
+ *     this.billboards.remove(layerName);
+ *     this.primitives.remove(layerName);
+ *   }
+ * }
+ *
+ * // Example 2: Extend the class for Domain-Specific Needs
+ * class BuildingCollection extends Collection<EntityCollection, Entity> {
+ *   constructor(viewer: Viewer) {
+ *     super({ collection: viewer.entities, tag: 'buildings' });
+ *   }
+ *
+ *   addBuilding(options: {
+ *     position: Cartesian3;
+ *     height: number;
+ *     floors: number;
+ *     type: 'residential' | 'commercial' | 'industrial';
+ *   }): Entity {
+ *     const building = new Entity({
+ *       position: options.position,
+ *       box: {
+ *         dimensions: new Cartesian3(50, 50, options.height),
+ *         material: this.getMaterialForType(options.type)
+ *       }
+ *     });
+ *
+ *     // Tag by type AND by floor count
+ *     this.add(building, options.type);
+ *     this.add(building, `floors-${options.floors}`);
+ *
+ *     return building;
+ *   }
+ *
+ *   getByFloorRange(min: number, max: number): Entity[] {
+ *     const results: Entity[] = [];
+ *     for (let i = min; i <= max; i++) {
+ *       results.push(...this.get(`floors-${i}`));
+ *     }
+ *     return results;
+ *   }
+ *
+ *   private getMaterialForType(type: string): Material {
+ *     const colors = {
+ *       residential: Color.GREEN,
+ *       commercial: Color.BLUE,
+ *       industrial: Color.YELLOW
+ *     };
+ *     return new ColorMaterialProperty(colors[type] || Color.WHITE);
+ *   }
+ * }
+ */
+declare class Collection<C extends Collection.Base, I extends Collection.ItemFor<C>> {
+    /**
+     * 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: Collection.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;
+    /**
+     * For cleaning up the instances
+     * @private
+     */
+    private _eventCleanupFunctions;
+    /**
+     * 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?: Collection.Tag;
+    });
+    /**
+     * Makes the collection directly iterable, allowing it to be used in `for...of` loops
+     * and with spread operators.
+     *
+     * @returns 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];
+     */
+    [Symbol.iterator](): Iterator<I>;
+    /**
+     * 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 unique tags currently in use in the collection.
+     *
+     * @returns An array of all unique tags
+     *
+     * @example
+     * // Get all tags
+     * const tags = collection.tags;
+     * console.log(`Collection has these tags: ${tags.join(', ')}`);
+     */
+    get tags(): Collection.Tag[];
+    /**
+     * 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: Collection.Event, handler: Collection.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: Collection.Event, handler: Collection.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 collection instance for method chaining
+     *
+     * @example
+     * const entity = collection.add(new Entity({ ... }), 'landmarks');
+     */
+    add(item: I, tag?: Collection.Tag, index?: number): this;
+    /**
+     * 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 collection instance for method chaining
+     *
+     * @example
+     * // Add multiple entities with the same tag
+     * const entities = [new Entity({ ... }), new Entity({ ... })];
+     * const addedEntities = collection.add(entities, 'buildings');
+     */
+    add(items: I[], tag?: Collection.Tag): this;
+    /**
+     * Returns true if the provided item is in this collection, false otherwise.
+     *
+     * @param item - The item instance to check for
+     * @returns True if the item is in the collection, false otherwise
+     */
+    contains(item: I): boolean;
+    /**
+     * 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.contains('temporary')) {
+     *   console.log('Temporary items exist');
+     * }
+     */
+    contains(tag: Collection.Tag): boolean;
+    /**
+     * Removes an item from the collection.
+     *
+     * @param item - The item to remove
+     * @returns The collection instance for method chaining
+     */
+    remove(item: I): this;
+    /**
+     * Removes all items with the specified tag from the collection.
+     *
+     * @param by - The tag identifying which items to remove
+     * @returns The collection instance for method chaining
+     */
+    remove(by: Collection.Tag): this;
+    /**
+     * Removes all items with the array of tags from the collection.
+     *
+     * @param by - The tags identifying which items to remove
+     * @returns The collection instance for method chaining
+     */
+    remove(by: Collection.Tag[]): this;
+    /**
+     * Removes all items from the collection.
+     */
+    removeAll(): void;
+    /**
+     * Permanently destroys this Collection instance.
+     * Removes all event listeners and clears internal state.
+     * The Collection instance should not be used after calling this method.
+     */
+    destroy(): void;
+    /**
+     * Gets all items with the specified tag from the collection.
+     * Uses an optimized internal map for faster lookups.
+     *
+     * @param by - 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.get('buildings');
+     */
+    get(by: Collection.Tag): I[];
+    /**
+     * Gets the first item matching the tag. More efficient than `get` when
+     * you only need one item, especially for large collections.
+     *
+     * @param by - The tag to search for
+     * @returns The first matching item or undefined if none found
+     *
+     * @example
+     * // Get the first building
+     * const firstBuilding = collection.first('buildings');
+     */
+    first(by: Collection.Tag): I | undefined;
+    /**
+     * Updates the tag for all items with the specified tag.
+     *
+     * @param from - The tag to replace
+     * @param to - The new tag to assign
+     * @returns The number of items updated
+     *
+     * @example
+     * // Rename a tag
+     * const count = collection.update('temp', 'temporary');
+     * console.log(`Updated ${count} items`);
+     */
+    update(from: Collection.Tag, to: Collection.Tag): number;
+    /**
+     * Makes all items with the specified tag visible.
+     * Only affects items that have a 'show' property.
+     *
+     * @param by - The tag identifying which items to show
+     * @returns The collection itself.
+     *
+     * @example
+     * // Show all buildings
+     * collection.show('buildings');
+     */
+    show(by: Collection.Tag): this;
+    /**
+     * Hides all items with the specified tag.
+     * Only affects items that have a 'show' property.
+     *
+     * @param by - The tag identifying which items to hide
+     * @returns The collection itself.
+     *
+     * @example
+     * // Hide all buildings
+     * collection.hide('buildings');
+     */
+    hide(by: Collection.Tag): this;
+    /**
+     * Toggles visibility of all items with the specified tag.
+     * Only affects items that have a 'show' property.
+     *
+     * @param by - The tag identifying which items to toggle
+     * @returns The collection itself.
+     *
+     * @example
+     * // Toggle visibility of all buildings
+     * collection.toggle('buildings');
+     */
+    toggle(by: Collection.Tag): this;
+    /**
+     * Sets a property value on all items with the specified tag.
+     * Supports nested property paths using dot notation (e.g., 'billboard.scale').
+     *
+     * @template Path - A nested property path type
+     *
+     * @param property - The property name or nested path to set (e.g., 'name' or 'billboard.scale')
+     * @param value - The value to set
+     * @param by - The tag identifying which items to update
+     * @returns The collection itself.
+     *
+     * @example
+     * // Change color of all buildings to red
+     * collection.setProperty('color', Color.RED, 'buildings');
+     *
+     * @example
+     * // Change billboard scale using nested path
+     * collection.setProperty('billboard.scale', 2.0, 'buildings');
+     */
+    setProperty<Path extends NestedKeyOf<I>>(property: Path, value: NestedValueOf<I, Path>, by?: Collection.Tag): this;
+    /**
+     * 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 by - 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, by?: Collection.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 by - 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: (value: I, index: number) => void, by?: Collection.Tag): void;
+    /**
+     * Creates a new array with the results of calling a provided function on every element
+     * in the collection. Optionally filters by tag before mapping.
+     *
+     * @param callbackfn - Function that produces an element of the new array
+     * @param by - Optional tag to filter items by before mapping
+     * @returns 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'
+     * );
+     */
+    map<R>(callbackfn: (value: I, index: number) => R, by?: Collection.Tag): R[];
+    /**
+     * Returns the first element in the collection that satisfies the provided testing function.
+     * Optionally filters by tag before searching.
+     *
+     * @param predicate - Function to test each element
+     * @param by - Optional tag to filter items by before searching
+     * @returns 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'
+     * );
+     */
+    find(predicate: (value: I) => boolean, by?: Collection.Tag): I | undefined;
+    /**
+     * 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;
+    /**
+     * Sets up automatic cache invalidation by registering event listeners on the underlying Cesium collection.
+     *
+     * @private
+     * @param collection - The Cesium collection to monitor for changes
+     *
+     * @see {@link destroy} For cleanup of event listeners
+     * @see {@link _invalidateCache} For the actual cache invalidation logic
+     */
+    private _setupCacheInvalidator;
+}
+/**
+ * @namespace
+ */
+declare namespace Collection {
+    /**
+     * The underlying Cesium collection type being wrapped.
+     */
+    export type Base = DataSourceCollection | EntityCollection | ImageryLayerCollection | PrimitiveCollection;
+    /**
+     * The item types that can be added to the `PrimitiveCollection` instance.
+     */
+    type Primitives = Billboard | Cesium3DTileset | GroundPrimitive | Label | PointPrimitive | Polyline | Primitive;
+    /**
+     * Cesium item type that can be added to the {@link Collection.Base} instance.
+     */
+    export type Item = DataSource | Entity | ImageryLayer | Primitives;
+    /**
+     * Gets the item type for a given collection type
+     */
+    export type ItemFor<C extends Base> = C extends DataSourceCollection ? DataSource : C extends EntityCollection ? Entity : C extends ImageryLayerCollection ? ImageryLayer : C extends PrimitiveCollection ? Primitives : never;
+    /**
+     * Collection tag type.
+     */
+    export type Tag = string | number;
+    export interface WithTag {
+        [key: symbol]: Tag;
+    }
+    /**
+     * Collection event types
+     */
+    export type Event = "add" | "remove" | "update" | "clear";
+    /**
+     * Event handler function type
+     */
+    export type EventHandler<I> = (event: {
+        type: Event;
+        items?: I[];
+        tag?: Collection.Tag;
+    }) => void;
+    export {  };
+}
+
+/**
+ * @class
+ * Lightweight multiton highlight manager for Cesium using flyweight pattern.
+ *
+ * @example
+ * ```
+ * // Setup
+ * const viewer1 = new Viewer('cesiumContainer1');
+ * const viewer2 = new Viewer('cesiumContainer2');
+ *
+ * const highlighter1 = Highlight.getInstance(viewer1);
+ * const highlighter2 = Highlight.getInstance(viewer2);
+ *
+ * // This highlight only affects viewer1
+ * highlighter1.show(someEntity, { color: Color.RED });
+ *
+ * // This highlight only affects viewer2
+ * highlighter2.show(someEntity, { color: Color.BLUE });
+ *
+ * // When done with viewers
+ * Highlight.releaseInstance(viewer1);
+ * Highlight.releaseInstance(viewer2);
+ * viewer1.destroy();
+ * viewer2.destroy();
+ * ```
+ */
+declare class Highlight {
+    private static instances;
+    private _surface;
+    private _silhouette;
+    private _color;
+    /**
+     * Creates a new `Highlight` instance.
+     * @private Use {@link getInstance `Highlight.getInstance()`}
+     * @param viewer A viewer to create highlight entity in
+     */
+    private constructor();
+    /** Gets the highlight color. */
+    get color(): Color;
+    /**
+     * Sets the highlight color.
+     * @param color The new color for highlights
+     */
+    set color(color: Color);
+    /**
+     * Gets or creates highlight instance from a viewer.
+     * @param viewer The viewer to get or create a new instance from.
+     */
+    static getInstance(viewer: Viewer): Highlight;
+    /**
+     * Releases the highlight instance associated with a viewer.
+     * @param viewer The viewer whose highlight instance should be released.
+     */
+    static releaseInstance(viewer: Viewer): void;
+    /**
+     * Highlights a picked object or a direct instance.
+     * @param picked The result of `Scene.pick()` or direct instance to be highlighted.
+     * @param options Optional style for the highlight.
+     * @see {@link Highlight.Options}
+     */
+    show(picked: Highlight.Picked, options?: Highlight.Options): void | Entity;
+    private _getObject;
+    /**
+     * Clears the current highlight effects.
+     */
+    hide(): void;
+}
+declare namespace Highlight {
+    export interface Base {
+        show(object: any, options?: Highlight.Options): void;
+        hide(): void;
+        destroy(): void;
+        color: Color;
+    }
+    export interface Options {
+        /** Color of the highlight */
+        color?: Color;
+        /** To apply outline style for the highlight */
+        outline?: boolean;
+        /** Outline width */
+        width?: number;
+    }
+    type PickedObject = {
+        id?: Entity;
+        primitive?: Primitive | GroundPrimitive | Model | Cesium3DTileset;
+        tileset?: Cesium3DTileset;
+        detail?: {
+            model?: Model;
+        };
+    };
+    export type Picked = Entity | Cesium3DTileFeature | GroundPrimitive | PickedObject;
+    export {  };
+}
+
+/**
+ * @class
+ * An implementation for highlighting 3D objects in Cesium.
+ *
+ * **Supported Object Types:**
+ * - `Entity` with model graphics. (adjustable outline width)
+ * - `Cesium3DTileset` instances. (fixed outline width)
+ *
+ * Currently supports outline style only.
+ *
+ * @example
+ * ```typescript
+ * const viewer = new Viewer("cesiumContainer");
+ * const silhouetteHighlight = new SilhouetteHighlight(viewer);
+ *
+ * // Highlight an object
+ * const entity = viewer.entities.add(new Entity({
+ *   model: new ModelGraphics(),
+ * }));
+ * silhouetteHighlight.show(entity);
+ * ```
+ */
+declare class SilhouetteHighlight implements Highlight.Base {
+    private _color;
+    private _silhouette;
+    private _composite;
+    private _stages;
+    private _entity?;
+    private _currentObject;
+    private _currentOptions;
+    /**
+     * Creates a new `Silhouette` instance.
+     * @param viewer A viewer to create highlight silhouette in
+     */
+    constructor(viewer: Viewer);
+    /** Gets the highlight color. */
+    get color(): Color;
+    /** Sets the highlight color. */
+    set color(color: Color);
+    /** Gets the currently highlighted object */
+    get currentObject(): Cesium3DTileFeature | Entity | undefined;
+    /**
+     * Highlights a picked `Cesium3DTileset` by updating silhouette composite.
+     * @param object The object to be highlighted.
+     * @param options Optional style for the highlight.
+     */
+    show(object: Cesium3DTileFeature, options?: Highlight.Options): void;
+    /**
+     * Highlights a picked `Entity` by updating the model properties.
+     * @param object The object to be highlighted.
+     * @param options Optional style for the highlight.
+     */
+    show(object: Entity, options?: Highlight.Options): void;
+    /** Clears the current highlight */
+    hide(): void;
+    /** Clean up the instances */
+    destroy(): void;
+    /**
+     * Compares two Highlight.Options objects for equality
+     * @private
+     */
+    private _optionsEqual;
+    /**
+     * Clears all current highlights
+     * @private
+     */
+    private _clearHighlights;
+}
+
+/**
+ * @class
+ * A flyweight implementation for highlighting 2D surface objects in Cesium.
+ *
+ * This class provides highlighting for ground-clamped geometries (polygons, polylines, rectangles)
+ *
+ * **Supported Geometry Types:**
+ * - `Entity` with polygon, polyline, or rectangle graphics
+ * - `GroundPrimitive` instances
+ *
+ * **Highlighting Modes:**
+ * - **Fill mode** (default): Creates a filled geometry using the original shape
+ * - **Outline mode**: Creates a polyline outline of the original geometry
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const viewer = new Viewer('cesiumContainer');
+ * const surfaceHighlight = new SurfaceHighlight(viewer);
+ *
+ * // Highlight an entity with default red fill
+ * const entity = viewer.entities.add(new Entity({
+ *   polygon: {
+ *     hierarchy: Cartesian3.fromDegreesArray([-75, 35, -74, 35, -74, 36, -75, 36]),
+ *     material: Color.BLUE
+ *   }
+ * }));
+ * surfaceHighlight.show(entity);
+ * ```
+ */
+declare class SurfaceHighlight implements Highlight.Base {
+    private _color;
+    private _entity;
+    private _entities;
+    private _currentObject;
+    private _currentOptions;
+    /**
+     * Creates a new `SurfaceHighlight` instance.
+     * @param viewer A viewer to create highlight entity in
+     */
+    constructor(viewer: Viewer);
+    /** Gets the highlight color. */
+    get color(): Color;
+    /** Sets the highlight color. */
+    set color(color: Color);
+    /** Gets the highlight entity */
+    get entity(): Entity;
+    /** Gets the currently highlighted object */
+    get currentObject(): Entity | GroundPrimitive | undefined;
+    /**
+     * Highlights a picked object by updating the reusable entity
+     * @param object The object to be highlighted.
+     * @param options Optional style for the highlight.
+     * @see {@link Highlight.Options}
+     */
+    show(object: Entity | GroundPrimitive, options?: Highlight.Options): Entity | undefined;
+    /**
+     * Clears the current highlight
+     */
+    hide(): void;
+    /** Clean up the instances */
+    destroy(): void;
+    /**
+     * Compares two Highlight.Options objects for equality
+     * @private
+     */
+    private _optionsEqual;
+    /**
+     * Removes all geometry properties from the highlight entity
+     * @private
+     */
+    private _clearGeometries;
+    /**
+     * Updates the highlight entity from an Entity object
+     * @private
+     */
+    private _update;
+}
+
+/**
+ * @class
+ * Provides terrain by delegating requests to different terrain providers
+ * based on geographic regions and zoom levels. This allows combining
+ * multiple terrain sources into a single seamless terrain.
+ *
+ * @example
+ * ``` typescript
+ * // Tile-coordinate based for precise control (multiple levels)
+ * const customTiles: TerrainTiles = new Map();
+ * customTiles.set(15, { x: [55852, 55871], y: [9556, 9575] });
+ * customTiles.set(16, { x: [111704, 111742], y: [19112, 19150] });
+ *
+ * const hybridTerrain = new HybridTerrainProvider({
+ *   regions: [
+ *     {
+ *       provider: customProvider,
+ *       tiles: customTiles,
+ *     }
+ *   ],
+ *   defaultProvider: worldTerrain
+ * });
+ *
+ * viewer.terrainProvider = hybridTerrain;
+ * ```
+ */
+declare class HybridTerrainProvider implements TerrainProvider {
+    private _regions;
+    private _defaultProvider;
+    private _fallbackProvider;
+    private _tilingScheme;
+    private _ready;
+    private _availability?;
+    private _errorEvent;
+    private _removeEventListeners;
+    private _hasWaterMask;
+    private _hasVertexNormals;
+    private _credit?;
+    /**
+     * Creates a new `HybridTerrainProvider` instance.
+     * @param options {@link HybridTerrainProvider.ConstructorOptions}
+     * @returns A new `HybridTerrainProvider` instance.
+     */
+    constructor(options: HybridTerrainProvider.ConstructorOptions);
+    /**
+     * Gets a value indicating whether or not the provider is ready for use,
+     * or a promise that resolves when the provider becomes ready.
+     */
+    get ready(): boolean;
+    /**
+     * Gets the tiling scheme used by this provider.
+     */
+    get tilingScheme(): TilingScheme;
+    /**
+     * Gets an object that can be used to determine availability of terrain from this provider.
+     */
+    get availability(): TileAvailability | undefined;
+    /**
+     * Gets the list of terrain regions managed by this provider.
+     */
+    get regions(): readonly HybridTerrainProvider.TerrainRegion[];
+    /**
+     * Gets the default terrain provider.
+     */
+    get defaultProvider(): TerrainProvider;
+    /**
+     * Gets the fallback terrain provider.
+     */
+    get fallbackProvider(): TerrainProvider;
+    /**
+     * Gets the credit to display when this terrain provider is active.  Typically this is used to credit
+     * the source of the terrain.
+     */
+    get credit(): Credit;
+    /**
+     * Gets an event that is raised when the terrain provider encounters an asynchronous error.  By subscribing
+     * to the event, you will be notified of the error and can potentially recover from it.  Event listeners
+     * are passed an instance of `TileProviderError`.
+     */
+    get errorEvent(): Event;
+    /**
+     * Gets a value indicating whether or not the provider includes a water mask.  The water mask
+     * indicates which areas of the globe are water rather than land, so they can be rendered
+     * as a reflective surface with animated waves.
+     */
+    get hasWaterMask(): boolean;
+    /** Gets a value indicating whether or not the requested tiles include vertex normals. */
+    get hasVertexNormals(): boolean;
+    /**
+     * Makes sure we load availability data for a tile
+     * @param x - The X coordinate of the tile for which to request geometry.
+     * @param y - The Y coordinate of the tile for which to request geometry.
+     * @param level - The level of the tile for which to request geometry.
+     * @returns Undefined if nothing need to be loaded or a Promise that resolves when all required tiles are loaded
+     */
+    loadTileDataAvailability(x: number, y: number, level: number): Promise<void> | undefined;
+    /**
+     * Gets the maximum geometric error allowed in a tile at a given level, taken as the
+     * worst case across the default provider and all region providers. Because the hybrid
+     * provider's coverage is a composition of multiple sources, the reported error reflects
+     * the highest error any source could contribute at this level, ensuring the LOD system
+     * refines conservatively enough for all sources.
+     * @param level - The tile level for which to get the maximum geometric error.
+     * @returns The maximum geometric error across all providers.
+     */
+    getLevelMaximumGeometricError(level: number): number;
+    /**
+     * Requests the terrain for a given tile coordinate.
+     * @param x The X coordinate of the tile.
+     * @param y The Y coordinate of the tile.
+     * @param level The zoom level of the tile.
+     * @param request The request.
+     * @returns A promise for the requested terrain.
+     */
+    requestTileGeometry(x: number, y: number, level: number, request?: Request): Promise<TerrainData> | undefined;
+    /**
+     * Determines whether data for a tile is available to be loaded. Checks the specified terrain regions first.
+     * @param x - The X coordinate of the tile for which to request geometry.
+     * @param y - The Y coordinate of the tile for which to request geometry.
+     * @param level - The level of the tile for which to request geometry.
+     * @returns Undefined if not supported by the terrain provider, otherwise true or false.
+     */
+    getTileDataAvailable(x: number, y: number, level: number): boolean | undefined;
+    /**
+     * Cleans up resources used in the `HybridTerrainProvider`.
+     *
+     * This method only releases additional resources used to instantiate the `HybridTerrainProvider`.
+     */
+    destroy(): void;
+}
+/**
+ * @namespace
+ * Contains types and factory methods for `HybridTerrainProvider` instance.
+ */
+declare namespace HybridTerrainProvider {
+    /** Initialization options for `HybridTerrainProvider` constructor. */
+    interface ConstructorOptions {
+        /** An array of terrain regions to include in the hybrid terrain. */
+        regions?: TerrainRegion[];
+        /** Default provider to use outside of specified terrain regions. */
+        defaultProvider: TerrainProvider;
+        /** Optional fallback provider when data is not available from default provider. @default EllipsoidTerrainProvider */
+        fallbackProvider?: TerrainProvider;
+        /** A credit for the data source, which is displayed on the canvas. */
+        credit?: Credit | string;
+    }
+    /**
+     * A factory function which creates a HybridTerrainProvider from tile-coordinate based regions.
+     * @param regions Array of regions with tile-coordinate bounds
+     * @param defaultProvider Default terrain provider
+     * @param fallbackProvider Optional fallback provider
+     */
+    function fromTileRanges(regions: Array<{
+        provider: TerrainProvider;
+        tiles: Map<number, {
+            x: number | [number, number];
+            y: number | [number, number];
+        }>;
+        levels?: number[];
+    }>, defaultProvider: TerrainProvider, fallbackProvider?: TerrainProvider): HybridTerrainProvider;
+    /** Represents a terrain region with provider and geographic bounds. */
+    interface TerrainRegion {
+        /** The terrain provider for this region. */
+        provider: TerrainProvider;
+        /**
+         * Tile-coordinate based bounds (precise control).
+         * Map of level to tile coordinate ranges for that level.
+         */
+        tiles?: Map<number, {
+            /** X tile coordinate range [min, max] or single value. */
+            x: number | [number, number];
+            /** Y tile coordinate range [min, max] or single value. */
+            y: number | [number, number];
+        }>;
+        /** Optional level constraints. If specified, region only applies to these levels. */
+        levels?: number[];
+    }
+    /**
+     * @namespace
+     * Utility functions for working with TerrainRegion objects.
+     */
+    namespace TerrainRegion {
+        /**
+         * Checks if a terrain region contains the specified tile.
+         * @param region The terrain region to check
+         * @param x The X coordinate of the tile
+         * @param y The Y coordinate of the tile
+         * @param level The zoom level of the tile
+         * @returns True if the region contains the tile, false otherwise
+         */
+        function contains(region: HybridTerrainProvider.TerrainRegion, x: number, y: number, level: number): boolean;
+    }
+}
+
+type TerrainTiles = NonNullable<HybridTerrainProvider.TerrainRegion["tiles"]>;
+type TerrainRegion = HybridTerrainProvider.TerrainRegion;
+type TerrainOptions = HybridTerrainProvider.ConstructorOptions;
+
+/**
+ * Copies configuration and state from one Cesium Viewer to another.
+ * @param source - The source viewer to copy properties from
+ * @param container - DOM element ID or element for the new viewer
+ * @param options - Optional override options for the new viewer
+ * @returns A new Viewer instance with copied properties
+ */
+declare function cloneViewer(source: Viewer, container: Element | string, options?: Viewer.ConstructorOptions): Viewer;
+
+/**
+ * Copies camera state from source viewer to destination viewer.
+ * @param source The source viewer to copy camera states from.
+ * @param dest The destination viewer to apply camera properties from the source.
+ */
+declare function syncCamera(source: Viewer, dest: Viewer): void;
+
+/**
+ * Utility for managing deprecation warnings in the cesium-utils library.
+ * Provides runtime warnings to help developers identify deprecated API usage.
+ */
+declare namespace Deprecate {
+    /**
+     * Configuration options for deprecation warnings.
+     */
+    interface Options {
+        /**
+         * Whether to show the warning only once per deprecation message.
+         * @default true
+         */
+        once?: boolean;
+        /**
+         * Custom prefix for the warning message.
+         * @default "[DEPRECATED]"
+         */
+        prefix?: string;
+        /**
+         * Whether to include a stack trace in the warning.
+         * @default true
+         */
+        includeStack?: boolean;
+        /**
+         * Version when the feature will be removed.
+         */
+        removeInVersion?: string;
+    }
+    /**
+     * Displays a deprecation warning message.
+     *
+     * @param message - The deprecation message to display
+     * @param options - Configuration options for the warning
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * deprecationWarning("oldFunction() is deprecated. Use newFunction() instead.");
+     *
+     * // With removal version
+     * deprecationWarning("TerrainArea is deprecated.", {
+     *   removeInVersion: "v0.3.0"
+     * });
+     *
+     * // Allow multiple warnings
+     * deprecationWarning("Repeated warning", { once: false });
+     * ```
+     */
+    function warn(message: string, options?: Options): void;
+    /**
+     * Creates a deprecation wrapper function that shows a warning when called.
+     *
+     * @param fn - The function to wrap
+     * @param message - The deprecation message
+     * @param options - Configuration options for the warning
+     * @returns A wrapped function that shows a deprecation warning when called
+     *
+     * @example
+     * ```typescript
+     * const oldFunction = deprecate(
+     *   () => console.log("old implementation"),
+     *   "oldFunction() is deprecated. Use newFunction() instead."
+     * );
+     *
+     * oldFunction(); // Shows warning and executes function
+     * ```
+     */
+    function deprecate<T extends (...args: any[]) => any>(fn: T, message: string, options?: Options): T;
+    /**
+     * Clears all shown warning messages.
+     * Useful for testing or when you want to reset the warning state.
+     *
+     * @example
+     * ```typescript
+     * clearDeprecationWarnings();
+     * deprecationWarning("This will show again");
+     * ```
+     */
+    function clear(): void;
+    /**
+     * Gets the count of unique deprecation warnings that have been shown.
+     *
+     * @returns The number of unique deprecation warnings shown
+     */
+    function getWarningCount(): number;
+    /**
+     * Checks if a specific deprecation warning has been shown.
+     *
+     * @param message - The deprecation message to check
+     * @returns True if the warning has been shown, false otherwise
+     */
+    function hasShown(message: string): boolean;
+}
+
+declare const deprecate: typeof Deprecate.deprecate;
+
+/**
+ * @since Cesium 1.132.0
+ * @experimental
+ * Point sunlight analysis utility for shadow calculations.
+ *
+ * ⚠️ **Warning**: This is an experimental feature that uses Cesium's internal APIs.
+ * The API may change or break in future versions of Cesium or cesium-utils.
+ *
+ * @example
+ * ```typescript
+ * const sunlight = new Sunlight(viewer);
+ * sunlight.analyze(point, JulianDate.now());
+ * ```
+ */
+declare class Sunlight {
+    private _uniformState;
+    private _viewer;
+    private _analyzing;
+    private _pointEntityId?;
+    private _objectsToExclude;
+    private _polylines;
+    private _points;
+    constructor(viewer: Viewer);
+    /** The sun position in 3D world coordinates at the current scene time. */
+    get sunPositionWC(): Cartesian3;
+    /** A normalized vector to the sun in 3D world coordinates at the current scene time. */
+    get sunDirectionWC(): Cartesian3;
+    /** Whether sunlight analysis is currently in progress. */
+    get isAnalyzing(): boolean;
+    /**
+     * Gets virtual position and direction of the sun to reduce calculation overhead.
+     *
+     * @param from target point to start from
+     * @param radius virtual distance between target point and the sun. Defaults to 10000 (10km)
+     */
+    virtualSun(from: Cartesian3, radius?: number): {
+        position: Cartesian3;
+        direction: Cartesian3;
+    };
+    /**
+     * Analyze the sunlight acceptance from a given point at a given time.
+     * @param from target point to analyze
+     * @param at time to analyze
+     * @param options {@link Sunlight.AnalyzeOptions}
+     */
+    analyze(from: Cartesian3, at: JulianDate, options?: Sunlight.AnalyzeOptions): Promise<Sunlight.AnalysisResult>;
+    /**
+     * Analyze the sunlight acceptance from a given point at a given time range.
+     * @param from target point to analyze
+     * @param range time range to analyze
+     * @param options {@link Sunlight.AnalyzeOptions}
+     */
+    analyze(from: Cartesian3, range: Sunlight.TimeRange, options?: Sunlight.AnalyzeOptions): Promise<Sunlight.AnalysisResult[]>;
+    /**
+     * Remove all instances created for debug purpose
+     */
+    clear(): void;
+    /**
+     * Create an ellipsoid entity for ray collision detection to complement cesium's native click event accuracy
+     * @param at where to create the entity
+     * @param show whether to show point entity
+     * @param errorBoundary size of the point entity for error tolerance
+     */
+    setTargetPoint(at: Cartesian3, show?: boolean, errorBoundary?: number, color?: Color): Entity;
+    private _analyzeSingleTime;
+    private _analyzeTimeRange;
+    /**
+     * @returns A promise tht resolves to an object containing the object and position of the first intersection.
+     * @see https://github.com/CesiumGS/cesium/blob/1.136/packages/engine/Source/Scene/Scene.js#L4868
+     */
+    private _pick;
+    private _getExcludedObjects;
+}
+declare namespace Sunlight {
+    const DETECTION_ELLIPSOID_ID = "sunlight-detection-ellipsoid";
+    /** for time-range analysis */
+    interface TimeRange {
+        /** When to start analysis */
+        start: JulianDate;
+        /** When to end analysis */
+        end: JulianDate;
+        /** Step interval (seconds) inside the range */
+        step: number;
+    }
+    interface AnalyzeOptions {
+        /** List of objects to exclude from ray pick */
+        objectsToExclude?: any[];
+        /** size of the point entity for error tolerance */
+        errorBoundary?: number;
+        /** Whether to show sunlight paths */
+        debugShowRays?: boolean;
+        /** Whether to show points */
+        debugShowPoints?: boolean;
+    }
+    interface AnalysisResult {
+        /** ISO time string */
+        timestamp: string;
+        /** Whether the sunlight has reached */
+        result: boolean | any;
+    }
+}
+
+/**
+ * @class
+ * Utility class for visualizing terrain provider boundaries and debugging terrain loading.
+ */
+declare class TerrainVisualizer {
+    private _viewer;
+    private _terrainProvider;
+    private _visible;
+    private _tileCoordinatesLayer;
+    private _hybridImageryLayer;
+    private _colors;
+    /**
+     * Creates a new `TerrainVisualizer`.
+     * @param viewer The Cesium viewer instance
+     * @param options {@link TerrainVisualizer.ConstructorOptions}
+     */
+    constructor(viewer: Viewer, options: TerrainVisualizer.ConstructorOptions);
+    /**
+     * Sets the terrain provider to visualize.
+     * @param terrainProvider The terrain provider to visualize.
+     */
+    setTerrainProvider(terrainProvider: HybridTerrainProvider): void;
+    /**
+     * Updates all active visualizations.
+     */
+    update(): void;
+    /**
+     * Clears all visualizations.
+     */
+    clear(): void;
+    /**
+     * Shows terrain visualization using HybridImageryProvider.
+     * Optionally adds tile coordinate grid overlay.
+     * @param options Visualization options
+     */
+    show(options?: {
+        /** Show tile coordinate labels. Default: true */
+        showTileCoordinates?: boolean;
+        /** Transparency level (0-1). Default: 0.5 */
+        alpha?: number;
+    }): void;
+    private _ensureTileCoordinatesLayer;
+    /**
+     * Hides the terrain visualization.
+     */
+    hide(): void;
+    /**
+     * Sets the colors used for visualization.
+     * @param colors Map of role names to colors
+     */
+    setColors(colors: Record<string, Color>): void;
+    /**
+     * Shows terrain regions using HybridImageryProvider (performant, global coverage).
+     * This replaces the entity-based approach with an imagery layer.
+     * @param alpha Transparency level (0-1), default 0.5
+     */
+    showImageryOverlay(alpha?: number): void;
+    /**
+     * Hides the imagery overlay.
+     */
+    hideImageryOverlay(): void;
+    /**
+     * Shows tile coordinate grid overlay.
+     */
+    showTileCoordinates(): void;
+    /**
+     * Hides tile coordinate grid overlay.
+     */
+    hideTileCoordinates(): void;
+    /**
+     * Sets the transparency of the imagery overlay.
+     * @param alpha Transparency level (0-1), where 0 is fully transparent and 1 is fully opaque
+     */
+    setAlpha(alpha: number): void;
+    /**
+     * Flies the camera to focus on a rectangle.
+     * @param rectangle The rectangle to focus on.
+     * @param options {@link Viewer.flyTo}
+     */
+    flyTo(rectangle: Rectangle, options?: {
+        duration?: number;
+    }): void;
+    /** Whether tile coordinates are currently visible. */
+    get tileCoordinatesVisible(): boolean;
+    /** Whether the grid is currently visible. */
+    get visible(): boolean;
+    /** The viewer used in the visualizer */
+    get viewer(): Viewer;
+    /** The colors used in the visualizer */
+    get colors(): Map<string, Color>;
+    /** The hybrid terrain instance used in the visualizer */
+    get terrainProvider(): HybridTerrainProvider;
+}
+/**
+ * @namespace
+ * Contains types, utility functions, and constants for terrain visualization.
+ */
+declare namespace TerrainVisualizer {
+    /** Initialization options for `TerrainVisualizer` constructor. */
+    interface ConstructorOptions {
+        /** Colors to use for different visualization elements */
+        colors?: Record<string, Color>;
+        /** Whether to show tile grid initially. */
+        tile?: boolean;
+        /** Initial zoom level to use for visualizations. */
+        activeLevel?: number;
+        /** Terrain provider to visualize. */
+        terrainProvider: HybridTerrainProvider;
+    }
+    /** Options for {@link TerrainVisualizer.visualize} */
+    interface Options {
+        color?: Color;
+        show?: boolean;
+        maxTilesToShow?: number;
+        levels?: number[];
+        tag?: string;
+        alpha?: number;
+        tileAlpha?: number;
+    }
+}
+
+export { Collection, Deprecate, Highlight, HybridTerrainProvider, SilhouetteHighlight, Sunlight, SurfaceHighlight, type TerrainOptions, TerrainRegion, type TerrainTiles, TerrainVisualizer, cloneViewer, deprecate, syncCamera };