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:*Graphicsclasses belong here;*Geometryclasses 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.entitiesis a shortcut to the default DataSource's EntityCollectionviewer.dataSourcesholds all loaded DataSources; each owns anEntityCollection
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 resolvestrueon completion.- For DataSources loaded via
await ...load(...), callviewer.zoomTo(ds)(notds.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/flyToon the array of entities or the DataSource -- this auto-fits a bounding sphere that includes every target. Hand-rolledCartesian3destinations 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.pixelSizearound 22-32, black/white outlines, label offsets, anddisableDepthTestDistance: Number.POSITIVE_INFINITYon 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. Seecesiumjs-camerafor 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/billboardandlabelto 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
阅读完整来源 ↗