01
项目介绍 (README)
02
功能列表 (v1.6.2)
A. 核心加载能力
* 多格式原生支持：.3dm (Rhino 5/6/7/8)、.glb/.gltf (Draco压缩)、.obj + .mtl
* 智能坐标系处理：自动检测 Z-up/Y-up 差异，提供手动修正选项
* 智能代理降级系统：多级代理自动重试，解决移动端/跨域加载失败问题
* 大体积模型优化：加载前预计算顶点，超200万顶点性能预警，支持渐进式渲染
B. 视觉风格化系统 (完整预设)
* 预设风格模板：
- 原色 (Original)：模型材质轻量级显示
- 素模 (Clay)：模拟石膏材质，强调形体与光影
- 蓝图 (Blueprint)：深蓝背景 + 白色轮廓，工程图效果
- X光 (X-Ray)：半透明 + 黑色轮廓，观察内部结构
- 消隐 (Ghosted)：低透明度材质，体块关系研究
- 赛博 (Cyber)：网格基底 + 荧光轮廓，科技风格展示
- 手绘 (Sketch)：边缘检测后处理显示
- 高度热力 (Heatmap)：高度着色显示
- 着色 (Shaded)：强化体块感的着色模式 [NEW]
- 漫画 (Comic)：黑白半色调网点风格 [NEW]
- 复古 (Retro)：低保真复古像素风格 [NEW]
- 像素艺术 (PixelArt)：可调节像素颗粒大小 [NEW]
* 分析模式：
- 高度热力图：支持Y/Z轴映射，自定义色带范围
- 深度图：可视化相机深度信息
- 法线视图：显示表面法线方向
- 世界坐标网格：显示表面坐标网格，可调密度与颜色
C. 交互与分析工具
* 实时剖切系统：三轴独立/组合剖切，实时滑动与反向切换，支持剖面填充 (Visualization Cap)
* 测量工具：智能线段测量 (悬停显示边缘长度)，实时三维空间标注，盒体范围测量
* 对象操作 (实验性)：
- 物件隐藏：支持选择单个物件进行隐藏/恢复 [NEW]
- 物件移动：支持选择单个物件进行位置调整 [NEW]
* 相机系统：
- 视口记忆：支持记录并一键还原当前相机视角 [NEW]
- 正交/透视/两点透视一键切换，自适应视口
* 阴影与光照：动态VSM阴影 (可调软硬度/分辨率)，三点布光系统 (主光/顶光/补光)
D. 动画与演示功能
* 自动演示模式：
- 独立速度控制：旋转速度与光照循环速度可单独调节 [NEW]
- 转盘动画 / 光照巡航 / 剖面扫描
* 屏幕录制：WebM视频直录（不重置用户设定的材质/线条风格），全屏优化适配
* 输出功能：无损PNG截图 (支持透明通道)，一键高清导出
E. AI 深度集成 (1.6.2新增)
* AI 动画生成：基于 DeepSeek 模型，通过自然语言描述自动生成相机运镜与剖切脚本
* 智能出图 (Smart Export)：集成云端主流生成式模型 (支持图生图渲染)
* 实景合成：调用设备摄像头作为背景 (AR-Lite)
* 批量导出：一键打包分析图纸 (轴测/正背/透视/剖面)
F. 界面与用户体验
* 现代化UI：Fluent Design 亚克力效果，移动端/平板横屏适配
* 智能控制台：
- 新增“触控/滚轮灵敏度”调节滑块 [NEW]
- 可拖拽折叠面板
* 背景系统：
- 支持纯色/网格/透明/自定义图片背景
- 实时相机背景：修复了AR模式下的镜像显示问题 [FIX]
G. 高级渲染特性
* 后期处理：素描风格 (Sobel)，半色调 (Halftone)，泛光 (Bloom)，像素（Pixel）
* 雾气与大气：指数雾气模拟大气透视，可调密度与颜色
03
技术文档
ArchViz Lite — 技术说明书 (v1.6.2 Updated)
一、项目概述
本技术说明面向 ArchViz Lite（以下简称“工具”）的技术实现、逻辑框架、功能能力、部署选项及典型应用场景进行系统性说明。该工具的核心目标是在浏览器端提供对设计用三维模型（尤其是 Rhino .3dm 格式）的一体化可视化与工程分析能力，强调“轻量、可携带、隐私优先”的产品设计理念，适配移动设备和临时办公环境，支持本地文件解析与可选的私有云共享通道。
二、设计原则与技术栈
设计原则：1. 本地优先：所有模型文件在默认工作流下保持本地读取与解析，避免必须上传至第三方服务器。2. 轻量可携：单文件分发、零后端依赖或可选私有化部署，使工具在不同设备上快速启动。3. 模块化与可扩展：采用清晰的模块职责划分，便于维护与功能拓展。
技术栈要点：Three.js（WebGL2）作为渲染引擎，rhino3dm.wasm 提供对 .3dm 原生解析，常见格式使用对应 loader（GLTF/OBJ），前端 UI 基于 Tailwind + 自定义控件（lil-gui）。关键的实时计算与视觉效果通过自定义 GLSL shader 与 EffectComposer 实现后处理。
三、逻辑框架与模块设计
整体架构：工具采用低耦合、高内聚的模块化对象设计，核心模块包括：Core、Runtime、Lighting、ModelManager、UIManager。各模块职责如下：
— Core：负责渲染器、主场景与主摄像机的初始化与生命周期管理，提供基础渲染上下文与资源注册接口（纹理、着色器、几何缓存等）。Core 保证全局渲染状态一致性，并向其他模块暴露必要的渲染钩子。
— Runtime：管理运行时状态与主循环（animate），协调渲染调度、性能监控与帧率控制。Runtime 实现帧预算管理、降级策略触发条件以及定时/异步任务队列（例如延后计算轮廓或导入后修复任务）。
— Lighting：集中管理光源、阴影策略与后期光照参数，封装阴影实现（如 VSM）、shadow catcher、环境光探针采样等，使场景光照在不同设备上通过参数表实现可控降级和视觉一致性。
— ModelManager：负责模型导入、源数据校验与清洗（剔除非法顶点、修复法线、坐标归一化）、包围盒与层次结构重建、LOD 策略与内存统计。该模块还提供几何的工程分析能力（体量高度热力图、剖切算法、测量工具）。v1.6.2 中新增了多级代理降级系统以解决跨域问题。
— SmartExportEngine (New)：v1.6.2 新增模块，负责智能出图、背景合成及与云端 AI 服务的异步通信（Task Polling）。
— AIAnimationEngine (New)：v1.6.2 新增模块，集成 DeepSeek 模型，负责解析自然语言指令并生成标准化的动画脚本 (JSON Protocol)。
— UIManager：处理用户输入、控件绑定、手势/触控映射与状态同步（State），并将 UI 操作转化为对 Runtime/Core/ModelManager 的指令调用。
模块间通过明确定义的接口与事件总线（或轻量级观察者模式）通信，保证单一职责与可测试性。该设计使得每一模块可以独立替换或扩展，例如在需要时将 ModelManager 的部分预处理移到 WebWorker 中，或替换 Lighting 模块以接入更复杂的基于物理的光照系统。
四、核心流程与关键方法说明
1) 文件读取与解析：使用浏览器 File API 与 URL.createObjectURL() 完成本地文件流读取，rhino3dm.wasm 在主线程或独立 Worker 中解析 .3dm 数据结构，将几何、层级与材质信息序列化为 Three.js 可用的几何体（BufferGeometry）与材质描述。v1.6.2 引入了 es-module-shims 以兼容旧版 iOS 设备。
2) 模型清洗与定位：ModelManager 在导入时执行脏数据检测（NaN / 无限值）、法线校正、坐标系/单位归一化与 AABB 重新定位，自动计算合适的场景缩放因子并重置相机到合适的观察距离。
3) 材质覆盖系统 (updateMaterials)：工具实现了中央化的材质覆盖机制，用于在运行时统一替换或增强模型材质，以支持快速切换视觉模板（例如素模/蓝图/热力着色等）、用于工程视图（法线视图、深度视图）以及性能优化（合并材质、减少 shader 分支）。updateMaterials 的实现要点包括：- 输入：目标视图类型、全局材质参数（如金属度、粗糙度、色彩映射表）、以及可选的材质白名单/黑名单。- 处理：遍历场景可渲染对象，根据对象原始材质特性决定是否保留原材质或替换为轻量占位材质；应用统一的 GPU 数据（例如纹理单通道采样表）以实现热力图或法线渲染。- 输出：批量更新后的材质实例集合，并在必要时触发材质资源回收与显存清理。该系统允许在不修改底层几何的情况下，通过参数化的材质层实现多套可视化风格，从而显著减少针对不同表达而重复导出模型的需要。
4) 渲染循环 (animate)：渲染循环由 Runtime 管理，核心为一个受控的 animate 函数：- 在每帧开始时读取 Runtime 的帧预算与优先级队列，决定本帧需要执行的子任务（例如高级阴影、轮廓计算或剖切重建）。- 执行场景更新：更新物理交互、相机平滑插值、动画混合器以及 UI 引发的场景变更。- 调用 updateMaterials。- 执行渲染：按需分层渲染主通道与后处理链（EffectComposer），在低性能设备上自动降级（例如关闭 VSM、降低后处理分辨率或跳帧）。- 执行性能采样与日志（FPS、显存占用、顶点计数），并在达到阈值时触发降级或向用户显示建议。该循环可由 requestAnimationFrame 驱动或在节能模式下以固定较低频率运行，以兼顾交互性与电量/发热控制。
五、关键实现细节与工程权衡
— .3dm 原生支持：通过 rhino3dm.wasm 在客户端解析 .3dm，保留 Rhino 本地层级与复杂 NURBS 结构的元信息。由于 NURBS 到三角网格的转换可能计算量大，工具采用按需三角化且支持使用 Rhino 端预先导出轻量网格的工作流。
— 着色器与后处理：核心视觉效果通过自定义 GLSL 实现（高度热力、法线编码、深度可视化），后处理链包括抗锯齿、色调映射与可选的图像空间效果。
— 性能与降级策略：导入阶段进行顶点计数与内存估算，高模触发降级提示（自动简化、LOD 或阻塞部分高开销效果）。运行时以视锥剔除、层级化渲染与延迟计算减少每帧开销。对移动设备做额外检查（WebGL1 回退、最大纹理大小、离屏渲染限制）。
六、功能清单与典型应用场景
功能（概要）：.3dm 直接加载、实时剖切与剖面填充、测量标注、热力/深度/法线视图、材质快速切换模板、设备相机叠合背景（AR式预览）、屏幕录制与截图导出、私有化加密页面通道（可选云端部署）。
典型场景示例：1) 现场快速预览与客户沟通（手机/笔记本本地运行）。2) AR 叠合到场地相机并生成 AI 渲染输入。3) 私有化受控分享（私有云 + 加密页面）。4) 教学与审图流程中的快速可视化与录制。
七、与同类产品的比较与优势
核心竞争力：原生 .3dm 支持、本地数据解析与隐私保证、零后端或低运维部署、移动端即时可用。相比需要服务器端格式转换与云渲染的商业产品，ArchViz Lite 在快速交流、隐私敏感项目与现地临时演示方面具有显著优势。当然了，最大的优势应该是性价比，我并不计划对私定云端部署方案外的内容进行任何形式的收费，且由于本地运算的方式使得公共用户使用并不会对我的服务器造成很大开销，我便可以支持朋友们对这个工具的免费使用。
八、部署、隐私与运维建议
默认模式：完全本地运行，用户仅在浏览器端打开静态 HTML 文件即可，不会上传任何项目内容至云端。可选模式：私有化托管，提供一个受控的上传-生成-访问流程，平台在私有服务器上托管模型并生成带加密访问令牌的网页入口；访问端通过短期有效的加密 token 加载模型，模型内容仍可选择仅在服务器端实时流式传输或以加密形式下载到客户端解析。
九、性能指标与测试建议
内测初期，样本收集ing
十、附录：代码示例
之后再弄吧。
04
开发路线图
ArchViz Lite — 开发路线图
因为这个项目我的工作时间不固定，做其他事情之余有时想到了就弄一下，版本更新可能会比开发线路图更新快；例如AI动画功能现在已经实现部署了，下一次测试版本就会实装上；再下一个版本可能会实装点云粒子显示效果；
关于收费的云服务方案能实现的功能，包括它们的优势、可行性、技术实现方式等，之后会更新详细介绍；
05
已知问题与功能期望
ArchViz Lite — 已知问题/功能期望（欢迎持续反馈）
已知问题：
剖面工具的剖面填色会把一些非剖面的物件也填色 ——暂时没有轻量解决方案，被错误填色的一般为曲面薄片或非封闭多重曲面，如有需要可在建模中做相关处理；
演示录制功能播放太快了/视角不是我要的 ——因为目前功能主要用于开发阶段的技术实现测试，未来的开发有计划对这方面做（一键分析动画生成、一键批量视角图导出等）更多扩充；
模型范围长宽高显示开启后无法关闭 ——是开启后切换了视角或显示模式可能导致的问题，再次点击开关一下整体尺寸框这个选项就能解决，我暂时就不去做针对修复了；
预设的显示风格不理想/有一些材质显示或后处理的相关参数调节看不到效果 ——目前的交互可以理解为几个带有多个图层的PS文件叠加再一起，需要各种参数搭配自己多尝试，可以自己试出一些有趣的或者实用的搭配，如果试出好的参数搭配欢迎记录下来并反馈给我；
功能期望：
想要上传微信聊天记录文件 ——这个跟微信的权限设置相关，关于微信的适配比较完美的实现方式是开发小程序版本，但是微信小程序的程序架构跟目前的web架构不同，代码框架需要重构，所以我目前还没有决定要不要做这件事情；
想要上传Su的模型文件 ——本工具开发初衷是辅助我自己平时的Rhino工作流，另外Three.js社区虽然有第三方SketchUp加载器，但不如本工具目前调用自Rhino官方的.3dm 原生解析成熟与稳定，所以除非收到来自单位的正式需求，暂不计划做相关适配；
想要更真实的光影渲染 ——区别于D5等渲染器，本工具主打轻量化，不会有渲染相关的提升计划，但是有一个野心勃勃的关于更多风格化显示、分析模式、可视化这块的开发计划；
06
开发者自述
ArchViz Lite（暂命名） — 开发者自述
这段文本我将会说明这个工具的创作初衷以及核心开发目的，让读者更好地理解工具未来的开发计划：
简要的初衷就是，自进入大学以来，在校内外的设计实践中便开始体会在酷暑的室外捧着笨重的笔记本电脑看rhino，没桌子还不方便操作，施工现场还各种粉尘飞进电脑散热的难绷场景，跟朋友合作项目时又微信文件复制来复制去的，包括在学校课程中经常需要跟老师看方案，这些场景都很需要一个轻便的方式来实时查看基本的3D模型，而不是单薄的静态图纸；然而，已有的商业化产品工具，各种注册收费，还要下载App，还要上传文件到它们的云端，要么就不支持直接导入rhino，而且那些产品基本面向复杂的大型工程建设用途，而非像美院主要做一些小型构筑装置，要么就具有的功能太少，另外再一些商业项目上，由于市面上的产品普遍依赖云端，使其对设计项目的保密性缺乏保障；所以我研究了一下发现实现这些各功能也没什么技术壁垒，所以就时不时抽时间学习研究捣鼓了下，然后最近再借助AI帮我解决了一些重要技术难题（详见技术文档），实现基本功能的内测版本就出来了；
主要的重点就是，这个东西轻量化、本地化、免费、可以直接导入rhino文件，对于我自己的日常工作流来说非常有用，加上它特有的一些功能，我觉得这个工具现在是很值得使用的；
然后要说的就是，由于我目前有其他优先级更高的事项，而且我虽然懂参数化设计（grasshopper），但在编程方面我完全不专业，很多技术内容我需要现学现摸，所以这个工具的开发进度要看情况；
此外要说的就是，我不介意靠它获得一些收入，但是我希望保持初心，用户本地运算可以免费使用所有功能，如果用户多到我现在的服务器担负不起了（不太可能，详见技术文档），我很乐意去搞点电诈什么的弄点钱来升级服务器，所有我计划的收入来源是单位找我私定云端部署方案（详见技术文档），做这方面的收费，当然这是后话了；
最后要说的就是，关于本工具当下的主要工作是做内测，接收大家的反馈，让我了解不同设备可能出现的问题，以及听听大伙对这个工具的看法，觉得它有没有搞头，或者是有没有什么相关可以拓展到有搞头的东西；