### Basic Vesium.js Usage in Vue

Source: https://github.com/vesiumjs/vesium/blob/main/packages/start.en.md

Demonstrates a basic setup for using Vesium.js within a Vue 3 application. It shows how to create a Cesium viewer instance, manage camera state using `useCameraState`, and log camera position changes.

```vue
<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>
```

--------------------------------

### Install Vesium.js with Package Managers

Source: https://github.com/vesiumjs/vesium/blob/main/packages/start.en.md

Install Vesium.js along with Cesium and VueUse using NPM, Yarn, or pnpm. These commands ensure all necessary dependencies are added to your project for Cesium integration.

```bash
# NPM
npm install cesium @vueuse/core vesium

# Yarn
yarn add cesium @vueuse/core vesium

# pnpm
pnpm add cesium @vueuse/core vesium
```

--------------------------------

### Installation

Source: https://context7.com/vesiumjs/vesium/llms.txt

Instructions for installing Vesium and its peer dependencies using NPM, Yarn, or pnpm.

```APIDOC
## Installation

Install Vesium and its peer dependencies using your preferred package manager.

```bash
# NPM
npm install cesium @vueuse/core vesium

# Yarn
yarn add cesium @vueuse/core vesium

# pnpm
pnpm add cesium @vueuse/core vesium
```
```

--------------------------------

### Load Vesium.js via CDN

Source: https://github.com/vesiumjs/vesium/blob/main/packages/start.en.md

Load Vesium.js and its dependencies (Cesium, VueUse) directly from a CDN. This method exposes all functionalities through the global `window.Vesium` object, suitable for quick integration without a build process.

```html
<!-- 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>
```

--------------------------------

### Load Single or Multiple Entities with useEntity (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useEntity/index.en.md

Demonstrates the usage of the useEntity hook for loading single or multiple Entity instances. It shows basic overloads and an example with optional configuration parameters like collection, isActive, and evaluating (loading status).

```typescript
// Overload 1: Load a single instance
const entity = useEntity(entity);

// Overload 2: Load an array of instances
const entities = useEntity([entity1, entity2]);

const isActive = ref(true);
const isLoading = ref(true);

// Options
const entity = useEntity(entity, {
  collection,
  isActive,
  evaluating: isLoading
});
```

--------------------------------

### Vesium: Usage Examples for toPromiseValue (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/best.en.md

Demonstrates practical applications of the toPromiseValue function with different input types: a direct value, a Vue ref, and an async getter. It also shows integration with VueUse's computedAsync for managing asynchronous computed properties.

```typescript
// Usage examples
toPromiseValue(1);
toPromiseValue(ref(1));
toPromiseValue(async () => await fetchData()); // -> Promise<T>

const value = computedAsync(() => toPromiseValue(asyncData));
```

--------------------------------

### Avoid Hooks in Global State Management (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/best.en.md

Explains why Vesium hooks should not be used directly within global state management solutions like Vuex or Pinia. It provides examples of the non-recommended approach and the recommended separation of concerns, handling viewer-related logic within components.

```typescript
// ❌ Not recommended: using Hooks in store
// /src/store/main.ts
defineStore('main', () => {
  const entity = shallowRef(new Cesium.Entity({}));
  useEntity(entity); // Error: cannot access viewer instance
});
```

```typescript
// ✅ Recommended: separation of concerns
// /src/store/main.ts
defineStore('main', () => {
  const entity = shallowRef(new Cesium.Entity({}));
  return { entity };
});

// /src/components/entity.vue
const mainStore = useMainStore();

const { viewer } = useViewer();
useEntity(() => mainStore.entity); // Handle viewer-related logic in component
```

--------------------------------

### Use useScenePick Hook (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useScenePick/index.en.md

Demonstrates how to use the useScenePick hook in TypeScript. It initializes a window position and then calls the hook to get the pick functionality. The hook returns a function that can be called with the current window position to perform the pick operation.

```typescript
import { shallowRef } from "vue";
import * as Cesium from "cesium";
import { useScenePick } from "@vesiumjs/vesium";

const windowPosition = shallowRef(new Cesium.Cartesian2());
const pick = useScenePick(windowPosition, { /** options */ });

// To perform a pick operation:
// const pickedObject = await pick();
```

--------------------------------

### Access Reactive Instances in Lifecycle Hooks (Vue)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/best.en.md

Illustrates the correct way to access and manipulate reactive Cesium instances within Vue components. It highlights the importance of using lifecycle hooks like `watchEffect` to ensure instances are initialized before interaction, contrasting it with direct access in `setup`.

```vue
// ❌ Not recommended: accessing directly in setup
<script setup>
const entity = useEntity(new Cesium.Entity());
entity.value.position = 'xxx'; // Error: entity.value might be undefined at this time
</script>
```

```vue
// ✅ Recommended: accessing in lifecycle hooks
<script setup>
const entity = useEntity(new Cesium.Entity());

watchEffect(() => {
  if (entity.value) { // Ensure instance is initialized
    entity.value.position = 'xxx';
  }
});
</script>
```

--------------------------------

### Use Shallow Reactivity for Cesium Instances (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/best.en.md

Demonstrates the recommended use of `shallowRef` for Cesium instances to avoid performance issues and interference with Cesium's internal mechanisms. It contrasts this with the non-recommended deep reactivity approach.

```typescript
// ❌ Not recommended: using deep reactivity
const entity = ref(new Cesium.Entity());

useEntity(entity);

watch(position, (position) => {
  entity.position = position; // Error: not accessing with .value
});
```

```typescript
// ✅ Recommended: using shallow reactivity
const entity = shallowRef(new Cesium.Entity());

useEntity(entity);

watch(position, (position) => {
  entity.value.position = position; // Correct: accessing with .value
  triggerRef(entity); // Manually trigger update
});
```

--------------------------------

### Basic useElementOverlay Usage (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useElementOverlay/index.en.md

Demonstrates the fundamental usage of the useElementOverlay composable. It requires a target HTML element and a Cesium position. Optional configuration includes alignment, offset, and reference window settings.

```typescript
const { x, y, elementOverlay } = useElementOverlay(
  targetElement,
  position,
  {
    horizontal: 'center',
    vertical: 'bottom',
    offset: { x: 0, y: 0 },
    referenceWindow: false,
  }
);
```

--------------------------------

### Initialize or Reuse Viewer Instance (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/createViewer/index.en.md

Demonstrates how to initialize a new VesiumJS Viewer instance or reuse an existing one using createViewer. The first overload creates a new instance managed by the component's lifecycle, while the second injects a pre-existing instance. The useViewer hook can then access the created or injected instance.

```typescript
// overLoad1: Creates a new instance, which is automatically destroyed when the component unmounts
const viewer = createViewer(elRef, {
  // ...options
});

// overLoad2: Injects an existing instance, which is not automatically destroyed when the component unmounts
const viewer = createViewer(window.viewer);

// After creating an instance, the current component and its descendant components can access the instance using useViewer
const viewer = useViewer();
```

--------------------------------

### Manage Cesium Collection Side Effects with useCollectionScope (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useCollectionScope/index.en.md

This example demonstrates how to use the `useCollectionScope` hook to add and remove entities from a Cesium viewer's collection. It automatically handles the removal of entities when the component unmounts, preventing memory leaks. The hook requires `addEffect` and `removeEffect` functions to interact with the Cesium collection.

```typescript
import { useCollectionScope } from 'vesium';

const { add, remove, scope } = useCollectionScope({
  addEffect: instance => viewer.entities.add(instance),
  removeEffect: instance => viewer.entities.remove(instance)
});

const entity = add({ id: 'test' });
// When the component is unmounted, the entity is automatically removed from viewer.entities
```

--------------------------------

### Configure Primitive Loading with Options using usePrimitive (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/usePrimitive/index.en.md

Shows how to configure the usePrimitive hook with additional options for advanced control. This overload allows specifying a primitive collection, activation status, and a loading status reference, enabling fine-grained management of primitive behavior and state.

```typescript
import { usePrimitive } from 'vesiumjs';
import { ref } from 'vue';

// Assume 'collection' is a Cesium PrimitiveCollection
const collection = new Cesium.PrimitiveCollection();
const isActive = ref(true);
const isLoading = ref(true);

const primitive = usePrimitive(primitiveToLoad, {
  collection: collection,
  isActive: isActive,
  evaluating: isLoading // Loading status reference
});
```

--------------------------------

### createViewer

Source: https://context7.com/vesiumjs/vesium/llms.txt

Initializes a Cesium Viewer instance or reuses an existing one. The viewer is automatically destroyed when the component unmounts.

```APIDOC
## createViewer

Initializes a Cesium Viewer instance or reuses an existing instance. The created viewer can be accessed by `useViewer` in the current component and its descendant components. The viewer is automatically destroyed when the component unmounts.

### Method

```
createViewer(container: HTMLElement | ShallowRef<HTMLElement>, options?: Viewer.ViewerOptions): Ref<Viewer>
createViewer(viewer: Viewer): Ref<Viewer>
```

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

**container** (HTMLElement | ShallowRef<HTMLElement>) - Required - The HTML element or shallow ref to contain the Cesium Viewer.
**options** (Viewer.ViewerOptions) - Optional - Configuration options for the Cesium Viewer.
**viewer** (Viewer) - Required - An existing Cesium Viewer instance to be managed.

### Request Example

```vue
<script setup>
import { createViewer } from 'vesium';
import { shallowRef } from 'vue';

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

// Overload 1: Create a new Viewer instance (automatically destroyed on unmount)
const viewer = createViewer(cesiumContainer, {
  animation: false,
  timeline: false,
  baseLayerPicker: false,
  geocoder: false,
  homeButton: false,
  sceneModePicker: false,
  navigationHelpButton: false,
  fullscreenButton: false,
});

// Overload 2: Inject an existing Viewer instance (not automatically destroyed)
// const viewer = createViewer(window.existingViewer);
</script>

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

### Response

#### Success Response (200)

- **viewer** (Ref<Viewer>) - A Vue ref containing the Cesium Viewer instance.

#### Response Example

```json
{
  "viewer": "Cesium.Viewer instance"
}
```
```

--------------------------------

### Create Cesium Viewer Instance (Vue)

Source: https://context7.com/vesiumjs/vesium/llms.txt

Initializes a Cesium Viewer instance within a Vue component. It can create a new viewer or reuse an existing one, automatically managing its lifecycle. The viewer is accessible via `useViewer` in descendant components.

```vue
<script setup>
import { createViewer } from 'vesium';
import { shallowRef } from 'vue';

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

// Overload 1: Create a new Viewer instance (automatically destroyed on unmount)
const viewer = createViewer(cesiumContainer, {
  animation: false,
  timeline: false,
  baseLayerPicker: false,
  geocoder: false,
  homeButton: false,
  sceneModePicker: false,
  navigationHelpButton: false,
  fullscreenButton: false,
});

// Overload 2: Inject an existing Viewer instance (not automatically destroyed)
// const viewer = createViewer(window.existingViewer);
</script>

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

--------------------------------

### Understanding MaybeRefOrGetter and toValue (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/best.en.md

Demonstrates the `MaybeRefOrGetter` type and the `toValue` utility function commonly used in Vue and VueUse. It shows how `toValue` correctly extracts the value from refs, getters, or plain values to ensure compatibility with Vue's reactivity system.

```typescript
type MaybeRefOrGetter<T> = Ref<T> | (() => T) | T;

function toValue<T>(value: MaybeRefOrGetter<T>): T;

toValue(1); // -> 1
toValue(ref(1)); // -> 1
toValue(() => 1); // -> 1
```

--------------------------------

### useCameraState

Source: https://context7.com/vesiumjs/vesium/llms.txt

Provides reactive access to the Cesium Camera instance state, including position, direction, and view rectangle.

```APIDOC
## useCameraState

Provides reactive access to the Cesium Camera instance state. Returns computed properties for camera position, direction, heading, pitch, roll, and view rectangle that automatically update when the camera moves.

### Method

```
useCameraState(options?: { event?: 'changed' | 'moveStart' | 'moveEnd'; delay?: number }): {
  camera: Ref<Camera>;
  position: Ref<Cartesian3 | undefined>;
  positionCartographic: Ref<Cartographic | undefined>;
  heading: Ref<number | undefined>;
  pitch: Ref<number | undefined>;
  roll: Ref<number | undefined>;
  viewRectangle: Ref<Rectangle | undefined>;
  level: Ref<number | undefined>;
}
```

### Parameters

#### Query Parameters

- **options** (object) - Optional - Configuration options for camera state tracking.
  - **event** (string) - Optional - The camera event to listen for. Defaults to 'changed'. Possible values: 'changed', 'moveStart', 'moveEnd'.
  - **delay** (number) - Optional - Throttle delay in milliseconds for updates. Defaults to 0.

### Request Example

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

const cesiumContainer = shallowRef<HTMLElement>();
const viewer = createViewer(cesiumContainer);

// Get reactive camera state
const {
  camera,
  position,
  positionCartographic,
  heading,
  pitch,
  roll,
  viewRectangle,
  level,
} = useCameraState({
  event: 'changed',
  delay: 8,
});

// Watch for camera position changes
watch(positionCartographic, (newPos) => {
  if (newPos) {
    const lon = Cesium.Math.toDegrees(newPos.longitude);
    const lat = Cesium.Math.toDegrees(newPos.latitude);
    console.log(`Camera at: ${lon.toFixed(4)}, ${lat.toFixed(4)}, Level: ${level.value}`);
  }
});
</script>
```

### Response

#### Success Response (200)

- **camera** (Ref<Camera>) - A Vue ref containing the Cesium Camera instance.
- **position** (Ref<Cartesian3 | undefined>) - A Vue ref containing the Cartesian3 position of the camera.
- **positionCartographic** (Ref<Cartographic | undefined>) - A Vue ref containing the Cartographic position (longitude, latitude, height in radians) of the camera.
- **heading** (Ref<number | undefined>) - A Vue ref containing the camera's heading in radians.
- **pitch** (Ref<number | undefined>) - A Vue ref containing the camera's pitch in radians.
- **roll** (Ref<number | undefined>) - A Vue ref containing the camera's roll in radians.
- **viewRectangle** (Ref<Rectangle | undefined>) - A Vue ref containing the visible rectangle on the ellipsoid.
- **level** (Ref<number | undefined>) - A Vue ref containing the computed zoom level.

#### Response Example

```json
{
  "camera": "Cesium.Camera instance",
  "position": {
    "x": 1234567.89,
    "y": 2345678.90,
    "z": 3456789.01
  },
  "positionCartographic": {
    "longitude": 1.2345,
    "latitude": 0.6789,
    "height": 10000.0
  },
  "heading": 0.5,
  "pitch": -0.2,
  "roll": 0.0,
  "viewRectangle": {
    "west": -1.0,
    "south": -0.5,
    "east": 1.0,
    "north": 0.5
  },
  "level": 15
}
```
```

--------------------------------

### Use Viewer Instance in Same Component (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useViewer/index.en.md

Demonstrates how to create a Viewer instance and then retrieve it within the same component using the useViewer hook. This ensures the component has access to the viewer's functionalities.

```typescript
createViewer(/** options */);

// Must be called after `createViewer`
const viewer = useViewer();
```

--------------------------------

### Use Cesium Event Listener with Throttling (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useCesiumEventListener/index.en.md

Demonstrates how to use `useCesiumEventListener` with throttling for Cesium's `postRender` event. It shows how to integrate with `@vesium/shared`'s `throttle` and `@vueuse/core`'s `refThrottled` to manage frequent event triggers.

```typescript
import { throttle } from '@vesium/shared';
import { refThrottled } from '@vueuse/core';
import { useCesiumEventListener } from 'vesium';

const listener = throttle(() => {
  // TODO
}, 100);
useCesiumEventListener(() => viewer.value?.scene.postRender, listener);

const current = refThrottled(ref(new Date().getTime()), 100);
useCesiumEventListener(() => viewer.value?.scene.postRender, () => {
  current.value = new Date().getTime();
});
```

--------------------------------

### useViewer

Source: https://context7.com/vesiumjs/vesium/llms.txt

Retrieves the Viewer instance injected by `createViewer` in the current component or its ancestor components.

```APIDOC
## useViewer

Retrieves the Viewer instance injected by `createViewer` in the current component or its ancestor components. Must be called after `createViewer` when used in the same component.

### Method

```
useViewer(): Ref<Viewer>
```

### Parameters

None

### Request Example

```vue
<!-- Parent.vue -->
<script setup>
import { createViewer } from 'vesium';
import { shallowRef } from 'vue';

const elRef = shallowRef<HTMLElement>();
const viewer = createViewer(elRef);
</script>

<template>
  <div ref="elRef" style="width: 100%; height: 100vh" />
  <ChildComponent />
</template>
```

```vue
<!-- ChildComponent.vue -->
<script setup>
import { useViewer } from 'vesium';
import { watchEffect } from 'vue';

// Retrieve the viewer instance from ancestor component
const viewer = useViewer();

// Use viewer in reactive context
watchEffect(() => {
  if (viewer.value) {
    console.log('Viewer is ready:', viewer.value);
    // Access viewer properties safely
    viewer.value.scene.globe.enableLighting = true;
  }
});
</script>
```

### Response

#### Success Response (200)

- **viewer** (Ref<Viewer>) - A Vue ref containing the Cesium Viewer instance.

#### Response Example

```json
{
  "viewer": "Cesium.Viewer instance"
}
```
```

--------------------------------

### Configure ImageryLayer Loading with Options

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useImageryLayer/index.en.md

Loads an ImageryLayer instance with advanced configuration options using the useImageryLayer composable. This includes specifying the imagery layer collection, activation status, loading indicator, and destruction behavior.

```typescript
const dataSource = useImageryLayer(layer, {
  collection,
  isActive,
  evaluating: isLoading,
  destroyOnRemove: false,
});
```

--------------------------------

### Load Basic ImageryLayer Instance with useImageryLayer

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useImageryLayer/index.en.md

Loads a basic ImageryLayer instance using the useImageryLayer composable. This function is suitable for straightforward layer loading scenarios where the layer data is readily available.

```typescript
const images = useImageryLayer(layer);
```

--------------------------------

### Load Single Primitive Instance with usePrimitive (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/usePrimitive/index.en.md

Demonstrates how to use the usePrimitive hook to load a single Cesium Primitive instance. This overload accepts either a pre-defined primitive object or a new instance of a Cesium Primitive class. It's useful for managing individual 3D tilesets or other primitive elements.

```typescript
import { usePrimitive } from 'vesiumjs';
import * as Cesium from 'cesium';

// Load a single instance using a pre-defined primitive
const primitive = usePrimitive(predefinedPrimitive);

// Load a single instance by creating a new Cesium3DTileset
const primitive = usePrimitive(new Cesium.Cesium3DTileset());
```

--------------------------------

### Use Viewer Instance in Descendant Component (Vue)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useViewer/index.en.md

Shows how to create a Viewer instance in a parent Vue component and then access it in a child component using the useViewer hook. This pattern is useful for managing viewer state across a component tree.

```vue
// parent.vue
<script setup>
import { ref } from 'vue';
import { createViewer } from 'vesiumjs';

const elRef = ref<HTMLElement>();
const viewer = createViewer(elRef);
</script>

<template>
  <div ref="elRef" />
  <Child />
</template>
```

```vue
// child.vue
<script setup>
import { useViewer } from 'vesiumjs';

const viewer = useViewer();
</script>
```

--------------------------------

### Load 3D Tilesets, Models, and Geometries with usePrimitive

Source: https://context7.com/vesiumjs/vesium/llms.txt

The `usePrimitive` hook in VesiumJS allows for reactive loading of various 3D primitives like Cesium 3DTilesets, glTF models, and custom geometries. It supports loading individual primitives, collections, or multiple primitives simultaneously, managing their lifecycle within the Cesium scene.

```vue
<script setup>
import { createViewer, usePrimitive } from 'vesium';
import { 
  Cesium3DTileset,
  Model,
  Primitive,
  GeometryInstance,
  RectangleGeometry,
  Rectangle,
  Material,
  MaterialAppearance
} from 'cesium';
import { shallowRef, ref } from 'vue';

const cesiumContainer = shallowRef<HTMLElement>();
createViewer(cesiumContainer);

const isLoading = ref(true);

// Load 3D Tileset
const tileset = usePrimitive(async () => {
  return await Cesium3DTileset.fromUrl('/data/tileset/tileset.json', {
    maximumScreenSpaceError: 2,
  });
}, { evaluating: isLoading });

// Load glTF model
const model = usePrimitive(async () => {
  return await Model.fromGltfAsync({
    url: '/models/aircraft.glb',
    modelMatrix: Cesium.Transforms.eastNorthUpToFixedFrame(
      Cesium.Cartesian3.fromDegrees(-75.62898254394531, 40.02804946899414, 0)
    ),
    scale: 100,
  });
});

// Load geometry primitive
const rectanglePrimitive = usePrimitive(
  new Primitive({
    geometryInstances: new GeometryInstance({
      geometry: new RectangleGeometry({
        rectangle: Rectangle.fromDegrees(-100, 30, -90, 40),
        height: 0,
      }),
    }),
    appearance: new MaterialAppearance({
      material: Material.fromType('Color', { color: Cesium.Color.RED.withAlpha(0.5) }),
    }),
  })
);

// Load to ground primitives collection
const groundPrimitive = usePrimitive(somePrimitive, {
  collection: 'ground', // Use scene.groundPrimitives
});

// Load multiple primitives
const primitives = usePrimitive([primitive1, primitive2]);
</script>
```

--------------------------------

### Load Imagery Layers Reactively with useImageryLayer (Vue.js)

Source: https://context7.com/vesiumjs/vesium/llms.txt

The `useImageryLayer` hook from VesiumJS provides reactive loading of Cesium imagery layers to the globe. It supports various imagery providers and manages layers automatically, including cleanup. Dependencies include Vue's reactivity system and CesiumJS.

```vue
<script setup>
import { createViewer, useImageryLayer } from 'vesium';
import {
  ImageryLayer,
  UrlTemplateImageryProvider,
  WebMapServiceImageryProvider,
  IonImageryProvider
} from 'cesium';
import { shallowRef, ref, computed } from 'vue';

const cesiumContainer = shallowRef<HTMLElement>();
createViewer(cesiumContainer);

const isLoading = ref(true);
const layerOpacity = ref(0.7);

// Load OpenStreetMap tiles
const osmLayer = useImageryLayer(
  computed(() => new ImageryLayer(
    new UrlTemplateImageryProvider({
      url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
      maximumLevel: 19,
    }),
    { alpha: layerOpacity.value }
  ))
);

// Load WMS layer asynchronously
const wmsLayer = useImageryLayer(async () => {
  const provider = new WebMapServiceImageryProvider({
    url: 'https://example.com/wms',
    layers: 'layer_name',
    parameters: { transparent: true, format: 'image/png' },
  });
  return new ImageryLayer(provider);
}, {
  evaluating: isLoading,
  destroyOnRemove: false,
  index: 1, // Layer order index
});

// Load multiple imagery layers
const layers = useImageryLayer([
  new ImageryLayer(new IonImageryProvider({ assetId: 2 })),
  new ImageryLayer(new IonImageryProvider({ assetId: 3 })),
]);

// Conditionally active layer
const isActive = ref(true);
const conditionalLayer = useImageryLayer(osmLayer, { isActive });
</script>
```

--------------------------------

### Scale Bar Demo Component (Vue)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useScaleBar/index.en.md

A Vue.js component demonstrating the usage of the useScaleBar hook. It initializes a scale bar and provides controls to update its properties.

```html
<template>
  <div class="scale-bar-container">
    <div ref="scaleBarWrapper" class="scale-bar-wrapper"></div>
    <div class="controls">
      <label>Segments:</label>
      <input type="number" v-model.number="scaleBarOptions.segments" />
      <label>Unit:</label>
      <input type="text" v-model="scaleBarOptions.unit" />
      <label>Color:</label>
      <input type="color" v-model="scaleBarOptions.color" />
      <label>Width:</label>
      <input type="number" v-model.number="scaleBarOptions.width" />
      <label>Height:</label>
      <input type="number" v-model.number="scaleBarOptions.height" />
      <label>Display Label:</label>
      <input type="checkbox" v-model="scaleBarOptions.displayLabel" />
      <label>Font Size:</label>
      <input type="number" v-model.number="scaleBarOptions.fontSize" />
      <label>Font Color:</label>
      <input type="color" v-model="scaleBarOptions.fontColor" />
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, reactive, onMounted, watch } from 'vue';
import { useScaleBar, ScaleBarOptions } from '../src'; // Adjust import path as needed

const scaleBarWrapper = ref<HTMLDivElement | null>(null);
let scaleBarInstance: ReturnType<typeof useScaleBar> | null = null;

const scaleBarOptions = reactive<ScaleBarOptions>({
  segments: 5,
  unit: 'px',
  color: '#ffffff',
  width: 100,
  height: 10,
  displayLabel: true,
  fontSize: 12,
  fontColor: '#ffffff',
});

onMounted(() => {
  if (scaleBarWrapper.value) {
    scaleBarInstance = useScaleBar({
      ...scaleBarOptions,
      // You can set initial options here or let them be reactive
    });
    scaleBarWrapper.value.appendChild(scaleBarInstance.svg.value as SVGElement);
  }
});

watch(scaleBarOptions, (newOptions) => {
  if (scaleBarInstance) {
    scaleBarInstance.updateOptions(newOptions);
  }
}, { deep: true });
</script>

<style scoped>
.scale-bar-container {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 20px;
  padding: 20px;
  background-color: #333;
  border-radius: 8px;
}

.scale-bar-wrapper {
  width: 200px; /* Adjust as needed */
  height: 50px; /* Adjust as needed */
  border: 1px solid #555;
  display: flex;
  justify-content: center;
  align-items: center;
}

.controls {
  display: grid;
  grid-template-columns: auto 1fr;
  gap: 10px;
  align-items: center;
  color: #eee;
}

.controls label {
  font-weight: bold;
}

.controls input[type="number"],
.controls input[type="text"] {
  padding: 8px;
  border-radius: 4px;
  border: 1px solid #666;
  background-color: #444;
  color: #eee;
}

.controls input[type="color"] {
  height: 30px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.controls input[type="checkbox"] {
  justify-self: start;
}
</style>

```

--------------------------------

### Load Multiple Primitive Instances with usePrimitive (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/usePrimitive/index.en.md

Illustrates loading an array of Cesium Primitive instances using the usePrimitive hook. This overload is suitable when you need to manage multiple primitives reactively, such as several 3D tilesets or different types of primitives simultaneously.

```typescript
import { usePrimitive } from 'vesiumjs';

// Assume primitive1 and primitive2 are defined Cesium Primitive instances
const primitives = usePrimitive([primitive1, primitive2]);
```

--------------------------------

### Access Reactive Cesium Camera State (Vue)

Source: https://context7.com/vesiumjs/vesium/llms.txt

Provides reactive access to the Cesium Camera instance and its state, including position, direction, and view rectangle. It allows watching for camera changes with configurable event types and throttling.

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

const cesiumContainer = shallowRef<HTMLElement>();
const viewer = createViewer(cesiumContainer);

// Get reactive camera state
const {
  camera,
  position,
  positionCartographic,
  heading,
  pitch,
  roll,
  viewRectangle,
  level,
} = useCameraState({
  event: 'changed',
  delay: 8,
});

// Watch for camera position changes
watch(positionCartographic, (newPos) => {
  if (newPos) {
    const lon = Cesium.Math.toDegrees(newPos.longitude);
    const lat = Cesium.Math.toDegrees(newPos.latitude);
    console.log(`Camera at: ${lon.toFixed(4)}, ${lat.toFixed(4)}, Level: ${level.value}`);
  }
});
</script>
```

--------------------------------

### Reactive Scene Picking with useScenePick (Vue)

Source: https://context7.com/vesiumjs/vesium/llms.txt

The `useScenePick` hook provides reactive results for Cesium's Scene.pick function, allowing for efficient picking of objects at screen coordinates. It supports throttling and customizable picking rectangle dimensions. Dependencies include `vesium` and `cesium`.

```vue
<script setup>
import { createViewer, useScenePick, useScreenSpaceEventHandler } from 'vesium';
import { ScreenSpaceEventType, Cartesian2 } from 'cesium';
import { shallowRef, watch } from 'vue';

const cesiumContainer = shallowRef<HTMLElement>();
createViewer(cesiumContainer);

// Track mouse position
const mousePosition = shallowRef<Cartesian2>();

useScreenSpaceEventHandler(
  ScreenSpaceEventType.MOUSE_MOVE,
  (event) => {
    mousePosition.value = event.endPosition;
  }
);

// Get pick result reactively
const pick = useScenePick(mousePosition, {
  throttled: 16,  // Throttle interval in ms
  width: 5,       // Pick rectangle width
  height: 5,      // Pick rectangle height
  isActive: true, // Toggle picking
});

// React to pick changes
watch(pick, (newPick) => {
  if (newPick) {
    if (newPick.id) {
      console.log('Hovered entity:', newPick.id);
    } else if (newPick.primitive) {
      console.log('Hovered primitive:', newPick.primitive);
    }
  }
});
</script>
```

--------------------------------

### Camera State Type Definitions (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useCameraState/index.en.md

Defines the TypeScript types for the Camera instance state, enabling type-safe access and manipulation. This is crucial for understanding the structure of the camera's reactive state.

```typescript
import {
  CameraState,
  CameraStateUpdateOptions
} from "./index.d";

export declare function useCameraState(): {
  state: CameraState;
  update: (options: CameraStateUpdateOptions) => void;
};
```

--------------------------------

### Subscribe to Cesium Events with useCesiumEventListener

Source: https://context7.com/vesiumjs/vesium/llms.txt

The `useCesiumEventListener` hook provides a convenient way to subscribe to Cesium Event instances, ensuring automatic cleanup of listeners. It's recommended to use this with throttling for high-frequency events like scene rendering. It accepts an event source (or an array of sources) and a callback function, with an optional configuration object for conditional activation. Dependencies include `vesium`, `@vesium/shared`, and `@vueuse/core`.

```vue
<script setup>
import { createViewer, useViewer, useCesiumEventListener } from 'vesium';
import { throttle } from '@vesium/shared';
import { refThrottled } from '@vueuse/core';
import { shallowRef, ref } from 'vue';

const cesiumContainer = shallowRef<HTMLElement>();
createViewer(cesiumContainer);

const viewer = useViewer();

// Listen to scene post-render event (with throttling)
const frameTime = ref(0);
const throttledFrameTime = refThrottled(frameTime, 100);

useCesiumEventListener(
  () => viewer.value?.scene.postRender,
  () => {
    frameTime.value = performance.now();
  }
);

// Listen to camera change with throttled callback
const cameraChanged = throttle(() => {
  console.log('Camera position changed');
}, 100);

useCesiumEventListener(
  () => viewer.value?.camera.changed,
  cameraChanged
);

// Listen to multiple events
useCesiumEventListener(
  [
    () => viewer.value?.scene.preUpdate,
    () => viewer.value?.scene.postUpdate,
  ],
  () => {
    console.log('Scene update cycle');
  }
);

// Conditionally active listener
const isActive = ref(true);
useCesiumEventListener(
  () => viewer.value?.clock.onTick,
  (clock) => {
    console.log('Current time:', clock.currentTime);
  },
  { isActive }
);
</script>
```

--------------------------------

### Load Array of ImageryLayers with useImageryLayer

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useImageryLayer/index.en.md

Loads multiple ImageryLayer instances from an array using the useImageryLayer composable. This allows for efficient loading and management of several layers simultaneously.

```typescript
const dataSources = useImageryLayer([layer1, layer2]);
```

--------------------------------

### Load Asynchronous ImageryLayer Instance with useImageryLayer

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useImageryLayer/index.en.md

Loads an ImageryLayer instance asynchronously using the useImageryLayer composable. This is useful when the layer data needs to be fetched before it can be loaded, ensuring the layer is ready when needed.

```typescript
const dataSource = useImageryLayer(async () => await getLayer());
```

--------------------------------

### Normalize to Promise Instance with toPromiseValue (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/toPromiseValue/index.en.md

Demonstrates how to use toPromiseValue to normalize Promises, async functions, and regular Refs into Promise instances. This function is particularly useful when working with asynchronous data sources and integrating with tools like computedAsync.

```typescript
import { computedAsync, ref } from '@vueuse/core';
import { toPromiseValue } from 'vesium';

// Handling Promise instances
const promiseRef = ref(Promise.resolve('Hello World'));
const data = computedAsync(() => toPromiseValue(promiseRef));
// data.value -> 'Hello World'

// Handling async functions
async function asyncFn() {
  return 'Hello World';
}
const data = computedAsync(() => toPromiseValue(asyncFn));
// data.value -> 'Hello World'

// Handling regular Refs
const normalRef = ref('Hello World');
const data = computedAsync(() => toPromiseValue(normalRef));
// data.value -> 'Hello World'
```

--------------------------------

### Use Scene Drill Pick with TypeScript

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useSceneDrillPick/index.en.md

Demonstrates how to use the useSceneDrillPick hook with a CesiumJS Cartesian2 window position. The hook returns computed pick results based on the provided position and optional configuration.

```typescript
const windowPosition = shallowRef(new Cesium.Cartesian2());
const picks = useSceneDrillPick(windowPosition, { /** options */ });
```

--------------------------------

### Configure useDataSource with Options (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useDataSource/index.en.md

Explains how to configure the useDataSource hook with various options for advanced control. Options include specifying the collection, activation status, loading state, and destruction behavior.

```typescript
const isLoading = ref(true);

// Use options
const dataSource = useDataSource(someDataSource, {
  collection: someCollection, // DataSource collection
  isActive: true, // Whether to activate
  evaluating: isLoading, // Loading status reference
  destroyOnRemove: true, // Whether to destroy when the DataSource is removed
});
```

--------------------------------

### Load Basic Cesium DataSource with useDataSource (TypeScript)

Source: https://github.com/vesiumjs/vesium/blob/main/packages/core/useDataSource/index.en.md

Demonstrates the basic usage of the useDataSource hook to load a single Cesium DataSource instance. It takes a DataSource object as input and returns a reactive DataSource.

```typescript
// Load a basic instance
const dataSource = useDataSource(someDataSource);
```

--------------------------------

### Overlay HTML Elements on Cesium Map with useElementOverlay

Source: https://context7.com/vesiumjs/vesium/llms.txt

The `useElementOverlay` hook allows you to overlay HTML elements on the Cesium map at specific geographic positions. It automatically updates the element's position as the camera moves. You provide a reference to the HTML element and its desired geographic position (in various formats like [lon, lat, height], or Cartesian3). The hook returns reactive `x`, `y` coordinates and a `style` object for positioning. Dependencies include `vesium` and `cesium`.

```vue
<script setup>
import { createViewer, useElementOverlay } from 'vesium';
import { Cartesian3 } from 'cesium';
import { shallowRef, ref } from 'vue';

const cesiumContainer = shallowRef<HTMLElement>();
createViewer(cesiumContainer);

// Reference to the overlay element
const popupElement = shallowRef<HTMLElement>();

// Position in various formats
const position = ref([116.4074, 39.9042, 100]); // [lon, lat, height]
// Or: { longitude: 116.4074, latitude: 39.9042, height: 100 }
// Or: new Cartesian3(...)

// Create overlay
const { x, y, style } = useElementOverlay(
  popupElement,
  position,
  {
    horizontal: 'center',    // 'left' | 'center' | 'right'
    vertical: 'bottom',      // 'top' | 'center' | 'bottom'
    offset: { x: 0, y: -10 }, // Pixel offset
    referenceWindow: false,  // true = browser viewport, false = canvas
    applyStyle: true,        // Automatically apply position styles
    clampToGround: false,    // Clamp position to terrain
  }
);
</script>

<template>
  <div ref="cesiumContainer" style="width: 100%; height: 100vh">
    <!-- Popup overlay -->
    <div
      ref="popupElement"
      style="position: absolute; pointer-events: auto;"
    >
      <div class="popup-content">
        <h3>Beijing</h3>
        <p>Position: {{ position[0] }}, {{ position[1] }}</p>
        <p>Screen X: {{ x }}, Y: {{ y }}</p>
      </div>
    </div>
  </div>
</template>
```

--------------------------------

### Apply Post-Processing Effects with usePostProcessStage

Source: https://context7.com/vesiumjs/vesium/llms.txt

The `usePostProcessStage` hook enables the reactive addition of post-processing effects, such as shaders, to the Cesium scene. It handles the lifecycle management and automatic cleanup of these stages, allowing for effects like bloom or custom shader manipulations.

```vue
<script setup>
import { createViewer, usePostProcessStage } from 'vesium';
import { PostProcessStage, PostProcessStageLibrary } from 'cesium';
import { shallowRef, ref } from 'vue';

const cesiumContainer = shallowRef<HTMLElement>();
createViewer(cesiumContainer);

// Add bloom effect
const bloomStage = usePostProcessStage(
  PostProcessStageLibrary.createBloomStage()
);

// Add custom shader effect
const customStage = usePostProcessStage(
  new PostProcessStage({
    fragmentShader: ""
      "uniform sampler2D colorTexture;
      in vec2 v_textureCoordinates;
      out vec4 fragColor;

      void main() {
        vec4 color = texture(colorTexture, v_textureCoordinates);
        // Apply sepia tone
        float gray = dot(color.rgb, vec3(0.299, 0.587, 0.114));
        fragColor = vec4(gray * vec3(1.2, 1.0, 0.8), color.a);
      }
    ",
  })
);

// Conditionally enable effect
const isActive = ref(true);
const conditionalEffect = usePostProcessStage(bloomStage, { isActive });

// Multiple post-process stages
const stages = usePostProcessStage([
  PostProcessStageLibrary.createSilhouetteStage(),
  PostProcessStageLibrary.createEdgeDetectionStage(),
]);
</script>
```

--------------------------------

### Retrieve Cesium Viewer Instance (Vue)

Source: https://context7.com/vesiumjs/vesium/llms.txt

Retrieves a Cesium Viewer instance that was previously injected by `createViewer` in an ancestor component. This hook must be called after `createViewer` if used within the same component.

```vue
<!-- Parent.vue -->
<script setup>
import { createViewer } from 'vesium';
import { shallowRef } from 'vue';

const elRef = shallowRef<HTMLElement>();
const viewer = createViewer(elRef);
</script>

<template>
  <div ref="elRef" style="width: 100%; height: 100vh" />
  <ChildComponent />
</template>
```

```vue
<!-- ChildComponent.vue -->
<script setup>
import { useViewer } from 'vesium';
import { watchEffect } from 'vue';

// Retrieve the viewer instance from ancestor component
const viewer = useViewer();

// Use viewer in reactive context
watchEffect(() => {
  if (viewer.value) {
    console.log('Viewer is ready:', viewer.value);
    // Access viewer properties safely
    viewer.value.scene.globe.enableLighting = true;
  }
});
</script>
```

--------------------------------

### Load Entities Reactively with useEntity (Vue.js)

Source: https://context7.com/vesiumjs/vesium/llms.txt

The `useEntity` hook from VesiumJS allows for reactive loading of Cesium Entity objects within a Vue.js application. It automatically handles updates and cleanup when the component unmounts or data changes. Dependencies include Vue's reactivity system and CesiumJS.

```vue
<script setup>
import { createViewer, useEntity } from 'vesium';
import { Entity, Cartesian3, Color, ConstantProperty, ConstantPositionProperty } from 'cesium';
import { shallowRef, ref, computed } from 'vue';

const cesiumContainer = shallowRef<HTMLElement>();
createViewer(cesiumContainer);

// Create a reactive entity
const position = ref([116.4074, 39.9042, 1000]); // Beijing coordinates

const entity = computed(() => new Entity({
  position: Cartesian3.fromDegrees(...position.value),
  point: {
    pixelSize: 20,
    color: Color.RED,
    outlineColor: Color.WHITE,
    outlineWidth: 2,
  },
  label: {
    text: 'Beijing',
    font: '14pt sans-serif',
    fillColor: Color.WHITE,
  },
}));

// Load single entity (automatically updates when position changes)
const loadedEntity = useEntity(entity);

// Load multiple entities
const entities = useEntity([
  new Entity({ id: 'entity1', point: { pixelSize: 10, color: Color.BLUE } }),
  new Entity({ id: 'entity2', point: { pixelSize: 10, color: Color.GREEN } }),
]);

// With options
const isLoading = ref(false);
const isActive = ref(true);

const conditionalEntity = useEntity(entity, {
  isActive,
  evaluating: isLoading,
});
</script>
```

--------------------------------

### Load Data Sources Reactively with useDataSource (Vue.js)

Source: https://context7.com/vesiumjs/vesium/llms.txt

The `useDataSource` hook from VesiumJS enables reactive loading of Cesium DataSource objects, supporting formats like GeoJSON, KML, and CZML. It handles both synchronous and asynchronous loading, with automatic cleanup. Dependencies include Vue's reactivity system and CesiumJS.

```vue
<script setup>
import { createViewer, useDataSource } from 'vesium';
import { GeoJsonDataSource, CzmlDataSource } from 'cesium';
import { shallowRef, ref } from 'vue';

const cesiumContainer = shallowRef<HTMLElement>();
createViewer(cesiumContainer);

const isLoading = ref(true);

// Load GeoJSON synchronously
const geoJsonDataSource = useDataSource(
  new GeoJsonDataSource('countries'),
  { evaluating: isLoading }
);

// Load GeoJSON asynchronously
const asyncDataSource = useDataSource(async () => {
  const dataSource = await GeoJsonDataSource.load('/data/countries.geojson', {
    stroke: Cesium.Color.HOTPINK,
    fill: Cesium.Color.PINK.withAlpha(0.5),
    strokeWidth: 3,
  });
  return dataSource;
}, {
  evaluating: isLoading,
  destroyOnRemove: true, // Destroy when removed from collection
});

// Load CZML data
const czmlDataSource = useDataSource(async () => {
  return await CzmlDataSource.load('/data/satellite.czml');
});

// Load multiple data sources
const dataSources = useDataSource([
  new GeoJsonDataSource('layer1'),
  new GeoJsonDataSource('layer2'),
]);
</script>
```