@geoql/maplibre-gl-starfield

中文文档
0.1.4发布于 2026/10/29MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 2477

一个 MapLibre GL JS 自定义层,用于渲染一个带有银河系全景的 Three.js Starfield 天盒

中文使用文档
文档目录10 节
  1. 安装
  2. 使用量
  3. 选项
  4. 银河纹理
  5. 如何运作
  6. 出口
  7. 所需资源
  8. 捐款
  9. 更多来自作者
  10. 许可证

@geoql/ maplibre-gl-starfield (英语)

三.js 星地天盒自定义层 MapLibre GL 联合来文 地球预测.

npm version JSR npm bundle size License: MIT

oxlint tsdown typescript

现场演示 • 妇女 无 • 妇女 日 尔

将可选的等角星系/密道全景纹理与可配置的亮度相接,再用添加剂混合成上千个个点星. 适合需要类似空间背景的地球投影图——地震可视化,卫星跟踪仪,飞行路径等等.

安装

# npm
npm install @geoql/maplibre-gl-starfield maplibre-gl three

# pnpm
pnpm add @geoql/maplibre-gl-starfield maplibre-gl three

# yarn
yarn add @geoql/maplibre-gl-starfield maplibre-gl three

# JSR
pnpm dlx jsr add @geoql/maplibre-gl-starfield

使用量

import * as maplibregl from 'maplibre-gl';
import { MaplibreStarfieldLayer } from '@geoql/maplibre-gl-starfield';
import 'maplibre-gl/dist/maplibre-gl.css';

const map = new maplibregl.Map({
  container: 'map',
  style: {
    version: 8,
    projection: { type: 'globe' },
    sources: {
      satellite: {
        type: 'raster',
        tiles: [
          'https://tiles.maps.eox.at/wmts/1.0.0/s2cloudless-2020_3857/default/g/{z}/{y}/{x}.jpg',
        ],
        tileSize: 256,
        attribution: '© EOX IT Services GmbH - S2 Cloudless',
      },
    },
    layers: [{ id: 'satellite', type: 'raster', source: 'satellite' }],
  },
  center: [0, 20],
  zoom: 1.5,
});

map.on('load', () => {
  const starfield = new MaplibreStarfieldLayer({
    galaxyTextureUrl: '/milkyway.jpg', // your panorama image
    galaxyBrightness: 0.35,
    starCount: 4000,
    starSize: 2.0,
  });

  // Add below all other layers so stars render behind the globe
  map.addLayer(starfield, map.getStyle().layers[0]?.id);
});

选项

interface MaplibreStarfieldLayerOptions {
  id?: string;
  starCount?: number;
  starSize?: number;
  starColor?: number;
  galaxyTextureUrl?: string;
  galaxyBrightness?: number;
}
选项类型默认说明
idstring'starfield'独特的层 ID
starCountnumber4000单个点星数
starSizenumber2.0恒星基点大小(随机±60%)
starColornumber0xffffff点星的正弦颜色
galaxyTextureUrlstringundefinedURL 到正方形全景图像 。 如果省去,则只让点星渲染出.
galaxyBrightnessnumber0.35银河纹理的亮度乘以 (0-1)

银河纹理

这个图书馆的确是 没有 捆绑一个银河系图像。 您需要通过 galaxyTextureUrl。 。 。 .

一个伟大的自由选择是 ESO/S. Brunier 银河全景 (单位:千美元)来源),根据 CC BY 4.0 (英语)。为了在质量和文件大小方面保持良好的平衡,下载并调整大小为~4096x2048:

# Download the 6000×3000 original (8 MB)
curl -o milkyway_full.jpg "https://cdn.eso.org/images/large/eso0932a.jpg"

# Resize to 4096×2048 (~3 MB)
sips --resampleWidth 4096 milkyway_full.jpg --out public/milkyway.jpg

归属:ESO/S.布鲁尼尔 - CC BY 4.0 (英语)

如何运作

该图层执行 MapLibre 的 CustomLayerInterface 并和 MapLibre 共享 WebGL 上下文 :

  1. 银河系 -一个三.js SphereGeometry 与 BackSide 渲染, 以全景图像纹理 。 通过顶点遮蔽术在接近无限深度的地方被渲染出.
  2. 点星 (单位:千美元) Points 以天然发光的添加剂混合制成.
  3. 相机同步 ——投影矩阵从MapLibre的模型-视图-投影矩阵中分解出,并脱去翻译,因此无论缩放/平放,天盒都保持无限.

出口

// Main class
export { MaplibreStarfieldLayer } from '@geoql/maplibre-gl-starfield';

// Default export (same class)
export { default } from '@geoql/maplibre-gl-starfield';

// Types
export type { MaplibreStarfieldLayerOptions } from '@geoql/maplibre-gl-starfield';

所需资源

  • MapLibre GL 联合来文
  • 三.js 0.135.0 (韩语)
  • 节点.js 24.0.0

捐款

  1. 叉并创建特性分支从 main
  2. 以下更改 常规承诺
  3. 确保承诺得到签署(为什么?(中文(简体) )
  4. 提交 PR
pnpm install
pnpm run build
pnpm run lint
pnpm run typecheck

演示会住在这里 example/ 并运行在云浮工人在 马图利布尔-gl-starfield.geoql.in。使用节点 26 或后会.

pnpm run dev:demo     # local dev server
pnpm run build:demo   # build the library, then the demo
pnpm run deploy:demo  # build and deploy the Worker (needs wrangler login)

更多来自作者

见每个项目 vinayakkulkarni.dev/项目 财务报告和审定财务报表 地理单位。 。 。 .

许可证

麻省理工学院

版本与发布记录

@geoql/maplibre-gl-starfield 共发布 7 个版本,首次发布于 2026/02/08;过去 12 个月发布了 7 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.1.4latest2026/10/2917 天前
0.1.32026/10/2819 天前
0.1.22026/08/153 个月前
0.1.12026/02/248 个月前
0.1.02026/02/208 个月前
0.0.22026/02/089 个月前

关于 @geoql/maplibre-gl-starfield 的常见问题

@geoql/maplibre-gl-starfield 是什么?

一个 MapLibre GL JS 自定义层,用于渲染一个带有银河系全景的 Three.js Starfield 天盒

如何安装 @geoql/maplibre-gl-starfield?

在项目目录运行 npm install @geoql/maplibre-gl-starfield,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:three(>=0.135.0)、maplibre-gl(>=3.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@geoql/maplibre-gl-starfield 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geoql/maplibre-gl-starfield 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@geoql/maplibre-gl-starfield 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@geoql/maplibre-gl-starfield 可以商用吗?

@geoql/maplibre-gl-starfield 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@geoql/maplibre-gl-starfield 的下载量有多少?

根据 npm 官方下载统计,@geoql/maplibre-gl-starfield 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,477 次,日均约 83 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geoql/maplibre-gl-starfield 还在维护吗?

最新版本 0.1.4 发布于 2026/10/29(17 天前);至今共发布 7 个版本,其中过去 12 个月发布了 7 个;首次发布于 2026/02/08。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。