@baidumap/mapv-three 1.0.0

package/dist/types/threemap/dataSource/DataSource.d.ts

@@ -0,0 +1,447 @@
+/**
+ * 抽象数据源类，用来管理传入原始数据到面向渲染数据的流转过程
+ * 数据源负责：
+ * - 加载和解析原始数据
+ * - 管理数据属性和着色器attribute映射
+ * - 提供数据操作接口（添加、删除、修改）
+ * - 生成可供渲染的数据结构
+ *
+ * 主要的子类包括：
+ * - {@link GeoJSONDataSource} GeoJSON格式数据源
+ * - {@link CSVDataSource} CSV格式数据源
+ * - {@link JSONDataSource} JSON格式数据源
+ *
+ * @category DataSource
+ * @example
+ * ```javascript
+ * // 创建一个基础数据源
+ * const dataSource = new DataSource();
+ *
+ * // 创建多个数据项
+ * const point1 = new DataItem([116.39, 39.9], { id: 'beijing', name: '北京', value: 100 });
+ * const point2 = new DataItem([121.47, 31.23], { id: 'shanghai', name: '上海', value: 90 });
+ *
+ * // 添加数据项到数据源
+ * dataSource.add(point1);
+ * dataSource.add(point2);
+ *
+ * // 定义数据属性到着色器属性的映射
+ * dataSource.defineAttributes({
+ *   color: 'value',
+ *   size: 'value',
+ * });
+ *
+ * // 将数据源与可视化对象关联
+ * const pointLayer = new SimplePoint({
+ *   size: 10,
+ *   color: 'red',
+ *   vertexColors: true,
+ *   vertexSizes: true,
+ * });
+ * pointLayer.dataSource = dataSource;
+ * engine.add(pointLayer);
+ * ```
+ */
+export class DataSource {
+    /**
+     * 创建数据源实例
+     * @param {object} options 配置选项
+     * @param {string} [options.id] 数据源ID，默认自动通过时间戳生成
+     * @param {object} [options.attributes] 属性映射对象，用于定义数据属性到着色器attribute的映射，映射的规则参考{@link DataSource.defineAttribute}
+     */
+    constructor(options?: {
+        id?: string | undefined;
+        attributes?: object | undefined;
+    });
+    /** @private 生成ID的递增索引 */
+    private _generatedIdIndex;
+    /** @private 挂接object对象 */
+    private _objects;
+    /** @private 解析后数据，buffer格式 */
+    private _data;
+    /** @private 解析后数据，object in array格式 */
+    private _userData;
+    /** @private 延迟更新userData标志 */
+    private _userDataNeedsUpdate;
+    /** @private 通过add方法设置的数据 */
+    private _dataItems;
+    /** @private attribute与属性名的映射关系 */
+    private _attributeMap;
+    /** @private 是否需要重新计算data */
+    private _needsUpdate;
+    /** @private ID到索引的映射 */
+    private _idIndexMap;
+    /** @private 索引到ID的映射 */
+    private _indexIdMap;
+    /** @private 队列中的数据操作 */
+    private _queuedData;
+    /** @private 是否自动生成曲线数据，只有在线数据的时候会生效 */
+    private _isCurve;
+    _options: {
+        id?: string | undefined;
+        attributes?: object | undefined;
+    };
+    /**
+     * @private
+     * 每个DataSource实例有个独立的id，默认为时间戳
+     */
+    private _id;
+    /**
+     * 主要入口方法，该方法为异步，根据路径或者原始数据请求并解析
+     * @param {string} url 请求路径
+     * @returns {Promise<DataSource>} 当前数据源实例
+     * @example
+     * ```javascript
+     * // 加载远程数据
+     * await dataSource.load('path/to/data.geojson');
+     * ```
+     */
+    load(url: string): Promise<DataSource>;
+    set needsUpdate(value: boolean);
+    /**
+     * 是否需要更新
+     * @internal
+     * @type {boolean}
+     */
+    get needsUpdate(): boolean;
+    /**
+     * 将请求数据转换为数组对象
+     * @internal
+     * @param {Response} rs 请求响应对象
+     * @returns {Promise<object>} 转换后的数据对象
+     */
+    _convertStreamingDataToObjectData(rs: Response): Promise<object>;
+    /**
+     * 解析对象数据到DataItem数组
+     * @internal
+     * @param {object} objectData 对象数据
+     * @returns {DataItem[]} DataItem数组
+     */
+    _parseObjectDataToDataItems(objectData: object): DataItem[];
+    /**
+     * 根据数据中属性名设置着色器attribute字段
+     * @param {string} attribute 着色器attribute对应变量名
+     * @param {string|function} property 数据中property名或回调函数
+     * @returns {DataSource} 当前数据源实例
+     * @example
+     * ```javascript
+     * // 用法1：将数据中的'height'属性映射到着色器中的'size'变量
+     * dataSource.defineAttribute('size', 'height');
+     *
+     * // 用法2：可以链式调用
+     * dataSource.defineAttribute('color', 'pointColor')
+     *          .defineAttribute('size', 'height');
+     *
+     * // 用法3：数据中的属性和着色器变量名相同时，可省略property参数
+     * dataSource.defineAttribute('size');
+     *
+     * // 用法4：property参数可传入回调函数，根据数据项的属性值动态计算着色器attribute的值
+     * dataSource.defineAttribute('color', attribute => {
+     *     return [attribute.red, attribute.green, attribute.blue, attribute.alpha];
+     * });
+     * ```
+     */
+    defineAttribute(attribute: string, property: string | Function): DataSource;
+    /**
+     * @internal
+     * @deprecated 已废弃，请使用defineAttribute
+     * @param {string} attribute 着色器attribute对应变量名
+     * @param {string} property 数据中property名
+     * @returns {DataSource} 当前数据源实例
+     */
+    setAttribute(attribute: string, property: string): DataSource;
+    /**
+     * 根据数据中属性名批量设置着色器attribute字段
+     * @param {Object} obj 着色器attribute变量名与数据中property名对应关系
+     * @returns {DataSource} 当前数据源实例
+     * @example
+     * ```javascript
+     * // 一次设置多个属性映射
+     * dataSource.defineAttributes({
+     *   color: 'pointColor',
+     *   size: 'height',
+     * });
+     * ```
+     */
+    defineAttributes(obj: Object): DataSource;
+    /**
+     * @internal
+     * @deprecated 已废弃，请使用defineAttributes
+     * @param {Object} obj 着色器attribute变量名与数据中property名对应关系
+     * @returns {DataSource} 当前数据源实例
+     */
+    setAttributes(obj: Object): DataSource;
+    /**
+     * 从着色器中移除属性名为name的attribute字段
+     * @param {string} name 属性名
+     * @returns {DataSource} 当前数据源实例
+     * @example
+     * ```javascript
+     * // 移除对'color'属性的映射
+     * dataSource.undefineAttribute('color');
+     * ```
+     */
+    undefineAttribute(name: string): DataSource;
+    /**
+     * @internal
+     * @deprecated 已废弃，请使用undefineAttribute
+     * @param {string} name 属性名
+     * @returns {DataSource} 当前数据源实例
+     */
+    removeAttribute(name: string): DataSource;
+    /**
+     * 从着色器移除所有添加的attribute字段，这些字段只能是通过defineAttribute或defineAttributes添加的
+     * @returns {DataSource} 当前数据源实例
+     * @example
+     * ```javascript
+     * // 清除所有属性映射
+     * dataSource.undefineAllAttributes();
+     * ```
+     */
+    undefineAllAttributes(): DataSource;
+    /**
+     * @internal
+     * @deprecated 已废弃，请使用undefineAllAttributes
+     * @returns {DataSource} 当前数据源实例
+     */
+    removeAttributes(): DataSource;
+    /**
+     * 向数据源中增加数据元素
+     * @param {DataItem|DataItem[]} dataItem 数据元素实例或数组
+     * @returns {DataSource} 当前数据源实例
+     * @example
+     * ```javascript
+     * // 添加单个点
+     * const point = new DataItem([116.39, 39.9], { name: '北京' });
+     * dataSource.add(point);
+     *
+     * // 添加多个要素
+     * const points = [
+     *   new DataItem([116.39, 39.9], { name: '北京' }),
+     *   new DataItem([121.47, 31.23], { name: '上海' })
+     * ];
+     * dataSource.add(points);
+     * ```
+     */
+    add(dataItem: DataItem | DataItem[]): DataSource;
+    /**
+     * 从数据源中移除数据元素
+     * @param {DataItem|DataItem[]} dataItem 数据元素实例或数组
+     * @returns {DataSource} 当前数据源实例
+     * @example
+     * ```javascript
+     * // 移除单个点
+     * dataSource.remove(point);
+     *
+     * // 通过ID移除点
+     * dataSource.remove('point1');
+     *
+     * // 移除多个点
+     * dataSource.remove([point1, point2]);
+     * ```
+     */
+    remove(dataItem: DataItem | DataItem[]): DataSource;
+    /**
+     * 设置指定ID数据项的单个属性值
+     * @param {string|string[]} ids 数据项ID或ID数组
+     * @param {string} key 属性名
+     * @param {*} value 属性值
+     * @returns {DataSource} 当前数据源实例
+     * @example
+     * ```javascript
+     * // 设置单个点的颜色
+     * dataSource.setAttributeValue('point1', 'color', [255, 0, 0]);
+     *
+     * // 设置多个点的颜色
+     * dataSource.setAttributeValue(['point1', 'point2'], 'color', [255, 0, 0]);
+     * ```
+     */
+    setAttributeValue(ids: string | string[], key: string, value: any): DataSource;
+    /**
+     * 设置指定ID数据项的多个属性值
+     * @param {string|string[]} ids 数据项ID或ID数组
+     * @param {object} values 属性名-值对象
+     * @returns {DataSource} 当前数据源实例
+     * @example
+     * ```javascript
+     * // 同时设置点的多个属性
+     * dataSource.setAttributeValues('point1', {
+     *   color: [255, 0, 0],
+     *   size: 10,
+     * });
+     *
+     * // 对多个点设置相同的属性
+     * dataSource.setAttributeValues(['point1', 'point2'], {
+     *   color: [255, 0, 0],
+     *   size: 10
+     * });
+     * ```
+     */
+    setAttributeValues(ids: string | string[], values: object): DataSource;
+    /**
+     * 设置指定ID数据项的坐标
+     * @param {string|string[]} ids 数据项ID或ID数组
+     * @param {number[]|number[][]} coordinates 坐标或坐标数组
+     * @param {string} [projection] 投影类型
+     * @returns {DataSource} 当前数据源实例
+     * @example
+     * ```javascript
+     * // 修改点的位置
+     * dataSource.setCoordinates('point1', [116.39, 39.9]);
+     *
+     * // 修改线的坐标
+     * dataSource.setCoordinates('line1', [
+     *   [116.39, 39.9],
+     *   [121.47, 31.23]
+     * ]);
+     * ```
+     */
+    setCoordinates(ids: string | string[], coordinates: number[] | number[][], projection?: string): DataSource;
+    /**
+     * 获取已解析后的第index个数据
+     * @param {number} index 索引下标
+     * @returns {object|undefined} 对应索引的数据项，若索引无效则返回undefined
+     * @example
+     * ```javascript
+     * // 获取第一个数据项
+     * const item = dataSource.get(0);
+     * console.log(item.position, item.color);
+     * ```
+     */
+    get(index: number): object | undefined;
+    /**
+     * 获取原始数据中的数据索引
+     * @param {number} index 绘制元素的索引
+     * @returns {number} 原始数据的索引
+     */
+    getDataItemIndex(index: number): number;
+    /**
+     * 获取原始数据
+     * @param {number} index 绘制元素的索引
+     * @returns {DataItem|undefined} 数据项实例，若索引无效则返回undefined
+     * @example
+     * ```javascript
+     * // 获取索引为0的数据项原始数据
+     * const dataItem = dataSource.getDataItem(0);
+     * console.log(dataItem.coordinates, dataItem.attributes);
+     * ```
+     */
+    getDataItem(index: number): DataItem | undefined;
+    /**
+     * 导出数据成GeoJSON格式
+     * @returns {object} GeoJSON格式的数据对象
+     * @example
+     * ```javascript
+     * // 导出整个数据源为GeoJSON
+     * const geojson = dataSource.exportToGeoJSON();
+     * console.log(geojson.features.length); // 数据项数量
+     *
+     * // 可以保存为文件或发送到服务器
+     * const json = JSON.stringify(geojson);
+     * ```
+     */
+    exportToGeoJSON(): object;
+    /**
+     * 执行添加数据操作
+     * @internal
+     * @param {DataItem[]} data 待添加的数据项数组
+     */
+    _executeAddData(data: DataItem[]): void;
+    /**
+     * 执行移除数据操作
+     * @internal
+     * @param {DataItem[]|string[]} data 待移除的数据项数组或ID数组
+     */
+    _executeRemoveData(data: DataItem[] | string[]): void;
+    /**
+     * 再处理手工add进来的DataItem数据
+     * @internal
+     * @param {object} data 最终data数据buffer格式
+     */
+    _processData(data: object): void;
+    _templateDataLength: any;
+    /**
+     * 更新数据源，处理队列中的操作并生成渲染数据
+     * @internal
+     */
+    update(): void;
+    /**
+     * 修改数据源中的数据
+     * @param {object} data 新的数据对象
+     * @example
+     * ```javascript
+     * // 替换整个数据源的数据
+     * const newData = {
+     *   type: 'FeatureCollection',
+     *   features: [...]
+     * };
+     * dataSource.setData(newData);
+     *
+     * // 更新相关的可视化对象会自动更新
+     * ```
+     */
+    setData(data: object): void;
+    /**
+     * 清空数据源中存储的数据，恢复初始状态
+     * @example
+     * ```javascript
+     * // 清空所有数据
+     * dataSource.clear();
+     * console.log(dataSource.size); // 0
+     * ```
+     */
+    clear(): void;
+    /**
+     * 清空数据后的回调函数，子类可覆盖此方法
+     * @internal
+     */
+    onClear(): void;
+    /**
+     * 格式化几何体对象
+     * @internal
+     * @param {object|Array|Vector3} geometry 几何体对象
+     * @returns {object|null} 格式化后的几何体对象
+     */
+    _formatGeometry(geometry: object | any[] | Vector3): object | null;
+    /**
+     * 释放数据源资源
+     */
+    dispose(): void;
+    /**
+     * 获取所有数据项
+     * @type {DataItem[]}
+     */
+    get dataItems(): DataItem[];
+    /**
+     * 数据大小
+     * @type {number}
+     */
+    get size(): number;
+    /**
+     * 对源数据解析后得到的数据，数据格式如{position: [], index: []}，这样的数据格式更方便着色器
+     * @internal
+     * @type {object}
+     */
+    get data(): object;
+    /**
+     * 对源数据解析后得到的数据，数据格式如[{position, index}]，这样的数据格式更方便用户
+     * @internal
+     * @type {object[]}
+     */
+    get userData(): object[];
+    set objects(data: any[]);
+    /**
+     * 该数据源连接的对象
+     * @type {Array}
+     */
+    get objects(): any[];
+    set isCurve(value: boolean);
+    /**
+     * 是否自动生成曲线数据，只有在线数据的时候会生效，会自动取线数据的首尾点生成3D贝塞尔曲线
+     * @internal
+     * @deprecated
+     * @type {boolean}
+     */
+    get isCurve(): boolean;
+}
+import { DataItem } from './DataItem';

package/dist/types/threemap/dataSource/DeprecatedDataSource.d.ts

@@ -0,0 +1,13 @@
+export class DeprecatedDataSource extends DataSource {
+    constructor(options: any);
+    isDirectBuffer: boolean;
+    type: string;
+    add(dataItem: any): void;
+    remove(dataItem: any): void;
+    /**
+     * 设置数据
+     * @param {Array} data 数据
+     */
+    setData(data?: any[]): void;
+}
+import { DataSource } from './DataSource';

package/dist/types/threemap/dataSource/GeoJSONDataSource.d.ts

@@ -0,0 +1,91 @@
+/**
+ * GeoJSON格式数据的数据源，支持加载标准GeoJSON对象或通过URL加载远程数据
+ *
+ * GeoJSONDataSource专门处理标准GeoJSON格式的地理数据，支持以下形式：
+ * - FeatureCollection（特征集合）
+ * - Feature（单个特征）
+ * - Features数组（特征数组）
+ *
+ * 支持所有标准GeoJSON几何类型：
+ * - Point（点）
+ * - LineString（线）
+ * - Polygon（面）
+ * - MultiPoint（多点）
+ * - MultiLineString（多线）
+ * - MultiPolygon（多面）
+ *
+ * @category DataSource
+ * @example
+ * ```javascript
+ * // 示例1: 从GeoJSON对象创建
+ * const geojson = {
+ *   type: 'FeatureCollection',
+ *   features: [{
+ *     type: 'Feature',
+ *     geometry: {
+ *       type: 'Point',
+ *       coordinates: [116.39, 39.9]
+ *     },
+ *     properties: {
+ *       name: '北京',
+ *       value: 100
+ *     }
+ *   }]
+ * };
+ * const dataSource = GeoJSONDataSource.fromGeoJSON(geojson);
+ *
+ * // 示例2: 从URL加载
+ * const dataSource = await GeoJSONDataSource.fromURL('path/to/data.geojson');
+ * ```
+ */
+export class GeoJSONDataSource extends DataSource {
+    /**
+     * 从GeoJSON对象创建数据源实例
+     * @param {object} geoJSONObject GeoJSON数据对象
+     * @param {object} [options] 配置选项，传递给{@link DataSource}构造函数
+     * @returns {GeoJSONDataSource} 新创建的数据源实例
+     * @example
+     * ```javascript
+     * const dataSource = GeoJSONDataSource.fromGeoJSON({
+     *   type: 'FeatureCollection',
+     *   features: [...]
+     * });
+     * ```
+     */
+    static fromGeoJSON: (geoJSONObject: object, options?: object) => GeoJSONDataSource;
+    /**
+     * 从URL异步加载GeoJSON数据
+     * @param {string} url 数据的URL路径
+     * @param {object} [options] 配置选项，传递给{@link DataSource}构造函数
+     * @returns {Promise<GeoJSONDataSource>} 包含数据源实例的Promise
+     * @example
+     * ```javascript
+     * const dataSource = await GeoJSONDataSource.fromURL('path/to/data.geojson');
+     * console.log(`加载了${dataSource.size}个数据项`);
+     * ```
+     */
+    static fromURL: (url: string, options?: object) => Promise<GeoJSONDataSource>;
+    /**
+     * @internal
+     * @deprecated 已废弃，请使用{@link GeoJSONDataSource.fromGeoJSON}
+     * @param {object} object GeoJSON数据对象
+     * @param {object} [options] 配置选项
+     * @returns {GeoJSONDataSource} 数据源实例
+     */
+    static fromGeoJSONObject: (object: object, options?: object) => GeoJSONDataSource;
+    /**
+     * @internal
+     * @deprecated 已废弃，请使用{@link GeoJSONDataSource.fromGeoJSON}
+     * @param {object} object GeoJSON数据对象
+     * @param {object} [options] 配置选项
+     * @returns {GeoJSONDataSource} 数据源实例
+     */
+    static fromObject: (object: object, options?: object) => GeoJSONDataSource;
+    /**
+     * 创建GeoJSONDataSource实例
+     * @param {object} [options] 配置选项，传递给{@link DataSource}构造函数
+     */
+    constructor(options?: object);
+    type: string;
+}
+import { DataSource } from './DataSource';