cesium-mars-op-cog 0.1.0

package/dist/cog.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @cog/cesium 公共 API 入口
+ *
+ * 提供简洁的工厂函数，返回 Cesium/Mars3D 可用的图层对象。
+ *
+ * 用法:
+ *   // Cesium
+ *   import { createCogProvider } from '@cog/cesium'
+ *   const provider = await createCogProvider('http://.../image.tif')
+ *   const layer = viewer.imageryLayers.addImageryProvider(provider)
+ *   layer.alpha = 0.5
+ *
+ *   // Mars3D (Mars3D = Cesium，用法完全一致)
+ *   const provider = await createCogProvider('http://.../image.tif')
+ *   const layer = map.imageryLayers.addImageryProvider(provider)
+ *
+ *   // 或一步到位
+ *   import { addCogLayerToMap } from '@cog/cesium'
+ *   const layer = await addCogLayerToMap(map, 'http://.../image.tif')
+ *   layer.alpha = 0.5
+ */
+import { CogImageryProvider } from './core/provider';
+import type { CogProviderOptions } from './core/provider';
+/** addCogLayerToMap 额外选项 */
+export interface AddLayerOptions extends CogProviderOptions {
+    /** 透明度（默认 1.0） */
+    alpha?: number;
+    /** 是否飞向图层（默认 true） */
+    flyTo?: boolean;
+}
+/**
+ * 创建并初始化一个 COG ImageryProvider
+ *
+ * @param url  COG 文件地址
+ * @param options 配置选项
+ * @returns 已初始化的 CogImageryProvider，可直接传入 viewer.imageryLayers.addImageryProvider()
+ */
+export declare function createCogProvider(url: string, options?: CogProviderOptions): Promise<CogImageryProvider>;
+/**
+ * 将 COG 影像直接添加到 Cesium/Mars3D 地图
+ *
+ * @param map   Cesium.Viewer 或 Mars3D 地图实例（需有 imageryLayers.addImageryProvider）
+ * @param url   COG 文件地址
+ * @param options 配置选项
+ * @returns 影像图层对象，可通过原生 API 操控（alpha、show、remove 等）
+ */
+export declare function addCogLayerToMap(map: {
+    imageryLayers: {
+        addImageryProvider: (provider: any) => any;
+        remove: (layer: any, destroy: boolean) => void;
+    };
+    camera?: {
+        flyTo: (opts: any) => void;
+    };
+    scene?: {
+        requestRender: () => void;
+    };
+}, url: string, options?: AddLayerOptions): Promise<any>;

package/dist/core/provider.d.ts

@@ -0,0 +1,56 @@
+/**
+ * CogImageryProvider — Cesium/Mars3D 可用的 COG 影像提供者
+ *
+ * 实现 Cesium.ImageryProvider 接口，可直接传入 viewer.imageryLayers.addImageryProvider()。
+ * Mars3D 基于 Cesium，同样适用。
+ *
+ * 用法:
+ *   const provider = new CogImageryProvider(url)
+ *   await provider.init()
+ *   const layer = viewer.imageryLayers.addImageryProvider(provider)
+ *   layer.alpha = 0.5  // 原生 API 操控
+ */
+import { Rectangle, GeographicTilingScheme } from 'cesium';
+export interface CogProviderOptions {
+    /** Worker 池大小，默认 max(2, min(6, CPU 核心数/2)) */
+    poolSize?: number;
+    /** 每个 Worker 最大并发任务数（默认 8） */
+    maxLoadPerWorker?: number;
+    /** 初始化超时毫秒（默认 30000） */
+    timeout?: number;
+    /** 瓦片缓存数量（默认 512） */
+    tileCacheSize?: number;
+    /** 影像透明度 0-1（默认 1.0，在 Worker 中与像素混合） */
+    alpha?: number;
+}
+export declare class CogImageryProvider {
+    readonly tileWidth = 256;
+    readonly tileHeight = 256;
+    readonly tilingScheme: GeographicTilingScheme;
+    readonly hasAlphaChannel = true;
+    readonly ready = true;
+    maximumLevel: number;
+    minimumLevel: number;
+    rectangle: ReturnType<typeof Rectangle.fromDegrees>;
+    _errorEvent: any;
+    get errorEvent(): any;
+    /** 影像的度坐标 bbox [west, south, east, north]，用于 flyTo 等场景 */
+    get bboxDegrees(): readonly [number, number, number, number];
+    private _url;
+    private _options;
+    private _workerPool;
+    private _tileCache;
+    private _inflightRequests;
+    private _emptyTile;
+    private _destroyed;
+    private _bbox;
+    private _initialized;
+    constructor(url: string, options?: CogProviderOptions);
+    init(): Promise<void>;
+    /** 将 COG 原始 bbox 转换为度坐标 */
+    private _normalizeBbox;
+    isDestroyed(): boolean;
+    requestImage(x: number, y: number, level: number): Promise<HTMLCanvasElement | undefined>;
+    private _fetchTile;
+    destroy(): void;
+}

package/dist/core/types.d.ts

@@ -0,0 +1,50 @@
+/** COG 图层初始化结果 */
+export interface CogInitResult {
+    /** 地理边界框 [west, south, east, north]（度坐标） */
+    bbox: [number, number, number, number];
+    /** CRS 类型：'4326' | '3857' | EPSG 代码字符串 */
+    crsType: string;
+    /** 最大瓦片级别 */
+    maxLevel: number;
+    /** 最小瓦片级别 */
+    minLevel: number;
+}
+/** 瓦片请求结果 */
+export interface TileResult {
+    /** 瓦片是否为空（无交集） */
+    empty: boolean;
+    /** 渲染好的 ImageBitmap（empty=true 时无值） */
+    bitmap?: ImageBitmap;
+}
+/** 瓦片矩形（度坐标） */
+export interface TileRect {
+    west: number;
+    south: number;
+    east: number;
+    north: number;
+}
+/** CogTileLayer 配置选项 */
+export interface CogLayerOptions {
+    /** 透明度 0-1（默认 1） */
+    alpha?: number;
+    /** Worker 池大小（默认 CPU 核心数/2） */
+    poolSize?: number;
+    /** 每个 Worker 最大并发任务数（默认 2） */
+    maxLoadPerWorker?: number;
+    /** 初始化超时毫秒（默认 30000） */
+    timeout?: number;
+}
+/** 框架适配器接口 - 所有适配器实现此接口 */
+export interface CogTileAdapter {
+    /** 获取图层边界框 [w, s, e, n] */
+    getBounds(): [number, number, number, number];
+    /** 获取瓦片级别范围 */
+    getLevelRange(): {
+        min: number;
+        max: number;
+    };
+    /** 请求瓦片数据 */
+    fetchTile(x: number, y: number, level: number): Promise<ImageBitmap | HTMLCanvasElement | null>;
+    /** 销毁释放资源 */
+    destroy(): void;
+}

package/dist/hooks/useCogManager.d.ts

@@ -0,0 +1,34 @@
+interface CogItem {
+    name: string;
+    url: string;
+}
+interface CogManagerOptions {
+    baseUrl?: string;
+    cogApiUrl?: string;
+    cogStaticBaseUrl?: string;
+    viewerOptions?: Record<string, any>;
+}
+/**
+ * COG 图层管理器
+ */
+export declare function useCogManager(options?: CogManagerOptions): {
+    viewer: import("vue").ShallowRef<any, any>;
+    cogList: import("vue").Ref<{
+        name: string;
+        url: string;
+    }[], CogItem[] | {
+        name: string;
+        url: string;
+    }[]>;
+    selectedCog: import("vue").Ref<string, string>;
+    isLoading: import("vue").Ref<boolean, boolean>;
+    error: import("vue").Ref<string | null, string | null>;
+    initViewer: (containerId?: string) => Promise<void>;
+    fetchCogList: () => Promise<void>;
+    loadCOG: () => Promise<void>;
+    removeCOG: () => void;
+    flyTo: () => void;
+    switchCog: (url: string) => Promise<void>;
+    destroy: () => void;
+};
+export {};

package/dist/hooks/useCogTif.d.ts

@@ -0,0 +1,24 @@
+import { CogImageryProvider } from '../core/provider';
+import type { CogProviderOptions } from '../core/provider';
+interface CogLayerInfo {
+    imageryLayer: any;
+    layerId: string;
+    provider: CogImageryProvider;
+    bbox: [number, number, number, number];
+}
+/**
+ * [Vue Composable] COG 影像图层管理
+ *
+ * 基于 CogImageryProvider 的 Vue 封装，管理图层生命周期。
+ * 非 Vue 项目请直接使用 createCogProvider / addCogLayerToMap。
+ */
+export declare function useCogTif(getViewer: () => any): {
+    addCogLayer(id: string, url: string, options?: CogProviderOptions & {
+        alpha?: number;
+        flyTo?: boolean;
+    }): Promise<CogLayerInfo>;
+    removeCogLayer(id: string): void;
+    flyToCogLayer(id: string): void;
+    destroyCogTools(): void;
+};
+export {};

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @cog/cesium — COG (Cloud Optimized GeoTIFF) 影像加载库
+ *
+ * 在 CesiumJS / Mars3D / OpenLayers 中加载云端 GeoTIFF 影像。
+ * 支持 EPSG:4326 / 3857 / CGCS2000 等投影，ZSTD 压缩，多线程 Worker 解码。
+ *
+ * 用法:
+ *   // === Cesium / Mars3D ===
+ *   import { addCogLayerToMap } from '@cog/cesium'
+ *   const layer = await addCogLayerToMap(viewer, 'http://.../image.tif')
+ *   layer.alpha = 0.5  // 原生 API
+ *
+ *   // === OpenLayers ===
+ *   import { addCogLayerToOpenLayers } from '@cog/cesium'
+ *   const layer = await addCogLayerToOpenLayers(olMap, 'http://.../image.tif')
+ *   layer.setOpacity(0.5)  // 原生 API
+ */
+export { CogImageryProvider } from './core/provider';
+export type { CogProviderOptions } from './core/provider';
+export { createCogProvider, addCogLayerToMap } from './cog';
+export type { AddLayerOptions } from './cog';
+export { addCogLayerToOpenLayers } from './adapters/openlayers';
+export type { OpenLayersLayerOptions } from './adapters/openlayers';
+export type { CogInitResult, CogLayerOptions, TileRect, TileResult } from './core/types';
+export { LRUCache } from './utils/cache';
+export { expandRectangle } from './utils/geo';
+export type { BBox } from './utils/geo';
+export { useCogTif } from './hooks/useCogTif';
+export { useCogManager } from './hooks/useCogManager';