Tellux

中文 | English

Tellux 是一个基于 Three.js 的开源 3D Earth Engine，用于在浏览器中构建数字地球、数字孪生、三维地图以及各类 3D Earth 应用。

它建立在 Three.js 强大的渲染能力与开源生态之上，提供统一的 API 来组织地球相机、Cesium Quantized Mesh 地形、多源影像与矢量图层、3D Tiles、天空大气、体积云及后处理效果，让开发者能够专注于构建从轻量级可视化到复杂三维地球场景的现代 Web 应用。

---

🌐 示例 | 📚 文档 | 🧪 Sandcastle | 💻 GitHub

---

🚀 开始使用

npm

Tellux 是 ESM 包。使用 Vite、Webpack、Rollup 等模块打包器时，安装 Tellux 及其必需的 peer dependencies：

pnpm add tellux three 3d-tiles-renderer @takram/three-geospatial @takram/three-geospatial-effects @takram/three-atmosphere @takram/three-clouds postprocessing

使用 MVT 矢量瓦片时，再安装可选依赖：

pnpm add @mapbox/vector-tile pbf

创建一个具有非零尺寸的容器，然后初始化 Viewer：

<div id="viewer"></div>

<style>
  #viewer {
    width: 100vw;
    height: 100vh;
  }
</style>

import tellux from 'tellux'

const viewer = new tellux.Viewer('viewer', {
  terrain: {
    url: 'https://example.com/terrain/'
  },
  layers: [
    {
      source: {
        type: 'xyz',
        url: 'https://example.com/imagery/{z}/{y}/{x}.png'
      }
    }
  ],
  camera: {
    longitude: 121.4737,
    latitude: 31.2304,
    height: 1200,
    pitch: -25
  }
})

📚 下一步

• 查看快速开始，了解 Draco 解码器、资源路径和 Viewer 生命周期。
• 阅读指南，配置相机、交互、地形、影像、3D Tiles、模型、大气和后处理。
• 在 Sandcastle 中浏览并编辑可运行示例。
• 查看公开 API 与类型参考。
• 希望参与开发？请阅读贡献指南，然后提交 Issue 或 Pull Request；提交信息遵循 Conventional Commits。

⚖️ License

MIT。Tellux 可用于商业和非商业项目。

🌍 地理内容从哪里来？

Tellux 是运行时和渲染库，不绑定或托管任何基础地理内容。你可以自由组合以下数据源：

• 自托管或公开服务提供的 Cesium quantized-mesh 地形、XYZ、WMS、WMTS、GeoJSON、MVT 和 3D Tiles。
• 通过 Cesium Ion token 访问的 terrain、imagery 和 3D Tiles 资源。
• 按经纬高放置的应用自有 glTF / GLB 模型和 Three.js 对象。

Cesium Ion 是可选的数据服务；Tellux 的地形、影像和 3D Tiles API 同时支持自托管 URL 与 Cesium Ion 资源。数据的授权、可用性与访问控制由使用方和数据提供方负责。

✨ 特性

• 在 WGS84 地球上使用经纬高、heading、pitch、roll 控制相机，并支持飞行定位、拾取和高度采样。
• 加载 Cesium quantized-mesh 地形、XYZ、WMS、WMTS、Cesium Ion 影像，以及 GeoJSON、MVT 贴地矢量 overlay。
• 加载 URL 或 Cesium Ion 3D Tiles，并处理 glTF / GLB 模型、动画和贴地放置。
• 使用大气天空、空气透视、体积云、昼夜光照、SMAA、镜头光晕和抖动等效果构建地理场景。
• 与 Three.js 场景、对象、坐标转换及自定义渲染循环互操作。
• 默认使用 WebGL；实验性的 WebGPU renderer 支持基础地球、地形、影像、3D Tiles、模型、拾取与大气，具体限制见能力边界。

🛠️ 开发

命令	说明
pnpm dev	启动示例站点与文档站点开发服务
pnpm type-check	执行 TypeScript 类型检查
pnpm test:run	运行测试
pnpm build	构建库产物和声明文件
pnpm build:examples	构建文档和示例站点