# 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 - 3D Space Visualization Platform

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

## 📖 Introduction

OpenCesium is an open-source 3D space visualization platform based on Vue 3 + Cesium, designed to provide developers with rich 3D geospatial information modules for rapid application development. The project adopts a modular architecture with plugin-based development, allowing developers to easily add custom feature modules.

### Core Features

- 🎯 **Modular Architecture**: Component-based design with independent, easily extensible modules
- 🚀 **Plugin-based Development**: Add new features through configuration files without modifying core code
- 🎨 **Modern UI**: Modern interface design based on Element Plus
- 📦 **Out of the Box**: Built-in various common 3D feature modules
- 🔧 **Easy to Extend**: Clear code structure for secondary development

### 📚 Related Documentation

- 📖 [Development Quick Reference](./DEVELOPMENT.md) - Quick lookup for common code snippets and development tips
- 🤝 [Contributing Guide](./CONTRIBUTING.md) - Detailed contribution workflow and code standards
- 🇨🇳 [中文文档](./README.md) - Chinese version of this documentation

## 🛠️ Tech Stack

- **Frontend Framework**: Vue 3 (Composition API)
- **3D Engine**: Cesium
- **State Management**: Pinia
- **Routing**: Vue Router 4
- **UI Component Library**: Element Plus
- **Build Tool**: Vite 6
- **CSS Preprocessor**: Sass/SCSS
- **HTTP Client**: Axios

## 📁 Project Structure

```
open-cesium/
├── public/                          # Static resources
│   ├── config/                      # Configuration files
│   │   ├── cesium-config.json       # Cesium feature configuration
│   │   └── icons-config.json        # Icon configuration
│   ├── data/                        # Data files (models, textures, etc.)
│   ├── Image/                       # Image resources
│   └── sdk/                         # Third-party SDKs (Cesium)
│
├── src/                             # Source code
│   ├── api/                         # API interfaces
│   │   └── auth.js                  # Authentication APIs
│   │
│   ├── components/                  # Global components
│   │   ├── CesiumSpace.vue          # Cesium space container
│   │   └── UserInfo.vue             # User info component
│   │
│   ├── libs/                        # Third-party library wrappers
│   │   └── ammo/                    # Ammo.js physics engine wrapper
│   │
│   ├── router/                      # Route configuration
│   │   └── index.js                 # Route definitions
│   │
│   ├── store/                       # State management
│   │   ├── index.js                 # Pinia instance
│   │   ├── spaceStore.js            # Space state management
│   │   └── userStore.js             # User state management
│   │
│   ├── utils/                       # Utility functions
│   │   ├── assets.js                # Asset path handling
│   │   ├── requests.js              # HTTP request wrapper
│   │   └── cesium/                  # Cesium utilities
│   │       ├── core/                # Core functionality
│   │       ├── entity/              # Entity related
│   │       ├── model/               # Model related
│   │       ├── terrain/             # Terrain related
│   │       ├── water/               # Water related
│   │       └── ...                  # Other feature modules
│   │
│   └── views/                       # Page components
│       ├── Login/                   # Login page
│       │   └── index.vue
│       └── Home/                     # Home page
│           ├── index.vue            # Home page entry
│           ├── UI/                  # UI components
│           │   ├── AppHeader.vue    # Top navigation bar
│           │   ├── AppSidebar.vue   # Sidebar (tool list)
│           │   ├── AppFooter.vue    # Footer
│           │   ├── CyberLoader.vue  # Loading animation
│           │   └── CyberNotification.vue # Notification component
│           └── components/          # Feature components
│               ├── CesiumComponents.vue # Cesium component container
│               └── Cesium/           # Cesium feature components
│                   ├── terrain/      # Terrain components
│                   │   ├── TerrainExcavation.vue
│                   │   ├── HeightMap.vue
│                   │   └── ...
│                   └── model/        # Model components
│                       ├── ModelLoad.vue
│                       ├── 3dTileControlPanel.vue
│                       └── ...
│
├── .env                              # Environment variables (create this)
├── vite.config.js                   # Vite configuration
├── package.json                     # Project dependencies
├── README.md                        # Project documentation (Chinese)
├── README.en.md                     # Project documentation (this file)
├── CONTRIBUTING.md                  # Contributing guide
└── DEVELOPMENT.md                   # Development quick reference guide
```

## 🚀 Quick Start

### Requirements

- Node.js >= 16.0.0
- npm >= 7.0.0 or yarn >= 1.22.0

### Installation

1. **Clone the repository**
   ```bash
   git clone https://gitee.com/cesium-developer/open-cesium.git
   cd open-cesium
   ```

2. **Install dependencies**
   ```bash
   npm install
   # or
   yarn install
   ```

3. **Configure environment variables**
   
   Create a `.env` file in the project root:
   ```env
   # API Configuration
   VITE_API_BASE_URL=http://192.168.31.179/prod-api
   VITE_API_TIMEOUT=30000

   # Application Configuration
   VITE_APP_TITLE=3D Space
   VITE_APP_DESCRIPTION=3D Space Visualization Platform
   VITE_APP_HEADER_TITLE=GISerLiu's 3D Space
   ```

4. **Start development server**
   ```bash
   npm run dev
   # or
   yarn dev
   ```

   Visit http://localhost:3003

5. **Build for production**
   ```bash
   npm run build
   # or
   yarn build
   ```

## 📚 Development Guide

> 💡 **Tip**: Need to quickly find common code snippets? Check out the [Development Quick Reference](./DEVELOPMENT.md)

### How to Add a New Feature Module

The core design philosophy of this project is **plugin-based development**. All feature modules are registered through configuration files without modifying core code.

#### Step 1: Create Feature Component

Create your feature component in `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>Your Feature Name</span>
          <el-button type="text" @click="handleClose">Close</el-button>
        </div>
      </template>
      <!-- Your feature content -->
      <div>
        <el-button @click="handleAction">Execute Action</el-button>
      </div>
    </el-card>
  </div>
</template>

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

const spaceStore = useSpaceStore()

// Get Cesium viewer instance
const viewer = spaceStore.viewer

// Your feature logic
const handleAction = () => {
  if (viewer) {
    // Use viewer for operations
    console.log('Execute action', viewer)
  }
}

// Close panel
const handleClose = () => {
  spaceStore.setSelectedTool(null)
}
</script>

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

**Important Notes**:
- Component file path must follow: `src/views/Home/components/Cesium/{category}/{ComponentName}.vue`
- Component must support `@close` event or call `spaceStore.setSelectedTool(null)` to close panel
- Access Cesium through `useSpaceStore()` to get `viewer` instance

#### Step 2: Register Feature in Configuration

Edit `public/config/cesium-config.json` and add your feature configuration:

```json
{
  "token": "your-cesium-token",
  "tabs": [
    {
      "key": "your-category",
      "name": "Your Category Name",
      "tools": [
        {
          "key": "yourFeature",
          "name": "Your Feature Name",
          "icon": "fa-solid fa-icon-name",
          "componentPath": "your-category/YourFeature"
        }
      ]
    }
  ]
}
```

**Configuration Notes**:
- `key`: Unique identifier for the feature
- `name`: Display name in sidebar
- `icon`: Font Awesome icon class name (see https://fontawesome.com/icons)
- `componentPath`: Component path (relative to `Cesium/` directory, without `.vue` extension)

#### Step 3: Use Utility Functions (Optional)

If your feature needs Cesium utility functions, create a utility file in `src/utils/cesium/`:

```javascript
// src/utils/cesium/yourFeature.js
export function createYourFeature(viewer, options) {
  // Your feature implementation
  return {
    // Return feature object
  }
}
```

Then import and use in your component:

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

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

### File Placement Standards

#### Component Files
- **Feature Components**: `src/views/Home/components/Cesium/{category}/{ComponentName}.vue`
- **UI Components**: `src/views/Home/UI/{ComponentName}.vue`
- **Global Components**: `src/components/{ComponentName}.vue`

#### Utility Functions
- **Cesium Utilities**: `src/utils/cesium/{feature}/{fileName}.js`
- **General Utilities**: `src/utils/{fileName}.js`

#### Configuration Files
- **Feature Configuration**: `public/config/cesium-config.json`
- **Icon Configuration**: `public/config/icons-config.json`

#### Static Resources
- **Images**: `public/Image/`
- **Models**: `public/data/model/`
- **Data**: `public/data/`

### Accessing Cesium Viewer

All feature components can access Cesium viewer through `spaceStore`:

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

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

// Use viewer for operations
if (viewer) {
  viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(116.39, 39.9),
    point: {
      pixelSize: 10,
      color: Cesium.Color.YELLOW
    }
  })
}
```

### State Management

#### SpaceStore

`spaceStore` provides the following state and methods:

```javascript
// State
spaceStore.viewer              // Cesium viewer instance
spaceStore.activeSpace         // Current active space (fixed to 'cesium')
spaceStore.selectedTool        // Currently selected tool
spaceStore.sidebarTabs        // Sidebar tool list
spaceStore.isFullscreen       // Fullscreen state

// Methods
spaceStore.setSelectedTool(tool)    // Set selected tool
spaceStore.clearAllEffects()        // Clear all effects
```

#### UserStore

User-related state management:

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

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

## 🔧 Configuration Files

### cesium-config.json

Feature module configuration file that defines the sidebar tool list:

```json
{
  "token": "Cesium Ion Token",
  "tabs": [
    {
      "key": "category-key",
      "name": "Category Name",
      "tools": [
        {
          "key": "tool-key",
          "name": "Tool Name",
          "icon": "fa-solid fa-icon",
          "componentPath": "category/tool-component"
        }
      ]
    }
  ]
}
```

### icons-config.json

Icon configuration file that defines category icons:

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

### .env

Environment variable configuration:

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

# Application Configuration
VITE_APP_TITLE=Application Title
VITE_APP_DESCRIPTION=Application Description
VITE_APP_HEADER_TITLE=Header Title
```

## 📖 API Usage

### Authentication API

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

// Get captcha
const captcha = await getCaptcha()

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

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

// Logout
await logout()
```

### HTTP Requests

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

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

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

## 🤝 Contributing

> 💡 **Detailed Guide**: Please check the [Contributing Guide](./CONTRIBUTING.md) for complete development workflow, code standards, commit conventions, and more.

> 🚀 **Quick Reference**: Need to quickly find code snippets and development tips? Check out the [Development Quick Reference](./DEVELOPMENT.md).

### Development Workflow

1. **Fork the project**
   ```bash
   # Fork to your account
   ```

2. **Create feature branch**
   ```bash
   git checkout -b feature/your-feature-name
   ```

3. **Develop feature**
   - Follow the steps in "How to Add a New Feature Module"
   - Follow project code standards
   - Add necessary comments

4. **Commit changes**
   ```bash
   git add .
   git commit -m "feat: add new feature description"
   git push origin feature/your-feature-name
   ```

5. **Create Pull Request**
   - Create Pull Request on Gitee
   - Describe your feature changes in detail
   - Attach screenshots or demo videos (if any)

### Code Standards

- Use ESLint for code checking
- Follow Vue 3 Composition API best practices
- Use PascalCase for component names
- Use PascalCase for components or camelCase for utility functions
- Add necessary comments and documentation

### Commit Message Convention

Use conventional commit format:

- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation update
- `style`: Code style adjustment
- `refactor`: Code refactoring
- `test`: Test related
- `chore`: Build/tool related

Example:
```
feat: add terrain excavation feature
fix: fix memory leak in model loading
docs: update development documentation
```

## 📝 FAQ

### Q: How to get Cesium viewer instance?

A: Get it through `useSpaceStore()`:
```javascript
import { useSpaceStore } from '@/store/spaceStore'
const spaceStore = useSpaceStore()
const viewer = spaceStore.viewer
```

### Q: What if component path configuration is wrong?

A: Ensure `componentPath` is configured correctly:
- Path is relative to `src/views/Home/components/Cesium/` directory
- Does not include `.vue` extension
- Use `/` to separate directory levels

### Q: How to debug feature components?

A: 
1. Add `console.log` in component for debugging
2. Use browser developer tools to view console
3. Check Network panel for API requests
4. Use Vue DevTools to view component state

### Q: How to add a new tool category?

A: Add a new `tabs` item in `cesium-config.json`:
```json
{
  "tabs": [
    {
      "key": "new-category",
      "name": "New Category",
      "tools": [...]
    }
  ]
}
```

## 📄 License

This project is licensed under the [MIT License](./LICENSE).

## 🙏 Acknowledgments

Thanks to all developers who contributed to this project!

## 📮 Contact

- Project URL: https://gitee.com/cesium-developer/open-cesium
- Issue Reports: Please submit in Gitee Issues

---

**Happy Coding! 🚀**