@juun-roh/cesium-utils 0.1.2 → 0.2.0

package/dist/highlight/index.d.cts

@@ -0,0 +1,245 @@
+import { Viewer, Entity, Color, Primitive, GroundPrimitive, Model, Cesium3DTileset, Cesium3DTileFeature } from 'cesium';
+
+/**
+ * @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 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;
+    /** Gets the highlight color. */
+    get color(): Color;
+    /**
+     * Sets the highlight color.
+     * @param color The new color for highlights
+     */
+    set color(color: Color);
+}
+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);
+    /**
+     * 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;
+    /**
+     * Compares two Highlight.Options objects for equality
+     * @private
+     */
+    private _optionsEqual;
+    /**
+     * Clears all current highlights
+     * @private
+     */
+    private _clearHighlights;
+    /** Clears the current highlight */
+    hide(): void;
+    /** Clean up the instances */
+    destroy(): void;
+    /** 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;
+}
+
+/**
+ * @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);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Clears the current highlight
+     */
+    hide(): void;
+    /** Clean up the instances */
+    destroy(): void;
+    /** 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;
+}
+
+export { Highlight, SilhouetteHighlight, SurfaceHighlight };

package/dist/highlight/index.d.ts

@@ -0,0 +1,245 @@
+import { Viewer, Entity, Color, Primitive, GroundPrimitive, Model, Cesium3DTileset, Cesium3DTileFeature } from 'cesium';
+
+/**
+ * @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 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;
+    /** Gets the highlight color. */
+    get color(): Color;
+    /**
+     * Sets the highlight color.
+     * @param color The new color for highlights
+     */
+    set color(color: Color);
+}
+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);
+    /**
+     * 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;
+    /**
+     * Compares two Highlight.Options objects for equality
+     * @private
+     */
+    private _optionsEqual;
+    /**
+     * Clears all current highlights
+     * @private
+     */
+    private _clearHighlights;
+    /** Clears the current highlight */
+    hide(): void;
+    /** Clean up the instances */
+    destroy(): void;
+    /** 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;
+}
+
+/**
+ * @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);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Clears the current highlight
+     */
+    hide(): void;
+    /** Clean up the instances */
+    destroy(): void;
+    /** 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;
+}
+
+export { Highlight, SilhouetteHighlight, SurfaceHighlight };

package/dist/highlight/index.js

@@ -0,0 +1 @@
+import{a,b,c}from"../chunk-RZ3PTU3G.js";export{c as Highlight,a as SilhouetteHighlight,b as SurfaceHighlight};