Skip to main content

Basic Concepts

This page introduces the core concepts you need to understand when developing with the DMap3D SDK.

Viewer (Scene Container)​

Viewer is the core class of Cesium, responsible for managing the rendering and interaction of the entire 3D scene. Typically, only one Viewer instance is created per page.

const viewer = new Cesium.Viewer('cesiumContainer', {
  animation: false,    // Animation widget
  timeline: false,     // Timeline
  baseLayerPicker: false, // Basemap picker
})

Common Properties​

PropertyDescription
viewer.sceneScene object, manages rendering and the globe
viewer.cameraCamera object, controls the viewpoint
viewer.entitiesEntity collection
viewer.imageryLayersImagery layer collection
viewer.scene.primitivesPrimitive collection (3DTiles, etc.)

Lifecycle​

// Create
const viewer = new Cesium.Viewer(container, options)

// Use
viewer.entities.add({ ... })
viewer.camera.flyTo({ ... })

// Destroy (release memory, must be called)
viewer.destroy()
Note

In React, make sure to call viewer.destroy() in the useEffect cleanup function to prevent memory leaks.

Coordinate Systems​

Cesium uses multiple coordinate systems, and understanding the relationships between them is important.

Longitude/Latitude (Degrees)​

The most intuitive geographic coordinate representation:

// Longitude, latitude, height (meters)
const longitude = 116.4074  // East longitude
const latitude = 39.9042    // North latitude
const height = 100          // Altitude above sea level

Cartesian3 (Cartesian Coordinates)​

The 3D Cartesian coordinate system used internally by Cesium, with the Earth's center as the origin:

// Longitude/Latitude -> Cartesian3
const position = Cesium.Cartesian3.fromDegrees(116.4074, 39.9042, 100)

// Radians -> Cartesian3
const position2 = Cesium.Cartesian3.fromRadians(lon, lat, height)

Cartographic (Radian Coordinates)​

// Cartesian3 -> Cartographic
const carto = Cesium.Cartographic.fromCartesian(position)
const lon = Cesium.Math.toDegrees(carto.longitude)
const lat = Cesium.Math.toDegrees(carto.latitude)
const alt = carto.height

Coordinate Conversion Quick Reference​

Degrees <-> Cartesian3 <-> Cartographic (Radians)
ConversionMethod
Degrees -> Cartesian3Cesium.Cartesian3.fromDegrees(lon, lat, height)
Cartesian3 -> DegreesCesium.Cartographic.fromCartesian(pos) + Math.toDegrees
Degrees -> RadiansCesium.Math.toRadians(degrees)
Radians -> DegreesCesium.Math.toDegrees(radians)

Entity​

Entity is the simplest way to add visual objects to a scene, supporting points, lines, polygons, labels, and more.

// Add a point
viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.4074, 39.9042),
  point: {
    pixelSize: 10,
    color: Cesium.Color.RED,
  },
})

// Add a line
viewer.entities.add({
  polyline: {
    positions: Cesium.Cartesian3.fromDegreesArray([
      116.39, 39.90,
      116.41, 39.92,
    ]),
    width: 3,
    material: Cesium.Color.YELLOW,
  },
})

// Add a polygon
viewer.entities.add({
  polygon: {
    hierarchy: Cesium.Cartesian3.fromDegreesArray([
      116.39, 39.90,
      116.41, 39.90,
      116.41, 39.92,
      116.39, 39.92,
    ]),
    material: Cesium.Color.BLUE.withAlpha(0.5),
  },
})

Camera​

The camera controls the viewing angle of the scene.

Instant Positioning​

viewer.camera.setView({
  destination: Cesium.Cartesian3.fromDegrees(116.4074, 39.9042, 10000),
  orientation: {
    heading: Cesium.Math.toRadians(0),    // Heading (0 = North)
    pitch: Cesium.Math.toRadians(-45),    // Pitch (negative = looking down)
    roll: 0,
  },
})

Flight Animation​

viewer.camera.flyTo({
  destination: Cesium.Cartesian3.fromDegrees(116.4074, 39.9042, 10000),
  duration: 2.0,  // Flight duration (seconds)
})

View Parameters​

ParameterDescriptionRange
headingHorizontal direction0° = North, 90° = East, 180° = South, 270° = West
pitchPitch angle-90° = straight down, 0° = horizontal
rollRoll angleUsually 0

Imagery Layers​

Imagery layers are 2D map basemaps overlaid on the globe surface.

// Satellite imagery
const imgLayer = new Cesium.WebMapTileServiceImageryProvider({
  url: 'https://t0.tianditu.gov.cn/img_w/wmts?tk=YOUR_TOKEN',
  layer: 'img',
  style: 'default',
  tileMatrixSetID: 'w',
  format: 'tiles',
  maximumLevel: 18,
})

// Vector annotations (overlaid on imagery to display place names)
const ciaLayer = new Cesium.WebMapTileServiceImageryProvider({
  url: 'https://t0.tianditu.gov.cn/cia_w/wmts?tk=YOUR_TOKEN',
  layer: 'cia',
  style: 'default',
  tileMatrixSetID: 'w',
  format: 'tiles',
  maximumLevel: 18,
})

// Add annotation layer
viewer.imageryLayers.addImageryProvider(ciaLayer)

Layer Management​

// Add a layer
const layer = viewer.imageryLayers.addImageryProvider(provider)

// Set opacity
layer.alpha = 0.5

// Remove a layer
viewer.imageryLayers.remove(layer)

Terrain​

Terrain gives the earth's surface realistic elevation relief.

// Use Cesium Ion global terrain
const viewer = new Cesium.Viewer(container, {
  terrain: Cesium.Terrain.fromWorldTerrain(),
})

// No terrain (flat ellipsoid)
const viewer = new Cesium.Viewer(container, {
  terrainProvider: new Cesium.EllipsoidTerrainProvider({}),
})
Choosing Terrain
  • Use fromWorldTerrain() when terrain analysis (slope, profile, etc.) is needed
  • Use EllipsoidTerrainProvider for flat display only, which loads faster

3DTiles (3D Models)​

3DTiles is a standard format for streaming large-scale 3D data (buildings, oblique photography, etc.).

// Load 3DTiles
const tileset = await Cesium.Cesium3DTileset.fromUrl(
  '/3DTiles/model/tileset.json'
)
viewer.scene.primitives.add(tileset)

// Fly to the model location
viewer.zoomTo(tileset)

DMap3D Namespace​

The DMap3D SDK organizes all functional modules through namespaces:

DMap3D
├── measurement          // Measurement tools
│   ├── spaceDistance     // Spatial distance
│   ├── horizontalDistance // Horizontal distance
│   ├── surfaceDistance   // Surface distance
│   ├── area             // Area
│   ├── height           // Height
│   ├── angle            // Angle
│   ├── slope            // Slope
│   └── azimuth          // Azimuth
├── analysis             // Analysis tools
│   ├── viewshed         // Viewshed
│   ├── viewshedArea     // Area viewshed
│   ├── contour          // Contour lines
│   ├── profile          // Profile
│   ├── skyline          // Skyline
│   ├── bufferAnalysis   // Buffer
│   ├── elevationExtremum // Elevation extremum
│   ├── aspectAnalyse    // Aspect
│   ├── slopAnalyse      // Slope analysis
│   ├── cutFill          // Cut and fill
│   └── flattenAnalysis  // Flatten
├── drawing              // Drawing tools
│   ├── point            // Point
│   ├── polyline         // Polyline
│   ├── polygon          // Polygon
│   └── circle           // Circle
└── military             // Military plotting
    ├── FineArrow        // Fine arrow
    ├── StraightArrow    // Straight arrow
    └── ...              // More plotting tools

Usage Pattern​

All tools follow a unified lifecycle:

// 1. Create tool (pass in viewer)
const tool = new DMap3D.measurement.spaceDistance(viewer, options)

// 2. Activate tool
tool.activate()

// 3. User interaction (left-click to operate, right-click to finish)

// 4. Clear results
tool.clear()

// 5. Destroy tool
tool.destroy()

Resource Cleanup​

In Cesium and DMap3D, properly cleaning up resources is very important:

useEffect(() => {
  const viewer = new Cesium.Viewer(container)
  const tool = new DMap3D.measurement.area(viewer)

  return () => {
    // Destroy tool first
    tool.destroy()
    // Then destroy Viewer
    viewer.destroy()
  }
}, [])
Memory Leaks

If destroy() is not called, Cesium's WebGL context and event listeners will not be released, causing severe memory leaks.

Next Steps​

After mastering the basic concepts, you can dive deeper into: