three-video-projection 0.0.8 → 0.1.0

package/README.md

@@ -37,12 +37,6 @@ git clone https://github.com/hh-hang/three-video-projection.git
 # 安装依赖
 npm install
 
-# 进入示例目录
-cd example
-
-# 安装示例依赖
-npm install
-
 # 运行开发服务器
 npm run dev
 ```
@@ -88,6 +82,8 @@ const projector = await createVideoProjector({
   opacity: 1.0, // 投影透明度
   projBias: 0.0001, // 深度偏移
   edgeFeather: 0.05, // 边缘羽化程度
+  cropRect: [0, 0, 1, 1], // 裁剪区域（UV空间，[x0, y0, x1, y1]，范围 0~1）
+  quadCorners: [[0, 0], [1, 0], [1, 1], [0, 1]], // 四角点变换（投影UV空间，顺序：左下、右下、右上、左上）
   isShowHelper: true, // 是否显示相机辅助器
 });
 
@@ -126,6 +122,8 @@ projector.dispose();
 - `opacity?: number` — 全局透明度，默认 `1.0`。
 - `projBias?: number` — 深度偏移，默认 `0.0001`。
 - `edgeFeather?: number` — 边缘羽化宽度，默认 `0.05`。
+- `cropRect?: [number, number, number, number]` — 视频纹理裁剪区域，UV 空间 `[x0, y0, x1, y1]`，范围 `0~1`。默认 `[0, 0, 1, 1]`（不裁剪）。
+- `quadCorners?: [[number, number], [number, number], [number, number], [number, number]]` — 四角点变换，在投影 UV 空间中指定四角坐标（顺序：左下、右下、右上、左上），用于梯形/透视校正。默认为单位正方形。
 - `isShowHelper?: boolean` — 是否显示 `CameraHelper` 来可视化投影相机，默认 `true`。
 
 ---
@@ -142,10 +140,12 @@ projector.dispose();
 - `updateElevationDeg(deg: number): void` — 设置俯仰角（度）。
 - `updateRollDeg(deg: number): void` — 设置滚转角（度）。
 - `updateOpacity(opacity: number): void` — 更新投影透明度（0~1）。
+- `updateCropRect(rect: [number, number, number, number]): void` — 动态更新裁剪区域（UV 空间，`[x0, y0, x1, y1]`）。
+- `updateQuadCorners(corners: [[number, number], [number, number], [number, number], [number, number]]): void` — 动态更新四角点变换（投影 UV 空间，顺序：左下、右下、右上、左上）。
 
 属性：
 
-- `uniforms` — 暴露给外部的着色器 uniform 对象（包含 `projectorMap`、`projectorDepthMap`、`projectorMatrix`、`intensity`、`projBias`、`edgeFeather`、`opacity` 等）。
+- `uniforms` — 暴露给外部的着色器 uniform 对象（包含 `projectorMap`、`projectorDepthMap`、`projectorMatrix`、`intensity`、`projBias`、`edgeFeather`、`opacity`、`cropRect`、`quadHomography` 等）。
 - `overlays: THREE.Mesh[]` — 内部创建的 overlay 列表（投影用透明网格）。
 - `targetMeshes: THREE.Mesh[]` — 当前被投影的目标网格列表。
 - `projCam: THREE.PerspectiveCamera` — 用于投影的相机。

package/dist/index.d.mts

@@ -21,6 +21,8 @@ type ProjectorToolOptions = {
     opacity?: number;
     projBias?: number;
     edgeFeather?: number;
+    cropRect?: [number, number, number, number];
+    quadCorners?: [[number, number], [number, number], [number, number], [number, number]];
     isShowHelper?: boolean;
 };
 type ProjectorTool = {
@@ -32,6 +34,8 @@ type ProjectorTool = {
     updateElevationDeg: (deg: number) => void;
     updateRollDeg: (deg: number) => void;
     updateOpacity: (opacity: number) => void;
+    updateCropRect: (rect: [number, number, number, number]) => void;
+    updateQuadCorners: (corners: [[number, number], [number, number], [number, number], [number, number]]) => void;
     uniforms: any;
     overlays: THREE.Mesh[];
     targetMeshes: THREE.Mesh[];

package/dist/index.d.ts

@@ -21,6 +21,8 @@ type ProjectorToolOptions = {
     opacity?: number;
     projBias?: number;
     edgeFeather?: number;
+    cropRect?: [number, number, number, number];
+    quadCorners?: [[number, number], [number, number], [number, number], [number, number]];
     isShowHelper?: boolean;
 };
 type ProjectorTool = {
@@ -32,6 +34,8 @@ type ProjectorTool = {
     updateElevationDeg: (deg: number) => void;
     updateRollDeg: (deg: number) => void;
     updateOpacity: (opacity: number) => void;
+    updateCropRect: (rect: [number, number, number, number]) => void;
+    updateQuadCorners: (corners: [[number, number], [number, number], [number, number], [number, number]]) => void;
     uniforms: any;
     overlays: THREE.Mesh[];
     targetMeshes: THREE.Mesh[];

package/dist/index.js

@@ -1,4 +1,3 @@
-"use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -36,8 +35,33 @@ module.exports = __toCommonJS(index_exports);
 
 // src/three-video-projection.ts
 var THREE = __toESM(require("three"));
+function computeQuadHomography(corners) {
+  const [[x0, y0], [x1, y1], [x2, y2], [x3, y3]] = corners;
+  const dx1 = x1 - x2, dy1 = y1 - y2;
+  const dx2 = x3 - x2, dy2 = y3 - y2;
+  const dx3 = x0 - x1 + x2 - x3, dy3 = y0 - y1 + y2 - y3;
+  const den = dx1 * dy2 - dx2 * dy1;
+  const pg = (dx3 * dy2 - dx2 * dy3) / den;
+  const ph = (dx1 * dy3 - dx3 * dy1) / den;
+  const m00 = x1 - x0 + pg * x1, m01 = x3 - x0 + ph * x3, m02 = x0;
+  const m10 = y1 - y0 + pg * y1, m11 = y3 - y0 + ph * y3, m12 = y0;
+  const m20 = pg, m21 = ph, m22 = 1;
+  const det = m00 * (m11 * m22 - m12 * m21) - m01 * (m10 * m22 - m12 * m20) + m02 * (m10 * m21 - m11 * m20);
+  const inv = new THREE.Matrix3();
+  inv.set(
+    (m11 * m22 - m12 * m21) / det,
+    -(m01 * m22 - m02 * m21) / det,
+    (m01 * m12 - m02 * m11) / det,
+    -(m10 * m22 - m12 * m20) / det,
+    (m00 * m22 - m02 * m20) / det,
+    -(m00 * m12 - m02 * m10) / det,
+    (m10 * m21 - m11 * m20) / det,
+    -(m00 * m21 - m01 * m20) / det,
+    (m00 * m11 - m01 * m10) / det
+  );
+  return inv;
+}
 async function createVideoProjector(opts) {
-  var _a, _b, _c, _d, _e, _f, _g;
   const {
     scene,
     renderer,
@@ -50,20 +74,22 @@ async function createVideoProjector(opts) {
     opacity = 1,
     projBias = 1e-4,
     edgeFeather = 0.05,
+    cropRect = [0, 0, 1, 1],
+    quadCorners = [[0, 0], [1, 0], [1, 1], [0, 1]],
     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
+    azimuthDeg: orientationParams.azimuthDeg ?? 0,
+    elevationDeg: orientationParams.elevationDeg ?? 0,
+    rollDeg: orientationParams.rollDeg ?? 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
+    projCamParams.fov ?? 30,
+    projCamParams.aspect ?? 1,
+    projCamParams.near ?? 0.5,
+    projCamParams.far ?? 50
   );
   projCam.position.set(
     projCamPosition[0],
@@ -86,7 +112,9 @@ async function createVideoProjector(opts) {
     projectorDepthMap: { value: null },
     projBias: { value: projBias },
     edgeFeather: { value: edgeFeather },
-    opacity: { value: opacity }
+    opacity: { value: opacity },
+    cropRect: { value: new THREE.Vector4(cropRect[0], cropRect[1], cropRect[2], cropRect[3]) },
+    quadHomography: { value: computeQuadHomography(quadCorners) }
   };
   const vertexShader = `
         varying vec3 vWorldPos;
@@ -106,6 +134,8 @@ async function createVideoProjector(opts) {
       uniform float projBias;
       uniform float edgeFeather;
       uniform float opacity;
+      uniform vec4 cropRect;
+      uniform mat3 quadHomography;
       varying vec3 vWorldPos;
       varying vec3 vWorldNormal;
 
@@ -114,8 +144,7 @@ async function createVideoProjector(opts) {
         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;
@@ -124,13 +153,22 @@ async function createVideoProjector(opts) {
           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));
+        // \u56DB\u89D2\u70B9\u53D8\u6362\uFF08\u6295\u5F71UV \u2192 \u89C6\u9891\u7EB9\u7406UV\uFF09
+        vec3 hw = quadHomography * vec3(uv, 1.0);
+        vec2 warpedUV = hw.xy / hw.z;
+
+        // \u81EA\u5B9A\u4E49\u88C1\u526A\u53CA\u7FBD\u5316
+        vec2 cropMin = cropRect.xy;
+        vec2 cropMax = cropRect.zw;
+        if (warpedUV.x < cropMin.x || warpedUV.x > cropMax.x || warpedUV.y < cropMin.y || warpedUV.y > cropMax.y) discard;
+        float distX = min(warpedUV.x - cropMin.x, cropMax.x - warpedUV.x);
+        float distY = min(warpedUV.y - cropMin.y, cropMax.y - warpedUV.y);
+        float minDist = min(distX, distY);
         float edgeFactor = 1.0;
         if (edgeFeather > 0.0) {
             edgeFactor = smoothstep(0.0, edgeFeather, minDist);
         }
+        vec4 color = texture(projectorMap, warpedUV);
         float effectiveAlpha = color.a * edgeFactor;
 
         // \u8F93\u51FA
@@ -283,6 +321,12 @@ async function createVideoProjector(opts) {
     const clamped = Math.max(0, Math.min(1, v));
     projectorUniforms.opacity.value = clamped;
   }
+  function updateCropRect(rect) {
+    projectorUniforms.cropRect.value.set(rect[0], rect[1], rect[2], rect[3]);
+  }
+  function updateQuadCorners(corners) {
+    projectorUniforms.quadHomography.value.copy(computeQuadHomography(corners));
+  }
   return {
     addTargetMesh,
     removeTargetMesh,
@@ -292,6 +336,8 @@ async function createVideoProjector(opts) {
     updateElevationDeg,
     updateRollDeg,
     updateOpacity,
+    updateCropRect,
+    updateQuadCorners,
     uniforms: projectorUniforms,
     overlays,
     targetMeshes,
@@ -300,7 +346,3 @@ async function createVideoProjector(opts) {
     orientationParams: orientParams
   };
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  createVideoProjector
-});

package/dist/index.mjs

@@ -1,7 +1,32 @@
 // src/three-video-projection.ts
 import * as THREE from "three";
+function computeQuadHomography(corners) {
+  const [[x0, y0], [x1, y1], [x2, y2], [x3, y3]] = corners;
+  const dx1 = x1 - x2, dy1 = y1 - y2;
+  const dx2 = x3 - x2, dy2 = y3 - y2;
+  const dx3 = x0 - x1 + x2 - x3, dy3 = y0 - y1 + y2 - y3;
+  const den = dx1 * dy2 - dx2 * dy1;
+  const pg = (dx3 * dy2 - dx2 * dy3) / den;
+  const ph = (dx1 * dy3 - dx3 * dy1) / den;
+  const m00 = x1 - x0 + pg * x1, m01 = x3 - x0 + ph * x3, m02 = x0;
+  const m10 = y1 - y0 + pg * y1, m11 = y3 - y0 + ph * y3, m12 = y0;
+  const m20 = pg, m21 = ph, m22 = 1;
+  const det = m00 * (m11 * m22 - m12 * m21) - m01 * (m10 * m22 - m12 * m20) + m02 * (m10 * m21 - m11 * m20);
+  const inv = new THREE.Matrix3();
+  inv.set(
+    (m11 * m22 - m12 * m21) / det,
+    -(m01 * m22 - m02 * m21) / det,
+    (m01 * m12 - m02 * m11) / det,
+    -(m10 * m22 - m12 * m20) / det,
+    (m00 * m22 - m02 * m20) / det,
+    -(m00 * m12 - m02 * m10) / det,
+    (m10 * m21 - m11 * m20) / det,
+    -(m00 * m21 - m01 * m20) / det,
+    (m00 * m11 - m01 * m10) / det
+  );
+  return inv;
+}
 async function createVideoProjector(opts) {
-  var _a, _b, _c, _d, _e, _f, _g;
   const {
     scene,
     renderer,
@@ -14,20 +39,22 @@ async function createVideoProjector(opts) {
     opacity = 1,
     projBias = 1e-4,
     edgeFeather = 0.05,
+    cropRect = [0, 0, 1, 1],
+    quadCorners = [[0, 0], [1, 0], [1, 1], [0, 1]],
     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
+    azimuthDeg: orientationParams.azimuthDeg ?? 0,
+    elevationDeg: orientationParams.elevationDeg ?? 0,
+    rollDeg: orientationParams.rollDeg ?? 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
+    projCamParams.fov ?? 30,
+    projCamParams.aspect ?? 1,
+    projCamParams.near ?? 0.5,
+    projCamParams.far ?? 50
   );
   projCam.position.set(
     projCamPosition[0],
@@ -50,7 +77,9 @@ async function createVideoProjector(opts) {
     projectorDepthMap: { value: null },
     projBias: { value: projBias },
     edgeFeather: { value: edgeFeather },
-    opacity: { value: opacity }
+    opacity: { value: opacity },
+    cropRect: { value: new THREE.Vector4(cropRect[0], cropRect[1], cropRect[2], cropRect[3]) },
+    quadHomography: { value: computeQuadHomography(quadCorners) }
   };
   const vertexShader = `
         varying vec3 vWorldPos;
@@ -70,6 +99,8 @@ async function createVideoProjector(opts) {
       uniform float projBias;
       uniform float edgeFeather;
       uniform float opacity;
+      uniform vec4 cropRect;
+      uniform mat3 quadHomography;
       varying vec3 vWorldPos;
       varying vec3 vWorldNormal;
 
@@ -78,8 +109,7 @@ async function createVideoProjector(opts) {
         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;
@@ -88,13 +118,22 @@ async function createVideoProjector(opts) {
           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));
+        // \u56DB\u89D2\u70B9\u53D8\u6362\uFF08\u6295\u5F71UV \u2192 \u89C6\u9891\u7EB9\u7406UV\uFF09
+        vec3 hw = quadHomography * vec3(uv, 1.0);
+        vec2 warpedUV = hw.xy / hw.z;
+
+        // \u81EA\u5B9A\u4E49\u88C1\u526A\u53CA\u7FBD\u5316
+        vec2 cropMin = cropRect.xy;
+        vec2 cropMax = cropRect.zw;
+        if (warpedUV.x < cropMin.x || warpedUV.x > cropMax.x || warpedUV.y < cropMin.y || warpedUV.y > cropMax.y) discard;
+        float distX = min(warpedUV.x - cropMin.x, cropMax.x - warpedUV.x);
+        float distY = min(warpedUV.y - cropMin.y, cropMax.y - warpedUV.y);
+        float minDist = min(distX, distY);
         float edgeFactor = 1.0;
         if (edgeFeather > 0.0) {
             edgeFactor = smoothstep(0.0, edgeFeather, minDist);
         }
+        vec4 color = texture(projectorMap, warpedUV);
         float effectiveAlpha = color.a * edgeFactor;
 
         // \u8F93\u51FA
@@ -247,6 +286,12 @@ async function createVideoProjector(opts) {
     const clamped = Math.max(0, Math.min(1, v));
     projectorUniforms.opacity.value = clamped;
   }
+  function updateCropRect(rect) {
+    projectorUniforms.cropRect.value.set(rect[0], rect[1], rect[2], rect[3]);
+  }
+  function updateQuadCorners(corners) {
+    projectorUniforms.quadHomography.value.copy(computeQuadHomography(corners));
+  }
   return {
     addTargetMesh,
     removeTargetMesh,
@@ -256,6 +301,8 @@ async function createVideoProjector(opts) {
     updateElevationDeg,
     updateRollDeg,
     updateOpacity,
+    updateCropRect,
+    updateQuadCorners,
     uniforms: projectorUniforms,
     overlays,
     targetMeshes,

package/package.json

@@ -1,54 +1,52 @@
-{
-  "name": "three-video-projection",
-  "version": "0.0.8",
-  "description": "Projector utility for projecting video textures onto meshes (three.js)",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "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",
-    "@vitejs/plugin-vue": "^6.0.3",
-    "tsup": "^8.5.1",
-    "typescript": "^5.0.0",
-    "vite": "^7.3.1",
-    "vue": "^3.5.27",
-    "hls.js": "^1.6.15",
-    "stats.js": "^0.17.0",
-    "three-player-controller": "^0.3.1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/hh-hang/three-video-projection"
-  },
-  "homepage": "https://hh-hang.github.io/three-video-projection/"
-}
+{
+  "name": "three-video-projection",
+  "version": "0.1.0",
+  "description": "Projector utility for projecting video textures onto meshes (three.js)",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "three",
+    "videoProjection",
+    "videoFusion"
+  ],
+  "author": "hh-hang",
+  "license": "MIT",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsup",
+    "prepare": "npm run build",
+    "build:example": "vite build"
+  },
+  "peerDependencies": {
+    "three": "^0.182.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "@types/three": "^0.182.0",
+    "@vitejs/plugin-vue": "^6.0.3",
+    "hls.js": "^1.6.15",
+    "sass-embedded": "^1.98.0",
+    "stats.js": "^0.17.0",
+    "three-player-controller": "^0.3.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.0.0",
+    "vite": "^7.3.1",
+    "vue": "^3.5.27"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hh-hang/three-video-projection"
+  },
+  "homepage": "https://hh-hang.github.io/three-video-projection/"
+}