开源了一个轻量级 Web 3D 模型检视 SDK：免后端纯前端解压 ZIP/OBJ，带工程测量与截面剖切

在线 Demo 体验 ：https://giszhc.github.io/three-model-viewer/

GitHub 仓库 ：https://github.com/giszhc/three-model-viewer

NPM 地址 ：npm i @giszhc/three-model-viewer

一、做这个库的背景

在工业制造、3D 打印、数模展示或者 BIM 场景下，把 3D 模型搬到网页端经常遇到几个很恶心的问题：

资源零散 ：美术或工程导出的都是 .obj + .mtl + 一堆 .png/.jpg 贴图。传统做法是要么后台搭个服务转成 .gltf，要么让用户一个个文件选择。
缺少轻量级工业工具：Three.js 官方只提供了基础 Loader 和场景，测距、测高程差、测角度、测多边形面积、截面剖切、动态包围盒尺寸这些功能，每次写新项目都得从头造一遍轮子。
点选精度与视距畸变：射线检测经常点偏，缺少顶点磁吸；放大缩小视角时，标点和尺寸标签跟着放大缩小，遮挡模型。

为了彻底解决这些痛点，我把这套业务层代码抽离并开源成了一个独立的 SDK ------ @giszhc/three-model-viewer。

二、核心能力一览

📦 纯前端解压加载 ZIP ：用户直接丢一个 .zip 压缩包（内含 obj、mtl 及多张贴图），浏览器纯内存利用 JSZip 解压并自动关联贴图路径，不需要任何后端转换服务。
🔗 支持网络直链与本地双模式 ：不仅支持本地文件拖拽/选择，也支持直接传入远程直链（.zip 或 .obj）。
🎯 带顶点磁吸的表面测量 ：
- 基于 three-mesh-bvh 空间加速索引，鼠标靠近网格顶点时毫秒级磁吸；
- 测量交互严格限制在模型表面，点到模型外部空白区域自动拦截；
- 表面标点与文字标签使用屏幕空间像素恒定渲染，不管怎么缩放模型，标签大小不变、不畸变。
📐 全套工业测量工具 ：
- 空间距离：两点测距 + 三维浮动尺寸标签；
- 标高高度：计算高程差 ΔH 与水平投影跨度，生成 CAD 标高引线；
- 空间角度：三点绘制空间夹角，动态弧线扇形标注；
- 表面多边形面积：多点连线，自动三角剖分计算表面积并填充半透明面。
📏 自适应三向包围盒：旋转模型时，长宽高尺寸线与数值在空间中自动自适应最佳可视角度。
✂️ 双向剖切系统：支持 XYZ 三轴滑动剖切，以及模型表面任意 2 点视线利落截切。
🌐 双通道分发 ：支持现代化工程项目的 npm/pnpm/yarn 安装，也支持普通 HTML 单页直接通过 CDN 单文件 <script> 标签开箱即用。

三、快速上手

方式 1：Vue / React / Vite 等工程化项目（NPM）

1. 安装

bash 复制代码

# 安装 SDK 与 peer 依赖 three
npm i @giszhc/three-model-viewer three
# 或
pnpm add @giszhc/three-model-viewer three

2. 代码实现

typescript 复制代码

import { Viewer } from '@giszhc/three-model-viewer';
import '@giszhc/three-model-viewer/style.css'; // 导入 3D 尺寸标注与测量标签样式

// 1. 初始化画布
const viewer = new Viewer({
  container: document.getElementById('viewport')!,
  background: '#0a0f1d', // 背景色，支持 16 进制或传 null 保持透明
  unit: 'm',             // 测量单位：m / cm / mm
  antialias: true,
});

// 2. 加载在线 ZIP 模型（含材质和贴图）
await viewer.loadZip('https://your-domain.com/models/motor.zip');

// 3. 开启测量模式（单次测量后自动复位，防止误触）
viewer.setMeasurementMode('distance'); // 距离测量
// viewer.setMeasurementMode('height');   // 标高测量
// viewer.setMeasurementMode('angle');    // 角度测量
// viewer.setMeasurementMode('area');     // 面积测量

// 4. 控制长宽高范围盒显示
viewer.setBoundingBoxVisible(true);

// 5. 视角切换 (支持 front, back, left, right, top, bottom, iso-front, iso-back)
viewer.setCameraView('top');

方式 2：纯 HTML 单页 / CDN 引入（无需任何脚手架）

SDK 打包了自包含的 UMD 单文件 ，内部集成了 Three.js、解压模块与算法，引入即可在全局拿到 window.ThreeModelViewer：

html 复制代码

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>3D 检视器 CDN 引入示例</title>
  <!-- 1. 引入配套样式 -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@giszhc/three-model-viewer/dist/style.css">
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    #viewer-container { width: 100vw; height: 100vh; overflow: hidden; }
  </style>
</head>
<body>
  <div id="viewer-container"></div>

  <!-- 2. 引入自包含 UMD 脚本 -->
  <script src="https://cdn.jsdelivr.net/npm/@giszhc/three-model-viewer/dist/index.umd.js"></script>

  <script>
    // 3. 全局对象直接解构使用
    const { Viewer } = window.ThreeModelViewer;

    const viewer = new Viewer({
      container: document.getElementById('viewer-container'),
      background: '#070a14',
      unit: 'm'
    });

    // 4. 直接载入在线 ZIP 压缩包或 OBJ 模型
    viewer.loadZip('https://your-domain.com/models/engine.zip')
      .then(info => {
        console.log(`模型加载完成！顶点数: ${info.vertexCount}, 面数: ${info.faceCount}`);
      })
      .catch(err => {
        console.error('加载失败:', err);
      });
  </script>
</body>
</html>

四、常用核心 API

1. 模型加载与卸载

方法	说明
`loadZip(source)`	支持传入本地 `File/Blob` 或远程 `URL`，纯前端解压并关联贴图
`loadOBJ(objUrl, mtlUrl?)`	传入 OBJ 地址与可选的 MTL 材质直链进行加载
`clearModel()`	释放所有网格、材质与几何体显存，重置场景

2. 测量与空间工具

typescript 复制代码

// 测量模式切换
viewer.setMeasurementMode('distance' | 'height' | 'angle' | 'area' | 'none');

// 撤销上一个标点 / 清空所有测量标记
viewer.undoMeasurement();
viewer.clearMeasurements();

// 显示形态控制 ('solid' 实体表面 | 'wireframe' 线框模式)
viewer.setDisplayStyle('wireframe');

// 开启/关闭纹理贴图（关闭时自动降级为标准工业蓝模）
viewer.toggleTexture(false);

// 开启正交剖切 (设置 X 轴切面位置与反向)
viewer.setSectioningEnabled(true);
viewer.setSectionAxisEnabled('x', true);
viewer.setSectionAxisOffset('x', 0.2);
viewer.setSectionAxisInverted('x', true);

3. 高清截图导出

typescript 复制代码

// 支持导出原画质（按实际贴图原始尺寸导出），或者 1x / 2x / 4x 超清截图
viewer.exportScreenshot({
  resolution: 'original', // 'original' | '1x' | '2x' | '4x'
  filename: 'model-render.png'
});

五、源码与在线体验

项目采用 MIT 协议开源，无商业化限制。如果你的业务正好需要网页端轻量化 3D 检视、模型展示或在线量测，欢迎 Star 和提 Issue：

GitHub 源码 ：https://github.com/giszhc/three-model-viewer
在线 Demo 演示 ：https://giszhc.github.io/three-model-viewer/