# cesiumjs-demo

**Repository Path**: rzcgis/cesiumjs-demo

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-20
- **Last Updated**: 2025-08-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CesiumJS Demo Project

This project demonstrates various CesiumJS features in a modular structure with multiple demos.

AI-Agent开发必须遵守：[AI-Agent开发规范](./docs/AI-Agent-开发规范.md)

## Project Structure

```
src/
├── App.vue                  # Main application component
├── main.js                  # Application entry point
├── demoRegistry.js          # Demo registry (auto-generated)
├── demoLoader.js            # Demo loader (auto-generated)
├── demoLoader.template.js   # Template for demoLoader.js
├── demoRegistry.template.js # Template for demoRegistry.js
├── assets/                  # Static assets
├── components/              # General components
│   ├── DemoNavigation.vue   # Navigation component for switching demos
│   └── DemoInfo.vue         # Demo information component
├── core/                    # Core components that can be reused
│   └── BaseCesiumViewer.vue # Base Cesium viewer component
├── demos/                   # Individual demo components
│   ├── DemoTemplate.vue     # Template for creating new demos
│   ├── PolygonAnimationDemo.utils.js # Demo-specific utilities
│   ├── PolygonAnimationDemo.vue
│   ├── PointAnimationDemo.vue
│   ├── BillboardDemo.vue
│   └── PathAnimationDemo.vue
└── utils/                   # Utility functions
    ├── index.js             # Main utility export
    ├── viewerUtils.js       # Viewer-related utilities
    ├── entityUtils.js       # Entity creation utilities
    ├── animationUtils.js    # Animation utilities
    └── demoUtils.js         # Demo utilities (auto-generated)
    └── demoUtils.template.js # Template for demoUtils.js
```

## How to Add a New Demo

**IMPORTANT: Always use the automated script to add new demos. Manual creation can lead to issues with source code loading and other functionality.**

### Method 1: Automated Creation (Recommended and Only Supported Method)

Use the provided script to automatically create a new demo:

```bash
npm run add-demo <DemoName> "<Demo Title>" ["<Demo Description>"] ["<Category>"]
```

For example:
```bash
npm run add-demo PolygonDemo "Polygon Demo" "This demo shows how to create polygons" "Basic"
```

This will:
1. Create a new Vue component in `src/demos/` based on the demo template
2. Automatically register the demo in `src/demoRegistry.js`
3. Add the demo to `src/demoLoader.js` for dynamic loading
4. Add the demo to `src/utils/demoUtils.js` for source code loading
5. All files are automatically generated from templates if they don't exist

### Removing a Demo

To properly remove a demo and clean up all references:

```bash
npm run remove-demo <DemoName>
```

For example:
```bash
npm run remove-demo PolygonDemo
```

This will:
1. Remove all references to the demo from the registry files
2. Delete the demo component file

## Development Plan

The development tasks are tracked in [docs/development-list.md](docs/development-list.md). This file contains a comprehensive list of planned, in-progress, and completed demos and features.

To work on items from the development list:
1. Check the status in [development-list.md](docs/development-list.md)
2. Select an item marked as "Planned" or "Not Started"
3. Create the demo using the automated script (`npm run add-demo`)
4. Update the status in [development-list.md](docs/development-list.md) to "In Progress" or "Done" as appropriate

## Working with the Development List

To work on demos from the [development-list.md](docs/development-list.md):

1. Check the development list for items marked as "Planned" (🔵) or "Not Started" (⚪)
2. Choose an item to implement
3. Create the demo using the automated script (`npm run add-demo`)
4. Update the development list to reflect the current status

For example, when working on "3D Model Animation":
1. Find the item in [development-list.md](docs/development-list.md)
2. Change its status from "Not Started" (⚪) to "In Progress" (🟡)
3. Implement the demo using `npm run add-demo ModelAnimation "Model Animation" "Animating 3D models" "Advanced"`

This helps track progress and ensures work is done according to the project plan.

## Utility Functions

The utility functions are now organized into separate modules to prevent the "bloat" problem:

### Viewer Utilities (`viewerUtils.js`)
- `setViewRectangle` - Set the camera view to a specific rectangle
- `setViewPosition` - Set the camera view to a specific position

### Entity Utilities (`entityUtils.js`)
- `createPolygon` - Create static polygons
- `createPoint` - Create static points
- `createBillboard` - Create static billboards
- `createLabel` - Create labels

### Animation Utilities (`animationUtils.js`)
- `createAnimatedPolygon` - Create polygons with animated materials
- `createAnimatedPoint` - Create points with animated properties
- `createAnimatedBillboard` - Create billboards with animated properties
- `createPathAnimation` - Create moving entities along a path

### Demo-Specific Utilities
For utilities that are only used in a single demo, create a demo-specific utility file:
- `MyDemo.utils.js` for utilities only used in `MyDemo.vue`

This approach prevents the utility files from growing indefinitely as more demos are added.

## Managing Cesium Bundle Size

This project implements several strategies to manage Cesium's large bundle size:

1. **Code Splitting**: Cesium is bundled separately from the main application
2. **Lazy Loading**: Demos are loaded on-demand when selected
3. **Tree Shaking**: Unused Cesium modules are excluded from the build
4. **Asset Optimization**: Cesium assets are copied directly rather than bundled
5. **Modular Utilities**: Only import the utility functions you need

### Customizing Cesium Build (Advanced)

For further size reduction, you can create a custom Cesium build that includes only the modules you need:

1. Install the Cesium source code: `npm install cesium --save-dev`
2. Create a custom build configuration
3. Build the custom version: `node Build/build.js --include-only [modules]`

See the [Cesium documentation](https://cesium.com/docs/custom-builds/) for more details on custom builds.

## Available Demos

1. **Polygon Animation Demo** - Demonstrates animated polygon materials
2. **Point Animation Demo** - Shows animated point entities
3. **Billboard Animation Demo** - Features animated billboard entities
4. **Path Animation Demo** - Illustrates moving entities along a path

## Component Architecture

All demo components follow a consistent pattern:

1. They use the [BaseCesiumViewer.vue](src/core/BaseCesiumViewer.vue) component to create a Cesium viewer
2. They listen for the `viewer-ready` event to initialize their content
3. They use the Composition API with the `setup()` function
4. They properly handle cleanup when components are unmounted

This approach ensures that:
- The viewer is properly initialized before any operations are performed
- Components are not trying to access a null viewer reference
- The code is more reliable and less prone to timing issues

## Development

### Project setup
```
npm install
```

### Compiles and hot-reloads for development
```
npm run serve
```

### Compiles and minifies for production
```
npm run build
```

### Lints and fixes files
```
npm run lint
```

## Modular Design Benefits

This project structure provides several benefits:

1. **Reusability**: The `BaseCesiumViewer` component can be extended by all demos
2. **Maintainability**: Each demo is isolated in its own component
3. **Extensibility**: Adding new demos is straightforward with the automated scripts
4. **Code Organization**: Related functionality is grouped together
5. **Separation of Concerns**: UI, logic, and utilities are separated
6. **Scalability**: The modular utility system prevents bloat as demos are added
7. **Automation**: Scripts automatically manage demo registration and cleanup