2026-11-07 16:09:06 +08:00
2026-11-07 16:05:56 +08:00
2026-11-07 16:09:06 +08:00
2026-11-07 16:05:56 +08:00
2026-11-07 16:05:56 +08:00
2026-11-07 16:05:56 +08:00
2026-11-07 16:05:56 +08:00
2026-11-07 16:05:56 +08:00
2026-11-07 16:05:56 +08:00
2026-11-07 16:05:56 +08:00

Earth Model Studio

天文教学模型启动器:主页管理/启动模型、从链接导入模型源并下载、设置模型源与启动内存分配。

分层约定(重要)

  • src/ = 启动器:扫描、下载、开窗口、显示启动进度。不渲染、不含任何模型内容、不预置模型源。
  • model/ = 模型的一切:源码、编译后的 dll、场景数据、封面、语言包、共享引擎、契约,独立分发、独立版本。

结论:模型相关代码全部直接存在模型目录里,仓库根目录没有 model-src/ / model-sdk/ 这类旁路目录。 启动器只负责下载和启动;想加新内容 = 在 model/<id>/ 里放模型,src 一行都不用改。

  • UI:C# + .NET 8(可切 .NET 10)+ Avalonia,跨平台
  • 模型加载:AssemblyLoadContext 加载模型自带 dll,契约与 Avalonia 走默认上下文,关窗即卸载
  • 目标平台:macOS arm64 / Windows x64 / Windows arm64,一条命令全部编译

目录结构

EarthModelStudio/
├── EarthModelStudio.sln
├── Directory.Build.props            # 公共构建属性(-p:TargetFramework=net10.0 可切 .NET 10)
├── build.sh / build.ps1             # 构建脚本(build/run/test/publish/models/pack-models)
├── src/                             # ★ 启动器(没有渲染逻辑)
│   └── main/dotnet/EarthModelStudio/
│       ├── Models/                  #   模型清单、设置(只有启动器需要的元数据)
│       ├── Services/                #   目录探测/设置/i18n/模型库/模型源/下载/内存预算/**ModelHost**
│       ├── ViewModels/  Views/      #   主页、下载、设置、模型窗口壳
│       └── Assets/i18n/             #   启动器界面语言包
├── src/test/dotnet/…Tests/          # 离屏校验(启动器页面 + 真实加载模型窗口)
├── model/                           # ★ 模型的一切(源码 + 数据 + dll + 封面 + 语言包)
│   ├── _sdk/EarthModelStudio.ModelSdk/  #  模型契约(启动器与模型唯一的共享代码)
│   ├── _engine/                     #   共享引擎源码(渲染、界面、交互)
│   │   ├── src/                     #     CelestialView / PlanetTexture / EarthModelView …
│   │   └── PreviewGen/              #     用模型渲染器生成封面
│   ├── earth-rotation/
│   │   ├── earth-rotation.json      #   清单
│   │   ├── src/                     #   本模型源码(csproj + 入口工厂)
│   │   └── earth-rotation.model/    #   dll + scene.json/land.json + preview.png + i18n
│   └── earth-revolution/            #   同上结构,封面是公转场景
└── dist/                            # 发布产物(启动器 + 单独打包的模型)

模型库查找顺序:EMS_MODELS 环境变量 → 开发态仓库根 model/ → 可执行文件旁 model/ → 用户数据目录。

构建与运行

./build.sh build         # 编译启动器
./build.sh models        # 编译模型 dll + 生成封面(写进 model/)
./build.sh run           # 运行
./build.sh test          # 离屏校验:页面截图 + 真实加载模型窗口截图
./build.sh publish       # 一次性编译三个平台(启动器,不含模型)
./build.sh pack-models   # 编译模型后打包 -> dist/models-<version>.zip
./build.sh clean

Windows 用 .\build.ps1(参数相同)。

产物 平台
dist/mac-arm64/EarthModelStudio.app macOS Apple Silicon
dist/win-x64/EarthModelStudio.exe Windows x64
dist/win-arm64/EarthModelStudio.exe Windows on ARM

均为自包含单文件启动器,model/ 目录为空(只有 README)。模型用 pack-models 单独分发。

模型契约

public interface IModelFactory        // 模型入口
{
    int ApiVersion { get; }           // 目前为 1
    IModelRuntime Create();
}

public interface IModelRuntime : IDisposable
{
    void Prepare(IModelContext context);         // 后台线程:读数据、烘焙纹理、汇报进度
    Control CreateView(IModelContext context);   // UI 线程:模型自己做界面
}

public interface IModelContext
{
    string ModelId { get; }
    string ModelDirectory { get; }
    string DataDirectory { get; }
    string Language { get; }
    int MemoryBudgetMb { get; }
    void RequestClose();
    void ReportProgress(double value, string? message = null);
    void Log(string message);
}

启动器先弹进度窗,在后台调用 Prepare(模型用 ReportProgress 汇报真实进度), 再在 UI 线程调用 CreateView,把返回的控件直接铺满窗口 —— 除此之外什么都不做。

详细清单字段、数据格式、封面生成见 model/README.md。

模型窗口

  • 启动模型 → 带进度条的加载窗(读取数据 → 生成地表纹理 → 构建界面,真实进度)→ 新开独立窗口
  • 主界面保持原页面,可同时开多个模型窗口;关窗即卸载模型程序集
  • 快捷键 Esc 关闭、F11 全屏(其余快捷键由模型自己决定)

地球模型(model/_engine + model//src)

  • 地表:加载时烘焙 1024×512 等经纬度纹理 —— 海洋深度、沙漠/雨林/针叶林/苔原分带、极地冰盖、 山脉起伏(高度梯度参与光照)、云层、夜间城市辉光;每帧只做双线性采样 + 地形光照,60 FPS
  • 自转:球面像素渲染、晨昏线、大气边缘光、经纬网、地轴、太阳直射点;只有自转视角, 没有节气定位(节气属于公转)
  • 公转:太阳—轨道—地球全景、地轴方向空间固定、二分二至标记与一键定位、HUD
  • 交互:滚轮 / 工具栏 −+ 缩放(0.6×–6×,带缓动);暂停后拖动可旋转地球或沿轨道拖动公转位置; 松手有惯性;缩放、视角、面板都有过渡动画
  • 两个模型共用 model/_engine 的代码,各自 src/ 只提供入口工厂;界面、文案、封面都在模型包里

模型源(git 仓库)

模型源就是普通 git 仓库,仓库根目录下的 model/ 文件夹即模型列表。 支持 https://github.com/<user>/<repo>.git(GitLab / Gitee 同理,走 zip 归档,失败回退 git clone --depth 1)、 zip 直链、本地目录。导入后缓存在 数据目录/cache/sources/<id>,下载时把模型目录复制进本地 model/。

启动时运行内存分配

设置页的「启动时运行内存分配」类似启动器的 -Xmx:启动器把这份预算通过 IModelContext.MemoryBudgetMb 交给模型,具体怎么用(掩膜分辨率、缓存)由模型自己决定。

S
Description
No description provided
Readme
270 MiB
0 Stars 1 Watchers 0 Forks
Generate repository badges
Languages
C# 76.6%
Dart 12.7%
Shell 4%
PowerShell 2.2%
CMake 2.2%
Other 2.1%