three-earth-3d 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 GhostCat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,303 @@
+# three-earth-3d
+
+[![npm](https://img.shields.io/npm/v/three-earth-3d)](https://www.npmjs.com/package/three-earth-3d)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+A 3D Earth visualization component built with [Three.js](https://threejs.org/), mountable to any DOM element.
+
+> This project is a refactored version of [GhostCatcg/3d-earth](https://github.com/GhostCatcg/3d-earth). It migrates the build system to Vite and publishes the project as an npm package, enabling multiple independent 3D Earth instances to be created in any frontend project.
+
+![Preview](./3d-earth.png)
+
+**[中文 README](./README.md)**
+
+---
+
+## Features
+
+- 🌏 Earth texture with animated scan-light shader
+- ✨ Glow and atmosphere effects
+- 🛰 Orbiting satellite rings
+- 🇨🇳 City markers + city labels (rendered via html2canvas)
+- 🪐 Animated arc fly-lines between cities
+- 🎛 Fully configurable options and custom data
+- 🔧 `dispose()` method for clean instance teardown
+
+---
+
+## Installation
+
+```bash
+# pnpm
+pnpm add three-earth-3d three
+
+# npm
+npm install three-earth-3d three
+
+# yarn
+yarn add three-earth-3d three
+```
+
+> `three` is a **peerDependency** and must be installed separately. Requires `three >= 0.130.0`.
+
+---
+
+## Quick Start
+
+### 1. Set up static assets
+
+A built-in CLI tool copies all textures to your project's `public/` directory in **one command**:
+
+```bash
+# Copy to ./public/images/earth/ (default)
+npx three-earth-3d
+
+# Or specify a custom destination (e.g. Nuxt / SvelteKit's static/)
+npx three-earth-3d --dest static
+```
+
+Resulting structure:
+
+```
+public/
+└── images/
+    └── earth/
+        ├── earth.jpg        ← Earth texture map (~2.4 MB)
+        ├── glow.png
+        ├── gradient.png
+        ├── aperture.png
+        ├── label.png
+        ├── light_column.png
+        ├── redCircle.png
+        └── aircraft.png
+```
+
+> **Why not bundle images into the JS?**  
+> `earth.jpg` is ~2.4 MB. Inlining it as base64 would inflate the bundle to ~3 MB, which is unacceptable.  
+> Serving images separately allows browser caching and makes it easy to swap in a custom Earth texture.
+
+### 2. HTML markup
+
+The container must have an explicit width and height — the Earth will fill it:
+
+```html
+<div id="earth-canvas" style="width: 100%; height: 100vh; background: #010826;"></div>
+```
+
+### 3. Initialize
+
+```typescript
+import { World } from 'three-earth-3d'
+
+const world = new World({
+  dom: document.getElementById('earth-canvas'),
+  // Base path where images are hosted (parent of /images/earth/)
+  // e.g. if images are at /public/images/earth/, set baseUrl to '' or '/'
+  baseUrl: '',
+  onReady() {
+    console.log('Earth is ready!')
+  },
+})
+```
+
+### 4. Destroy
+
+```typescript
+world.dispose()
+```
+
+---
+
+## Full Options
+
+```typescript
+import { World } from 'three-earth-3d'
+
+const world = new World({
+  /** Required: target DOM element */
+  dom: document.getElementById('earth-canvas'),
+
+  /**
+   * Base URL for static image assets.
+   * Images are loaded from `${baseUrl}/images/earth/`.
+   * Default: '' (loads from /images/earth/ at site root)
+   */
+  baseUrl: '',
+
+  /** Fired after the Earth is initialized and the entrance animation begins */
+  onReady: () => { console.log('ready') },
+
+  /**
+   * Custom route data. Omit to use the built-in demo data.
+   * Each entry has one start point and multiple end points.
+   */
+  data: [
+    {
+      startArray: { name: 'Beijing', E: 116.322056, N: 39.89491 },
+      endArray: [
+        { name: 'Shanghai', E: 121.473701, N: 31.230416 },
+        { name: 'Guangzhou', E: 113.264385, N: 23.129112 },
+      ],
+    },
+  ],
+
+  /** Earth settings */
+  earth: {
+    radius: 50,          // Earth radius. Default: 50
+    rotateSpeed: 0.002,  // Auto-rotation speed. Default: 0.002
+    isRotation: true,    // Enable auto-rotation. Default: true
+  },
+
+  /** Satellite settings */
+  satellite: {
+    show: true,          // Show satellites. Default: true
+    rotateSpeed: -0.01,  // Orbit rotation speed. Default: -0.01
+    size: 1,             // Satellite sphere size. Default: 1
+    number: 2,           // Satellites per ring. Default: 2
+  },
+
+  /** Marker and light-pillar settings */
+  punctuation: {
+    circleColor: 0x3892ff,   // Base ring color
+    lightColumn: {
+      startColor: 0xffffff,  // Start-point pillar color
+      endColor: 0xff0000,    // End-point pillar color
+    },
+  },
+
+  /** Fly-line settings */
+  flyLine: {
+    color: 0xd18547,         // Arc track line color
+    speed: 0.004,            // Fly-line trailing speed
+    flyLineColor: 0xff7714,  // Fly-line dot color
+  },
+})
+```
+
+---
+
+## API
+
+### `new World(options: IWord)`
+
+Creates a 3D Earth instance and mounts it to the specified DOM element.
+
+### `world.dispose()`
+
+Destroys the instance: releases the WebGL context, stops the animation loop, removes DOM elements, and cleans up event listeners. Always call this when navigating away in SPAs.
+
+---
+
+## Framework Integration
+
+### Vue 3
+
+```vue
+<template>
+  <div ref="earthEl" class="earth-container" />
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, onBeforeUnmount } from 'vue'
+import { World } from 'three-earth-3d'
+
+const earthEl = ref<HTMLElement | null>(null)
+let world: World | null = null
+
+onMounted(() => {
+  world = new World({
+    dom: earthEl.value!,
+    baseUrl: '',
+  })
+})
+
+onBeforeUnmount(() => {
+  world?.dispose()
+})
+</script>
+
+<style scoped>
+.earth-container {
+  width: 100%;
+  height: 100vh;
+  background: #010826;
+}
+</style>
+```
+
+### React
+
+```tsx
+import { useEffect, useRef } from 'react'
+import { World } from 'three-earth-3d'
+
+export default function EarthView() {
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const world = new World({
+      dom: containerRef.current!,
+      baseUrl: '',
+    })
+    return () => world.dispose()
+  }, [])
+
+  return (
+    <div
+      ref={containerRef}
+      style={{ width: '100%', height: '100vh', background: '#010826' }}
+    />
+  )
+}
+```
+
+---
+
+## Local Development
+
+```bash
+# Clone
+git clone https://github.com/adoin/three-earth-3d.git
+cd three-earth-3d
+
+# Install dependencies
+pnpm install
+
+# Start dev server (http://localhost:5173)
+pnpm dev
+
+# Build the library (outputs to dist/)
+pnpm build
+
+# Build demo and preview production output (http://localhost:4173)
+pnpm preview
+```
+
+---
+
+## Notes
+
+1. **Static assets**: The package does not bundle images. Copy `static/images/earth/` to your `public` folder or CDN and point `baseUrl` to their parent path.
+
+2. **Container dimensions**: The mount element must have a defined width and height, otherwise the render size is 0.
+
+3. **Multiple instances**: Each `new World()` creates an independent WebGL context. Browsers typically allow 8–16 simultaneous WebGL contexts. Call `dispose()` on instances that are no longer needed.
+
+---
+
+## Credits
+
+This project is based on [GhostCatcg/3d-earth](https://github.com/GhostCatcg/3d-earth). Many thanks to the original author **GhostCat** for the creative work and implementation.
+
+Key changes in this fork:
+- Build tool migrated from **Webpack** to **Vite** with library mode output
+- Published as an **npm package** — instantiate via `new World({ dom })`
+- Asset paths changed from hardcoded to configurable via `baseUrl`
+- Renderer size now derived from `dom.offsetWidth/Height` instead of the global `window`
+- Added `onReady` callback, `dispose()` method, and full TypeScript type exports
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/README.md

@@ -0,0 +1,303 @@
+# three-earth-3d
+
+[![npm](https://img.shields.io/npm/v/three-earth-3d)](https://www.npmjs.com/package/three-earth-3d)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+基于 [Three.js](https://threejs.org/) 构建的 3D 地球可视化组件，可挂载到任意 DOM 元素上。
+
+> 本项目由 [GhostCatcg/3d-earth](https://github.com/GhostCatcg/3d-earth) 改造而来，在其基础上迁移至 Vite 构建体系，并以 npm 包的形式发布，支持在任意前端项目中实例化多个独立的 3D 地球。
+
+![预览图](./3d-earth.png)
+
+**[English README](./README.en.md)**
+
+---
+
+## 功能特性
+
+- 🌏 地球贴图 + 扫光 Shader 动画
+- ✨ 辉光、大气层效果
+- 🛰 卫星轨道环绕
+- 🇨🇳 城市标点 + 城市标签（html2canvas 渲染）
+- 🪐 城市间弧线飞线
+- 🎛 全部参数可配置，支持自定义数据
+- 🔧 提供 `dispose()` 方法，干净销毁实例
+
+---
+
+## 安装
+
+```bash
+# pnpm
+pnpm add three-earth-3d three
+
+# npm
+npm install three-earth-3d three
+
+# yarn
+yarn add three-earth-3d three
+```
+
+> `three` 为 **peerDependency**，需要单独安装，支持 `three >= 0.130.0`。
+
+---
+
+## 快速上手
+
+### 1. 准备静态资源
+
+包内提供了一个 CLI 工具，**一条命令**即可将所有贴图复制到你项目的 `public/` 目录：
+
+```bash
+# 复制到 ./public/images/earth/（默认）
+npx three-earth-3d
+
+# 或指定目标目录（例如 Nuxt / SvelteKit 的 static/）
+npx three-earth-3d --dest static
+```
+
+执行后目录结构如下：
+
+```
+public/
+└── images/
+    └── earth/
+        ├── earth.jpg        ← 地球贴图（主要素材，约 2.4 MB）
+        ├── glow.png
+        ├── gradient.png
+        ├── aperture.png
+        ├── label.png
+        ├── light_column.png
+        ├── redCircle.png
+        └── aircraft.png
+```
+
+> **为什么不内置到 JS 里？**  
+> `earth.jpg` 约 2.4 MB，base64 内联后会让 bundle 膨胀到 ~3 MB，得不偿失。  
+> 独立部署贴图可以被浏览器缓存，也更容易替换成自定义地球图。
+
+### 2. HTML 结构
+
+容器需要有明确的宽高，地球会撑满容器：
+
+```html
+<div id="earth-canvas" style="width: 100%; height: 100vh; background: #010826;"></div>
+```
+
+### 3. 初始化
+
+```typescript
+import { World } from 'three-earth-3d'
+
+const world = new World({
+  dom: document.getElementById('earth-canvas'),
+  // 图片所在的基础路径（相对或绝对），对应 /images/earth/ 的上级
+  // 例如图片放在 /public/images/earth/，baseUrl 填 '' 或 '/'
+  baseUrl: '',
+  onReady() {
+    console.log('地球加载完成！')
+  },
+})
+```
+
+### 4. 销毁
+
+```typescript
+world.dispose()
+```
+
+---
+
+## 完整配置项
+
+```typescript
+import { World } from 'three-earth-3d'
+
+const world = new World({
+  /** 必填：挂载的 DOM 元素 */
+  dom: document.getElementById('earth-canvas'),
+
+  /**
+   * 静态图片资源根路径
+   * 组件会在 `${baseUrl}/images/earth/` 下加载图片
+   * 默认值：''（即从网站根路径 /images/earth/ 加载）
+   */
+  baseUrl: '',
+
+  /** 地球初始化并开始入场动画后触发 */
+  onReady: () => { console.log('ready') },
+
+  /**
+   * 自定义航线数据，不传则使用内置示例数据（北京/杭州为起点的航线）
+   * 每一条记录包含一个起点和多个终点
+   */
+  data: [
+    {
+      startArray: { name: '北京', E: 116.322056, N: 39.89491 },
+      endArray: [
+        { name: '上海', E: 121.473701, N: 31.230416 },
+        { name: '广州', E: 113.264385, N: 23.129112 },
+      ],
+    },
+  ],
+
+  /** 地球参数 */
+  earth: {
+    radius: 50,          // 地球半径，默认 50
+    rotateSpeed: 0.002,  // 自转速度，默认 0.002
+    isRotation: true,    // 是否自转，默认 true
+  },
+
+  /** 卫星参数 */
+  satellite: {
+    show: true,          // 是否显示卫星，默认 true
+    rotateSpeed: -0.01,  // 轨道旋转速度，默认 -0.01
+    size: 1,             // 卫星球体大小，默认 1
+    number: 2,           // 每条轨道的卫星数量，默认 2
+  },
+
+  /** 标点和光柱参数 */
+  punctuation: {
+    circleColor: 0x3892ff,    // 底座圆圈颜色
+    lightColumn: {
+      startColor: 0xffffff,   // 起点光柱颜色
+      endColor: 0xff0000,     // 终点光柱颜色
+    },
+  },
+
+  /** 飞线参数 */
+  flyLine: {
+    color: 0xd18547,          // 轨迹线颜色
+    speed: 0.004,             // 飞线拖尾运动速度
+    flyLineColor: 0xff7714,   // 飞线自身颜色
+  },
+})
+```
+
+---
+
+## API
+
+### `new World(options: IWord)`
+
+创建一个 3D 地球实例并挂载到指定 DOM。
+
+### `world.dispose()`
+
+销毁实例，释放 WebGL 上下文、停止动画循环、移除 DOM 元素及监听器。在 SPA 框架中切换路由时务必调用。
+
+---
+
+## 在框架中使用
+
+### Vue 3
+
+```vue
+<template>
+  <div ref="earthEl" class="earth-container" />
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, onBeforeUnmount } from 'vue'
+import { World } from 'three-earth-3d'
+
+const earthEl = ref<HTMLElement | null>(null)
+let world: World | null = null
+
+onMounted(() => {
+  world = new World({
+    dom: earthEl.value!,
+    baseUrl: '',
+  })
+})
+
+onBeforeUnmount(() => {
+  world?.dispose()
+})
+</script>
+
+<style scoped>
+.earth-container {
+  width: 100%;
+  height: 100vh;
+  background: #010826;
+}
+</style>
+```
+
+### React
+
+```tsx
+import { useEffect, useRef } from 'react'
+import { World } from 'three-earth-3d'
+
+export default function EarthView() {
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const world = new World({
+      dom: containerRef.current!,
+      baseUrl: '',
+    })
+    return () => world.dispose()
+  }, [])
+
+  return (
+    <div
+      ref={containerRef}
+      style={{ width: '100%', height: '100vh', background: '#010826' }}
+    />
+  )
+}
+```
+
+---
+
+## 本地开发
+
+```bash
+# 克隆
+git clone https://github.com/adoin/three-earth-3d.git
+cd three-earth-3d
+
+# 安装依赖
+pnpm install
+
+# 启动开发服务器（访问 http://localhost:5173）
+pnpm dev
+
+# 构建库产物（输出到 dist/）
+pnpm build
+
+# 构建 demo 并预览生产效果（访问 http://localhost:4173）
+pnpm preview
+```
+
+---
+
+## 注意事项
+
+1. **图片资源**：组件本身不内置图片，需要将 `static/images/earth/` 下的素材部署到你的 public 或 CDN，并通过 `baseUrl` 指向其上级路径。
+
+2. **容器尺寸**：挂载的 DOM 必须有确定的宽高，否则渲染尺寸为 0。
+
+3. **多实例**：每个 `new World()` 会创建独立的 WebGL 上下文，注意浏览器对同时存在的 WebGL 上下文数量有限制（通常 8~16 个），请在不需要时及时调用 `dispose()`。
+
+---
+
+## 致谢
+
+本项目基于 [GhostCatcg/3d-earth](https://github.com/GhostCatcg/3d-earth) 改造，感谢原作者 **GhostCat** 的创意与实现。
+
+主要改动：
+- 构建工具从 Webpack 迁移至 **Vite**，支持库模式打包
+- 以 **npm 包**形式发布，可在任意项目中通过 `new World({ dom })` 实例化
+- 资源路径由硬编码改为可配置的 `baseUrl`
+- 挂载容器改用 `dom.offsetWidth/Height` 而非全局 `window` 尺寸
+- 新增 `onReady` 回调、`dispose()` 方法及完整 TypeScript 类型导出
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/bin/copy-assets.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * three-earth-3d copy-assets
+ *
+ * 将包内的静态贴图资源复制到消费方项目的 public 目录。
+ *
+ * 用法：
+ *   npx three-earth-3d                  → 复制到 ./public/images/earth/
+ *   npx three-earth-3d --dest static    → 复制到 ./static/images/earth/
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+// 解析 --dest 参数，默认 public
+const destArg = (() => {
+  const idx = process.argv.indexOf('--dest')
+  return idx !== -1 ? process.argv[idx + 1] : 'public'
+})()
+
+const SRC_DIR = path.resolve(__dirname, '../static/images/earth')
+const DEST_DIR = path.resolve(process.cwd(), destArg, 'images/earth')
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true })
+  const entries = fs.readdirSync(src, { withFileTypes: true })
+  let count = 0
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath)
+    } else {
+      fs.copyFileSync(srcPath, destPath)
+      console.log(`  ✔  ${entry.name}`)
+      count++
+    }
+  }
+  return count
+}
+
+console.log(`\nthree-earth-3d: copying assets`)
+console.log(`  from: ${SRC_DIR}`)
+console.log(`  to:   ${DEST_DIR}\n`)
+
+try {
+  if (!fs.existsSync(SRC_DIR)) {
+    console.error('❌  Source assets not found. Please reinstall three-earth-3d.')
+    process.exit(1)
+  }
+
+  const count = copyDir(SRC_DIR, DEST_DIR)
+  console.log(`\n✅  Done! ${count} files copied to ${path.relative(process.cwd(), DEST_DIR)}`)
+  console.log(`\n   Now set  baseUrl: ''  (or your custom path) when calling new World().\n`)
+} catch (err) {
+  console.error('❌  Copy failed:', err.message)
+  process.exit(1)
+}