DOCSEARCHbyAlgolia
Submit Docs

cesium-extends

repository·master·Indexed 18 days ago

https://github.com/hongfaqiu/cesium-extends

A framework-agnostic extension library for CesiumJS providing a suite of components and utilities for geospatial tasks. It includes tools for GeoJSON rendering, measurement (ground and non-ground distance/area), drawing shapes (polygons, polylines, points, circles, rectangles), heatmap layers with auto-resizing and dynamic radius, UI popups, a compass widget, and an event subscription system for Cesium entities.

Tokens
52.4K
Snippets
185
Records
246
Agent score
62%

What's inside cesium-extends

  1. Overview of cesium-extends features

    master

    The cesium-extends library provides a variety of specialized modules for CesiumJS. Key features include:

    • Data Rendering: Accelerated GeoJSON rendering using primitives (@cesium-extends/primitive-geojson) and rich GeoJSON style rendering (@cesium-extends/geojson-render).
    • UI Components: Tooltips (@cesium-extends/tooltip), popups (@cesium-extends/popup), compasses (@cesium-extends/compass), and zoom controls (@cesium-extends/zoom-control).
    • Tools: Drawing tools (@cesium-extends/drawer), measurement tools (@cesium-extends/measure), and dual-screen synchronization (@cesium-extends/sync-viewer).
    • Analysis: Heatmaps (@cesium-extends/heat).
    • Utilities: Event subscription (@cesium-extends/subscriber).

    For detailed API documentation and live demos, visit the official API documentation.

  2. What is the Widget base class?

    master

    The Widget class is a base class designed for creating custom UI components (widgets) within a Cesium application. You should extend this class to implement your own widget logic. It provides lifecycle management and visibility controls.

    // Example concept of extending Widget
class MyCustomWidget extends Widget {
  constructor(viewer, wrapper) {
    super(viewer, wrapper);
  }
}

  4. Configure GeoJsonStyle for rendering GeoJSON data

    master

    The GeoJsonStyle object controls how GeoJSON data (points, lines, polygons, etc.) is rendered on the map. It is composed of several specialized style types depending on the geometry type and the desired visual effect.

    Core Components

    • GeoJsonCommonStyle: Base properties for all styles, including symbol (label conditions) and sprite (sprite sheet configuration).
    • SymbolStyle: Controls label appearance (text, font, size, color, halo, and offsets).
    • Sprite Configuration: Uses a url and optional params to define sprite sheet assets.

    Available Rendering Schemes

    • SymbolStyle: For label rendering.
    • GeoJsonPointStyle: For point geometries.
    • GeoJsonLineStyle: For line geometries.
    • GeoJsonPolygonStyle: For polygon geometries.
    • GeoJsonMixStyle: For mixed geometry types, providing configuration similar to native Cesium GeoJSON rendering.

  5. How @cesium-extends/subscriber works

    master

    The @cesium-extends/subscriber package provides a convenient way to subscribe to events within a Cesium scene. It allows you to attach event listeners to specific entities (or arrays of entities) and trigger callbacks when those events occur.

    It supports two main modes of subscription:

    1. Entity-based subscription (add): Listeners are filtered by specific entities. The callback receives the event arguments and the associated entity.
    2. External subscription (addExternal): Listeners are not filtered by entities (global listeners). The callback receives event arguments and potentially a pick result if enabled.

    You can globally pause all callbacks by setting subscriber.enable = false and should call subscriber.destroy() to clean up resources.

    import Subscriber, { EventType } from "@cesium-extends/subscriber";
import { viewer, entities } from "./cesiumInit";

// Create subscriber
const subscriber = new Subscriber(viewer);

// Add entity-specific listener
subscriber.add(
  entities[0],
  (movement, entity) => {
    console.log(movement);
    console.log(entity);
  },
  EventType.LEFT_CLICK,
);

// Add global (external) listener
subscriber.addExternal((movement, result) => {
  console.log(movement);
  console.log(result);
}, EventType.MOUSE_MOVE);

// Pause callbacks
subscriber.enable = false;

// Cleanup
subscriber.destroy();

  6. How the measurement tools work

    master

    The @cesium-extends/measure package provides several specialized classes for measuring distance and area. All measurement classes inherit from a base Measure class.

    There are two primary modes of measurement:

    1. Standard (Non-surface): Measures distance or area in 3D space (e.g., AreaMeasure, DistanceMeasure).
    2. Surface (Clamped to terrain): Measures distance or area following the terrain/surface (e.g., AreaSurfaceMeasure, DistanceSurfaceMeasure).

    To use a tool, instantiate the class with a Cesium Viewer and an optional MeasureOptions object, then call .start() to begin the interaction.

    import { Viewer } from "cesium";
import { AreaMeasure } from "@cesium-extends/measure";

const viewer = new Viewer("cesiumContainer");
const areaMeasure = new AreaMeasure(viewer, { /* options */ });

areaMeasure.start();

  7. Enable automatic radius adjustment with autoRadiusConfig

    master

    You can automatically adjust the radius of each point based on the current camera height. Enable this by setting enabled: true in the autoRadiusConfig object.

    • min / max: The camera height range (in meters) where adjustment occurs.
    • minRadius / maxRadius: The corresponding radius range for the points.
    const heatmap = new HeatMapLayer({
  viewer,
  data,
  autoRadiusConfig: {
    enabled: true,
    min: 1000000,
    max: 10000000,
    minRadius: 1,
    maxRadius: 10,
  },
});

  10. Use GeoJsonPrimitiveLayer to load GeoJSON data

    master

    To visualize GeoJSON or TopoJSON data in Cesium, import the GeoJsonPrimitiveLayer class, instantiate it, and use the .load() method with the path to your data file. The .load() method returns a Promise that resolves when the data is fully loaded.

    import { GeoJsonPrimitiveLayer } from "@cesium-extends/primitive-geojson";

const layer = new GeoJsonPrimitiveLayer();
layer.load("path/to/data.json").then(() => {
  // Perform actions after data is loaded
});

  12. Use the Compass widget

    master

    To use the Compass widget, import it and instantiate it by passing your Cesium.Viewer instance to the constructor. The widget will automatically attach itself to the viewer.

    import Compass from '@cesium-extends/compass';

const viewer = new Cesium.Viewer('cesiumContainer');
const compass = new Compass(viewer);