# OpenCesium

**Repository Path**: cesium-developer/open-cesium

## Basic Information

- **Project Name**: OpenCesium
- **Description**: 本项目开源市面上常见的各种基础功能
- **Primary Language**: JavaScript
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-23
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenCesium - 三维空间可视化平台

[English](./README.en.md) | 中文

## 📖 项目介绍

OpenCesium 是一个基于 Vue 3 + Cesium 的开源三维空间可视化平台，旨在为开发者提供丰富的三维地理信息功能模块，便于快速构建和实现应用。本项目采用模块化设计，支持插件式开发，开发者可以轻松添加自定义功能模块。

### 核心特性

- 🎯 **模块化架构**：采用组件化设计，功能模块独立，易于扩展和维护
- 🚀 **插件式开发**：通过配置文件即可添加新功能，无需修改核心代码
- 🎨 **现代化 UI**：基于 Element Plus 的现代化界面设计
- 📦 **开箱即用**：内置多种常用三维功能模块
- 🔧 **易于扩展**：清晰的代码结构，便于二次开发

### 📚 相关文档

- 📖 [开发快速参考指南](./DEVELOPMENT.md) - 快速查找常用代码片段和开发技巧
- 🤝 [贡献指南](./CONTRIBUTING.md) - 详细的贡献流程和代码规范
- 🌐 [English Documentation](./README.en.md) - English version of this documentation

## 🛠️ 技术栈

- **前端框架**: Vue 3 (Composition API)
- **三维引擎**: Cesium
- **状态管理**: Pinia
- **路由管理**: Vue Router 4
- **UI 组件库**: Element Plus
- **构建工具**: Vite 6
- **样式预处理**: Sass/SCSS
- **HTTP 客户端**: Axios

## 📁 项目结构

```
open-cesium/
├── public/                          # 静态资源目录
│   ├── config/                      # 配置文件目录
│   │   ├── cesium-config.json       # Cesium 功能配置（工具列表）
│   │   └── icons-config.json        # 图标配置
│   ├── data/                        # 数据文件（模型、纹理等）
│   ├── Image/                       # 图片资源
│   └── sdk/                         # 第三方 SDK（Cesium）
│
├── src/                             # 源代码目录
│   ├── api/                         # API 接口
│   │   └── auth.js                  # 认证相关接口
│   │
│   ├── components/                  # 全局组件
│   │   ├── CesiumSpace.vue          # Cesium 空间容器组件
│   │   └── UserInfo.vue             # 用户信息组件
│   │
│   ├── libs/                        # 第三方库封装
│   │   └── ammo/                    # Ammo.js 物理引擎封装
│   │
│   ├── router/                      # 路由配置
│   │   └── index.js                 # 路由定义
│   │
│   ├── store/                        # 状态管理
│   │   ├── index.js                  # Pinia 实例
│   │   ├── spaceStore.js             # 空间状态管理
│   │   └── userStore.js              # 用户状态管理
│   │
│   ├── utils/                        # 工具函数
│   │   ├── assets.js                 # 资源路径处理
│   │   ├── requests.js               # HTTP 请求封装
│   │   └── cesium/                    # Cesium 相关工具
│   │       ├── core/                  # 核心功能
│   │       ├── entity/                # 实体相关
│   │       ├── model/                 # 模型相关
│   │       ├── terrain/               # 地形相关
│   │       ├── water/                 # 水体相关
│   │       └── ...                    # 其他功能模块
│   │
│   └── views/                        # 页面组件
│       ├── Login/                     # 登录页面
│       │   └── index.vue
│       └── Home/                      # 主页面
│           ├── index.vue              # 主页面入口
│           ├── UI/                    # UI 组件
│           │   ├── AppHeader.vue      # 顶部导航栏
│           │   ├── AppSidebar.vue     # 侧边栏（工具列表）
│           │   ├── AppFooter.vue      # 底部栏
│           │   ├── CyberLoader.vue    # 加载动画
│           │   └── CyberNotification.vue # 通知组件
│           └── components/             # 功能组件
│               ├── CesiumComponents.vue # Cesium 组件容器
│               └── Cesium/              # Cesium 功能组件
│                   ├── terrain/        # 地形相关组件
│                   │   ├── TerrainExcavation.vue
│                   │   ├── HeightMap.vue
│                   │   └── ...
│                   └── model/          # 模型相关组件
│                       ├── ModelLoad.vue
│                       ├── 3dTileControlPanel.vue
│                       └── ...
│
├── .env                              # 环境变量配置（需要创建）
├── vite.config.js                    # Vite 配置
├── package.json                      # 项目依赖
└── README.md                         # 项目文档
```

## 🚀 快速开始

### 环境要求

- Node.js >= 18.17.1
- npm >= 7.0.0 或 yarn >= 1.22.0 或 pnpm >= 9.10.0

### 安装步骤

1. **克隆项目**
   ```bash
   git clone https://gitee.com/cesium-developer/open-cesium.git
   cd open-cesium
   ```

2. **安装依赖**
   ```bash
   npm install
   # 或
   yarn install
   ```

3. **配置环境变量**
   
   在项目根目录创建 `.env` 文件：
   ```env
   # API配置
   VITE_API_BASE_URL=http://192.168.31.179/prod-api
   VITE_API_TIMEOUT=30000

   # 应用配置
   VITE_APP_TITLE=3D Space
   VITE_APP_DESCRIPTION=Cesium空间可视化平台
   VITE_APP_HEADER_TITLE=GISer的三维空间
   ```

4. **启动开发服务器**
   ```bash
   npm run dev
   # 或
   yarn dev
   ```

   访问 http://localhost:3003

5. **构建生产版本**
   ```bash
   npm run build
   # 或
   yarn build
   ```

## 📚 开发指南

> 💡 **提示**: 需要快速查找常用代码片段？请查看 [开发快速参考指南](./DEVELOPMENT.md)

### 如何添加新功能模块

本项目的核心设计理念是**插件式开发**，所有功能模块通过配置文件注册，无需修改核心代码。

#### 步骤 1: 创建功能组件

在 `src/views/Home/components/Cesium/` 目录下创建你的功能组件：

```vue
<!-- src/views/Home/components/Cesium/your-feature/YourFeature.vue -->
<template>
  <div class="feature-panel">
    <el-card>
      <template #header>
        <div class="card-header">
          <span>你的功能名称</span>
          <el-button type="text" @click="handleClose">关闭</el-button>
        </div>
      </template>
      <!-- 你的功能内容 -->
      <div>
        <el-button @click="handleAction">执行操作</el-button>
      </div>
    </el-card>
  </div>
</template>

<script setup>
import { useSpaceStore } from '@/store/spaceStore'

const spaceStore = useSpaceStore()

// 获取 Cesium viewer 实例
const viewer = spaceStore.viewer

// 你的功能逻辑
const handleAction = () => {
  if (viewer) {
    // 使用 viewer 进行操作
    console.log('执行操作', viewer)
  }
}

// 关闭面板
const handleClose = () => {
  spaceStore.setSelectedTool(null)
}
</script>

<style scoped lang="scss">
.feature-panel {
  position: absolute;
  top: 20px;
  right: 20px;
  width: 400px;
  z-index: 1000;
}
</style>
```

**重要提示**：
- 组件文件路径必须遵循：`src/views/Home/components/Cesium/{category}/{ComponentName}.vue`
- 组件必须支持 `@close` 事件或调用 `spaceStore.setSelectedTool(null)` 来关闭面板
- 通过 `useSpaceStore()` 获取 `viewer` 实例来操作 Cesium

#### 步骤 2: 注册功能到配置文件

编辑 `public/config/cesium-config.json`，添加你的功能配置：

```json
{
  "token": "your-cesium-token",
  "tabs": [
    {
      "key": "your-category",
      "name": "你的分类名称",
      "tools": [
        {
          "key": "yourFeature",
          "name": "你的功能名称",
          "icon": "fa-solid fa-icon-name",
          "componentPath": "your-category/YourFeature"
        }
      ]
    }
  ]
}
```

**配置说明**：
- `key`: 功能的唯一标识符
- `name`: 在侧边栏显示的名称
- `icon`: Font Awesome 图标类名（参考 https://fontawesome.com/icons）
- `componentPath`: 组件路径（相对于 `Cesium/` 目录，不包含 `.vue` 扩展名）

#### 步骤 3: 使用工具函数（可选）

如果你的功能需要用到 Cesium 工具函数，可以在 `src/utils/cesium/` 目录下创建工具文件：

```javascript
// src/utils/cesium/yourFeature.js
export function createYourFeature(viewer, options) {
  // 你的功能实现
  return {
    // 返回功能对象
  }
}
```

然后在组件中引入使用：

```javascript
import { createYourFeature } from '@/utils/cesium/yourFeature'

const feature = createYourFeature(viewer, { /* options */ })
```

### 文件放置规范

#### 组件文件
- **功能组件**: `src/views/Home/components/Cesium/{category}/{ComponentName}.vue`
- **UI 组件**: `src/views/Home/UI/{ComponentName}.vue`
- **全局组件**: `src/components/{ComponentName}.vue`

#### 工具函数
- **Cesium 工具**: `src/utils/cesium/{feature}/{fileName}.js`
- **通用工具**: `src/utils/{fileName}.js`

#### 配置文件
- **功能配置**: `public/config/cesium-config.json`
- **图标配置**: `public/config/icons-config.json`

#### 静态资源
- **图片**: `public/Image/`
- **模型**: `public/data/model/`
- **数据**: `public/data/`

### 访问 Cesium Viewer

所有功能组件都可以通过 `spaceStore` 访问 Cesium viewer：

```javascript
import { useSpaceStore } from '@/store/spaceStore'

const spaceStore = useSpaceStore()
const viewer = spaceStore.viewer

// 使用 viewer 进行操作
if (viewer) {
  viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(116.39, 39.9),
    point: {
      pixelSize: 10,
      color: Cesium.Color.YELLOW
    }
  })
}
```

### 状态管理

#### SpaceStore

`spaceStore` 提供了以下状态和方法：

```javascript
// 状态
spaceStore.viewer              // Cesium viewer 实例
spaceStore.activeSpace         // 当前活动空间（固定为 'cesium'）
spaceStore.selectedTool        // 当前选中的工具
spaceStore.sidebarTabs        // 侧边栏工具列表
spaceStore.isFullscreen       // 全屏状态

// 方法
spaceStore.setSelectedTool(tool)    // 设置选中的工具
spaceStore.clearAllEffects()        // 清除所有效果
```

#### UserStore

用户相关的状态管理：

```javascript
import { useUserStore } from '@/store/userStore'

const userStore = useUserStore()
await userStore.userLogin(loginForm)
await userStore.userRegister(registerForm)
```

## 🔧 配置文件说明

### cesium-config.json

功能模块配置文件，定义侧边栏的工具列表：

```json
{
  "token": "Cesium Ion Token",
  "tabs": [
    {
      "key": "category-key",
      "name": "分类名称",
      "tools": [
        {
          "key": "tool-key",
          "name": "工具名称",
          "icon": "fa-solid fa-icon",
          "componentPath": "category/tool-component"
        }
      ]
    }
  ]
}
```

### icons-config.json

图标配置文件，定义分类图标：

```json
{
  "categoryIcons": {
    "terrain": "fa-solid fa-mountain",
    "model": "fa-solid fa-cube"
  },
  "defaultIcon": "fas fa-tools"
}
```

### .env

环境变量配置：

```env
# API 配置
VITE_API_BASE_URL=http://your-api-url
VITE_API_TIMEOUT=30000

# 应用配置
VITE_APP_TITLE=应用标题
VITE_APP_DESCRIPTION=应用描述
VITE_APP_HEADER_TITLE=头部标题
```

## 📖 API 使用说明

### 认证 API

```javascript
import { login, register, logout, getCaptcha } from '@/api/auth'

// 获取验证码
const captcha = await getCaptcha()

// 用户登录
const result = await login({
  username: 'user',
  password: 'pass',
  code: 'captcha',
  uuid: 'captcha-uuid'
})

// 用户注册
await register({
  username: 'user',
  email: 'user@example.com',
  password: 'pass',
  confirmPassword: 'pass',
  code: 'captcha',
  uuid: 'captcha-uuid'
})

// 退出登录
await logout()
```

### HTTP 请求

```javascript
import request from '@/utils/requests'

// GET 请求
const data = await request.get('/api/endpoint')

// POST 请求
const result = await request.post('/api/endpoint', {
  key: 'value'
})
```

## 🤝 贡献指南

> 💡 **详细指南**: 请查看 [贡献指南文档](./CONTRIBUTING.md) 获取完整的开发流程、代码规范、提交规范等详细信息。

> 🚀 **快速参考**: 需要快速查找代码片段和开发技巧？请查看 [开发快速参考指南](./DEVELOPMENT.md)。

### 开发流程

1. **Fork 项目**
   ```bash
   # Fork 到你的账号
   ```

2. **创建功能分支**
   ```bash
   git checkout -b feature/your-feature-name
   ```

3. **开发功能**
   - 按照上述"如何添加新功能模块"的步骤开发
   - 遵循项目代码规范
   - 添加必要的注释

4. **提交代码**
   ```bash
   git add .
   git commit -m "feat: 添加新功能描述"
   git push origin feature/your-feature-name
   ```

5. **创建 Pull Request**
   - 在 Gitee 上创建 Pull Request
   - 详细描述你的功能变更
   - 附上截图或演示视频（如有）

### 代码规范

- 使用 ESLint 进行代码检查
- 遵循 Vue 3 Composition API 最佳实践
- 组件命名使用 PascalCase
- 文件命名使用 PascalCase（组件）或 camelCase（工具函数）
- 添加必要的注释和文档

### 提交信息规范

使用约定式提交格式：

- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建/工具相关

示例：
```
feat: 添加地形开挖功能
fix: 修复模型加载时的内存泄漏问题
docs: 更新开发文档
```

## 📝 常见问题

### Q: 如何获取 Cesium viewer 实例？

A: 通过 `useSpaceStore()` 获取：
```javascript
import { useSpaceStore } from '@/store/spaceStore'
const spaceStore = useSpaceStore()
const viewer = spaceStore.viewer
```

### Q: 组件路径配置错误怎么办？

A: 确保 `componentPath` 配置正确：
- 路径相对于 `src/views/Home/components/Cesium/` 目录
- 不包含 `.vue` 扩展名
- 使用 `/` 分隔目录层级

### Q: 如何调试功能组件？

A: 
1. 在组件中添加 `console.log` 输出调试信息
2. 使用浏览器开发者工具查看控制台
3. 检查 Network 面板查看 API 请求
4. 使用 Vue DevTools 查看组件状态

### Q: 如何添加新的工具分类？

A: 在 `cesium-config.json` 中添加新的 `tabs` 项：
```json
{
  "tabs": [
    {
      "key": "new-category",
      "name": "新分类",
      "tools": [...]
    }
  ]
}
```

## 📄 许可证

本项目采用 [MIT License](./LICENSE) 许可证。

## 🙏 致谢

感谢所有为本项目做出贡献的开发者！

## 📮 联系方式

- 项目地址: https://gitee.com/cesium-developer/open-cesium
- 问题反馈: 请在 Gitee Issues 中提交

---

**Happy Coding! 🚀**