Getting Started

Installation

Run the following command in your project directory:

pnpm add dde-earth

Quick Start

To initialize the Earth, pass in the element ID or HTML element.

💡

Optional configurations include the Earth background color, custom internationalization content, etc. Click here for more details.

If you already have a created Cesium Viewer object, you can also pass it as a parameter to the Earth constructor, and immediately gain all the capabilities of the Earth object.

import { Earth } from "dde-earth";
 
const earth = new Earth("container");

The default Earth object only has a few features, such as switching between 2D and 3D, and resetting the default viewport. You need to add more plugins to enable capabilities like adding layers, subscribing to Earth events, and so on.

Adding Plugins

Adding a plugin is very easy. The official team provides some commonly used plugins. After downloading the npm package, you only need a few lines of code to gain the extended capabilities of the plugin on the Earth object.

import { Earth } from "dde-earth";
import { LayerLoaders } from "@dde-earth/recommend-plugins";
 
const earth = new Earth("container");
 
// Use the base layer addition plugin
earth.usePlugin(new LayerLoaders());

The LayerLoaders plugin supports adding various map service protocols natively supported by Cesium.

// Add an ArcGIS layer
const arcgisLayer = await earth.addLayer({
  url: "https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer",
  enablePickFeatures: false,
  method: "arcgis",
});
 
// Add a TMS layer
const tmsLayer = await earth.addLayer({
  id: "scotese",
  url: "https://alpha.deep-time.org/tms/Scotese2018/5304326/{z}/{x}/{reverseY}.png",
  srs: "EPSG:4326", // Supports 4326 and 3857 projections by default
  method: "tms",
});

The created map object integrates common layer operations such as zooming and rendering.

// Adjust rendering parameters
tmsLayer.render({
  alpha: 0.5
});
 
// Zoom to the map
tmsLayer.zoomTo();
 
// Hide the layer
tmsLayer.show = false;

To remove a layer, you can use the remove method directly on the map object or the removeLayer method on the earth object.

// Remove a layer using the layer ID
earth.removeLayer("scotese");
 
// Remove a layer using the layer object
earth.removeLayer(tmsLayer);
 
// Call the remove method directly on the layer object
tmsLayer.remove();

Before operating on a layer, you can add event listeners to monitor the addition, rendering, and removal of the layer.

// Add a layer rendering event listener
earth.on("layer:render", (layerItem) => {
  console.log("render", layerItem);
});