s3m-three 0.4.19 → 0.4.21

package/dist/render/viewer/types.d.ts

@@ -0,0 +1,256 @@
+/**
+ * `S3MViewer` 的公共类型：选项、光照、拾取结果、路径跟随。
+ *
+ * 从 `S3MViewer.ts` 整块搬出来的纯类型定义（零运行时）。搬出去的原因只有一个：
+ * 这些类型占了两百多行，和「类怎么实现」没有关系，留在主类里会把真正的逻辑冲淡。
+ *
+ * `S3MViewer.ts` 仍然 re-export 它们，所以 `import { S3MViewerOptions } from '.../S3MViewer'`
+ * 这类既有写法不受影响。
+ */
+import * as THREE from 'three';
+import type { EasingFn, EasingName } from '../../anim/easing.js';
+import type { FeatureAttributes, GeoPackageEntry, ParsedTile, Stats } from '../../core/types.js';
+import type { UnsupportedPolicy } from '../../core/degradations.js';
+import type { AttributeQueryOptions } from '../../core/AttributeQuery.js';
+import type { AuthenticateFn } from '../../core/AuthFetch.js';
+import type { LightingPreset } from '../lightingPreset.js';
+import type { S3MStyle } from '../StyleMaterial.js';
+import type { BuildTileFn } from '../../tileset/S3MTileset.js';
+import type { S3MDatasetEntry, S3MDatasetOptions } from '../DatasetManager.js';
+import type { GroundOptions } from '../GroundManager.js';
+export interface PickResult extends FeatureAttributes {
+    datasetId: string;
+    datasetName: string;
+    /** 网格编号 */
+    objectId: number;
+    /** 单体控制位（顶点区间型 = batchId，实例化型 = 状态纹理下标），-1 表示没有单体化信息 */
+    batchId: number;
+    /** 实例化几何命中的实例序号；非实例化为 undefined */
+    instanceIndex?: number;
+    skeletonName: string;
+    /** 单体中心经纬度，拿不到时为 null */
+    centerLngLat: [number, number] | null;
+    /** 命中点三维场景坐标 [x, y, z]（米，场景 ENU） */
+    point?: [number, number, number] | null;
+    /** 命中点经纬度 [lng, lat] */
+    lngLat?: [number, number] | null;
+    /** 命中点高程（米） */
+    altitude?: number | null;
+    mesh: THREE.Mesh;
+}
+export interface LightOptions {
+    /** 环境光强度，默认 0.4 */
+    ambientIntensity?: number;
+    /** 环境光颜色，十六进制或 CSS 颜色字符串，默认 0xffffff */
+    ambientColor?: number | string;
+    /** 半球光天空强度，默认 0.8 */
+    hemisphereIntensity?: number;
+    /** 半球光天空颜色，默认 0xffffff */
+    hemisphereColor?: number | string;
+    /** 半球光地面颜色，默认 0xb6c0cb */
+    hemisphereGroundColor?: number | string;
+    /** 主平行光强度，默认 1.0 */
+    keyLightIntensity?: number;
+    /** 主平行光强度别名（兼容写法） */
+    mainIntensity?: number;
+    /** 主平行光颜色，默认 0xffffff */
+    keyLightColor?: number | string;
+    /** 主平行光颜色别名（兼容写法） */
+    mainColor?: number | string;
+    /** 补光强度，默认 0.35 */
+    fillLightIntensity?: number;
+    /** 补光颜色，默认 0xffffff */
+    fillLightColor?: number | string;
+    /**
+     * 光照朝向模式：
+     * - 'headlamp': 默认头灯模式（随相机 bearing 旋转，受光面始终面向镜头）
+     * - 'fixed': 固定世界坐标方位角（如太阳光模拟）
+     */
+    mode?: 'headlamp' | 'fixed';
+    /** 方位角（度，0~360），固定模式下以正北为 0 顺时针，头灯模式下为相机相对偏角，默认 150 */
+    azimuth?: number;
+    /** 太阳/光源仰角（度，0~90），默认 50 */
+    altitude?: number;
+}
+export interface S3MViewerOptions {
+    /**
+     * 光照预设：
+     * - `'default'`（默认）：现有 PBR 打光，亮部线性总量 ≈ 2.55；
+     * - `'supermap'`：对齐 iClient3D 观感（暗部 0.46 / 亮部 2.44），远处不发灰、饱和度更高。
+     *   只改光源，不动材质与色调映射；`light` 里的显式字段仍然优先生效。
+     */
+    lightingPreset?: LightingPreset;
+    /** 光照参数配置（强度、颜色、朝向模式、太阳方位角/仰角等） */
+    light?: LightOptions;
+    /**
+     * 三角面材质深度偏移（共面摩尔纹 / 重合面归属的人工定序）。
+     * 例：factor -1 / units -2 把配置材质的片元深度略微拉近。
+     * 这是 mesh 粒度开关，见 BuildTileOptions.polygonOffset 的说明。
+     */
+    polygonOffset?: {
+        factor: number;
+        units: number;
+    };
+    /**
+     * 色调映射模式（默认 THREE.NoToneMapping，避免 ACESFilmic 压暗中暗部及导致底图与建筑色彩失真；
+     * 可传入 THREE.ACESFilmicToneMapping、THREE.LinearToneMapping、THREE.ReinhardToneMapping 等）
+     */
+    toneMapping?: THREE.ToneMapping;
+    /** 色调映射曝光度，默认 1.0 */
+    toneMappingExposure?: number;
+    /** 全局总驻留瓦片上限（多数据集多图层共享预算），在所有可见数据集之间动态均衡分配，彻底防止爆显存 */
+    totalMaxTiles?: number;
+    /** 单数据集简写 */
+    configUrl?: string;
+    /** 多数据集 */
+    datasets?: S3MDatasetOptions[];
+    style?: Partial<S3MStyle>;
+    /** 3D 物理地表面 / 基坑开挖配置 */
+    ground?: GroundOptions;
+    pickable?: boolean;
+    /** 每个数据集最多驻留瓦片 */
+    maxTiles?: number;
+    /** 每个数据集并发请求数 */
+    maxConcurrent?: number;
+    /**
+     * 图层级默认的降级处置策略（默认 `'warn'`），数据集可用 `unsupported` 单独覆盖。
+     * 见 `S3MTilesetOptions.unsupported`。
+     */
+    unsupported?: UnsupportedPolicy;
+    /** 是否用 Web Worker 解析经典 .s3mb 瓦片（默认开，崩溃自动降级主线程），见 S3MTilesetOptions.useWorker */
+    useWorker?: boolean;
+    /** LOD 切换范围缩放系数（默认 1.0），> 1 更倾向保留粗模，< 1 提前换细模 */
+    lodRangeScale?: number;
+    /**
+     * LOD 判定用屏幕高度时的「设备像素比上限」（默认不限制，行为与旧版一致）。
+     *
+     * LOD 的屏幕空间误差按 `canvasHeight` 物理像素算（与官方 `calcPixFromCam` 同口径），
+     * 于是 3x DPR 的手机上判定高度是 2556 而不是 852，细化层数与瓦片数都会远多于桌面。
+     * 传 2 表示「按 CSS 高度 × 2 截断」，砍掉 3x 屏的超采样余量；传 `Infinity` = 不截断。
+     *
+     * 代价：截断会把每块瓦片的屏幕投影放大同样倍数，几何误差与纹理密度同步变差，
+     * 所以默认不启用，由接入方按设备档位自行决定。运行时可用 `setLodPixelRatioCap()` 调整。
+     */
+    lodPixelRatioCap?: number;
+    /**
+     * 每个数据集驻留三角形总数的软上限（默认不限制）。
+     * 见 `S3MTilesetOptions.maxTriangles`：瓦片数管不住的场景（精模、大面片）用这条刹车。
+     */
+    maxTriangles?: number;
+    /**
+     * 每个数据集驻留显存/内存字节总数的软上限（默认 Infinity = 不限制）。
+     * 包含几何顶点缓冲（精确字节）与纹理显存估计。
+     * 超限时在每帧末尾（make-before-break）主动回收非显示的瓦片及其独占纹理。
+     */
+    maxMemory?: number;
+    /**
+     * 纹理缓存条数上限（默认 128）。一条对应一张已解码的瓦片纹理，
+     * 1024² 的 RGBA 一张约 4MB，128 条就是 512MB 显存 —— 低端设备建议 32~48。
+     * 与 `maxTextureSize` 配合使用：后者降单张尺寸，这条降张数。
+     */
+    maxImageCache?: number;
+    /**
+     * 各向异性过滤上限（默认不封顶，取 GPU 报的最大值，通常 16）。
+     * 移动端封到 4 或 8 肉眼通常无差，采样成本明显下降。只影响**之后创建**的纹理。
+     */
+    anisotropyCap?: number;
+    /**
+     * 纹理长边像素上限（默认不限制）。
+     * 非图集的 RGBA / WebP 纹理会按 2× 盒式滤波逐次减半到上限内；DXT 压缩直传与
+     * 图集（UV 已重映射）不受影响。手机上 1024 与 2048 肉眼几乎无差，显存差 4 倍。
+     */
+    maxTextureSize?: number;
+    /**
+     * 光照模型（默认 `'pbr'`）。
+     *
+     * - `'pbr'`：`MeshStandardMaterial`，GGX + 环境球谐，质感最好也最贵
+     * - `'lambert'`：`MeshLambertMaterial`，只保留漫反射 + 平行光，片元开销约省一半；
+     *   白模 / 纯色 / 按高度着色这类不需要高光的模式肉眼差别很小
+     *
+     * 模块级全局状态：同页多个图层会互相覆盖，后创建的那个决定全局。
+     * 只影响**之后创建**的材质 —— 已加载的瓦片要重新加载才会换。
+     */
+    materialQuality?: 'pbr' | 'lambert';
+    /** 自定义瓦片构建器（测试 / 服务端渲染时注入） */
+    buildTile?: BuildTileFn | null;
+    /**
+     * 可选：业务属性查询配置（iServer 数据服务）。
+     * 配上之后才能用 `colorByField()` 按业务字段着色 —— 属性值不在 S3M 瓦片里，只能去数据服务查。
+     */
+    attributes?: AttributeQueryOptions;
+    /** 宿主请求重画的信号。MapLibre 传 `() => map.triggerRepaint()`；纯 three 宿主传自己的渲染循环 */
+    onRequestRepaint?: () => void;
+    /** 地图朝向（弧度），用于让灯光跟着视角走。不传则灯光方向固定 */
+    getBearing?: () => number;
+    /**
+     * 鉴权适配函数（全局默认，数据集可用自己的 `authenticate` 覆盖）。
+     * 内核主线程发出的全部请求（配置 scp / 瓦片 / 子图集 / 棱线缓存 / 属性查询）
+     * 发出前都过一遍，可改写 URL（加 `?token=`）或附加请求头。
+     * 不传 = 行为与旧版完全一致。见 `AuthenticateFn`。
+     */
+    authenticate?: AuthenticateFn;
+    onStats?: (stats: Stats) => void;
+    onReady?: (entry: S3MDatasetEntry) => void;
+    onPick?: (result: PickResult | null) => void;
+    onError?: (error: unknown) => void;
+    /**
+     * 首次出现瓦片后自动预热另一种 `shading` 变体（默认开）。
+     *
+     * `flat` / `smooth` 是编译期变体，不预热的话第一次 `setStyle({ shading })` 会同步
+     * 编译着色器、卡一帧。预热在首帧之后异步做，期间跳一两帧渲染，肉眼不可见。
+     */
+    prewarmShading?: boolean;
+}
+export interface PickableRef {
+    datasetId: string;
+    mesh: THREE.Mesh;
+    tile: ParsedTile;
+    skeletonName: string;
+}
+export interface MeshUserData {
+    pickId?: number;
+    datasetId?: string;
+    skeletonName?: string;
+    geoRef?: GeoPackageEntry;
+    tileRef?: ParsedTile;
+    primitiveType?: number;
+    /** 点云对象（THREE.Points）：不吃面着色，也没有棱可描 */
+    isPointCloud?: boolean;
+    /** CPU 端现算的棱线对象（等宽线 Mesh） */
+    edges?: THREE.Object3D | null;
+    /** 背面外扩轮廓壳（edges 含 'hull' 时挂上） */
+    edgeHull?: THREE.Mesh | null;
+    /** 数据自带棱线包（此时不再用 EdgesGeometry 现算） */
+    nativeEdges?: boolean;
+    /** 数据本身有没有棱线包（不受 forceCpuEdges 影响，用来运行中切换时重算 nativeEdges） */
+    nativeEdgesRaw?: boolean;
+    /** 数据自带的棱线对象本身 */
+    isEdgeLines?: boolean;
+    /** CPU 现算的等宽棱线（与 isEdgeLines 区分，便于刷新样式） */
+    isThickEdge?: boolean;
+    /** 背面外扩轮廓壳（edges 含 'hull' 时挂上） */
+    isEdgeHull?: boolean;
+    /** 选中单体的棱线对象 */
+    isSelectionEdge?: boolean;
+    /** 该网格正在淡入时占用的动画通道 key，瓦片淘汰时要回收 */
+    tileFadeKey?: string;
+    pickMaterial?: THREE.Material;
+    [key: string]: unknown;
+}
+export interface PathFollowOptions {
+    /** 走完全程的时长（毫秒）。不传则按 speed 或默认 2000ms 推算 */
+    duration?: number;
+    /** 线速度（米/秒）。给了 duration 就以 duration 为准 */
+    speed?: number;
+    /** 是否循环 */
+    loop?: boolean;
+    /** 是否把折线首尾相连 */
+    closed?: boolean;
+    /** 缓动曲线：作用在**已走距离**上，默认 linear（恒速） */
+    easing?: EasingName | EasingFn;
+    /** 路径整体偏移（米），相当于路径原点 */
+    offset?: [number, number, number];
+    /** 单次走完（非循环）时回调 */
+    onComplete?: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/render/viewer/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/render/viewer/types.ts"],"names":[],"mappings":"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"}

package/dist/render/viewer/types.js

@@ -0,0 +1,3 @@
+export {};
+/* ------------------------------------------------------------------ 图层 */
+//# sourceMappingURL=types.js.map

package/dist/render/viewer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/render/viewer/types.ts"],"names":[],"mappings":";AAsQA,2EAA2E"}

package/dist/tileset/S3MTileset.d.ts

@@ -81,6 +81,7 @@ export interface TileNode {
         meshes: number;
         vertices: number;
         triangles: number;
+        memory?: number;
     };
 }
 /** 瓦片构建器可注入，用于测试 / 服务端渲染（此时不需要 three） */
@@ -139,6 +140,14 @@ export interface S3MTilesetOptions {
      * 不传 = 不限制，行为与旧版完全一致。运行时可用 `setMaxTriangles()` 调整。
      */
     maxTriangles?: number;
+    /**
+     * 本数据集**驻留显存/内存字节数**的软上限（默认不限制）。
+     * 包含几何顶点缓冲（精确字节）与纹理显存估计。超限时按同一套 make-before-break
+     * 主动淘汰非显示瓦片及其独占纹理。
+     *
+     * 不传 = 不限制（Infinity），行为与旧版完全一致。运行时可用 `setMaxMemory()` 调整。
+     */
+    maxMemory?: number;
     /**
      * 是否请求 `.texblock` 子图集（S3MBLOCK 根图集的清晰版）。**默认关**。
      *
@@ -166,6 +175,10 @@ export interface S3MTilesetOptions {
      */
     unsupported?: UnsupportedPolicy;
 }
+/** 估算单个纹理占用的显存字节数 */
+export declare function estimateTextureBytes(tex: any): number;
+/** 估算三维对象树中包含的几何缓冲字节数 */
+export declare function estimateObjectGeometryBytes(obj: any): number;
 export declare class S3MTileset {
     configUrl: string;
     config: Record<string, unknown> | null;
@@ -211,6 +224,10 @@ export declare class S3MTileset {
      * 判据与旧版逐字一致，不会多算一次面数。
      */
     maxTriangles: number;
+    /**
+     * 驻留显存/内存字节数的软上限。`Infinity` = 不限制（默认）。
+     */
+    maxMemory: number;
     lodRangeScale: number;
     /** 数据集配置声明的高度范围（米），若配置未声明则返回 null */
     get heightRange(): {
@@ -232,7 +249,6 @@ export declare class S3MTileset {
     /** 子瓦片 URL → 父瓦片 URL，用于淘汰后补洞 */
     private readonly _parentOf;
     private _frame;
-    private _lodDbgOnce;
     /** 格式类永久错误只向上报一次，避免整棵瓦片树刷同样的日志 */
     private _permanentReported;
     /** 请求量的硬上限（软上限 maxTiles 的超额余量），见构造函数注释 */
@@ -282,14 +298,25 @@ export declare class S3MTileset {
      * 收紧后不会立刻掉内容，要等下一次 `_trimBudget`（下一帧 update）才生效。
      */
     setMaxTriangles(n: number): void;
+    /**
+     * 运行时调整显存/内存字节预算。`Infinity` = 不限制（默认）。
+     * 收紧后不会立刻掉内容，要等下一次 `_trimBudget`（下一帧 update）才生效。
+     */
+    setMaxMemory(bytes: number): void;
+    /**
+     * 当前数据集驻留的显存与内存总字节数（几何缓冲精确大小 + 纹理显存估计）
+     */
+    residentMemory(): number;
+    private _residentGeometryBytes;
+    private _residentTextureBytes;
     /**
      * 预算裁剪 —— 必须在可见性算完之后调用（make-before-break）：
      * 新瓦片已经落地、也已经决定由谁负责显示，这时候才把没人依赖的那块裁掉。
      * 只踢「当前不显示」或「位置已被可见子瓦接手」的瓦片；挑不出安全候选时允许
      * 暂时超出预算，等下一帧再裁 —— 宁可多占一会儿内存，也不在画面上开洞。
      *
-     * 两条预算并行：瓦片数（`maxTiles`）与三角形总数（`maxTriangles`，默认不限制）。
-     * `maxTriangles` 为 Infinity 时短路，行为与只有瓦片数预算时完全一致。
+     * 三条预算并行：瓦片数（`maxTiles`）、三角形总数（`maxTriangles`）与显存字节（`maxMemory`）。
+     * `maxTriangles` / `maxMemory` 为 Infinity 时短路，行为与只有瓦片数预算时完全一致。
      */
     private _trimBudget;
     /**

package/dist/tileset/S3MTileset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"S3MTileset.d.ts","sourceRoot":"","sources":["../../src/tileset/S3MTileset.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"S3MTileset.d.ts","sourceRoot":"","sources":["../../src/tileset/S3MTileset.ts"],"names":[],"mappings":"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"}

package/dist/tileset/S3MTileset.js

@@ -172,6 +172,60 @@ export function parseConfigText(text) {
     }
     return JSON.parse(trimmed);
 }
+/** 估算单个纹理占用的显存字节数 */
+export function estimateTextureBytes(tex) {
+    if (!tex)
+        return 0;
+    if (Array.isArray(tex.mipmaps) && tex.mipmaps.length > 0) {
+        let bytes = 0;
+        for (const m of tex.mipmaps) {
+            if (m?.data?.byteLength)
+                bytes += m.data.byteLength;
+        }
+        if (bytes > 0)
+            return bytes;
+    }
+    const img = tex.image;
+    if (!img)
+        return 0;
+    if (img.data && typeof img.data.byteLength === 'number') {
+        return img.data.byteLength;
+    }
+    const w = img.width ?? 0;
+    const h = img.height ?? 0;
+    if (w > 0 && h > 0) {
+        const factor = tex.generateMipmaps ? 1.3333333333333333 : 1;
+        return Math.round(w * h * 4 * factor);
+    }
+    return 0;
+}
+/** 估算三维对象树中包含的几何缓冲字节数 */
+export function estimateObjectGeometryBytes(obj) {
+    let bytes = 0;
+    if (!obj)
+        return 0;
+    obj.traverse?.((child) => {
+        const geo = child.geometry;
+        if (geo) {
+            if (geo.attributes) {
+                for (const attr of Object.values(geo.attributes)) {
+                    if (attr?.array?.byteLength)
+                        bytes += attr.array.byteLength;
+                }
+            }
+            if (geo.index?.array?.byteLength) {
+                bytes += geo.index.array.byteLength;
+            }
+        }
+        if (child.isInstancedMesh) {
+            if (child.instanceMatrix?.array?.byteLength)
+                bytes += child.instanceMatrix.array.byteLength;
+            if (child.instanceColor?.array?.byteLength)
+                bytes += child.instanceColor.array.byteLength;
+        }
+    });
+    return bytes;
+}
 export class S3MTileset {
     configUrl;
     config = null;
@@ -232,6 +286,10 @@ export class S3MTileset {
      * 判据与旧版逐字一致，不会多算一次面数。
      */
     maxTriangles;
+    /**
+     * 驻留显存/内存字节数的软上限。`Infinity` = 不限制（默认）。
+     */
+    maxMemory;
     lodRangeScale;
     /** 数据集配置声明的高度范围（米），若配置未声明则返回 null */
     get heightRange() {
@@ -256,7 +314,6 @@ export class S3MTileset {
     /** 子瓦片 URL → 父瓦片 URL，用于淘汰后补洞 */
     _parentOf = new Map();
     _frame = 0;
-    _lodDbgOnce = false;
     /** 格式类永久错误只向上报一次，避免整棵瓦片树刷同样的日志 */
     _permanentReported = false;
     /** 请求量的硬上限（软上限 maxTiles 的超额余量），见构造函数注释 */
@@ -291,6 +348,9 @@ export class S3MTileset {
         this.maxConcurrent = options.maxConcurrent ?? 4;
         this.maxTiles = options.maxTiles ?? 64;
         this.maxTriangles = options.maxTriangles ?? Infinity;
+        this.maxMemory = Number.isFinite(options.maxMemory) && options.maxMemory > 0
+            ? options.maxMemory
+            : Infinity;
         this.maxImageCache = options.maxImageCache ?? 128;
         // 硬上限 = 软上限 + 余量。淘汰只在「新瓦片已经落地并接管显示」之后做（make-before-break），
         // 所以中间态允许临时超出 maxTiles；硬上限只用来挡住失控的请求量，不用于挤掉正在显示的内容。
@@ -499,14 +559,46 @@ export class S3MTileset {
     setMaxTriangles(n) {
         this.maxTriangles = n > 0 ? n : Infinity;
     }
+    /**
+     * 运行时调整显存/内存字节预算。`Infinity` = 不限制（默认）。
+     * 收紧后不会立刻掉内容，要等下一次 `_trimBudget`（下一帧 update）才生效。
+     */
+    setMaxMemory(bytes) {
+        this.maxMemory = Number.isFinite(bytes) && bytes > 0 ? bytes : Infinity;
+    }
+    /**
+     * 当前数据集驻留的显存与内存总字节数（几何缓冲精确大小 + 纹理显存估计）
+     */
+    residentMemory() {
+        return this._residentGeometryBytes() + this._residentTextureBytes();
+    }
+    _residentGeometryBytes() {
+        let total = 0;
+        for (const node of this.nodes.values()) {
+            if (node.stats && typeof node.stats.memory === 'number') {
+                total += node.stats.memory;
+            }
+            else if (node.group) {
+                total += estimateObjectGeometryBytes(node.group);
+            }
+        }
+        return total;
+    }
+    _residentTextureBytes() {
+        let total = 0;
+        for (const tex of this.textureCache.values()) {
+            total += estimateTextureBytes(tex);
+        }
+        return total;
+    }
     /**
      * 预算裁剪 —— 必须在可见性算完之后调用（make-before-break）：
      * 新瓦片已经落地、也已经决定由谁负责显示，这时候才把没人依赖的那块裁掉。
      * 只踢「当前不显示」或「位置已被可见子瓦接手」的瓦片；挑不出安全候选时允许
      * 暂时超出预算，等下一帧再裁 —— 宁可多占一会儿内存，也不在画面上开洞。
      *
-     * 两条预算并行：瓦片数（`maxTiles`）与三角形总数（`maxTriangles`，默认不限制）。
-     * `maxTriangles` 为 Infinity 时短路，行为与只有瓦片数预算时完全一致。
+     * 三条预算并行：瓦片数（`maxTiles`）、三角形总数（`maxTriangles`）与显存字节（`maxMemory`）。
+     * `maxTriangles` / `maxMemory` 为 Infinity 时短路，行为与只有瓦片数预算时完全一致。
      */
     _trimBudget() {
         let removed = false;
@@ -514,9 +606,10 @@ export class S3MTileset {
         // 在途的也算进"预期驻留数"：不然一批瓦片同时落地时会先把画面撑爆再疯狂裁
         const overTiles = () => this.nodes.size + this.pending.size > this.maxTiles;
         const overTriangles = () => Number.isFinite(this.maxTriangles) && this._residentTriangles() > this.maxTriangles;
-        // 面数预算生效时可能要连踢多块，迭代上限跟着驻留规模走；不生效时根本进不了循环
+        const overMemory = () => Number.isFinite(this.maxMemory) && this.residentMemory() > this.maxMemory;
+        // 预算生效时可能要连踢多块，迭代上限跟着驻留规模走；不生效时根本进不了循环
         const iterationCap = this.nodes.size + this.maxTiles + 16;
-        while ((overTiles() || overTriangles()) && guard++ <= iterationCap) {
+        while ((overTiles() || overTriangles() || overMemory()) && guard++ <= iterationCap) {
             if (!this._evictOne(this.nodes.size + this.pending.size > this.hardCap))
                 break;
             removed = true;
@@ -1033,6 +1126,7 @@ export class S3MTileset {
                     meshes: stats.meshes ?? 0,
                     vertices: stats.vertices ?? 0,
                     triangles: stats.triangles ?? 0,
+                    memory: stats.memory ?? estimateObjectGeometryBytes(group),
                 },
             };
             this.nodes.set(url, node);