@avatar-platform/avatar-render 0.1.0 → 0.2.0

package/README.md

@@ -61,7 +61,25 @@ await viewer.loadEnvironment('/signed-download?id=123', 'exr');
 - 模型只在显示层居中、统一尺寸，保留模型原始节点变换、骨骼及 PBR 材质。不拼装/导出模型，不播放动画。Y 轴向上、默认面向 +Z，其他朝向可用 `modelRotation` 调整。
 - 同一类资源连续加载采用最后一次调用优先；旧请求完成后释放资源并抛 `AbortError`，不覆盖新请求。替换失败保留先前有效资源。`dispose()` 后的迟到加载同样释放并抛 `AbortError`。底层请求不保证中途停止下载。
 - Draco / KTX2 压缩模型可通过构造参数 `configureModelLoader(loader, renderer)` 配置 Three.js 解码器；解码器地址、加载及解码器自身销毁由宿主负责。默认 GLTFLoader 不配置远端解码设施。
-- GLB、HDR、EXR、凭据、业务地址均不打包；HDR 必须由调用方传入。PNG 全景预览图不作为 HDR 环境输入。
+- 包内置原摄影棚和三套柔光 HDR（合计约 4.34 MB）；模型、其他 HDR / EXR、凭据、业务地址不打包。PNG 全景预览图不作为 HDR 环境输入。
+
+## 内置 HDR 场景
+
+```ts
+import { ENVIRONMENT_PRESETS } from '@avatar-platform/avatar-render';
+
+await viewer.loadEnvironmentPreset(); // studio：原默认摄影棚
+await viewer.loadEnvironmentPreset('overcast'); // 阴天户外 · 柔和天空
+await viewer.loadEnvironmentPreset('window'); // 室内大窗 · 柔光
+await viewer.loadEnvironmentPreset('soft-studio'); // 均匀展示棚 · 低反差
+// ENVIRONMENT_PRESETS 的只读 id / name / url 可用于创建宿主下拉菜单。
+```
+
+构造器仍不自动加载环境；需要默认摄影棚时显式调用 `loadEnvironmentPreset()`。切换只替换环境照明，保留曝光、强度、旋转及模型材质，加载失败保留当前环境。`reset()` 只重置渲染配置和视角，不切换 HDR。`/render-lab` 默认使用原摄影棚，提供四个场景及自定义文件入口。
+
+HDR 随 npm 包的 `assets/` 分发，通过相对模块的 `new URL(..., import.meta.url)` 解析；Vite 等支持此写法的构建器会复制资源。直接以原生 ESM 部署时，保留 `dist/` 与 `assets/` 的相对目录；其他构建器需配置 HDR 静态资源处理，或部署 assets 后使用 `loadEnvironment(url, 'hdr')`。按选择加载一套，不会预加载全部 HDR。
+
+新增三套为建模师提供的原创程序化 2048×1024 Radiance RGBE、线性光环境，分别为微冷天空、暖中性侧窗和中性低反差棚光；名称描述照明风格，不是真实场景照片。可保持强度 1 对比，过亮时尝试 0.7；不覆盖原模型 roughness / metalness。包仅包含 HDR，不包含材质球测试或全景预览 PNG。
 
 ## 配置
 

package/dist/environments.d.ts

@@ -0,0 +1,20 @@
+/** Bundled HDR assets, resolved relative to this module by browser bundlers. */
+export declare const ENVIRONMENT_PRESETS: readonly [Readonly<{
+    id: "studio";
+    name: "默认摄影棚";
+    url: string;
+}>, Readonly<{
+    id: "overcast";
+    name: "阴天户外 · 柔和天空";
+    url: string;
+}>, Readonly<{
+    id: "window";
+    name: "室内大窗 · 柔光";
+    url: string;
+}>, Readonly<{
+    id: "soft-studio";
+    name: "均匀展示棚 · 低反差";
+    url: string;
+}>];
+export type EnvironmentPresetId = typeof ENVIRONMENT_PRESETS[number]['id'];
+export declare const DEFAULT_ENVIRONMENT_PRESET: EnvironmentPresetId;

package/dist/environments.js

@@ -0,0 +1,8 @@
+/** Bundled HDR assets, resolved relative to this module by browser bundlers. */
+export const ENVIRONMENT_PRESETS = Object.freeze([
+    Object.freeze({ id: 'studio', name: '默认摄影棚', url: new URL('../assets/studio.hdr', import.meta.url).href }),
+    Object.freeze({ id: 'overcast', name: '阴天户外 · 柔和天空', url: new URL('../assets/overcast.hdr', import.meta.url).href }),
+    Object.freeze({ id: 'window', name: '室内大窗 · 柔光', url: new URL('../assets/window.hdr', import.meta.url).href }),
+    Object.freeze({ id: 'soft-studio', name: '均匀展示棚 · 低反差', url: new URL('../assets/soft-studio.hdr', import.meta.url).href })
+]);
+export const DEFAULT_ENVIRONMENT_PRESET = 'studio';

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import * as THREE from 'three';
 import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
 import { type RenderConfig } from './config.js';
+import { type EnvironmentPresetId } from './environments.js';
+export { DEFAULT_ENVIRONMENT_PRESET, ENVIRONMENT_PRESETS, type EnvironmentPresetId } from './environments.js';
 export { DEFAULT_RENDER_CONFIG, type RenderConfig } from './config.js';
 export type AssetSource = string | File;
 export type EnvironmentFormat = 'hdr' | 'exr';
@@ -39,6 +41,8 @@ export declare class AvatarRenderer {
     reset(): void;
     /** Latest request wins. Failed replacements preserve the last valid model. */
     loadModel(source: AssetSource): Promise<void>;
+    /** Load bundled lighting without changing render settings. Defaults to the original studio. */
+    loadEnvironmentPreset(id?: EnvironmentPresetId): Promise<void>;
     /** Format is inferred from file name or URL path; pass it explicitly for opaque URLs. */
     loadEnvironment(source: AssetSource, format?: EnvironmentFormat): Promise<void>;
     /** Fit the entire model and return the camera to the front. */

package/dist/index.js

@@ -4,6 +4,8 @@ import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
 import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
 import { DEFAULT_RENDER_CONFIG, resolveConfig } from './config.js';
+import { DEFAULT_ENVIRONMENT_PRESET, ENVIRONMENT_PRESETS } from './environments.js';
+export { DEFAULT_ENVIRONMENT_PRESET, ENVIRONMENT_PRESETS } from './environments.js';
 export { DEFAULT_RENDER_CONFIG } from './config.js';
 function disposeModel(root) {
     const geometries = new Set();
@@ -144,6 +146,14 @@ export class AvatarRenderer {
             asset.release();
         }
     }
+    /** Load bundled lighting without changing render settings. Defaults to the original studio. */
+    async loadEnvironmentPreset(id = DEFAULT_ENVIRONMENT_PRESET) {
+        this.assertActive();
+        const preset = ENVIRONMENT_PRESETS.find((entry) => entry.id === id);
+        if (!preset)
+            throw new TypeError(`Unknown environment preset: ${id}`);
+        await this.loadEnvironment(preset.url, 'hdr');
+    }
     /** Format is inferred from file name or URL path; pass it explicitly for opaque URLs. */
     async loadEnvironment(source, format) {
         this.assertActive();

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "@avatar-platform/avatar-render",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-independent GLB viewer with configurable HDR/EXR studio lighting",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
-  "files": ["dist", "README.md"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "assets",
+    "README.md"
+  ],
   "sideEffects": false,
   "publishConfig": {
     "access": "public",
@@ -18,7 +27,9 @@
     "test": "vitest run",
     "prepack": "pnpm build"
   },
-  "peerDependencies": { "three": "^0.180.0" },
+  "peerDependencies": {
+    "three": "^0.180.0"
+  },
   "devDependencies": {
     "three": "^0.180.0",
     "@types/three": "^0.180.0",