three-video-projection 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 屈航
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+⭐ 开源不易，点个Star支持下吧 ⭐
+
+---
+
+[英文](README_En.md)
+
+---
+
+# three-video-projector
+
+[![NPM Package][npm]][npm-url]
+
+基于 `three.js` 的视频投影工具。
+
+> 该工具将 `THREE.VideoTexture` 从一个投影相机投影到场景中的目标模型上，支持深度遮挡剔除、边缘羽化、强度与透明度控制等。
+
+---
+
+# 示例
+
+- [视频融合](https://hh-hang.github.io/three-video-projection/)
+
+- [电影院](https://hh-hang.github.io/three-video-projection/cinema.html)
+
+- ![视频融合](https://github.com/hh-hang/three-video-projection/blob/master/example/public/imgs/2.gif)
+
+- ![电影院](https://github.com/hh-hang/three-video-projection/blob/master/example/public/imgs/1.gif)
+
+---
+
+## 特性
+
+- 将视频纹理投影到场景中指定的模型（Mesh）。
+- 使用深度渲染目标进行遮挡剔除（保证投影不会穿透）。
+- 边缘羽化以获得柔和的投影边缘。
+- 可调整投影相机位置与姿态（方位角/俯仰/滚转）。
+- 监控视频-设置合适参数能做到与视频融合。
+
+---
+
+## 安装
+
+```bash
+npm install three-video-projection
+```
+
+---
+
+## 快速开始
+
+```ts
+import * as THREE from "three";
+import { createVideoProjector } from "./path/to/projector";
+
+// 创建video元素并生成 VideoTexture
+const video = document.createElement("video");
+video.src = "path/to/video.mp4";
+video.loop = true;
+video.muted = true;
+video.playsInline = true;
+await video.play();
+const videoTexture = new THREE.VideoTexture(video);
+
+// 注：可以使用视频流，只要保证最后成功创建videoTexture
+
+// 创建投影器
+const projector = await createVideoProjector({
+  scene, // three 场景
+  renderer, // three 渲染器
+  videoTexture, // 视频纹理
+  projCamPosition: [2, 2, 2], // 投影相机位置
+  projCamParams: { fov: 30, aspect: 1, near: 0.5, far: 50 }, // 投影相机参数
+  orientationParams: { azimuthDeg: 180, elevationDeg: -10, rollDeg: 0 }, // 方位角/俯仰/滚转
+  intensity: 1.0, // 投影颜色强度
+  opacity: 1.0, // 投影透明度
+  projBias: 0.0001, // 深度偏移
+  edgeFeather: 0.05, // 边缘羽化程度
+  isShowHelper: true, // 是否显示相机辅助器
+});
+
+// 将需要被投影的 mesh 加入
+projector.addTargetMesh(myMesh1);
+
+// 渲染循环
+function animate() {
+  // ... 更新场景、控制器
+  projector.update();
+}
+animate();
+
+// 销毁时
+projector.dispose();
+```
+
+---
+
+## API
+
+### createVideoProjector(opts: ProjectorToolOptions): Promise<ProjectorTool>
+
+#### ProjectorToolOptions
+
+- `scene: THREE.Scene` — three 场景（必需）。
+- `renderer: THREE.WebGLRenderer` — three 渲染器（必需）。
+- `videoTexture: THREE.VideoTexture` — 用于投影的视频纹理（必需）。
+- `projCamPosition?: [number, number, number]` — 投影相机在世界空间的位置。默认 `[0,0,0]`。
+- `projCamParams?: { fov?: number; aspect?: number; near?: number; far?: number }` — 投影相机参数。默认 `{ fov: 30, aspect: 1, near: 0.5, far: 50 }`。
+- `orientationParams?: { azimuthDeg?: number; elevationDeg?: number; rollDeg?: number }` — 方位角/俯仰/滚转（度）。默认均为 `0`。
+- `depthSize?: number` — 深度渲染目标分辨率（宽/高）。默认 `1024`。
+- `intensity?: number` — 投影颜色强度，默认 `1.0`。
+- `opacity?: number` — 全局透明度，默认 `1.0`。
+- `projBias?: number` — 深度偏移，默认 `0.0001`。
+- `edgeFeather?: number` — 边缘羽化宽度，默认 `0.05`。
+- `isShowHelper?: boolean` — 是否显示 `CameraHelper` 来可视化投影相机，默认 `true`。
+
+---
+
+#### ProjectorTool (返回对象)
+
+方法：
+
+- `addTargetMesh(mesh: THREE.Mesh): void` — 将目标网格加入投影列表。会在场景中创建一个 overlay（投影用）和 depth proxy（用于深度渲染）。
+- `removeTargetMesh(mesh: THREE.Mesh): void` — 从投影列表移除指定 mesh，并清理对应资源。
+- `update(): void` — 每帧调用以更新深度渲染目标、投影矩阵，并同步 overlay 的矩阵。
+- `dispose(): void` — 销毁内部资源并从场景中移除创建的对象。
+- `updateAzimuthDeg(deg: number): void` — 设置方位角（度）并应用到投影相机。
+- `updateElevationDeg(deg: number): void` — 设置俯仰角（度）。
+- `updateRollDeg(deg: number): void` — 设置滚转角（度）。
+- `updateOpacity(opacity: number): void` — 更新投影透明度（0~1）。
+
+属性：
+
+- `uniforms` — 暴露给外部的着色器 uniform 对象（包含 `projectorMap`、`projectorDepthMap`、`projectorMatrix`、`intensity`、`projBias`、`edgeFeather`、`opacity` 等）。
+- `overlays: THREE.Mesh[]` — 内部创建的 overlay 列表（投影用透明网格）。
+- `targetMeshes: THREE.Mesh[]` — 当前被投影的目标网格列表。
+- `projCam: THREE.PerspectiveCamera` — 用于投影的相机。
+- `camHelper: THREE.CameraHelper | null` — 可选的相机辅助器实例。
+- `orientationParams` — 当前的方位/俯仰/滚转角（度）。
+
+---
+
+[npm]: https://img.shields.io/npm/v/
+[npm-url]: https://www.npmjs.com/package/

package/dist/index.d.mts

@@ -0,0 +1,48 @@
+import * as THREE from 'three';
+
+type ProjectorToolOptions = {
+    scene: THREE.Scene;
+    renderer: THREE.WebGLRenderer;
+    videoTexture: THREE.VideoTexture;
+    projCamPosition?: [number, number, number];
+    projCamParams?: {
+        fov?: number;
+        aspect?: number;
+        near?: number;
+        far?: number;
+    };
+    orientationParams?: {
+        azimuthDeg?: number;
+        elevationDeg?: number;
+        rollDeg?: number;
+    };
+    depthSize?: number;
+    intensity?: number;
+    opacity?: number;
+    projBias?: number;
+    edgeFeather?: number;
+    isShowHelper?: boolean;
+};
+type ProjectorTool = {
+    addTargetMesh: (mesh: THREE.Mesh) => void;
+    removeTargetMesh: (mesh: THREE.Mesh) => void;
+    update: () => void;
+    dispose: () => void;
+    updateAzimuthDeg: (deg: number) => void;
+    updateElevationDeg: (deg: number) => void;
+    updateRollDeg: (deg: number) => void;
+    updateOpacity: (opacity: number) => void;
+    uniforms: any;
+    overlays: THREE.Mesh[];
+    targetMeshes: THREE.Mesh[];
+    projCam: THREE.PerspectiveCamera;
+    camHelper: THREE.CameraHelper | null;
+    orientationParams: {
+        azimuthDeg: number;
+        elevationDeg: number;
+        rollDeg: number;
+    };
+};
+declare function createVideoProjector(opts: ProjectorToolOptions): Promise<ProjectorTool>;
+
+export { type ProjectorTool, type ProjectorToolOptions, createVideoProjector };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import * as THREE from 'three';
+
+type ProjectorToolOptions = {
+    scene: THREE.Scene;
+    renderer: THREE.WebGLRenderer;
+    videoTexture: THREE.VideoTexture;
+    projCamPosition?: [number, number, number];
+    projCamParams?: {
+        fov?: number;
+        aspect?: number;
+        near?: number;
+        far?: number;
+    };
+    orientationParams?: {
+        azimuthDeg?: number;
+        elevationDeg?: number;
+        rollDeg?: number;
+    };
+    depthSize?: number;
+    intensity?: number;
+    opacity?: number;
+    projBias?: number;
+    edgeFeather?: number;
+    isShowHelper?: boolean;
+};
+type ProjectorTool = {
+    addTargetMesh: (mesh: THREE.Mesh) => void;
+    removeTargetMesh: (mesh: THREE.Mesh) => void;
+    update: () => void;
+    dispose: () => void;
+    updateAzimuthDeg: (deg: number) => void;
+    updateElevationDeg: (deg: number) => void;
+    updateRollDeg: (deg: number) => void;
+    updateOpacity: (opacity: number) => void;
+    uniforms: any;
+    overlays: THREE.Mesh[];
+    targetMeshes: THREE.Mesh[];
+    projCam: THREE.PerspectiveCamera;
+    camHelper: THREE.CameraHelper | null;
+    orientationParams: {
+        azimuthDeg: number;
+        elevationDeg: number;
+        rollDeg: number;
+    };
+};
+declare function createVideoProjector(opts: ProjectorToolOptions): Promise<ProjectorTool>;
+
+export { type ProjectorTool, type ProjectorToolOptions, createVideoProjector };

package/dist/index.js

@@ -0,0 +1,305 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createVideoProjector: () => createVideoProjector
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/three-video-projection.ts
+var THREE = __toESM(require("three"));
+async function createVideoProjector(opts) {
+  var _a, _b, _c, _d, _e, _f, _g;
+  const {
+    scene,
+    renderer,
+    videoTexture,
+    projCamPosition = [0, 0, 0],
+    projCamParams = { fov: 30, aspect: 1, near: 0.5, far: 50 },
+    orientationParams = { azimuthDeg: 0, elevationDeg: 0, rollDeg: 0 },
+    depthSize = 1024,
+    intensity = 1,
+    opacity = 1,
+    projBias = 1e-4,
+    edgeFeather = 0.05,
+    isShowHelper = true
+  } = opts;
+  let orientParams = {
+    azimuthDeg: (_a = orientationParams.azimuthDeg) != null ? _a : 0,
+    elevationDeg: (_b = orientationParams.elevationDeg) != null ? _b : 0,
+    rollDeg: (_c = orientationParams.rollDeg) != null ? _c : 0
+  };
+  let projCam;
+  let camHelper = null;
+  projCam = new THREE.PerspectiveCamera(
+    (_d = projCamParams.fov) != null ? _d : 30,
+    (_e = projCamParams.aspect) != null ? _e : 1,
+    (_f = projCamParams.near) != null ? _f : 0.5,
+    (_g = projCamParams.far) != null ? _g : 50
+  );
+  projCam.position.set(
+    projCamPosition[0],
+    projCamPosition[1],
+    projCamPosition[2]
+  );
+  projCam.lookAt(0, 0, 0);
+  scene.add(projCam);
+  applyOrientationFromAngles();
+  camHelper = new THREE.CameraHelper(projCam);
+  camHelper.name = "camHelper";
+  camHelper.visible = isShowHelper;
+  scene.add(camHelper);
+  videoTexture.minFilter = THREE.LinearFilter;
+  videoTexture.generateMipmaps = false;
+  const projectorUniforms = {
+    projectorMap: { value: videoTexture },
+    projectorMatrix: { value: new THREE.Matrix4() },
+    intensity: { value: intensity },
+    projectorDepthMap: { value: null },
+    projBias: { value: projBias },
+    edgeFeather: { value: edgeFeather },
+    opacity: { value: opacity }
+  };
+  const vertexShader = `
+        varying vec3 vWorldPos;
+        varying vec3 vWorldNormal;
+        void main() {
+            vec4 worldPos = modelMatrix * vec4(position, 1.0);
+            vWorldPos = worldPos.xyz;
+            vWorldNormal = normalize(mat3(modelMatrix) * normal);
+            gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+        }
+    `;
+  const fragmentShader = `
+      uniform sampler2D projectorMap;
+      uniform sampler2D projectorDepthMap;
+      uniform mat4 projectorMatrix;
+      uniform float intensity;
+      uniform float projBias;
+      uniform float edgeFeather;
+      uniform float opacity;
+      varying vec3 vWorldPos;
+      varying vec3 vWorldNormal;
+
+      void main() {
+        vec4 projPos = projectorMatrix * vec4(vWorldPos, 1.0);
+        if (projPos.w <= 0.0) discard;
+        vec2 uv = projPos.xy / projPos.w * 0.5 + 0.5;
+        if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) discard;
+        vec4 color = texture(projectorMap, uv);
+        
+        // \u906E\u6321\u5254\u9664
+        float projNDCz = projPos.z / projPos.w;
+        float projDepth01 = projNDCz * 0.5 + 0.5;
+        float sceneDepth01 = texture(projectorDepthMap, uv).x;
+        if (projDepth01 > sceneDepth01 + projBias) {
+          discard;
+        }
+
+        // \u8FB9\u7F18\u7FBD\u5316
+        vec2 adjUV = uv;
+        float minDist = min(min(adjUV.x, 1.0 - adjUV.x), min(adjUV.y, 1.0 - adjUV.y));
+        float edgeFactor = 1.0;
+        if (edgeFeather > 0.0) {
+            edgeFactor = smoothstep(0.0, edgeFeather, minDist);
+        }
+        float effectiveAlpha = color.a * edgeFactor;
+
+        // \u8F93\u51FA
+        vec3 outRGB = color.rgb * intensity * edgeFactor * opacity;
+        float outA = effectiveAlpha * opacity;
+        gl_FragColor = vec4(outRGB, outA);
+      }
+    `;
+  const projectorMat = new THREE.ShaderMaterial({
+    uniforms: projectorUniforms,
+    vertexShader,
+    fragmentShader,
+    transparent: true,
+    depthWrite: false,
+    depthTest: true,
+    side: THREE.FrontSide,
+    polygonOffset: true,
+    polygonOffsetFactor: -1,
+    polygonOffsetUnits: -4,
+    alphaTest: 0.02
+  });
+  const projectorDepthRT = new THREE.WebGLRenderTarget(depthSize, depthSize, {
+    minFilter: THREE.NearestFilter,
+    magFilter: THREE.NearestFilter,
+    stencilBuffer: false,
+    depthBuffer: true
+  });
+  projectorDepthRT.depthTexture = new THREE.DepthTexture(
+    depthSize,
+    depthSize,
+    THREE.UnsignedShortType
+  );
+  const depthScene = new THREE.Scene();
+  const depthMaterial = new THREE.MeshDepthMaterial();
+  depthMaterial.depthPacking = THREE.RGBADepthPacking;
+  depthMaterial.side = THREE.FrontSide;
+  const overlays = [];
+  const targetMeshes = [];
+  const depthProxies = [];
+  function makeProjectorOverlayAndProxy(mesh) {
+    const overlay = new THREE.Mesh(mesh.geometry, projectorMat);
+    overlay.matrixAutoUpdate = false;
+    overlay.renderOrder = (mesh.renderOrder || 0) + 1;
+    mesh.updateMatrixWorld(true);
+    overlay.matrix.copy(mesh.matrixWorld);
+    scene.add(overlay);
+    const proxy = new THREE.Mesh(mesh.geometry, depthMaterial);
+    proxy.matrixAutoUpdate = false;
+    depthScene.add(proxy);
+    overlays.push(overlay);
+    depthProxies.push(proxy);
+    return { overlay, proxy };
+  }
+  function addTargetMesh(mesh) {
+    if (targetMeshes.indexOf(mesh) !== -1) return;
+    mesh.castShadow = true;
+    mesh.receiveShadow = true;
+    targetMeshes.push(mesh);
+    makeProjectorOverlayAndProxy(mesh);
+  }
+  function removeTargetMesh(mesh) {
+    const idx = targetMeshes.indexOf(mesh);
+    if (idx === -1) return;
+    targetMeshes.splice(idx, 1);
+    const ov = overlays.splice(idx, 1)[0];
+    if (ov) scene.remove(ov);
+    const proxy = depthProxies.splice(idx, 1)[0];
+    if (proxy) depthScene.remove(proxy);
+  }
+  function update() {
+    for (let i = 0; i < targetMeshes.length; i++) {
+      const src = targetMeshes[i];
+      const proxy = depthProxies[i];
+      src.updateMatrixWorld(true);
+      proxy.matrix.copy(src.matrixWorld);
+    }
+    renderer.setRenderTarget(projectorDepthRT);
+    renderer.clear();
+    renderer.render(depthScene, projCam);
+    renderer.setRenderTarget(null);
+    projectorUniforms.projectorDepthMap.value = projectorDepthRT.depthTexture;
+    const projectorMatrix = new THREE.Matrix4();
+    projectorMatrix.multiplyMatrices(
+      projCam.projectionMatrix,
+      projCam.matrixWorldInverse
+    );
+    projectorUniforms.projectorMatrix.value.copy(projectorMatrix);
+    for (let i = 0; i < targetMeshes.length; i++) {
+      const src = targetMeshes[i];
+      const overlay = overlays[i];
+      src.updateMatrixWorld(true);
+      overlay.matrix.copy(src.matrixWorld);
+    }
+  }
+  function dispose() {
+    for (let ov of overlays) scene.remove(ov);
+    for (let p of depthProxies) depthScene.remove(p);
+    overlays.length = 0;
+    depthProxies.length = 0;
+    targetMeshes.length = 0;
+    projectorMat.dispose();
+    depthMaterial.dispose();
+    try {
+      projectorDepthRT.dispose();
+    } catch (e) {
+    }
+    try {
+      videoTexture.dispose();
+    } catch (e) {
+    }
+    if (camHelper) {
+      try {
+        scene.remove(camHelper);
+      } catch (e) {
+      }
+      camHelper = null;
+    }
+  }
+  function updateAzimuthDeg(deg) {
+    orientParams.azimuthDeg = deg;
+    applyOrientationFromAngles();
+  }
+  function updateElevationDeg(deg) {
+    orientParams.elevationDeg = deg;
+    applyOrientationFromAngles();
+  }
+  function updateRollDeg(deg) {
+    orientParams.rollDeg = deg;
+    applyOrientationFromAngles();
+  }
+  function applyOrientationFromAngles() {
+    const az = THREE.MathUtils.degToRad(orientParams.azimuthDeg);
+    const el = THREE.MathUtils.degToRad(orientParams.elevationDeg);
+    const dir = new THREE.Vector3(
+      Math.cos(el) * Math.cos(az),
+      Math.sin(el),
+      Math.cos(el) * Math.sin(az)
+    ).normalize();
+    const lookTarget = new THREE.Vector3().copy(projCam.position).add(dir);
+    projCam.up.set(0, 1, 0);
+    projCam.lookAt(lookTarget);
+    projCam.updateMatrixWorld(true);
+    const rollRad = THREE.MathUtils.degToRad(orientParams.rollDeg);
+    projCam.rotateOnAxis(new THREE.Vector3(0, 0, 1), rollRad);
+    projCam.updateMatrixWorld(true);
+    if (camHelper) camHelper.update();
+  }
+  function updateOpacity(v) {
+    const clamped = Math.max(0, Math.min(1, v));
+    projectorUniforms.opacity.value = clamped;
+  }
+  return {
+    addTargetMesh,
+    removeTargetMesh,
+    update,
+    dispose,
+    updateAzimuthDeg,
+    updateElevationDeg,
+    updateRollDeg,
+    updateOpacity,
+    uniforms: projectorUniforms,
+    overlays,
+    targetMeshes,
+    projCam,
+    camHelper,
+    orientationParams: orientParams
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createVideoProjector
+});

package/dist/index.mjs

@@ -0,0 +1,268 @@
+// src/three-video-projection.ts
+import * as THREE from "three";
+async function createVideoProjector(opts) {
+  var _a, _b, _c, _d, _e, _f, _g;
+  const {
+    scene,
+    renderer,
+    videoTexture,
+    projCamPosition = [0, 0, 0],
+    projCamParams = { fov: 30, aspect: 1, near: 0.5, far: 50 },
+    orientationParams = { azimuthDeg: 0, elevationDeg: 0, rollDeg: 0 },
+    depthSize = 1024,
+    intensity = 1,
+    opacity = 1,
+    projBias = 1e-4,
+    edgeFeather = 0.05,
+    isShowHelper = true
+  } = opts;
+  let orientParams = {
+    azimuthDeg: (_a = orientationParams.azimuthDeg) != null ? _a : 0,
+    elevationDeg: (_b = orientationParams.elevationDeg) != null ? _b : 0,
+    rollDeg: (_c = orientationParams.rollDeg) != null ? _c : 0
+  };
+  let projCam;
+  let camHelper = null;
+  projCam = new THREE.PerspectiveCamera(
+    (_d = projCamParams.fov) != null ? _d : 30,
+    (_e = projCamParams.aspect) != null ? _e : 1,
+    (_f = projCamParams.near) != null ? _f : 0.5,
+    (_g = projCamParams.far) != null ? _g : 50
+  );
+  projCam.position.set(
+    projCamPosition[0],
+    projCamPosition[1],
+    projCamPosition[2]
+  );
+  projCam.lookAt(0, 0, 0);
+  scene.add(projCam);
+  applyOrientationFromAngles();
+  camHelper = new THREE.CameraHelper(projCam);
+  camHelper.name = "camHelper";
+  camHelper.visible = isShowHelper;
+  scene.add(camHelper);
+  videoTexture.minFilter = THREE.LinearFilter;
+  videoTexture.generateMipmaps = false;
+  const projectorUniforms = {
+    projectorMap: { value: videoTexture },
+    projectorMatrix: { value: new THREE.Matrix4() },
+    intensity: { value: intensity },
+    projectorDepthMap: { value: null },
+    projBias: { value: projBias },
+    edgeFeather: { value: edgeFeather },
+    opacity: { value: opacity }
+  };
+  const vertexShader = `
+        varying vec3 vWorldPos;
+        varying vec3 vWorldNormal;
+        void main() {
+            vec4 worldPos = modelMatrix * vec4(position, 1.0);
+            vWorldPos = worldPos.xyz;
+            vWorldNormal = normalize(mat3(modelMatrix) * normal);
+            gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+        }
+    `;
+  const fragmentShader = `
+      uniform sampler2D projectorMap;
+      uniform sampler2D projectorDepthMap;
+      uniform mat4 projectorMatrix;
+      uniform float intensity;
+      uniform float projBias;
+      uniform float edgeFeather;
+      uniform float opacity;
+      varying vec3 vWorldPos;
+      varying vec3 vWorldNormal;
+
+      void main() {
+        vec4 projPos = projectorMatrix * vec4(vWorldPos, 1.0);
+        if (projPos.w <= 0.0) discard;
+        vec2 uv = projPos.xy / projPos.w * 0.5 + 0.5;
+        if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) discard;
+        vec4 color = texture(projectorMap, uv);
+        
+        // \u906E\u6321\u5254\u9664
+        float projNDCz = projPos.z / projPos.w;
+        float projDepth01 = projNDCz * 0.5 + 0.5;
+        float sceneDepth01 = texture(projectorDepthMap, uv).x;
+        if (projDepth01 > sceneDepth01 + projBias) {
+          discard;
+        }
+
+        // \u8FB9\u7F18\u7FBD\u5316
+        vec2 adjUV = uv;
+        float minDist = min(min(adjUV.x, 1.0 - adjUV.x), min(adjUV.y, 1.0 - adjUV.y));
+        float edgeFactor = 1.0;
+        if (edgeFeather > 0.0) {
+            edgeFactor = smoothstep(0.0, edgeFeather, minDist);
+        }
+        float effectiveAlpha = color.a * edgeFactor;
+
+        // \u8F93\u51FA
+        vec3 outRGB = color.rgb * intensity * edgeFactor * opacity;
+        float outA = effectiveAlpha * opacity;
+        gl_FragColor = vec4(outRGB, outA);
+      }
+    `;
+  const projectorMat = new THREE.ShaderMaterial({
+    uniforms: projectorUniforms,
+    vertexShader,
+    fragmentShader,
+    transparent: true,
+    depthWrite: false,
+    depthTest: true,
+    side: THREE.FrontSide,
+    polygonOffset: true,
+    polygonOffsetFactor: -1,
+    polygonOffsetUnits: -4,
+    alphaTest: 0.02
+  });
+  const projectorDepthRT = new THREE.WebGLRenderTarget(depthSize, depthSize, {
+    minFilter: THREE.NearestFilter,
+    magFilter: THREE.NearestFilter,
+    stencilBuffer: false,
+    depthBuffer: true
+  });
+  projectorDepthRT.depthTexture = new THREE.DepthTexture(
+    depthSize,
+    depthSize,
+    THREE.UnsignedShortType
+  );
+  const depthScene = new THREE.Scene();
+  const depthMaterial = new THREE.MeshDepthMaterial();
+  depthMaterial.depthPacking = THREE.RGBADepthPacking;
+  depthMaterial.side = THREE.FrontSide;
+  const overlays = [];
+  const targetMeshes = [];
+  const depthProxies = [];
+  function makeProjectorOverlayAndProxy(mesh) {
+    const overlay = new THREE.Mesh(mesh.geometry, projectorMat);
+    overlay.matrixAutoUpdate = false;
+    overlay.renderOrder = (mesh.renderOrder || 0) + 1;
+    mesh.updateMatrixWorld(true);
+    overlay.matrix.copy(mesh.matrixWorld);
+    scene.add(overlay);
+    const proxy = new THREE.Mesh(mesh.geometry, depthMaterial);
+    proxy.matrixAutoUpdate = false;
+    depthScene.add(proxy);
+    overlays.push(overlay);
+    depthProxies.push(proxy);
+    return { overlay, proxy };
+  }
+  function addTargetMesh(mesh) {
+    if (targetMeshes.indexOf(mesh) !== -1) return;
+    mesh.castShadow = true;
+    mesh.receiveShadow = true;
+    targetMeshes.push(mesh);
+    makeProjectorOverlayAndProxy(mesh);
+  }
+  function removeTargetMesh(mesh) {
+    const idx = targetMeshes.indexOf(mesh);
+    if (idx === -1) return;
+    targetMeshes.splice(idx, 1);
+    const ov = overlays.splice(idx, 1)[0];
+    if (ov) scene.remove(ov);
+    const proxy = depthProxies.splice(idx, 1)[0];
+    if (proxy) depthScene.remove(proxy);
+  }
+  function update() {
+    for (let i = 0; i < targetMeshes.length; i++) {
+      const src = targetMeshes[i];
+      const proxy = depthProxies[i];
+      src.updateMatrixWorld(true);
+      proxy.matrix.copy(src.matrixWorld);
+    }
+    renderer.setRenderTarget(projectorDepthRT);
+    renderer.clear();
+    renderer.render(depthScene, projCam);
+    renderer.setRenderTarget(null);
+    projectorUniforms.projectorDepthMap.value = projectorDepthRT.depthTexture;
+    const projectorMatrix = new THREE.Matrix4();
+    projectorMatrix.multiplyMatrices(
+      projCam.projectionMatrix,
+      projCam.matrixWorldInverse
+    );
+    projectorUniforms.projectorMatrix.value.copy(projectorMatrix);
+    for (let i = 0; i < targetMeshes.length; i++) {
+      const src = targetMeshes[i];
+      const overlay = overlays[i];
+      src.updateMatrixWorld(true);
+      overlay.matrix.copy(src.matrixWorld);
+    }
+  }
+  function dispose() {
+    for (let ov of overlays) scene.remove(ov);
+    for (let p of depthProxies) depthScene.remove(p);
+    overlays.length = 0;
+    depthProxies.length = 0;
+    targetMeshes.length = 0;
+    projectorMat.dispose();
+    depthMaterial.dispose();
+    try {
+      projectorDepthRT.dispose();
+    } catch (e) {
+    }
+    try {
+      videoTexture.dispose();
+    } catch (e) {
+    }
+    if (camHelper) {
+      try {
+        scene.remove(camHelper);
+      } catch (e) {
+      }
+      camHelper = null;
+    }
+  }
+  function updateAzimuthDeg(deg) {
+    orientParams.azimuthDeg = deg;
+    applyOrientationFromAngles();
+  }
+  function updateElevationDeg(deg) {
+    orientParams.elevationDeg = deg;
+    applyOrientationFromAngles();
+  }
+  function updateRollDeg(deg) {
+    orientParams.rollDeg = deg;
+    applyOrientationFromAngles();
+  }
+  function applyOrientationFromAngles() {
+    const az = THREE.MathUtils.degToRad(orientParams.azimuthDeg);
+    const el = THREE.MathUtils.degToRad(orientParams.elevationDeg);
+    const dir = new THREE.Vector3(
+      Math.cos(el) * Math.cos(az),
+      Math.sin(el),
+      Math.cos(el) * Math.sin(az)
+    ).normalize();
+    const lookTarget = new THREE.Vector3().copy(projCam.position).add(dir);
+    projCam.up.set(0, 1, 0);
+    projCam.lookAt(lookTarget);
+    projCam.updateMatrixWorld(true);
+    const rollRad = THREE.MathUtils.degToRad(orientParams.rollDeg);
+    projCam.rotateOnAxis(new THREE.Vector3(0, 0, 1), rollRad);
+    projCam.updateMatrixWorld(true);
+    if (camHelper) camHelper.update();
+  }
+  function updateOpacity(v) {
+    const clamped = Math.max(0, Math.min(1, v));
+    projectorUniforms.opacity.value = clamped;
+  }
+  return {
+    addTargetMesh,
+    removeTargetMesh,
+    update,
+    dispose,
+    updateAzimuthDeg,
+    updateElevationDeg,
+    updateRollDeg,
+    updateOpacity,
+    uniforms: projectorUniforms,
+    overlays,
+    targetMeshes,
+    projCam,
+    camHelper,
+    orientationParams: orientParams
+  };
+}
+export {
+  createVideoProjector
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "three-video-projection",
+  "version": "0.0.1",
+  "description": "Projector utility for projecting video textures onto meshes (three.js)",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/<your-org>/<repo>.git"
+  },
+  "keywords": [
+    "three",
+    "videoProjection",
+    "videoFusion"
+  ],
+  "author": "hh-hang",
+  "license": "MIT",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "prepare": "npm run build",
+    "build:cinema": "npm --prefix ./examples/cinema install && npm --prefix ./examples/cinema run build",
+    "build:monitor": "npm --prefix ./examples/monitor install && npm --prefix ./examples/monitor run build",
+    "collect": "node ./scripts/collect.js",
+    "build:examples": "npm run build:cinema && npm run build:monitor && npm run collect"
+  },
+  "peerDependencies": {
+    "three": "^0.182.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "@types/three": "^0.182.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@vitejs/plugin-vue": "^6.0.3",
+    "hls.js": "^1.6.15",
+    "path": "^0.12.7",
+    "stats.js": "^0.17.0",
+    "three-player-controller": "^0.2.52",
+    "vite": "^7.3.1",
+    "vue": "^3.5.27",
+    "vue-router": "^4.6.4"
+  }
+}