useScaleBar

Reactive generation of Cesium scale bar data: pixel distance, scale width, and formatted distance text. A hand-drawn scale bar requires computing how many meters one pixel represents and recomputing on camera moves or canvas resizes; this hook picks two adjacent pixels at the bottom-center of the canvas, computes the geodesic distance between their ground points, and selects a tick from a fixed table — recomputing automatically (throttled) on camera movement or canvas resize. Use it for a conventional scale bar overlaid on a corner of the Cesium canvas.

Usage

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

const viewer = useViewer();
watchEffect(() => {
  viewer.value?.camera.flyTo({
    destination: Cesium.Cartesian3.fromDegrees(100, 0, 10000),
    duration: 3,

  });
});
const { pixelDistance, width, distance, distanceText } = useScaleBar();
</script>

<template>
  <div class="p-10px flex flex-col w-200px">
    <div>pixelDistance: {{ pixelDistance?.toFixed(2) }}m</div>
    <div>distance: {{ distance }}m</div>
    <div class="border-b-2px border-b-#666" :style="{ width: `${width}px` }">
      {{ distanceText }}
    </div>
  </div>
</template>

import { useScaleBar } from 'vesium';

// maxPixel controls the maximum pixel width of the scale (default 80px)
const { pixelDistance, width, distance, distanceText } = useScaleBar({ maxPixel: 80 });

Options

• maxPixel - The maximum width of the scale (px), default 80.
• delay - Throttled delay (ms) for recomputation on camera events, default 8.

Return Value

• pixelDistance - The actual distance of a single pixel in the current canvas (m).
• width - The width of the scale (px).
• distance - The actual distance covered by the scale width (m).
• distanceText - Formatted distance text, e.g. 100m, 100km.

Notes

• Depends on useViewer(), so createViewer must be called first.
• The distance is computed by picking the ground with globe.pick: when the camera has no ground intersection (e.g. facing the sky), the last computed value is kept; pixelDistance is only undefined before the first successful pick.
• distanceText is shown in km when the distance exceeds 1000m.

Type Definitions

import type { MaybeRefOrGetter, Ref } from 'vue';
export interface UseScaleBarOptions {
    /**
     * The maximum width of the scale (px)
     * @default 80
     */
    maxPixel?: MaybeRefOrGetter<number>;
    /**
     * Throttled delay duration (ms)
     * @default 8
     */
    delay?: number;
}
export interface UseScaleBarReturn {
    /**
     * The actual distance of a single pixel in the current canvas
     */
    pixelDistance: Readonly<Ref<number | undefined>>;
    /**
     * The width of the scale.(px)
     */
    width: Readonly<Ref<number>>;
    /**
     * The actual distance corresponding to the width of the scale (m)
     */
    distance: Readonly<Ref<number | undefined>>;
    /**
     * Formatted content of distance.
     * eg. 100m,100km
     */
    distanceText: Readonly<Ref<string | undefined>>;
}
/**
 * Reactive generation of scale bars
 */
export declare function useScaleBar(options?: UseScaleBarOptions): UseScaleBarReturn;