Files
GC-XH/README.md
T
2026-11-07 16:05:56 +08:00

127 lines
6.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/` → 用户数据目录。
## 构建与运行
```bash
./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` 单独分发。
## 模型契约
```csharp
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`](model/README.md)。
## 模型窗口
- 启动模型 → **带进度条的加载窗**(读取数据 → 生成地表纹理 → 构建界面,真实进度)→ 新开独立窗口
- 主界面保持原页面,可同时开多个模型窗口;关窗即卸载模型程序集
- 快捷键 `Esc` 关闭、`F11` 全屏(其余快捷键由模型自己决定)
## 地球模型(model/_engine + model/<id>/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`
交给模型,具体怎么用(掩膜分辨率、缓存)由模型自己决定。