Getting Started

Vesium is a high-performance library designed for Cesium, adopting the Composable pattern consistent with VueUse. It integrates Cesium seamlessly using Hooks, providing type-safe APIs that significantly simplify the complexity of using Cesium in Vue applications.

🚧 Note: This project is actively under development, and the API may change frequently.

Prerequisites

Before you start, ensure you have the following:

• Experience with the Cesium mapping engine
• Basic knowledge of the Vue 3 Composition API
• Familiarity with the VueUse utility library

Installation

Using Package Managers

# NPM
npm install cesium @vueuse/core vesium

# Yarn
yarn add cesium @vueuse/core vesium

# pnpm
pnpm add cesium @vueuse/core vesium

Using CDN

You can also use Vesium via CDN:

<!-- Load Cesium core library -->
<script src="https://unpkg.com/cesium/Build/Cesium/Cesium.js"></script>

<!-- Load VueUse dependencies -->
<script src="https://unpkg.com/@vueuse/shared"></script>
<script src="https://unpkg.com/@vueuse/core"></script>

<!-- Load Vesium library -->
<script src="https://unpkg.com/vesium"></script>

When using CDN, all functionalities are exposed through the global object window.Vesium.

Basic Usage

Below is a simple example demonstrating how to use Vesium in a Vue project:

<script setup>
import { createViewer, useCameraState } from 'vesium';
import { ref, watch } from 'vue';

// Create container reference
const cesiumContainer = shallowRef<HtmlElement>();

// Create a Cesium Viewer instance
const viewer = createViewer(cesiumContainer);

// Use camera control hook
const { position, heading, pitch, roll } = useCameraState(viewer);

// Watch for camera position changes
watch(position, (newPosition) => {
  console.log('Camera position updated:', newPosition);
});
</script>

<template>
  <div ref="cesiumContainer" style="width: 100%; height: 100%" />
</template>

Module Overview

Vesium includes the following main modules:

• vesium: Main functionality module, providing basic Cesium operation hooks

  • createViewer: Creates a Cesium viewer instance
  • useCameraState: Camera state control
  • useEntity: Entity management
  • useImageryLayer: Imagery layer control
  • For more features, refer to the API documentation

• @vesium/serialize: Serialization tools module

  • Supports saving and restoring scene states
  • Provides data import/export functionality

Each module is optimized for on-demand loading and can be used based on your specific needs. For detailed API documentation and usage examples, refer to the specific module's documentation.