useImageryLayer

Reactively adds ImageryLayer instances to an ImageryLayerCollection (defaults to viewer.imageryLayers). Layers stack on top of each other and the insertion position (index) decides which covers which: useImageryLayer controls the insertion position via index, the removal behavior via destroyOnRemove, and automatically cleans up the previous batch when the data changes or the component unmounts. Note that display properties (alpha, brightness, splitDirection, etc.) are set on the ImageryLayer instance itself — the hook only handles collection addition/removal and ordering.

Usage

<script setup lang="ts">
import * as Cesium from 'cesium';
import { useImageryLayer, useViewer } from 'vesium';
import { ref, watchPostEffect } from 'vue';

const isActive = ref(true);

const imageryLayer = useImageryLayer(
  async () => new Cesium.ImageryLayer(new Cesium.GridImageryProvider({})),
  {
    isActive,
    destroyOnRemove: false,
  },
);

const viewer = useViewer();
watchPostEffect(() => {
  if (imageryLayer.value) {
    viewer.value?.flyTo(
      imageryLayer.value,
      {
        duration: 1,
      },
    );
  }
});
</script>

<template>
  <div class="p-10px">
    <button @click="isActive = !isActive">
      visible:{{ isActive }}
    </button>
  </div>
</template>

import * as Cesium from 'cesium';
import { useImageryLayer } from 'vesium';

const layer = useImageryLayer(new Cesium.ImageryLayer(
  new Cesium.ArcGisMapServerImageryProvider({ url: '/arcgis/rest/services/...' }),
));

const controlled = useImageryLayer(layer, {
  isActive: true, // When false, the layer is removed
  index: 0, // Insertion position: second argument of imageryLayers.add(layer, index)
  destroyOnRemove: false, // Keep the instance when toggling; the default destroys it
});

Options

• collection - The target ImageryLayerCollection; defaults to useViewer().value.imageryLayers.
• isActive - Whether active, defaults to true.
• evaluating - A ref receiving the async evaluation state.
• destroyOnRemove - Second argument of imageryLayers.remove; no default set (undefined passed through), Cesium treats it as true.
• index - Second argument of imageryLayers.add(layer, index), i.e. the stacking order; in array mode all layers share the same index.

Return Value

• A single value (or getter/ref/async getter) returns ComputedRef<T | undefined>.
• An array returns ComputedRef<T[] | undefined>.

Notes

• When toggling with isActive and destroyOnRemove is left at the default (undefined → Cesium treats it as true), removal destroys the layer instance and re-enabling cannot restore it; pass destroyOnRemove: false to toggle.
• The returned ref is driven by computedAsync with an initial value of [] — an empty array is truthy, so don't rely on truthiness to check existence.

Type Definitions

import type { ImageryLayer, ImageryLayerCollection } from 'cesium';
import type { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
import type { MaybeRefOrAsyncGetter } from '../toPromiseValue';
export interface UseImageryLayerOptions {
    /**
     * The collection of ImageryLayer to be added
     * @default useViewer().value.imageryLayers
     */
    collection?: ImageryLayerCollection;
    /**
     * default value of `isActive`
     * @default true
     */
    isActive?: MaybeRefOrGetter<boolean>;
    /**
     * Ref passed to receive the updated of async evaluation
     */
    evaluating?: Ref<boolean>;
    /**
     * The second parameter passed to the `remove` function
     *
     * `imageryLayers.remove(layer,destroyOnRemove)`
     */
    destroyOnRemove?: MaybeRefOrGetter<boolean | undefined>;
    /**
     * The second parameter passed to the `add` function
     *
     * `imageryLayers.add(layer,index)`
     */
    index?: MaybeRefOrGetter<number | undefined>;
}
/**
 * Add `ImageryLayer` to the `ImageryLayerCollection`, automatically update when the data changes, and destroy the side effects caused by the previous `ImageryLayer`.
 *
 * Overload 1: Parameter supports passing in a single value.
 */
export declare function useImageryLayer<T extends ImageryLayer = ImageryLayer>(layer?: MaybeRefOrAsyncGetter<T | undefined>, options?: UseImageryLayerOptions): ComputedRef<T | undefined>;
/**
 * Add `ImageryLayer` to the `ImageryLayerCollection`, automatically update when the data changes, and destroy the side effects caused by the previous `ImageryLayer`.
 *
 * Overload 2: Parameter supports passing in an array.
 */
export declare function useImageryLayer<T extends ImageryLayer = ImageryLayer>(layers?: MaybeRefOrAsyncGetter<Array<T | undefined> | undefined>, options?: UseImageryLayerOptions): ComputedRef<T[] | undefined>;