cesium添加各种实体的总结

在Cesium中，通过viewer.entities.add()可以添加多种类型的实体(Entity)。

• Entity API (viewer.entities.add)

  • 高级抽象：面向对象的设计，更易用，适合大多数应用场景。
  • 自动管理：Cesium内部会将其转换为底层的Primitive（通过DataSource机制）。
  • 功能集成：直接支持时间动态属性（如随时间变化的位置、旋转）、CZML数据绑定、Entity集合管理等。

• Primitive API

  • 底层控制：直接操作图形层（Graphics），需要手动管理更多细节。
  • 灵活性强：适合需要精细控制渲染性能或自定义图形行为的场景（如大量实例化模型、自定义着色器）。
  • 无自动转换：需要自行处理矩阵变换、材质、几何体等。

1. 基本图形实体

点(Point)

viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883),
    point: {
        pixelSize: 10, //点的大小
        color: Cesium.Color.RED, //颜色
        outlineColor: Cesium.Color.WHITE,//轮廓颜色
        outlineWidth: 2 //轮廓宽度
    }
});

线(Polyline)

var entity = viewer.entities.add({
    polyline: {
        positions: Cesium.Cartesian3.fromDegreesArray([-77, 35,-77.1, 35]),
        width: 5, //宽度
        material:Cesium.Color.RED， //材质，平面颜色
    }
});

var polyline = entity.polyline

//折线轮廓
polyline.material = new Cesium.PolylineOutlineMaterialProperty({
    color : Cesium.Color.ORANGE,
    outlineWidth : 3,
    outlineColor : Cesium.Color.BLACK
});
//折线光晕
polyline.material = new Cesium.PolylineGlowMaterialProperty({
    glowPower : 0.2,
    color : Cesium.Color.BLUE
});

多边形(Polygon)

viewer.entities.add({
    polygon: {
        hierarchy: Cesium.Cartesian3.fromDegreesArray([-115.0, 37.0, -115.0, 32.0, -107.0, 33.0, -102.0, 31.0, -102.0, 35.0]),
        material: Cesium.Color.RED.withAlpha(0.5), //材质
        height : 0,
        material : Cesium.Color.RED.withAlpha(0.5),
        outline : true,
        outlineColor : Cesium.Color.BLACK
    }
});

2. 3D形状实体

立方体(Box)

viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(-107.0, 40.0),
    box: {
        //`dimensions`是一个`Cartesian3`类型的属性,指（x）长(y)宽(z)高
        dimensions: new Cesium.Cartesian3(400000.0, 300000.0, 500000.0),
        material: Cesium.Color.BLUE.withAlpha(0.5), //材质
        outline: true, //描边
        outlineColor: Cesium.Color.BLACK //描边颜色
    }
});

椭圆体(Ellipsoid)

viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(-100.0, 40.0),
    ellipsoid: {
        //椭圆体在三个主轴方向上的半径长度。x：东向半径（经度方向）y：北向半径（纬度方向）z：垂直半径（高度方向）
        radii: new Cesium.Cartesian3(200000.0, 200000.0, 300000.0),
        material: Cesium.Color.GREEN.withAlpha(0.5),
        outline: true
    }
});

圆柱体(Cylinder)

viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(-105.0, 40.0),
    cylinder: {
        length: 400000.0,
        topRadius: 0.0,
        bottomRadius: 200000.0,
        material: Cesium.Color.CYAN.withAlpha(0.5),
        outline: true
    }
});

3. 标注类实体

标签(Label)

viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(-75.1641667, 39.9522222),
    label: {
        text: 'Philadelphia',
        font: '14pt sans-serif',
        style: Cesium.LabelStyle.FILL_AND_OUTLINE,
        outlineWidth: 2,
        verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
        pixelOffset: new Cesium.Cartesian2(0, -20)
    }
});

公告牌(Billboard)

viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883),
    billboard: {
        image: 'path/to/image.png',
        width: 50,
        height: 50,
        scale: 1.0,
        color: Cesium.Color.WHITE
    }
});

4. 模型类实体

3D模型(Model)

//平移矩阵 
viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706),
    //旋转控制
    orientation: Cesium.Quaternion.fromHeadingPitchRoll(
        new Cesium.HeadingPitchRoll(Cesium.Math.toRadians(45), 0, 0)
    )
    model: {
        uri: 'path/to/model.gltf',
        minimumPixelSize: 128,
        maximumScale: 20000,
        scale : 200.0,
        runAnimations: true,
       //如果你的GLTF模型有命名节点，可以单独控制这些节点的变换
        nodeTransformations: {
                'nodeName': {
                    rotation: Cesium.Quaternion.fromAxisAngle(
                        Cesium.Cartesian3.UNIT_X,
                        Cesium.Math.toRadians(45) // 绕X轴旋转45度
                    ),
                    // 也可以设置translation和scale
                }
            }

    }
});

Primitive API 示例

//平移矩阵
var modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(
    Cesium.Cartesian3.fromDegrees(-75.62898254394531, 40.02804946899414, 0.0));
    
//primitives添加
var model = viewer.scene.primitives.add(Cesium.Model.fromGltf({
    url : 'xx.glb',
    modelMatrix : modelMatrix,
    scale : 200.0
}));

//动画
//**addAll**用于播放模型中的所有动画
//*addAll*和*add*还提供了许多选项来控制动画的开始和停止时间、速度和方向。
Cesium.when(model.readyPromise).then(function(model) {
    model.activeAnimations.addAll({
        loop : Cesium.ModelAnimationLoop.REPEAT， //循环
        speedup : 0.5, //速度
        reverse : true //反向
    });
});

//将应用程序配置为自动播放动画
var viewer = new Cesium.Viewer('cesiumContainer', {
    shouldAnimate : true
});

路径(Path)

viewer.entities.add({
    availability: new Cesium.TimeIntervalCollection([/* 时间区间 */]),
    position: new Cesium.SampledPositionProperty(),
    path: {
        resolution: 1,
        material: new Cesium.PolylineGlowMaterialProperty({
            glowPower: 0.1,
            color: Cesium.Color.BLUE
        }),
        width: 10
    }
});

5. 高级实体

椭圆(Ellipse)

var entity = viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(-103.0, 40.0),
    ellipse: {
        semiMajorAxis: 300000.0,
        semiMinorAxis: 200000.0,
        material: Cesium.Color.BLUE.withAlpha(0.5),
        rotation: Cesium.Math.toRadians(45)
    }
});
var ellipse = entity.ellipse;

//贴图
ellipse.material = '//cesiumjs.org/tutorials/images/cats.jpg';

//棋盘
ellipse.material = new Cesium.CheckerboardMaterialProperty({
  evenColor : Cesium.Color.WHITE,
  oddColor : Cesium.Color.BLACK,
  repeat : new Cesium.Cartesian2(4, 4)
});

//条纹
ellipse.material = new Cesium.StripeMaterialProperty({
  evenColor : Cesium.Color.WHITE,
  oddColor : Cesium.Color.BLACK,
  repeat : 32
});

//网格
ellipse.material = new Cesium.GridMaterialProperty({
  color : Cesium.Color.YELLOW,
  cellAlpha : 0.2,
  lineCount : new Cesium.Cartesian2(8, 8),
  lineThickness : new Cesium.Cartesian2(2.0, 2.0)
});

//轮廓
ellipse.fill = false;
ellipse.outline = true;
ellipse.outlineColor = Cesium.Color.YELLOW;
ellipse.outlineWidth = 2.0;

矩形(Rectangle)

viewer.entities.add({
    rectangle: {
        coordinates: Cesium.Rectangle.fromDegrees(-100.0, 30.0, -90.0, 40.0),
        material: Cesium.Color.RED.withAlpha(0.5)
    }
});

Primitive API 示例

var scene = viewer.scene;

var instance = new Cesium.GeometryInstance({
  geometry : new Cesium.RectangleGeometry({
    rectangle : Cesium.Rectangle.fromDegrees(-100.0, 20.0, -90.0, 30.0),
    vertexFormat : Cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT
  }),
 attributes : {
    color : new Cesium.ColorGeometryInstanceAttribute(1.0, 0.0, 0.0, 0.8)
  }
});

scene.primitives.add(new Cesium.Primitive({
  geometryInstances : instance, //可以放数组[instance,anotherInstance]
  appearance : new Cesium.EllipsoidSurfaceAppearance({
    material : Cesium.Material.fromType('Stripe')
  })
}));

墙(Wall)

viewer.entities.add({
    wall: {
        positions: Cesium.Cartesian3.fromDegreesArrayHeights([-115.0, 50.0, 100000,
                                                             -112.0, 50.0, 100000]),
        minimumHeights: [50000, 50000],
        material: Cesium.Color.ORANGE
    }
});

走廊(Corridor)

viewer.entities.add({
    corridor: {
        positions: Cesium.Cartesian3.fromDegreesArray([-72.0, 40.0, -70.0, 35.0]),
        width: 200000.0,
        material: Cesium.Color.GREEN.withAlpha(0.5)
    }
});

6. 组合实体

可以组合多种实体类型：

viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883),
    point: { /* 点属性 */ },
    label: { /* 标签属性 */ },
    billboard: { /* 公告牌属性 */ }
});

7. 带时间轴的动态实体

const position = new Cesium.SampledPositionProperty();
position.addSample(Cesium.JulianDate.fromIso8601("2019-01-01T00:00:00Z"), 
                 Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883, 100));
position.addSample(Cesium.JulianDate.fromIso8601("2019-01-01T00:01:00Z"), 
                 Cesium.Cartesian3.fromDegrees(-75.59777, 40.13883, 1000));

viewer.entities.add({
    availability: new Cesium.TimeIntervalCollection([
        new Cesium.TimeInterval({
            start: Cesium.JulianDate.fromIso8601("2019-01-01T00:00:00Z"),
            stop: Cesium.JulianDate.fromIso8601("2019-01-01T00:01:00Z")
        })
    ]),
    position: position,
    point: {
        pixelSize: 10,
        color: Cesium.Color.RED
    },
    path: {
        resolution: 1,
        material: new Cesium.PolylineGlowMaterialProperty({
            glowPower: 0.1,
            color: Cesium.Color.YELLOW
        }),
        width: 5
    }
});

注意事项

1. 每个实体可以包含多种可视化表示，但通常只显示最适合当前视图的一种
2. 实体属性可以是静态值，也可以是动态Property对象
3. 使用viewer.entities.remove(entity)可以移除实体
4. 对于大量实体，考虑使用Primitive API以获得更好性能
5. 某些实体类型(如Model)需要额外资源加载时间