dxfview 0.0.2

package/dist/types/core/utils/MergeUtils.d.ts

@@ -0,0 +1,638 @@
+/**
+ * MergeUtils - 几何体合并工具类
+ *
+ * 此文件提供了完整的Three.js几何体合并功能，主要用于优化渲染性能。
+ * 通过将多个具有相同材质和属性的几何体合并为单个几何体，可以减少Draw Call数量。
+ *
+ * 主要功能：
+ * - 网格(Mesh)几何体合并
+ * - 线段(Line)几何体合并
+ * - 点云(Points)几何体合并
+ * - 批处理信息保存和查询
+ * - 合并对象的撤销和恢复
+ *
+ * 核心优化策略：
+ * 1. 仅合并具有相同材质和属性的对象
+ * 2. 保持原始对象的变换矩阵信息
+ * 3. 支持批处理信息的保存，用于后续查询和操作
+ * 4. 提供完整的合并统计信息
+ */
+import * as THREE from "three";
+/**
+ * Batch接口 - 合并批次信息
+ *
+ * 此接口定义了合并后几何体中每个批次的信息结构。
+ * 当多个几何体被合并为一个时，每个原始几何体在合并后的几何体中占据一个批次。
+ * 通过批次信息，可以精确定位原始几何体在合并几何体中的位置和范围。
+ *
+ * 应用场景：
+ * 1. 鼠标交互时确定点击的是哪个原始对象
+ * 2. 局部更新时确定需要更新的顶点范围
+ * 3. 统计和调试时追踪每个批次的信息
+ * 4. 撤销合并操作时恢复原始对象的几何数据
+ *
+ * @internal 内部使用，不对外暴露
+ */
+export interface Batch {
+    /**
+     * 批次ID - 唯一标识符
+     * 用于区分合并几何体中的不同批次，每个批次对应一个原始几何体
+     * 从0开始递增，方便索引和查找
+     */
+    batchId: number;
+    /**
+     * 原始对象名称 - 可选
+     * 保存原始几何体的名称信息，用于调试和追踪
+     * 如果原始对象没有名称，此字段可能为空
+     */
+    name?: string;
+    /**
+     * 原始对象ID - 可选
+     * 保存原始几何体的唯一标识符，如elementId等
+     * 用于业务逻辑中的对象识别和关联
+     */
+    id?: string;
+    /**
+     * 位置起始索引
+     * 在合并后的顶点数组中，此批次顶点的起始位置
+     * 用于确定此批次在合并几何体中的顶点范围
+     */
+    positionStart: number;
+    /**
+     * 位置数量
+     * 此批次包含的顶点数量
+     * 从positionStart开始，连续的positionCount个顶点属于此批次
+     */
+    positionCount: number;
+    /**
+     * 索引起始位置
+     * 在合并后的索引数组中，此批次的索引起始位置
+     * 对于有索引的几何体，此字段非常重要
+     */
+    indexStart: number;
+    /**
+     * 索引数量
+     * 此批次包含的索引数量
+     * 从indexStart开始，连续的indexCount个索引属于此批次
+     */
+    indexCount: number;
+    /**
+     * 包围球 - 可选
+     * 此批次的几何包围球，用于快速的碰撞检测和视锥剔除
+     * 只有线段(Line)类型的批次才会计算此信息，以节省内存
+     */
+    boundingSphere?: THREE.Sphere;
+    /**
+     * 用户数据 - 可选
+     * 保存原始几何体的userData信息
+     * 包含了原始对象的自定义属性，如layerName等
+     * 注意：为了节省内存，只有在需要时才会保存此信息
+     */
+    userData?: object;
+}
+/**
+ * MergeUtils类 - 几何体合并工具类
+ *
+ * 此类提供了完整的Three.js几何体合并功能，是DXF查看器的核心优化工具。
+ * 通过智能合并具有相同材质和属性的几何体，可以显著提升渲染性能。
+ *
+ * 主要特性：
+ * 1. 支持Mesh、Line、Points三种几何体类型的合并
+ * 2. 智能检测可合并对象，基于材质、几何属性、图层等条件
+ * 3. 保持原始对象的变换矩阵和用户数据
+ * 4. 提供详细的批处理信息，用于后续查询和交互
+ * 5. 完整的合并统计信息，便于性能监控和调试
+ *
+ * 使用建议：
+ * - 在大量几何体加载完成后调用deepMerge进行合并
+ * - 对于动态更新的场景，考虑使用mergeInner进行轻量级合并
+ * - 定期调用resetMergeInfo重置统计信息
+ *
+ * @internal 内部工具类，不直接对外暴露
+ */
+export declare class MergeUtils {
+    /**
+     * 合并统计信息
+     * 记录每次合并操作的详细统计数据，用于性能监控和调试
+     * 所有字段都会在每次合并操作后更新
+     */
+    static mergeInfo: {
+        /**
+         * 被移除的对象数量
+         * 统计被合并掉的原始对象总数
+         * 这些对象被合并到新的几何体中，原始对象被销毁
+         */
+        removedObjects: number;
+        /**
+         * 合并后的网格数量
+         * 统计成功合并的网格(Mesh)几何体数量
+         * 每个合并后的网格可能包含多个原始网格的数据
+         */
+        mergedMeshes: number;
+        /**
+         * 合并后的线段数量
+         * 统计成功合并的线段(Line)几何体数量
+         * 线段合并相对复杂，需要处理索引和线段模式
+         */
+        mergedLines: number;
+        /**
+         * 合并后的点云数量
+         * 统计成功合并的点云(Points)几何体数量
+         * 点云合并通常用于粒子系统或散点数据
+         */
+        mergedPoints: number;
+        /**
+         * 合并的未知类型对象数量
+         * 统计合并的非标准类型对象数量
+         * 通常这些对象类型不影响主要渲染性能
+         */
+        mergedUnknownTypeObjects: number;
+        /**
+         * 合并操作耗时
+         * 记录整个合并过程的总耗时，单位为毫秒
+         * 用于性能分析和优化
+         */
+        elapsedTime: number;
+    };
+    /**
+     * 重置合并统计信息
+     *
+     * 将所有统计字段重置为0，用于开始新的合并统计周期
+     * 建议在每次批量合并操作前调用此方法
+     *
+     * 使用场景：
+     * 1. 开始新的模型加载和合并流程前
+     * 2. 性能测试时需要独立的统计数据
+     * 3. 调试时需要清除之前的统计信息
+     */
+    static resetMergeInfo(): void;
+    /**
+     * 尝试处理可合并对象
+     *
+     * 此方法是合并算法的核心，负责检查两个对象是否可以合并。
+     * 如果可以合并，则将它们分组到同一个批次中。
+     * 该方法采用性能优化的策略，避免重复比较已经确认可合并的对象。
+     *
+     * 合并条件检查顺序：
+     * 1. 边界检查 - 确保索引有效
+     * 2. 对象类型检查 - 确保有几何体且为BufferGeometry
+     * 3. 合并条件检查 - 材质、几何属性、对象属性等
+     * 4. 批次管理 - 创建新批次或加入现有批次
+     *
+     * @private 私有方法，仅供内部调用
+     *
+     * @param object 父对象或对象数组 - 可以是THREE.Object3D或其子对象数组
+     * @param i 第一个对象的索引 - 在对象数组中的位置
+     * @param k 第二个对象的索引 - 在对象数组中的位置，用于比较
+     * @param dict 可合并对象字典 - 存储已分组的可合并对象索引
+     *                键为第一个对象的索引，值为包含该组所有索引的对象
+     * @param nonMergeIndexes 非合并索引数组 - 存储暂时找不到合并伙伴的对象索引
+     *                        用于优化性能，避免重复检查
+     *
+     * @returns 是否找到可合并对象 - true表示成功找到并处理，false表示未找到
+     */
+    private static tryHandleMergeableObjects;
+    /**
+     * 深度合并对象数组
+     *
+     * 这是MergeUtils的核心方法，负责将一组Three.js对象进行智能合并。
+     * 该方法采用深度合并策略，将具有相同材质和属性的几何体合并为单个几何体，
+     * 从而显著减少Draw Call数量，提升渲染性能。
+     *
+     * 合并策略：
+     * 1. 仅处理叶子节点的对象，不处理有子对象的容器对象
+     * 2. 基于材质相等性和几何属性兼容性进行合并
+     * 3. 保持原始对象的变换矩阵和用户数据
+     * 4. 支持批处理信息的保存，便于后续查询和交互
+     *
+     * 性能优化：
+     * - 使用字典结构缓存已分组的对象，避免重复比较
+     * - 从后往前遍历以提高缓存命中率
+     * - 支持非合并索引数组，减少不必要的比较
+     * - 详细的日志记录，便于性能分析
+     *
+     * 使用建议：
+     * - 在大量几何体加载完成后调用此方法
+     * - 对于实时更新的场景，可以考虑减少批处理信息保存
+     * - 注意合并后的对象会从原父对象移除并添加到levelObject
+     *
+     * @param objects 要合并的对象数组 - 必须是THREE.Object3D的实例
+     * @param levelObject 目标父对象 - 可选，合并后的对象会被添加到此对象中
+     * @param bRemovedAndAddedAfterMerge 是否自动移除和添加 - 默认为true，控制是否自动处理父子关系
+     * @param bRemoveEmptyObjectsAfterMerge 是否移除空对象 - 默认为true，清理合并后的空容器对象
+     * @param saveBatchInfo 是否保存批处理信息 - 默认为true，用于后续查询原始对象信息
+     *
+     * @returns 合并结果对象
+     *          - added: 新增的对象数组（合并后的对象）
+     *          - removed: 被移除的对象数组（被合并掉的原始对象）
+     */
+    static deepMerge(objects: THREE.Object3D[], levelObject?: THREE.Object3D | undefined, bRemovedAndAddedAfterMerge?: boolean, bRemoveEmptyObjectsAfterMerge?: boolean, saveBatchInfo?: boolean): {
+        added: THREE.Object3D[];
+        removed: THREE.Object3D[];
+    };
+    /**
+     * 应用变换矩阵到几何体
+     *
+     * 在合并过程中，由于几何体会被移动到新的父对象下，需要正确应用其祖先对象的变换矩阵。
+     * 此方法遍历对象的祖先链，累积所有变换矩阵，然后应用到几何体上。
+     *
+     * 对象层级结构示例：
+     * ```
+     * - root object (根对象)
+     *   - merged objects group (合并对象组)
+     *     - merged object 1 (合并后的对象1)
+     *     - merged object 2 (合并后的对象2)
+     * ```
+     *
+     * 矩阵应用原理：
+     * 1. 从当前对象开始，向上遍历所有祖先对象
+     * 2. 累积每个祖先对象的变换矩阵（从下往上累乘）
+     * 3. 将累积的变换矩阵应用到几何体的顶点上
+     * 4. 优化：如果累积矩阵为单位矩阵，则无需应用变换
+     *
+     * 性能优化：
+     * - 使用预分配的临时矩阵对象，避免频繁创建
+     * - 提前检查是否为单位矩阵，跳过不必要的计算
+     * - 支持可选的levelObject参数，控制遍历的终止条件
+     *
+     * @private 私有方法，仅供内部合并过程调用
+     *
+     * @param copyGeometry 要应用的几何体副本 - 必须是已经克隆的几何体，不能修改原始几何体
+     * @param object 当前对象 - 需要计算其相对于levelObject的变换矩阵
+     * @param levelObject 目标层级对象 - 可选，矩阵累积的终止对象，默认为场景根对象
+     *
+     * @returns 应用变换后的几何体 - 如果应用了变换则返回新几何体，否则返回原几何体
+     */
+    private static applyMatrix;
+    /**
+     * 合并线段几何体
+     *
+     * 专门用于合并线段(Line)和线段组(LineSegments)的几何体方法。
+     * 线段合并相对复杂，因为需要处理不同的线段模式和索引结构。
+     *
+     * 线段类型说明：
+     * - LineSegments: 每两个顶点构成一条线段 (0-1, 2-3, 4-5...)
+     * - Line: 所有顶点依次连接形成连续线段 (0-1-2-3-4...)
+     *
+     * 合并策略：
+     * 1. 对于非虚线材质：直接使用Three.js的标准合并方法
+     * 2. 对于虚线材质：需要特殊处理，将Line转换为LineSegments
+     *
+     * 索引重建逻辑：
+     * - LineSegments模式：保持原始索引结构，直接累加顶点偏移
+     * - Line模式：需要重建索引，将连续线段转换为独立线段
+     * - 无索引模式：遍历所有顶点，动态生成索引
+     *
+     * 批处理信息更新：
+     * - 保存每个批次的索引范围和顶点范围
+     * - 支持后续通过索引查询原始批次信息
+     *
+     * @param geometries 要合并的几何体数组 - 所有几何体必须有相同的属性结构
+     * @param saveBatchInfo 是否保存批处理信息 - 用于后续查询和交互
+     * @param isDashedMaterial 是否为虚线材质 - 虚线材质需要特殊处理
+     * @param batches 批次信息数组 - 可选，用于保存批处理详细信息
+     *
+     * @returns 合并后的几何体 - 如果合并失败返回undefined
+     */
+    static mergeLineGeometries(geometries: THREE.BufferGeometry[], saveBatchInfo: boolean, isDashedMaterial: boolean, batches?: Batch[]): THREE.BufferGeometry | undefined;
+    /**
+     * 将线段几何体转换为线段组并合并
+     *
+     * 专门处理虚线材质的线段合并方法。
+     * 当使用虚线材质(LineDashedMaterial或ShaderMaterial)时，
+     * 需要将普通的Line转换为LineSegments格式才能正确显示虚线效果。
+     *
+     * 转换原理：
+     * 原始Line: 顶点序列 [0,1,2,3,4] -> 连接为 0-1-2-3-4
+     * 转换为LineSegments: 顶点序列 [0,1,0,2,1,2,2,3,3,4] -> 连接为 0-1,0-2,1-2,2-3,3-4
+     *
+     * 处理步骤：
+     * 1. 检查所有几何体的属性兼容性
+     * 2. 转换有索引的几何体为非索引格式
+     * 3. 收集所有几何体的顶点属性
+     * 4. 为每个几何体生成对应的顶点和索引数据
+     * 5. 合并所有属性为单个几何体
+     * 6. 更新批处理信息
+     *
+     * 性能优化：
+     * - 预分配数组空间，避免动态扩容
+     * - 批量处理顶点属性，提高内存访问效率
+     * - 只在需要时计算批处理信息
+     *
+     * @private 私有方法，仅供线段合并过程调用
+     *
+     * @param geometries 要合并的几何体数组 - 所有几何体必须有相同的属性结构
+     * @param saveBatchInfo 是否保存批处理信息 - 用于后续查询和交互
+     * @param batches 批次信息数组 - 用于保存批处理详细信息
+     *
+     * @returns 合并后的几何体 - 如果合并失败返回undefined
+     */
+    private static mergeBufferGeometriesWithLinesToLineSegments;
+    /**
+     * 合并线段顶点属性（转换为线段组格式）
+     *
+     * 处理虚线材质时，将Line格式的顶点属性转换为LineSegments格式。
+     * 这个方法是线段合并过程中的核心属性处理逻辑。
+     *
+     * 属性转换规则：
+     * 1. LineSegments模式：顶点属性保持不变
+     * 2. Line模式：每个连续线段需要复制顶点属性
+     *
+     * 转换示例：
+     * 原始Line顶点: [A, B, C, D] (属性值: [a1, b1, c1, d1])
+     * 转换为LineSegments: [A, B, A, C, B, C, C, D] (属性值: [a1, b1, a1, c1, b1, c1, c1, d1])
+     *
+     * 处理步骤：
+     * 1. 验证所有属性的类型和大小一致性
+     * 2. 计算合并后的总数组长度
+     * 3. 逐个处理每个几何体的属性
+     * 4. 根据线段模式进行属性复制或直接使用
+     * 5. 返回合并后的BufferAttribute
+     *
+     * 性能优化：
+     * - 预计算数组长度，避免动态扩容
+     * - 使用TypedArray进行高效的内存操作
+     * - 批量处理所有属性，减少函数调用开销
+     *
+     * @private 私有方法，仅供属性合并过程调用
+     *
+     * @param attributes 要合并的属性数组 - 每个元素对应一个几何体的同名属性
+     * @param isLineSegmentsArray 线段模式标记数组 - 标识每个几何体是否为LineSegments模式
+     *
+     * @returns 合并后的BufferAttribute - 如果合并失败返回undefined
+     */
+    private static mergeBufferAttributesWithLinesToLineSegments;
+    /**
+     * 从数组中移除指定数字
+     *
+     * 从后往前遍历数组，查找并移除第一个匹配的元素。
+     * 使用从后往前遍历的方式可以避免移除元素时索引变化导致的bug。
+     *
+     * 使用场景：
+     * - 从非合并索引数组中移除已找到合并伙伴的索引
+     * - 清理临时数组中的过期数据
+     *
+     * 性能优化：
+     * - 从数组末尾开始遍历，通常能更快找到要删除的元素
+     * - 只删除第一个匹配的元素，避免意外删除多个相同值
+     * - 使用splice方法一次性完成删除操作
+     *
+     * @private 私有方法，仅供内部数组操作使用
+     *
+     * @param arr 要操作的数字数组 - 会被原地修改
+     * @param toBeDeleted 要删除的数字值 - 只删除第一个匹配的元素
+     */
+    private static removeFromArray;
+    /**
+     * 检查两个几何体是否可以合并
+     *
+     * 验证两个几何体是否具有相同的结构和属性，从而可以安全合并。
+     * 这是合并前的关键检查，确保合并后的几何体具有一致的属性结构。
+     *
+     * 检查条件：
+     * 1. 类型检查：两个几何体都必须是BufferGeometry
+     * 2. 实例类型排除：不支持InstancedBufferGeometry（实例化几何体）
+     * 3. 索引一致性：要么都有索引，要么都没有索引
+     * 4. 属性完整性：具有相同的属性集合
+     * 5. 属性存在性：每个属性在两个几何体中都存在
+     *
+     * 不支持InstancedBufferGeometry的原因：
+     * - 实例化几何体有特殊的实例变换矩阵
+     * - 合并后实例信息会丢失，导致渲染错误
+     * - 需要特殊的实例合并逻辑，超出了标准合并的范围
+     *
+     * 性能优化：
+     * - 提前进行简单的null检查
+     * - 使用Set进行属性比较，提高查找效率
+     * - 详细的错误日志，便于调试
+     *
+     * @param g1 第一个几何体 - 要比较的几何体对象
+     * @param g2 第二个几何体 - 要比较的几何体对象
+     *
+     * @returns 是否可以合并 - true表示两个几何体兼容，可以合并
+     */
+    static areGeometriesMergeable(g1: THREE.BufferGeometry, g2: THREE.BufferGeometry): boolean;
+    /**
+     * 检查两个对象是否可以合并
+     *
+     * 验证两个Three.js对象是否满足合并条件，确保合并后的对象具有一致的行为。
+     * 这是对象级别的重要检查，基于多个维度进行兼容性验证。
+     *
+     * 检查条件：
+     * 1. 图层掩码(layer.mask)：必须相同，确保对象在同一渲染层
+     * 2. 渲染顺序(renderOrder)：必须相同，保持渲染顺序一致性
+     * 3. 可见性(visible)：必须相同，确保可见性行为一致
+     * 4. 图层名称(layerName)：如果存在，必须相同（DXF文件专用）
+     * 5. 对象类型：要么完全相同，要么都是同一绘制类型（Mesh/Line/Points）
+     *
+     * 图层掩码重要性：
+     * - 控制对象在哪些渲染层中可见
+     * - 合并不同掩码的对象会导致渲染错误
+     * - 必须严格检查，确保合并安全
+     *
+     * 图层名称在DXF中的作用：
+     * - DXF文件中的对象按图层组织
+     * - 相同图层的对象通常具有相同的材质和属性
+     * - 合并不同图层的对象可能会破坏DXF的图层结构
+     *
+     * 类型兼容性：
+     * - 严格类型匹配：两个Mesh对象可以合并
+     * - 绘制类型匹配：一个Mesh和一个Mesh可以合并
+     * - 混合类型不匹配：Mesh和Line不能合并
+     *
+     * @param o1 第一个对象 - 要比较的Three.js对象
+     * @param o2 第二个对象 - 要比较的Three.js对象
+     *
+     * @returns 是否可以合并 - true表示两个对象兼容，可以合并
+     */
+    static areObjectsMergeable(o1: THREE.Object3D, o2: THREE.Object3D): any;
+    /**
+     * 检查网格是否为合并后的对象
+     *
+     * 通过检查网格的userData中是否存在batches属性来判断是否为合并对象。
+     * 合并后的对象会在userData中保存批次信息，用于后续查询和操作。
+     *
+     * 合并对象的特征：
+     * - userData.batches存在且为数组
+     * - 每个batch包含原始对象的几何信息
+     * - 可以支持按批次进行局部操作
+     *
+     * 使用场景：
+     * 1. 鼠标交互时判断是否需要特殊处理
+     * 2. 性能优化时跳过已合并的对象
+     * 3. 调试时识别合并状态
+     * 4. 撤销操作时判断是否需要拆分
+     *
+     * 注意事项：
+     * - 只有通过MergeUtils合并的对象才会设置batches信息
+     * - 手动创建的网格不会有此标记
+     * - 如果保存批处理信息时设置为false，此方法会返回false
+     *
+     * @param mesh 要检查的网格对象 - THREE.Mesh实例
+     *
+     * @returns 是否为合并对象 - true表示此网格是合并后的对象
+     */
+    static isMergedMesh(mesh: THREE.Mesh): boolean;
+    /**
+     * 检查面索引是否属于指定批次
+     *
+     * 验证给定的面索引是否位于合并几何体中指定批次的范围内。
+     * 用于鼠标交互、选择等场景，确定点击的面属于哪个原始对象。
+     *
+     * 支持两种索引模式：
+     * 1. BoundsTree模式：BVH加速结构改变了原始索引，使用顶点索引判断
+     * 2. 标准索引模式：使用面索引范围直接判断
+     * 3. 无索引模式：使用顶点索引范围判断
+     *
+     * 判断逻辑：
+     * - BoundsTree模式：检查顶点索引是否在批次的顶点范围内
+     * - 有索引模式：检查面索引是否在批次的索引范围内
+     * - 无索引模式：将面索引转换为顶点索引后进行范围检查
+     *
+     * 使用场景：
+     * 1. 鼠标点击时确定点击的是哪个原始对象的面
+     * 2. 面选择工具中高亮显示特定批次
+     * 3. 局部更新时确定需要重新计算的面范围
+     * 4. 统计特定批次的面数量
+     *
+     * @param geometry 合并后的几何体 - 包含批次的几何体对象
+     * @param batch 批次信息 - 要检查的批次对象
+     * @param faceIndex 面索引 - 要检查的面在几何体中的索引
+     *
+     * @returns 是否属于批次 - true表示该面属于指定的批次
+     */
+    static isFaceIndexInBatch(geometry: THREE.BufferGeometry, batch: Batch, faceIndex: number): boolean;
+    /**
+     * 根据面索引获取批次信息
+     *
+     * 遍历合并网格的所有批次，查找包含指定面索引的批次。
+     * 这是鼠标交互和选择功能的核心方法，用于确定用户操作的是哪个原始对象。
+     *
+     * 查找过程：
+     * 1. 验证输入参数的有效性
+     * 2. 检查网格是否包含批次信息
+     * 3. 遍历所有批次，使用isFaceIndexInBatch方法检查每个批次
+     * 4. 返回第一个匹配的批次或undefined
+     *
+     * 错误处理：
+     * - 无效的面索引（负数）会记录错误日志并返回undefined
+     * - 没有批次信息的网格会返回undefined
+     * - 没有找到匹配批次的面索引也会返回undefined
+     *
+     * 性能优化：
+     * - 提前进行边界检查，避免无效计算
+     * - 使用高效的范围检查算法
+     * - 支持BoundsTree等加速结构
+     *
+     * 使用场景：
+     * 1. 鼠标点击事件中确定点击的原始对象
+     * 2. 面选择工具中获取选中面的原始信息
+     * 3. 局部材质更新时确定影响范围
+     * 4. 统计和分析特定批次的几何信息
+     *
+     * @param mesh 合并后的网格对象 - 包含批次信息的网格
+     * @param faceIndex 面索引 - 要查找的面在几何体中的索引
+     *
+     * @returns 批次信息 - 如果找到匹配的批次则返回Batch对象，否则返回undefined
+     */
+    static getBatchByFaceIndex(mesh: THREE.Mesh, faceIndex: number): Batch | undefined;
+    /**
+     * 根据线段索引获取批次信息
+     *
+     * 专门用于线段对象的批次查询方法。
+     * 根据给定的索引查找包含该索引的批次，用于线段的选择和交互。
+     *
+     * 索引类型说明：
+     * - 有索引的线段：index直接对应顶点索引
+     * - 无索引的线段：index对应顶点数组中的位置
+     *
+     * 查找逻辑：
+     * 1. 验证索引的有效性（不能为负数）
+     * 2. 检查线段对象是否包含批次信息
+     * 3. 根据索引类型选择合适的比较方法
+     * 4. 遍历批次列表查找匹配的批次
+     *
+     * 性能优化：
+     * - 提前进行边界检查
+     * - 支持两种索引模式的自适应处理
+     * - 高效的范围查找算法
+     *
+     * 使用场景：
+     * 1. 线段选择工具中确定选中的线段属于哪个批次
+     * 2. 鼠标悬停在线段上时显示批次信息
+     * 3. 线段编辑时确定编辑范围
+     * 4. 线段属性统计和分析
+     *
+     * @param line 合并后的线段对象 - 包含批次信息的线段
+     * @param index 线段索引 - 要查找的索引值
+     *
+     * @returns 批次信息 - 如果找到匹配的批次则返回Batch对象，否则返回undefined
+     */
+    static getBatchByLineIndex(line: THREE.Line, index: number): Batch | undefined;
+    /**
+     * 根据面索引获取批次ID
+     *
+     * 通过面索引快速获取对应的批次ID，这是getBatchByFaceIndex方法的简化版本。
+     * 主要用于需要批次ID而不需要完整批次信息的场景。
+     *
+     * 实现原理：
+     * 1. 调用getBatchByFaceIndex获取完整的批次信息
+     * 2. 如果找到批次则返回其batchId
+     * 3. 如果没有找到则返回-1表示无效
+     *
+     * 性能优化：
+     * - 重用现有的批次查找逻辑
+     * - 避免重复的遍历操作
+     * - 提供统一的错误处理
+     *
+     * 使用场景：
+     * 1. 快速判断面是否属于有效批次
+     * 2. 批次ID用于哈希表或数组索引
+     * 3. 性能敏感的查找操作
+     * 4. 批次统计和分组
+     *
+     * 注意事项：
+     * - 返回-1表示无效批次，需要检查错误情况
+     * - 依赖于getBatchByFaceIndex的实现
+     * - 对于无效输入会返回-1
+     *
+     * @param mesh 合并后的网格对象 - 包含批次信息的网格
+     * @param faceIndex 面索引 - 要查找的面在几何体中的索引
+     *
+     * @returns 批次ID - 有效的批次ID（>=0）或-1（无效）
+     */
+    static getBatchIdByFaceIndex(mesh: THREE.Mesh, faceIndex: number): number;
+    /**
+     * 根据批次ID获取批次信息
+     *
+     * 通过批次ID直接查找对应的批次对象。
+     * 这是最直接高效的批次查找方法，适合已知批次ID的场景。
+     *
+     * 查找过程：
+     * 1. 验证网格是否包含批次信息
+     * 2. 遍历批次数组查找匹配的batchId
+     * 3. 返回找到的批次对象或undefined
+     *
+     * 性能优化：
+     * - O(n)时间复杂度，n为批次数量
+     * - 对于大量批次的场景可以考虑建立ID到批次的映射表
+     * - 提前进行有效性检查
+     *
+     * 使用场景：
+     * 1. 已知批次ID需要获取详细信息
+     * 2. 批次管理和维护操作
+     * 3. 跨组件的批次信息传递
+     * 4. 批次数据缓存和更新
+     *
+     * 注意事项：
+     * - 批次ID从0开始连续分配
+     * - 如果批次不存在会返回undefined
+     * - 非合并对象也会返回undefined
+     *
+     * @param mesh 合并后的网格对象 - 包含批次信息的网格
+     * @param batchId 批次ID - 要查找的批次唯一标识符
+     *
+     * @returns 批次信息 - 如果找到则返回Batch对象，否则返回undefined
+     */
+    static getBatchByBatchId(mesh: THREE.Mesh, batchId: number): Batch | undefined;
+}