跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

cesiumjs-entities

CesiumJS entities and data sources - Entity, EntityCollection, DataSource, GeoJsonDataSource, KmlDataSource, CzmlDataSource, Graphics types, PathGraphics, PathMode, Visualizers. Use when adding points, labels, models, polygons, polylines, or time-segmented paths, loading GeoJSON/KML/CZML/GPX data, or working with the high-level Entity API.

CesiumGS · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add CesiumGS/cesiumjs-skills --skill cesiumjs-entities

技能说明


name: cesiumjs-entities description: "CesiumJS entities and data sources - Entity, EntityCollection, DataSource, GeoJsonDataSource, KmlDataSource, CzmlDataSource, Graphics types, PathGraphics, PathMode, Visualizers. Use when adding points, labels, models, polygons, polylines, or time-segmented paths, loading GeoJSON/KML/CZML/GPX data, or working with the high-level Entity API."

CesiumJS Entities & DataSources

Version baseline: CesiumJS 1.144 -- ES module imports: import { ... } from "cesium"; Ownership rule: *Graphics classes belong here; *Geometry classes belong in cesiumjs-primitives. Properties (SampledProperty, CallbackProperty, MaterialProperty subtypes) belong in cesiumjs-time-properties.

Architecture

The Entity API is the high-level, data-driven layer of CesiumJS. Entities combine position, orientation, and one or more Graphics types into a single object managed by an EntityCollection. DataSources load external formats (GeoJSON, KML, CZML, GPX) and populate an EntityCollection automatically. Visualizers and GeometryUpdaters translate Entity descriptions into Primitives each frame.

DataSource --> EntityCollection --> Entity
                                     |-- position / orientation
                                     |-- billboard / point / label / model / polygon / polyline / ...
                                     |-- properties (PropertyBag)
  • viewer.entities is a shortcut to the default DataSource's EntityCollection
  • viewer.dataSources holds all loaded DataSources; each owns an EntityCollection

Coordinate & Framing Rules (Read First)

Most visual evaluation failures are not API errors -- they are coordinate-sign and camera-framing mistakes. Burn these in:

  • Western hemisphere longitudes are NEGATIVE. NYC = -74.006, Los Angeles = -118.24, Chicago = -87.63, Denver = -104.99. A missing minus sign places NYC over India/Pakistan. Double-check every Western-hemisphere coordinate before submitting.

  • fromDegrees(longitude, latitude, height?) -- longitude first, then latitude. Mixing these up is the most common bug.

  • After adding entities, always frame them. Do not leave the camera at the default Pacific-centered view. Pick one:

    • viewer.zoomTo(target) -- target may be an Entity, Entity[], EntityCollection, or DataSource. Resolves once data is loaded.
    • viewer.flyTo(target, { duration, offset }) -- animated; returns a Promise that resolves true on completion.
    • For DataSources loaded via await ...load(...), call viewer.zoomTo(ds) (not ds.entities) so the bounding sphere is computed across all entities.
  • For collections spanning a region or the whole globe (e.g. "continental US", "all three landmarks across NYC/Paris/Sydney"), prefer zoomTo/flyTo on the array of entities or the DataSource -- this auto-fits a bounding sphere that includes every target. Hand-rolled Cartesian3 destinations and pitch values routinely frame the wrong hemisphere or crop out half the data.

    const nyc    = viewer.entities.add({ /* Statue of Liberty, -74.04, 40.69 */ });
    const paris  = viewer.entities.add({ /* Eiffel Tower,     2.29,  48.86 */ });
    const sydney = viewer.entities.add({ /* Sydney Opera,   151.22, -33.86 */ });
    await viewer.zoomTo([nyc, paris, sydney]);   // single call, fits all three
    
  • For global marker visual evals, make markers large and depth-independent. Use point.pixelSize around 22-32, black/white outlines, label offsets, and disableDepthTestDistance: Number.POSITIVE_INFINITY on both point and label when available. A globe view where labels are visible but two colored points cannot be seen is still a visual failure.

  • When framing a single AOI without an entity to target, prefer viewer.camera.flyTo({ destination: Rectangle.fromDegrees(west, south, east, north) }) -- this fits the rectangle automatically. See cesiumjs-camera for full camera control.

Entity Basics

Point

import { Viewer, Cartesian3, Color, HeightReference } from "cesium";

const viewer = new Viewer("cesiumContainer");
const entity = viewer.entities.add({
  id: "my-point",                 // optional; auto-generated GUID if omitted
  name: "Sample Point",
  position: Cartesian3.fromDegrees(-75.59777, 40.03883),
  point: {
    pixelSize: 10,
    color: Color.YELLOW,
    outlineColor: Color.BLACK,
    outlineWidth: 2,
    heightReference: HeightReference.CLAMP_TO_GROUND,
  },
});
viewer.zoomTo(entity);

Billboard with Label

import { Viewer, Cartesian3, Cartesian2, Color, VerticalOrigin, HeightReference, LabelStyle } from "cesium";

const viewer = new Viewer("cesiumContainer");
viewer.entities.add({
  position: Cartesian3.fromDegrees(-122.4175, 37.7749),
  billboard: {
    image: "/assets/marker.png",
    scale: 0.5,
    verticalOrigin: VerticalOrigin.BOTTOM,
    heightReference: HeightReference.CLAMP_TO_GROUND,
  },
  label: {
    text: "San Francisco",
    font: "14px sans-serif",
    fillColor: Color.WHITE,
    outlineColor: Color.BLACK,
    outlineWidth: 2,
    style: LabelStyle.FILL_AND_OUTLINE,
    pixelOffset: new Cartesian2(0, -36),
    heightReference: HeightReference.CLAMP_TO_GROUND,
  },
});

One entity per point + label is usually cleaner than two. Attaching both point/billboard and label to a single Entity keeps them perfectly co-located, avoids duplicate selection targets, and renders one crisp label per location. Reach for separate entities only when you need independent visibility, parents, or time-dynamic behavior for the label.

Polygon (flat, extruded, with holes)

import { Viewer, Cartesian3, Color, PolygonHierarchy } from "cesium";

const viewer = new Viewer("cesiumContainer");
// Flat polygon
viewer.entities.add({
  polygon: {
    hierarchy: Cartesian3.fromDegreesArray([-115, 37, -115, 32, -107, 33, -102, 31, -102, 35]),
    material: Color.RED.with
阅读完整来源 ↗