s3m-three 0.4.18 → 0.4.20

package/src/render/TextureFactory.ts

@@ -31,6 +31,16 @@ export function setMaxAnisotropy(n: number, cap = Infinity): void {
   anisotropyCap = Number.isFinite(cap) && cap > 0 ? Math.max(1, cap) : Infinity;
 }
 
+/**
+ * 单独调各向异性上限（只影响之后创建的纹理）。
+ * supermap 预设会设成 1 —— 官方 iClient3D 不开各向异性，斜视角直接采高 mip
+ * 平均成纯色；我们默认拉满（Infinity）是为了倾斜摄影立面清晰度，代价是
+ * 米制平铺纹理的远处高频纹（点阵/砖缝）被硬保下来，怎么调光照都"不像官方"。
+ */
+export function setAnisotropyCap(cap: number): void {
+  anisotropyCap = Number.isFinite(cap) && cap > 0 ? Math.max(1, cap) : Infinity;
+}
+
 /**
  * 纹理长边像素上限（默认 Infinity = 不限制）。
  * 只作用于非图集的 RGBA / WebP 产物，见 `core/TextureDecode.ts` 的 `maxSize`。
@@ -86,6 +96,24 @@ async function decodeTexture(
   return decodeTextureData(tex, { compressed, maxSize });
 }
 
+/**
+ * 纹理是否做 sRGB→linear 解码。
+ *
+ * 默认 true（three 线性 PBR 管线的正确姿势）。`lightingPreset: 'supermap'` 会关掉它：
+ * 官方 iClient3D 把贴图字节值**不解码**直接进 shader、在 sRGB 数值空间做 Lambert 直乘，
+ * 要逐像素对齐就得让字节值原样进来（输出端由 StyleMaterial 的 S3M_DIRECT_COLOR 抵消）。
+ */
+let srgbTextureDecode = true;
+
+/** 切换纹理解码（只影响之后创建的纹理，已上传 GPU 的不受影响） */
+export function setSrgbTextureDecode(v: boolean): void {
+  srgbTextureDecode = v;
+}
+
+export function getSrgbTextureDecode(): boolean {
+  return srgbTextureDecode;
+}
+
 function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
   tex.wrapS = THREE.RepeatWrapping;
   tex.wrapT = THREE.RepeatWrapping;
@@ -94,7 +122,7 @@ function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
   tex.generateMipmaps = true;
   // 各向异性过滤对斜视角立面清晰度的提升比提高分辨率更直接
   tex.anisotropy = anisotropyCap === Infinity ? maxAnisotropy : Math.min(maxAnisotropy, anisotropyCap);
-  if (srgb) tex.colorSpace = THREE.SRGBColorSpace;
+  if (srgb && srgbTextureDecode) tex.colorSpace = THREE.SRGBColorSpace;
   tex.flipY = false;
   tex.needsUpdate = true;
   return tex;
@@ -145,12 +173,16 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
     texture = new THREE.Texture(data.bitmap);
   } else if (data.blocks && data.blockFormat) {
     // DXT 块直传：GPU 硬件解压，省 4~8 倍上传带宽与显存。压缩纹理不能 generateMipmaps
-    // （WebGL 限制），远处靠 LinearFilter 兜底；s3mHasAlpha 走 alphaTest 的 DXT1 1bit
-    // alpha 历史上没开过，DXT5 的 hasAlpha 由 decodeTextureData 判定
+    // （WebGL 限制）——所以**数据自带的内联 mip 链**（官方 iClient3D 逐层上传的那条）
+    // 必须切出来一起传，否则远处只有 level0 可采，高频纹/点阵全保留，永远"糊"不出
+    // 官方那种平均色；s3mHasAlpha 走 alphaTest 的 DXT1 1bit alpha 历史上没开过，
+    // DXT5 的 hasAlpha 由 decodeTextureData 判定
     const format =
       data.blockFormat === 'dxt1' ? THREE.RGB_S3TC_DXT1_Format : THREE.RGBA_S3TC_DXT5_Format;
     texture = new THREE.CompressedTexture(
-      [{ data: data.blocks, width: data.width, height: data.height }],
+      data.mipmaps && data.mipmaps.length > 1
+        ? data.mipmaps.map((m) => ({ data: m.data, width: m.width, height: m.height }))
+        : [{ data: data.blocks, width: data.width, height: data.height }],
       data.width,
       data.height,
       format,
@@ -165,7 +197,9 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
   const configured = isAtlas ? configureAtlas(texture) : configure(texture);
   if (data.blocks) {
     configured.generateMipmaps = false;
-    configured.minFilter = THREE.LinearFilter;
+    // 带链 → 三线性取链上高层级（官方同款平均效果）；纯 level0 才退回 Linear 兜底
+    configured.minFilter =
+      data.mipmaps && data.mipmaps.length > 1 ? THREE.LinearMipmapLinearFilter : THREE.LinearFilter;
   }
   // flipY 为真即 S3MBLOCK 图集（见 core/types.ts），必须无 mip
   return { texture: configured, decoded: data.kind };

package/src/render/lightingPreset.ts

@@ -0,0 +1,76 @@
+/**
+ * 光照预设。
+ *
+ * 默认那套（ambient 0.4 / hemi 0.8 / key 1.0 / fill 0.35）是为「线性 PBR 管线」
+ * 调的，亮部线性总量约 2.55。超图官方 iClient3D 走的是完全不同的着色模型
+ * （`S3MTiles/Shaders/S3MTilesFS.js`）：
+ *
+ * ```glsl
+ * const vec3 SunLightColor     = vec3(0.8);
+ * const vec3 AmbientLightColor = vec3(0.7);
+ * return uDiffuseColor.rgb * (SunLightColor * max(dot(n, L), 0.0) + AmbientLightColor * uAmbientColor.rgb);
+ * ```
+ *
+ * 也就是**在 sRGB 数值空间里直接做 Lambert**，因子范围 0.7 ~ 1.5，没有 gamma 编码、
+ * 没有 tonemap。我们在线性空间乘、最后再做 linear→sRGB，同一个中间灰（sRGB 0.5）：
+ *
+ * | | 官方 | 我们（默认） |
+ * |---|---|---|
+ * | 背光 | 0.5 × 0.7 = 0.35 | (0.214 × 0.8)^(1/2.2) ≈ 0.455 |
+ * | 受光 | 0.5 × 1.5 = 0.75 | (0.214 × 2.55)^(1/2.2) ≈ 0.76 |
+ *
+ * 暗部被 gamma 抬亮 30%，动态范围被压到 0.7~1.0，于是「发灰、饱和度低」。
+ *
+ * `'supermap'` 预设把线性光照总量重新压到与官方 sRGB 因子等效的区间：
+ * 0.7^2.2 ≈ 0.46（背光）到 1.5^2.2 ≈ 2.44（受光）。这不是逐像素复刻官方的
+ * sRGB 直乘（那需要放弃 PBR、改 `outputColorSpace = LinearSRGB`），
+ * 而是只动光源、可逆、不碰材质。
+ */
+export type LightingPreset = 'default' | 'supermap';
+
+export interface PresetLightIntensities {
+  ambientIntensity: number;
+  hemisphereIntensity: number;
+  keyLightIntensity: number;
+  fillLightIntensity: number;
+}
+
+/** 现有默认值，一字节不改 */
+export const DEFAULT_LIGHT_PRESET: PresetLightIntensities = {
+  ambientIntensity: 0.4,
+  hemisphereIntensity: 0.8,
+  keyLightIntensity: 1.0,
+  fillLightIntensity: 0.35,
+};
+
+/**
+ * 对齐官方观感：几乎只留平行光 + 极低环境光。
+ *
+ * 背光总和 = 0.12 + 0.20 + 0.15 = 0.47（≈ 0.7^2.2）
+ * 受光总和 = 0.47 + 1.95       = 2.42（≈ 1.5^2.2）
+ */
+export const SUPERMAP_LIGHT_PRESET: PresetLightIntensities = {
+  ambientIntensity: 0.12,
+  hemisphereIntensity: 0.2,
+  keyLightIntensity: 1.95,
+  fillLightIntensity: 0.15,
+};
+
+export const LIGHT_PRESETS: Record<LightingPreset, PresetLightIntensities> = {
+  default: DEFAULT_LIGHT_PRESET,
+  supermap: SUPERMAP_LIGHT_PRESET,
+};
+
+/** 预设名 → 强度组合；未知值回落默认，避免拼错名字把场景变全黑 */
+export function resolveLightingPreset(preset?: string | null): PresetLightIntensities {
+  if (preset && Object.prototype.hasOwnProperty.call(LIGHT_PRESETS, preset)) {
+    return LIGHT_PRESETS[preset as LightingPreset];
+  }
+  return DEFAULT_LIGHT_PRESET;
+}
+
+/** 线性总辐照度（供测试与调试：受光面 / 背光面） */
+export function presetLinearRange(p: PresetLightIntensities): { shadow: number; lit: number } {
+  const shadow = p.ambientIntensity + p.hemisphereIntensity + p.fillLightIntensity;
+  return { shadow, lit: shadow + p.keyLightIntensity };
+}

package/src/render/materialAlpha.ts

@@ -0,0 +1,75 @@
+/**
+ * S3MB 材质透明判定。
+ *
+ * 官方把 alphaMode 定义成三个**小写**枚举（`S3MTiles/Enum/AlphaMode.js`）：
+ * ```
+ * OPAQUE: 'opaque'   BLEND: 'blend'   MASK: 'mask'
+ * ```
+ * 而 S3M 规范文档里写的是 `AM_OPAQUE / AM_BLEND / AM_MASK`。线上数据用的是前者
+ * （`3D-BIMbuilding-2` 的 `WhiteMaterial_1` 就是 `"alphaMode": "blend"`），
+ * 所以两种写法都要认，否则 blend 材质会被当成不透明 —— 表现就是「透明度不见了」。
+ *
+ * 另外还有一条官方没写进规范、但数据里真实存在的透明度来源：**顶点色 alpha**。
+ * SMID 4421 的材质无纹理、`diffuse.a = 1`，顶点色是 u8 `(0,128,192,63)`，
+ * 也就是 alpha ≈ 0.247。官方片元 `outColor = baseColorWithAlpha * uDiffuseColor`
+ * 里 `baseColorWithAlpha = vColor`（vec4），alpha 就靠这条路传下去。
+ */
+
+export type S3MAlphaMode = 'opaque' | 'blend' | 'mask';
+
+/** 归一化 alphaMode：兼容小写枚举与规范里的 `AM_` 前缀，未知值一律按不透明处理 */
+export function resolveAlphaMode(raw: unknown): S3MAlphaMode {
+  const s = String(raw ?? '').trim().toLowerCase().replace(/^am_/, '');
+  return s === 'blend' || s === 'mask' ? s : 'opaque';
+}
+
+export interface MaterialAlphaInput {
+  /** 材质原始 alphaMode（'blend' / 'AM_BLEND' / 'mask' / 'opaque' …） */
+  alphaMode?: unknown;
+  /** 材质 diffuse.a，缺省视为 1 */
+  diffuseAlpha?: number;
+  /** 材质 transparentsorting（配置开启透明度优化时官方也按透明处理） */
+  transparentSorting?: boolean;
+  /** 该几何顶点色 alpha 的最小值：<1 说明有半透明顶点 */
+  vertexAlphaMin?: number;
+  /** 内置水面材质且块里没有像素（我们自己的兜底上色） */
+  isWaterWithoutMap?: boolean;
+}
+
+/**
+ * 是否走透明（alpha 混合）管线。
+ *
+ * - `blend`：官方 `isTransparent = true`，进 TRANSLUCENT pass；
+ * - `mask`：官方也算透明，但它是**镂空**语义（alphaTest）。我们保持不透明队列 +
+ *   alphaTest，否则树叶/栏杆之间会因 `depthWrite: false` 互相穿透；
+ * - 顶点色 alpha < 1：4421 这类"材质不透明但顶点半透明"的数据必须走混合。
+ */
+export function isTransparentMaterial(input: MaterialAlphaInput): boolean {
+  const mode = resolveAlphaMode(input.alphaMode);
+  if (mode === 'blend') return true;
+  if (mode === 'mask') return false;
+  if (input.transparentSorting === true) return true;
+  if (input.isWaterWithoutMap === true) return true;
+  if ((input.diffuseAlpha ?? 1) < 0.999) return true;
+  if ((input.vertexAlphaMin ?? 1) < 0.999) return true;
+  return false;
+}
+
+/**
+ * 顶点色 alpha 的最小值：材质要不要开混合，取决于这块几何里有没有半透明顶点。
+ *
+ * 顶点数在几千到几万量级，一次线性扫描即可；只在建材质时算一次（每个 primitive 一次）。
+ * 没有 alpha 分量（老数据的 RGB）按 1 处理 —— 不能因为读不到就当成 0，那会整片全透明。
+ */
+export function minVertexAlpha(color: { array: ArrayLike<number>; components?: number } | undefined): number {
+  if (!color || !color.array || color.array.length === 0) return 1;
+  const comp = color.components ?? 4;
+  if (comp < 4) return 1;
+  let min = 1;
+  for (let i = 3; i < color.array.length; i += comp) {
+    const a = color.array[i]!;
+    if (a < min) min = a;
+    if (min <= 0.999) return min; // 已经确定要透明，提前退出
+  }
+  return min;
+}