Cesium from Beginner to Master: A Practical Guide

Introduction

In the field of web visualization, if you need to build 3D earth, digital twin city, satellite orbit visualization or GIS system, there is a very powerful tool - CesiumJS.

Cesium is an open source JavaScript 3D map engine built on WebGL that can render high-performance 3D earth and spatial data in the browser.Originally developed by Cesium, it is now widely used in:

• 🌍 GIS Geographic Information System
• 🛰 Satellite orbit visualization
• 🏙 Digital Twin City
• 🚗 Traffic simulation system
• 🌦 Meteorological and environmental data visualization
• 🏗 Urban planning and architectural display

Many large-scale projects, such as smart cities and digital earth platforms, combine:

• CesiumJS
• Three.js
• Mapbox GL JS

Work together to build complex 3D GIS visualization systems.

This article is for beginners to intermediate developers. It will start from Environment Building → Basic Concepts → Practical Projects → Advanced Applications → Performance Optimization, and will take you step by step to master Cesium, and finally be able to independently develop a 3D map project.

1. Environmental preparation

1 Install Node.js and npm

First install Node.js (LTS version recommended).

Check after installation is complete:

node -v
npm -v

If the version number can be output, the installation is successful.

2 Introducing Cesium through CDN

The fastest way is to use a CDN.

Create index.html:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Cesium Demo</title>

    <script src="https://unpkg.com/cesium/Build/Cesium/Cesium.js"></script>

    <link
      href="https://unpkg.com/cesium/Build/Cesium/Widgets/widgets.css"
      rel="stylesheet"
    />

    <style>
      html,
      body,
      #cesiumContainer {
        width: 100%;
        height: 100%;
        margin: 0;
        padding: 0;
      }
    </style>
  </head>

  <body>
    <div id="cesiumContainer"></div>

    <script></script>
  </body>
</html>

3 Install via npm

Suitable for engineering development.

npm install cesium

Introduced into the project:

import * as Cesium from "cesium";

If using build tools (such as Vite/Webpack), you need to configure static resource path.

2. Basic concepts of Cesium

Cesium has several core objects that need to be understood.

1 Viewer

Viewer is Cesium entry object 。

It contains:

• Scene
• Camera
• Imagery
• Entity

Create Viewer:

const viewer = new Cesium.Viewer("cesiumContainer");

This line of code will:

• Create a 3D Earth
• Load default image
• Initialize camera control

2 Scene

Scene means Entire 3D scene 。

const scene = viewer.scene;

Scene management:

• earth
• light
• rendering

3 Camera

Camera controls View and Flight.

For example, flying to Beijing:

viewer.camera.flyTo({
  destination: Cesium.Cartesian3.fromDegrees(116.39, 39.9, 100000),
});

Parameter description:

Parameters	Meaning
longitude	longitude
latitude	latitude
height	height

4 Entity

Entity is a Cesium data object.

For example, add a point:

viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.39, 39.9),
  point: {
    pixelSize: 10,
    color: Cesium.Color.RED,
  },
});

5 ImageryProvider

ImageryProvider is used to load map images.

For example to load an image:

viewer.imageryLayers.addImageryProvider(
  new Cesium.UrlTemplateImageryProvider({
    url: "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
  }),
);

3. Getting Started: Creating a 3D Earth

Let's build a complete 3D Earth example.

Complete code

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>3D Earth Demo</title>

    <!-- 锁定到稳定版本，避免 API 变更导致报错 -->
    <script src="https://unpkg.com/cesium@1.95.0/Build/Cesium/Cesium.js"></script>
    <link
      href="https://unpkg.com/cesium@1.95.0/Build/Cesium/Widgets/widgets.css"
      rel="stylesheet"
    />

    <style>
      * {
        margin: 0;
        padding: 0;
        box-sizing: border-box;
      }
      html,
      body {
        width: 100%;
        height: 100%;
        overflow: hidden;
      }
      #cesiumContainer {
        width: 100%;
        height: 100vh;
      }

      #toolbar {
        position: absolute;
        top: 10px;
        left: 50%;
        transform: translateX(-50%);
        background: rgba(0, 0, 0, 0.6);
        color: #fff;
        padding: 8px 16px;
        border-radius: 6px;
        font-family: sans-serif;
        font-size: 14px;
        pointer-events: none;
      }
    </style>
  </head>

  <body>
    <div id="cesiumContainer"></div>
    <div id="toolbar">3D 地球演示 — 点击实体查看信息</div>

    <script>
      // -------------------------------------------------------
      // 1. 使用 ArcGIS 公开影像服务（无需 Token）
      // -------------------------------------------------------
      const imageryProvider = new Cesium.ArcGisMapServerImageryProvider({
        url: "https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer",
      });

      // -------------------------------------------------------
      // 2. 创建 Viewer
      //    terrainProvider 使用椭球体（无需 Cesium Ion Token）
      // -------------------------------------------------------
      const viewer = new Cesium.Viewer("cesiumContainer", {
        imageryProvider: imageryProvider,
        terrainProvider: new Cesium.EllipsoidTerrainProvider(),
        baseLayerPicker: false,
        geocoder: false,
        homeButton: true,
        sceneModePicker: true,
        navigationHelpButton: false,
        animation: false,
        timeline: false,
        fullscreenButton: true,
      });

      // 开启大气层 & 光照效果
      viewer.scene.globe.enableLighting = true;
      viewer.scene.skyAtmosphere.show = true;

      // -------------------------------------------------------
      // 3. 添加标注实体
      // -------------------------------------------------------
      const cities = [
        { name: "北京", lon: 116.39, lat: 39.9, color: Cesium.Color.YELLOW },
        { name: "上海", lon: 121.47, lat: 31.23, color: Cesium.Color.CYAN },
        { name: "广州", lon: 113.26, lat: 23.13, color: Cesium.Color.LIME },
        { name: "成都", lon: 104.06, lat: 30.67, color: Cesium.Color.ORANGE },
      ];

      cities.forEach(({ name, lon, lat, color }) => {
        viewer.entities.add({
          name: name,
          position: Cesium.Cartesian3.fromDegrees(lon, lat, 0),
          point: {
            pixelSize: 12,
            color: color,
            outlineColor: Cesium.Color.WHITE,
            outlineWidth: 2,
            heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
          },
          label: {
            text: name,
            font: "bold 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, -18),
            heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
          },
        });
      });

      // -------------------------------------------------------
      // 4. 镜头飞到初始视角（俯瞰中国）
      // -------------------------------------------------------
      viewer.camera.flyTo({
        destination: Cesium.Cartesian3.fromDegrees(105, 35, 6000000),
        orientation: {
          heading: Cesium.Math.toRadians(0),
          pitch: Cesium.Math.toRadians(-45),
          roll: 0.0,
        },
        duration: 3,
      });

      // -------------------------------------------------------
      // 5. 点击实体弹出信息框
      // -------------------------------------------------------
      viewer.screenSpaceEventHandler.setInputAction((click) => {
        const picked = viewer.scene.pick(click.position);
        if (Cesium.defined(picked) && Cesium.defined(picked.id)) {
          viewer.selectedEntity = picked.id;
        }
      }, Cesium.ScreenSpaceEventType.LEFT_CLICK);
    </script>
  </body>
</html>

Run steps

1 Create index.html 2 Run using local server

npx serve

3 Browser opens

http://localhost:3000

You will see:

• 🌍 3D Earth
• 📍 Beijing Mark
• 📷Camera Flying

4. Intermediate Advanced

1 Load 3D model (glTF)

Cesium supports the glTF model.

viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.39, 39.9),
  model: {
    uri: "model.gltf",
    scale: 1,
  },
});

Note:

• glTF path must be correct
• The model size needs to be adjusted to scale

2 Load GeoJSON

Much GIS data is GeoJSON.

Cesium.GeoJsonDataSource.load("data.geojson").then(function (dataSource) {
  viewer.dataSources.add(dataSource);
});

GeoJSON example:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [116.39, 39.9]
      }
    }
  ]
}

3 Custom materials

You can set materials for objects.

viewer.entities.add({
  polygon: {
    hierarchy: Cesium.Cartesian3.fromDegreesArray([
      116, 39, 117, 39, 117, 40, 116, 40,
    ]),
    material: Cesium.Color.BLUE.withAlpha(0.5),
  },
});

FAQ

The model cannot be seen

Possible reasons:

• Model path error
• Wrong height
• scale is too small

GeoJSON does not display

Possible reasons:

• Coordinate system is not WGS84
• wrong file path

5. Advanced practice: city simulation system

A typical project may include:

• urban architecture
• real time data
• Trajectory animation

1 Load KML

viewer.dataSources.add(Cesium.KmlDataSource.load("city.kml"));

2 Load CZML

CZML is used for time series data.

Such as satellite orbits.

viewer.dataSources.add(Cesium.CzmlDataSource.load("orbit.czml"));

3 Real-time data visualization

Data can be updated via WebSocket:

socket.onmessage = function (event) {
  const data = JSON.parse(event.data);

  viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(data.lon, data.lat),
    point: {
      pixelSize: 8,
    },
  });
};

4 Performance optimization

LOD (Level of Detail)

Load low-precision models from a distance.

Load high-precision models nearby.

Clustering

A large number of points need to be aggregated:

dataSource.clustering.enabled = true;

Recommended project structure

project
 ├ data
 ├ models
 ├ src
 ├ index.html

It is recommended to host the project on GitHub:

github.com/yourname/cesium-city-demo

6. Best Practices and Debugging

Common mistakes

1 Coordinate system error

Cesium uses:

WGS84

Many China maps use:

GCJ02

Need to convert.

2 Performance bottleneck

Avoid:

一次加载 10 万 entity

Suggestions:

• Use primitive
• Using 3D Tiles

WebGL Debugging Tools

Recommended:

• Chrome WebGL Inspector
• Spector.js

learning resources

Official documentation:

• CesiumJS official documentation

Example platform:

• Cesium Sandcastle

Community:

• GitHub
• Cesium Forum

7. Conclusion

Through this article, you have learned:

• 1 Cesium environment setup
• 2 Core concepts (Viewer/Camera/Entity)
• 3 Basic 3D Earth Project
• 4 GeoJSON and 3D model loading
• 5 City simulation system development
• 6 Performance Optimization Tips

Suggested learning paths:

Cesium 基础
↓
GIS 数据处理
↓
3D Tiles
↓
数字孪生系统

I suggest you do more research on:

• Cesium Sandcastle sample code
• Open source projects
• Official documentation

If you continue to practice, you can gradually grow from a Cesium beginner to a 3D GIS developer, and even participate in open source contributions to build more complex Digital Earth and City Visualization Systems.🌍🚀