# three-gif

**Repository Path**: mwyhm/three-gif

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Three.js 加载和展示 GIF 文件

这是一个完整的 Three.js 加载和展示真实 GIF 文件的示例项目。

## 📁 项目文件

- `index.html` - 主页面（推荐使用）
- `index-alternative.html` - 无依赖版本
- `main.js` - 主程序文件（支持 SuperGif 和降级模式）
- `main-no-dependency.js` - 纯 JavaScript 无依赖版本
- `gif-parser.js` - 自定义 GIF 解析器
- `example-usage.js` - 简化版示例

## 🚀 使用方法

### 推荐方式：index.html（自动降级）

1. 在项目目录启动本地服务器：
   ```bash
   # 使用 Python
   python -m http.server 8000
   
   # 或使用 Node.js http-server
   npx http-server
   ```

2. 在浏览器中打开：`http://localhost:8000`

3. 点击底部按钮选择一个 GIF 文件

4. 程序会自动检测 SuperGif 库是否可用：
   - ✅ SuperGif 可用：完整 GIF 动画支持
   - ⚠️ SuperGif 不可用：自动降级到简化模式（静态图片）

### 备用方式：index-alternative.html（无依赖）

如果上面的方式有问题，使用这个版本：

```bash
# 在浏览器中打开
http://localhost:8000/index-alternative.html
```

这个版本完全不依赖外部 GIF 库，会直接显示静态图片。

## ⚠️ 重要提示

1. **必须使用本地服务器**：浏览器安全策略限制了从 `file://` 协议加载图片，必须使用 HTTP/HTTPS 协议

2. **GIF 文件格式**：确保文件是有效的 GIF 格式（支持动态 GIF）

3. **SuperGif 库**：
   - 如果 `libgif-js` 库加载成功，支持完整的 GIF 动画
   - 如果加载失败，会自动降级到简化模式（只显示静态图片）

4. **CDN 问题**：如果遇到 CDN 加载问题，可以：
   - 使用 `index-alternative.html`（无依赖版本）
   - 或者下载 `libgif-js` 到本地

## 🎮 功能特性

### 基础功能
- ✅ 选择本地 GIF 文件
- ✅ 自动播放 GIF 动画
- ✅ 播放/暂停控制
- ✅ 单帧浏览
- ✅ 显示 GIF 信息（尺寸、帧数、宽高比）

### Three.js 功能
- ✅ 3D 场景渲染
- ✅ 轨道控制器（拖动旋转、滚轮缩放）
- ✅ 自动旋转动画
- ✅ 自适应窗口大小

## 🔧 核心原理

### 工作流程

```
1. 用户选择 GIF 文件
   ↓
2. FileReader 读取文件为 DataURL
   ↓
3. 创建 Image 对象加载图片
   ↓
4. SuperGif 解析 GIF 文件
   ↓
5. 获取 GIF 的 Canvas（自动播放动画）
   ↓
6. 创建 CanvasTexture 包装 Canvas
   ↓
7. 每帧更新纹理：texture.needsUpdate = true
   ↓
8. Three.js 渲染到 3D 对象上
```

### 关键代码

```javascript
// 1. 创建 GIF 加载器
gifLoader = new SuperGif({ 
    gif: img,
    loop_mode: true,
    auto_play: true,
    canvas_mode: true
});

// 2. 加载 GIF
gifLoader.load(function() {
    const canvas = gifLoader.get_canvas();
    
    // 3. 创建纹理
    gifTexture = new THREE.CanvasTexture(canvas);
    
    // 4. 每帧更新
    function update() {
        gifTexture.needsUpdate = true;
        requestAnimationFrame(update);
    }
    update();
});
```

## 🎨 自定义扩展

### 更改几何体

在 `main.js` 的 `createPlaceholder()` 函数中修改：

```javascript
// 立方体
const geometry = new THREE.BoxGeometry(3, 3, 3);

// 球体
const geometry = new THREE.SphereGeometry(2, 32, 32);

// 平面
const geometry = new THREE.PlaneGeometry(4, 4);

// 圆柱体
const geometry = new THREE.CylinderGeometry(1.5, 1.5, 3, 32);
```

### 添加更多对象

```javascript
// 创建第二个对象
const geometry2 = new THREE.SphereGeometry(1, 32, 32);
const material2 = new THREE.MeshBasicMaterial({ map: gifTexture });
const sphere = new THREE.Mesh(geometry2, material2);
sphere.position.set(3, 0, 0);
scene.add(sphere);
```

### 更改背景

```javascript
// 纯色背景
scene.background = new THREE.Color(0x000000);

// 渐变背景（使用 CSS）
body {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}
```

## 📦 依赖库

- **Three.js r128** - 3D 渲染引擎
- **OrbitControls** - 相机控制器
- **libgif-js (SuperGif)** - GIF 解析库

## 🔍 故障排除

### 问题：SuperGif is not defined

**原因**：`libgif-js` 库未正确加载

**解决方案**：
1. **使用自动降级版本**：直接打开 `index.html`，会自动降级到简化模式
2. **使用无依赖版本**：打开 `index-alternative.html`
3. **手动下载库**：
   ```bash
   # 下载 libgif-js 到本地
   curl -o libgif.min.js https://cdn.jsdelivr.net/npm/libgif-js@0.0.3/libgif.min.js
   ```
   然后修改 `index.html`：
   ```html
   <script src="libgif.min.js"></script>
   ```

### 问题：GIF 无法加载

**原因**：浏览器的 CORS 策略限制

**解决**：使用本地服务器而不是直接打开 HTML 文件

### 问题：GIF 显示静态图片

**原因**：
1. 使用了简化模式（降级模式）
2. SuperGif 库加载失败

**解决**：检查浏览器控制台是否有错误信息，尝试使用不同的加载方式

### 问题：CDN 加载失败

**解决**：
1. 检查网络连接
2. 使用 `index-alternative.html`（无 CDN 依赖）
3. 或者将需要的库下载到本地

### 问题：GIF 比例不对

**解决**：在 `onGifLoaded()` 中已自动调整，如需手动调整：

```javascript
gifMesh.scale.set(x, y, z);
```

## 📚 参考资料

- [Three.js 官方文档](https://threejs.org/docs/)
- [SuperGif 项目](https://github.com/buzzfeed/libgif-js)
- [CanvasTexture 文档](https://threejs.org/docs/#api/en/textures/CanvasTexture)

## 💡 最佳实践

1. **性能优化**：对于大尺寸 GIF，考虑缩小尺寸
2. **内存管理**：及时清理不需要的 GIF 对象
3. **用户体验**：添加加载进度提示
4. **错误处理**：妥善处理 GIF 加载失败的情况