Skip to main content

Add Marker

This example demonstrates how to add various markers on the map using the DMap3D SDK.

Preview​

Add marker points with icons and text labels on the 3D globe, with click interaction support.

Complete Code​

src/components/AddMarker.tsx
import { useEffect, useRef } from 'react'
import * as Cesium from 'cesium'
import './AddMarker.css'

function AddMarker() {
  const containerRef = useRef<HTMLDivElement>(null)
  const viewerRef = useRef<Cesium.Viewer | null>(null)

  useEffect(() => {
    if (!containerRef.current) return

    Cesium.Ion.defaultAccessToken = 'your-cesium-ion-token'

    const viewer = new Cesium.Viewer(containerRef.current, {
      animation: false,
      fullscreenButton: false,
      geocoder: false,
      homeButton: false,
      sceneModePicker: false,
      selectionIndicator: false,
      timeline: false,
      navigationHelpButton: false,
      infoBox: false,
      baseLayerPicker: false,
      terrainProvider: new Cesium.EllipsoidTerrainProvider({}),
    })
    viewerRef.current = viewer

    // Add point marker
    viewer.entities.add({
      name: 'Beijing',
      position: Cesium.Cartesian3.fromDegrees(116.4074, 39.9042),
      point: {
        pixelSize: 12,
        color: Cesium.Color.RED,
        outlineColor: Cesium.Color.WHITE,
        outlineWidth: 2,
      },
      label: {
        text: 'Beijing',
        font: '14px sans-serif',
        fillColor: Cesium.Color.WHITE,
        style: Cesium.LabelStyle.FILL_AND_OUTLINE,
        outlineWidth: 2,
        outlineColor: Cesium.Color.BLACK,
        verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
        pixelOffset: new Cesium.Cartesian2(0, -15),
      },
    })

    // Add billboard marker (icon)
    viewer.entities.add({
      name: 'Shanghai',
      position: Cesium.Cartesian3.fromDegrees(121.4737, 31.2304),
      billboard: {
        image: '/img/marker.png', // Custom icon
        width: 32,
        height: 32,
        verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
      },
      label: {
        text: 'Shanghai',
        font: '14px sans-serif',
        fillColor: Cesium.Color.WHITE,
        style: Cesium.LabelStyle.FILL_AND_OUTLINE,
        outlineWidth: 2,
        outlineColor: Cesium.Color.BLACK,
        verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
        pixelOffset: new Cesium.Cartesian2(0, -40),
      },
    })

    // Add custom styled marker
    viewer.entities.add({
      name: 'Guangzhou',
      position: Cesium.Cartesian3.fromDegrees(113.2644, 23.1291),
      point: {
        pixelSize: 16,
        color: Cesium.Color.BLUE,
        outlineColor: Cesium.Color.YELLOW,
        outlineWidth: 3,
        heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
      },
      label: {
        text: 'Guangzhou',
        font: 'bold 16px sans-serif',
        fillColor: Cesium.Color.YELLOW,
        style: Cesium.LabelStyle.FILL_AND_OUTLINE,
        outlineWidth: 2,
        outlineColor: Cesium.Color.BLACK,
        verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
        pixelOffset: new Cesium.Cartesian2(0, -20),
        heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
      },
    })

    // Fly to a panoramic view of China
    viewer.camera.flyTo({
      destination: Cesium.Cartesian3.fromDegrees(108.0, 34.0, 5000000.0),
    })

    return () => {
      viewer.destroy()
    }
  }, [])

  return (
    <div className="add-marker">
      <div ref={containerRef} className="cesium-container" />
      <div className="info-panel">
        <h3>Marker Examples</h3>
        <ul>
          <li><span className="dot red"></span> Beijing - Point marker</li>
          <li><span className="dot blue"></span> Shanghai - Icon marker</li>
          <li><span className="dot yellow"></span> Guangzhou - Custom style</li>
        </ul>
      </div>
    </div>
  )
}

export default AddMarker

Stylesheet​

src/components/AddMarker.css
.add-marker {
  position: relative;
  width: 100%;
  height: 100vh;
}

.cesium-container {
  width: 100%;
  height: 100%;
}

.info-panel {
  position: absolute;
  top: 20px;
  right: 20px;
  background: rgba(255, 255, 255, 0.95);
  padding: 20px;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
  min-width: 200px;
}

.info-panel h3 {
  margin: 0 0 10px 0;
  font-size: 18px;
}

.info-panel ul {
  list-style: none;
  padding: 0;
  margin: 0;
}

.info-panel li {
  display: flex;
  align-items: center;
  gap: 8px;
  margin: 8px 0;
  font-size: 14px;
}

.dot {
  width: 10px;
  height: 10px;
  border-radius: 50%;
  display: inline-block;
}

.dot.red { background: #ff0000; }
.dot.blue { background: #0000ff; }
.dot.yellow { background: #ffff00; border: 1px solid #999; }

Key Code Explanation​

1. Add Point Marker​

viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.4074, 39.9042),
  point: {
    pixelSize: 12,               // Point size (pixels)
    color: Cesium.Color.RED,     // Color
    outlineColor: Cesium.Color.WHITE, // Outline color
    outlineWidth: 2,             // Outline width
  },
})

2. Add Text Label​

label: {
  text: 'Beijing',
  font: '14px sans-serif',
  fillColor: Cesium.Color.WHITE,
  style: Cesium.LabelStyle.FILL_AND_OUTLINE,
  outlineWidth: 2,
  pixelOffset: new Cesium.Cartesian2(0, -15), // Offset to avoid overlap
}

3. Add Icon Marker​

billboard: {
  image: '/img/marker.png', // Icon path
  width: 32,
  height: 32,
  verticalOrigin: Cesium.VerticalOrigin.BOTTOM, // Bottom alignment
}

4. Clamp to Ground​

point: {
  heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
}

Using the heightReference property makes the marker conform to the terrain surface.

Extended Features​

  1. Click Interaction - Use ScreenSpaceEventHandler to show info popup when clicking markers
  2. Clustering - Use EntityCluster to automatically cluster markers when dense
  3. Dynamic Update - Modify Entity properties for dynamic marker changes
  4. Batch Loading - Batch load markers via GeoJSON data source