# campuscg

**Repository Path**: huxiqing/campuscg

## Basic Information

- **Project Name**: campuscg
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 青岛黄海学院 · 三维校园漫游系统

计算机图形学课程设计 —— 基于 **Three.js + Vue 3 + TypeScript** 的交互式三维校园漫游系统。
校园布局参照[青岛黄海学院官方校园地图（2024）](http://www.qdhhc.edu.cn/campusfw-4229.html)（原图存于 `docs/campus-map.jpg`）搭建。

![技术栈](https://img.shields.io/badge/Three.js-r185-blue) ![Vue](https://img.shields.io/badge/Vue-3.5-brightgreen) ![Vite](https://img.shields.io/badge/Vite-8-purple)

## 校园布局（照地图还原）

- **胶州湾东路**横贯校园，以北为**北区**、南为**南区**，西为**西区**宿舍群，北侧以**龙山**山体为屏障
- **北区**：J4 知行楼、J5 知韵楼（L 形）、J6 知信楼（L 形）、T1 第一体育场、小西湖、G5 体育馆、G3 博物馆、G4 雷锋纪念馆、孔子广场（雕像）、G1 东区图书馆、G2 方塘书屋（屋旁方塘）、B1 办公楼
- **西区**：学生公寓 8# ~ 21#、C3 双馨园餐厅、山体公园、观海亭、G6 阅享空间
- **南区**：学生公寓 1# ~ 7# 与东区公寓 8# ~ 18#、J1 知新楼、J2 知明楼、J3 知诚楼、S1/S2 实验楼、科技广场（雕塑）、T2 第二体育场、C1 学苑餐厅、C2 文苑餐厅、B2 招生办、B3 安保处、人才公寓（山海嘉园）、附属口腔医院、附属幼儿园、商业街
- **道路**：胶州湾东路、灵海路、玉皇路、八一路及校内支路；西区西门、西区大门、北区大门、北区东大门、南区大门五座门牌坊
- **周边环境**：南侧**灵山湾**大海（自定义海面着色器：涌浪 + 近岸泡沫带 + 深浅海色渐变）与沙滩；灵海路以南**海景公寓**群落；校园东西两侧**西海岸花园**、**东方海岸城**住宅小区及地标高楼

## 功能特性

### 交互功能
| 功能 | 操作 |
|------|------|
| 环绕漫游 | 鼠标左键旋转 / 右键平移 / 滚轮缩放（OrbitControls，带阻尼） |
| 第一人称漫游 | `W/A/S/D` 或方向键移动，`Shift` 加速（视野动态拉伸），`Space` 空中四段跳，下落时按 `G` 展开/收起滑翔（缓降 2.2m/s + 前冲加速），鼠标转视角（Pointer Lock），`Esc` 退出；含圆形碰撞体推离与校园边界约束 |
| 昼夜系统 | 拖动时间滑块（0–24 时）或勾选"自动流逝"；清晨 / 正午 / 黄昏 / 夜晚 一键预设 |
| 建筑查询 | 单击建筑弹出信息卡片，选中目标显示呼吸光环（Raycaster 拾取） |
| 实时小地图 | 右下角 Scissor 多视口渲染，红色箭头实时指示相机位置与朝向 |
| 其他 | 建筑标签开关、自动环绕巡游、复位视角、FPS 与坐标显示、帮助面板 |

### 昼夜系统联动效果
太阳 / 月亮升落与方向光切换、天空穹顶颜色渐变（含黄昏暮光）、星空渐显、雾色跟随、
路灯点光源与灯泡自发光、建筑窗户夜灯（自发光贴图）、水面反射色调联动。

## 图形学技术要点

1. **参数化建模**：`Box / Cylinder / Cone / Sphere / Torus / Ring / Icosahedron` 等基础几何体组合出 60+ 栋建筑；数据驱动的布局表摆放
2. **程序化纹理**：Canvas 生成草地、沥青路面、窗户网格（白天贴图 + 夜晚自发光贴图）、五星红旗、钟面、足球场与篮球场标线、门牌匾额
3. **自定义着色器（GLSL）**：
   - 天空穹顶：顶色 / 地平线色双渐变 + 太阳方向暮光光晕
   - 水面（小西湖 / 方塘）：顶点多组正弦波 + 解析法线 + 菲涅尔混合天空色 + 太阳镜面波光 + 岸边泡沫
   - 旗帜：顶点级行波动画
4. **光照与阴影**：平行光（太阳 / 月亮按时间切换）+ 半球光 + 点光源路灯；PCFSoft 阴影贴图（2048²）
5. **色彩管理**：ACES Filmic 色调映射 + sRGB 输出；线性雾模拟大气透视
6. **实例化渲染**：`InstancedMesh` 批量绘制 300+ 棵树木
7. **相机与交互**：OrbitControls 环绕 / 自研指针锁定第一人称控制器（YXZ 欧拉角、重力与跳跃/滑翔物理、碰撞推离）；Raycaster 拾取（区分点击与拖拽）
8. **多视口渲染**：`setScissor + setViewport` 双相机（透视 + 正交）单通道渲染小地图

## 项目结构

```
src/
├── main.ts              # Vue 入口
├── App.vue              # UI 外壳（控制面板 / 信息卡 / 帮助弹窗 / HUD）
├── style.css            # 全局样式
├── three/               # three.js 图形模块（与框架解耦）
│   ├── campus.ts        # 主应用：昼夜系统、拾取、小地图、渲染循环
│   ├── qdhh.ts          # 青岛黄海学院布局：60+ 建筑按官方地图坐标摆放
│   ├── buildings.ts     # 建筑工厂（图书馆/体育馆/实验楼/食堂/通用楼栋/校门牌坊）
│   ├── environment.ts   # 道路 / 水面着色器 / 山体 / 树木实例化 / 路灯
│   ├── props.ts         # 体育场 / 飞鸟 / 长椅 / 亭子 / 小径
│   ├── sky.ts           # 天空穹顶着色器、日月星辰、云层、基础光照
│   ├── controls.ts      # OrbitControls + 第一人称控制器（跳跃/滑翔/碰撞）
│   └── textures.ts      # Canvas 程序化纹理库
└── docs/campus-map.jpg  # 参照的官方校园平面图
```

## 运行

```sh
npm install        # 安装依赖
npm run dev        # 开发模式（http://localhost:5173）
npm run build      # 类型检查 + 生产构建
npm run preview    # 预览生产构建
```

> 建议使用 Chrome / Edge 等基于 Chromium 的现代浏览器打开，需支持 WebGL 2。

## 素材说明

场景中全部模型、纹理均由代码程序化生成，**未使用任何外部模型 / 贴图资源**，可完全离线运行。
校园布局参照官方公开地图抽象简化而来，建筑比例与位置为示意性还原。