3D历史建筑展览馆 THreeJS 开源

我用夸克网盘给你分享了「27-3D历史建筑展览馆 THreeJS」，点击链接或复制整段内容，打开「夸克APP」即可获取。

/~bde43aJRcR~:/

链接：https://pan.quark.cn/s/b15e70a3c23e

Empire Atlas（帝国图志）

探索古代文明的居住方式。这是一个跨越八大历史帝国的国内建筑交互式 3D 地图集。您可以旋转展台上的每座住宅，阅读标注在石墙上的建筑特征，并通过房间、器物与地理环境深入了解这些家庭。

目录

• 项目简介

• 住宅一览

• 技术实现

• 运行指南

• 项目结构

• 3D 查看器技术细节

• 无障碍设计

• 部署前须知

---

项目简介

本项目包含八座住宅，每个帝国一座，均经过 3D 建模并标注了使其作为家园运作的建筑特征。

**查看器（Viewer）**​ 是应用的核心：一个如同博物馆展柜般照明的旋转展台，您可以在此环绕、缩放、剖切模型并进行阅读。

您可以做些什么？

• 旋转住宅：环绕、平移和缩放模型，或使用键盘控制（方向键、+/-、Home 键）。

• 阅读建筑：每座住宅有四个热点标记（Hotspot），直接固定在几何体上；悬停可查看注释，点击可将镜头推近。

• 透视内部：提供线框模式、X 光截面图层以及旋转展台参考网格。

• 深入探索：内部视图、平面图、家庭器物、日常生活以及帝国地理。

• 学习与测试：每个帝国配有文字课程、时间线以及测验。

• 全局搜索 ：使用 ⌘K快速查找帝国、住宅及单个建筑特征。

---

住宅一览

帝国	住宅	时期
古埃及	庭院住宅 (Courtyard House)	约公元前 1500 年（新王国时期）
波斯帝国	贵族宅邸 (Noble Residence)	约公元前 500 年（阿契美尼德王朝）
中国汉朝	四合院 (Siheyuan)	约公元 100 年（东汉）
罗马帝国	罗马多姆斯 (Roman Domus)	公元 1 世纪
拜占庭帝国	城市住宅 (Urban House)	约公元 10 世纪
印加帝国	石头住宅 (Stone Dwelling)	约公元 15 世纪
奥斯曼帝国	庭院住宅 (Courtyard Home)	约公元 17 世纪
莫卧儿帝国	哈维利 (Haveli)	约公元 17 世纪

扩展提示 ：添加第九个帝国只需增加相应的数据文件和资源。查看器和 UI 完全由数据驱动，无需修改代码。请参阅 src/types/empire.ts了解数据契约。

---

技术实现

本项目完全使用生成式 AI 工具端到端制作，每种工具各司其职。

• 应用程序 --- Kimi K3：整个代码库（包括 React 应用、three.js 查看器、设计系统和帝国内容）均由 Kimi K3 生成。

• 3D 模型 --- Tripo 3D ：所有八座住宅均由 Tripo AI 建模，导出为 Draco 压缩的 glTF 格式（public/models/*.glb，每个约 2.1 MB）。它们以单网格模型和烘焙纹理的形式加载，查看器会在加载时将其标准化为一致的框架。

• 图像素材 --- GPT Image 2.0（通过 Tripo 运行）：56 张插图（包括英雄级剖视图、室内图、平面图、器物研究和帝国地图）均由 GPT Image 2.0 生成。

值得记录的一点：这些图像是通过 Tripo 的 GPT Image 2.0 接口生成的，而非直接调用 API。Tripo 对批量请求处理得非常好，实际上通过它批量生成图像集的速度明显快于直接调用 GPT Image 2。当一个帝国需要 7 张风格一致的图像，且随着艺术指导的确定需要重新生成时，这种速度优势至关重要。

---

运行指南

需要 Node 20 或更高版本。

npm install          # 安装依赖
npm run dev          # 在 :3000 端口启动开发服务器
npm run build        # 先运行类型检查 (tsc -b)，然后构建生产环境代码到 dist/ 目录
npm run preview      # 预览生产环境构建
npm run lint         # 运行代码检查

注意 ：npm run build会先执行 tsc -b，因此类型错误会导致构建失败，防止错误代码被发布。

---

项目结构

src/
├─ App.tsx                 # 应用外壳：布局、模态框路由、响应式行为
├─ three/
│  └─ engine.ts            # 整个 3D 查看器 ------ 渲染器、光照、相机、过渡动画、热点解析、模型驻留管理
├─ components/
│  ├─ Viewer.tsx           # 画布宿主、工具栏、图层菜单、请求排序
│  ├─ HotspotLayer.tsx     # 屏幕空间热点标记及其悬停注释
│  ├─ EmpireLibrary.tsx    # 帝国侧边栏（桌面端）和抽屉内容（移动端）
│  ├─ InfoPanel.tsx        # 选中住宅的详细信息（侧边栏或页面流中）
│  ├─ BottomCards.tsx      # 五个探索卡片
│  ├─ Banner.tsx           # 可关闭的归属栏
│  ├─ modals.tsx           # 课程、测验、器物、时间线、截面、⌘K 搜索等模态框
│  └─ ui/                  # shadcn/ui 基础组件
├─ data/
│  └─ empires/*.ts         # 每个帝国一个文件：文案、事实、热点、课程、测验、时间线
└─ types/empire.ts         # 每个帝国数据必须满足的数据契约

技术栈​ --- React 19 · TypeScript 5.9 · Vite 7 · Tailwind CSS 3.4 · three.js 0.185（使用 TSL 节点材料的 WebGPU 渲染器） · GSAP 3 · three-mesh-bvh · shadcn/ui

设计语言 ​ --- 在 Cormorant Garamond 和 Inter 字体上采用温暖的羊皮纸色调，作为 CSS 自定义属性统一定义在 src/index.css中，并桥接到 Tailwind 和 shadcn 的令牌系统中。

响应式行为​ --- 三列桌面舞台在 1280px 时启用。在此宽度以下，帝国库会移入汉堡菜单背后的抽屉中，住宅详细信息在模型下方内联显示，探索卡片的列数会从五列依次变为三列、两列，最后变为一列。

---

3D 查看器技术细节

以下是 src/three/engine.ts中一些从代码中不易看出的设计决策：

• 热点（Hotspots）基于几何体解析，而非固定坐标。如果将标记点固定在模型边界框中的某个点上，它经常会悬浮在空中而不是附着在建筑物上。因此，每个热点都会声明它属于哪种表面（屋顶、庭院或墙壁），引擎会在足迹上采样 20×20 的顶面高度场来寻找它，并优先选择从静止相机视角实际可见的候选点。作者提供的锚点仅用于打破平局。

• 舞台背景是 CSS，而非场景几何体。画布是透明的。如果渲染羊皮纸渐变，它会经过 ACES 色调映射并变成灰色，因此背景是在画布后面的 CSS 中绘制的，以保持与周围 UI 完全相同的调色板。

• 切换住宅是一个旋转展台动画。舞台上的住宅绕自身轴线旋转，在转速最快的时刻，下一座住宅接管相同的旋转并使其静止。没有任何东西离开地面，这避免了地平面切穿柱廊或露天庭院，并让住宅在整个过程中保持投射阴影。

• 阴影按需绘制。环绕操作只移动相机，不移动建筑物，因此阴影贴图仅在几何体实际发生变化时刷新，而不是每一帧都刷新。

• 最近查看的住宅保持驻留。六个模型会被保留在内存中解析，悬停在库中的帝国上就会开始获取它，因此随后的点击将落在一个已经下载、解析、构建 BVH 并解析了热点的模型上，而无需在动画过程中付出这些代价。

• 热点标记每帧的开销为零 。投影循环通过 ref 持有元素句柄，从 ResizeObserver而不是布局读取中获取舞台大小，重用其向量，并且仅在发生变化时写入 class。

---

无障碍设计

• 查看器支持完整的键盘控制，热点标记是可聚焦的按钮，在获得焦点（focus）和悬停（hover）时都会打开注释。

• 实时跟踪并遵守 prefers-reduced-motion：过渡动画会立即完成，热点和加载动画会停止。

• 语义化地标、带标签的控件、切换按钮上的 aria-pressed/ aria-expanded，以及加载状态的实时区域（live regions）。

• 焦点环（Focus rings）永远不会被移除，只会被重新样式化。

---

部署前须知

index.html中的 og:image和 og:url应该是绝对 URL。大多数爬虫会将相对路径解析为页面路径，但并非所有爬虫都如此。一旦站点有了域名，请将 /og-cover.jpg替换为完整 URL 并添加 og:url。代码中已有注释标记了需要修改的位置。