企业官网建设流程全解析

• 桌面应用
• 图形学
• 科研

导读

本文以 Stellarium 开源仓库中 navajo 星空文化包 的核心描述文档 description.md 为骨架，完整讲解纳瓦霍（Navajo）星空文化在 Stellarium 中的呈现方式：文化背景、8 个传统星座的连线定义、description.md在程序中的加载与渲染链路，以及如何在自己的 Stellarium 中启用与验证这一星空文化。读完本文，你将掌握 Stellarium 星空文化包的文件结构与配置格式，并理解描述文档如何被底层源码（StelSkyCultureMgr.cpp）解析为星空讲解文字与介绍信息。

一、纳瓦霍星空文化：从文档到星空

1.1 文化背景

description.md 的 Introduction 明确交代了纳瓦霍人的地理与文化范围：

The Navajo are the largest Native American tribe in the United States; the Navajo Nation extends across northeastern Arizona, southeastern Utah, and northwestern New Mexico.

纳瓦霍族是美国最大的原住民族，其保留地（Navajo Nation）横跨亚利桑那州东北部、犹他州东南部与新墨西哥州西北部。正是基于这一文化群体的传统星图，Stellarium 构建了独立的navajo星空文化包。

1.2 文档的元信息：作者与许可证

文档元信息完整记录了该文化包的可溯源性与合法性：

• 贡献者：Karrie Berglund（Digitalis Education Solutions, Inc.），内容主要依据 Don Childrey 的著作Star Trails-Navajo；
• 许可证：GNU GPL v2.0，与 Stellarium 整体开源许可保持一致；
• 参考资料：文档列举了纳瓦霍官方站点及 Clark Foundation Astro-Utah 项目关于 Dilyehe、Rabbit、Laws 等神话的网页（见文档 References 一节，均为原文档提供的文化考据来源）。

这些信息说明该星空文化并非随意创作，而是有民族志考据与书面文献支撑的民族志类（ethnographic）星空文化。

二、8 个纳瓦霍传统星座：index.json 数据解析

2.1 元数据总览

纳瓦霍文化包的元数据定义在 index.json，字段包括：

其中fallback_to_international_names: false意味着：当纳瓦霍星座没有对应名称时，程序不会自动套用现代国际星座名，而是坚持文化本位命名，保证传统星图的纯粹性。

2.2 星座连线定义

index.json中每个星座的lines是一系列星星编号（HIP/Hipparcos 星表编号）数组，每个数组内部相邻元素构成一段连线，多个数组代表多个不连通的线段组。common_name.english给出英文俗名。

纳瓦霍文化包的 8 个星座完整清单如下：

以CON navajo 005（Dilyehe）为例：

{ "id": "CON navajo 005", "lines": [[17847, 17851, 17702, 17847], [17702, 17608, 17499, 17531, 17702]], "common_name": {"english": "Dilyehe"} }

它由两个闭合线段组构成（17847→17851→17702→17847与17702→17608→17499→17531→17702），对应天文上两个相互交织的小星群。Dilyehe 正是文档 References 中 Clark Foundation 网页所讲述的纳瓦霍神话人物——这也印证了文化包"文档叙事 + JSON 星图"一一对应的设计。

需要特别说明：从index.json的连线数据本身无法直接得知每颗星星的实际名称与位置，星星坐标由 Stellarium 运行时通过 HIP 编号在恒星目录（如 hip_gaia3）中解析。这遵循了 Stellarium 星空文化包的标准约定：index.json只存"逻辑连线"，物理坐标由星表统一提供。

三、description.md 在 Stellarium 中的加载与渲染链路

3.1 两个核心用途

description.md并非静态说明文件，而是被 Stellarium 程序读取的动态数据源，主要有两大用途：

1. 提供文化包英文名：StelSkyCultureMgr::getSkyCultureEnglishName()读取文件的第一个顶级标题（# Navajo），作为该文化包在界面中显示的英文名称（StelSkyCultureMgr.cpp）。实现要求首行必须是#顶级标题，否则回退返回idFromJSON并打印警告日志。
2. 生成星空讲解（narration）文字：通过descriptionMarkdownToNarration()将文档转换为可朗读、可展示的叙述文本（StelSkyCultureMgr.cpp）。

3.2 Markdown → 讲解文字的转换流程

descriptionMarkdownToNarration()的处理逻辑（源码见此处）值得细读：

1. 先剥离 Markdown 注释（<!--...-->）；
2. 截断## Constellations之后的内容——该节通常放星图索引，不进入讲解；
3. 提取#顶级标题作为文化名，拼接为讲解开头（形如"Navajo . . . "）；
4. 遍历所有##二级标题，将各小节正文（如 Introduction、Description 等）分别经convertMarkdownLevel2SectionNarration()提取后拼接为叙述文本；
5. 全文经星文化描述翻译器（getSkyCultureDescriptionsTranslator()）本地化后再输出。

也就是说：你在 Stellarium 中选中某个纳瓦霍星座时看到的"传说"文字，正是从description.md各小节实时加工而来的。每个星座的叙述文本最终通过Constellation::setNarration()注入星座对象，并在信息面板中以markdownToHTML()（GitHub 方言 Markdown，实现见 StelSkyCultureMgr.cpp）渲染为富文本，同时convertReferenceLinks()会把文档里的[#N]引用标记自动转换为上标引注链接（源码）。

3.3 完整调用链

description.md └─ StelFileMgr::findFile("skycultures/navajo/description.md") ├─ getSkyCultureEnglishName() → 界面显示的文化包英文名 └─ descriptionMarkdownToNarration() └─ convertMarkdownLevel2SectionNarration() └─ Constellation::setNarration() → 星座对象 narration └─ getNarration() → 信息面板 / 语音讲解（含 TTS，见 Constellation.cpp 中 Speech 调试通道）

底层实现证据：

• 讲解文字的最终输出在 Constellation.cpp：信息面板中输出Legend字段，将 narration 经markdownToHTML()渲染并去除<br>与<img>标签；
• 星座的narration字段定义于 Constellation.hpp，注释明确注明"narration text from the respective section in description.md"；
• 测试用例 testStelSkyCultureMgr.cpp 验证了setCurrentSkyCultureID()、getCurrentSkyCultureEnglishName()等核心 API 的行为，是理解文化包加载机制的直接参考。

四、在 Stellarium 中启用与验证 navajo 星空文化

4.1 启用方式

安装 Stellarium 后，navajo文化包会随软件数据安装到skycultures/navajo目录（安装规则见 CMakeLists.txt：将目录内容整体安装到${SDATALOC}/skycultures/${skyculture}，排除CMakeLists.txt本身）。

在程序中启用：

1. 打开Sky and viewing options（天空与视角选项）窗口；
2. 进入Sky culture（星空文化）选项卡；
3. 在文化列表中选中Navajo；
4. 确认星座连线（flag_constellation_lines）、星座名称标签（flag_constellation_name）已开启，即可看到基于纳瓦霍神话的 8 个传统星座。

4.2 验证文化包正确加载

• 界面中文化包名称显示为Navajo（取自description.md的# Navajo标题，由getSkyCultureEnglishName()解析）；
• 星座列表中出现Revolving Male、Revolving Female、Lizard、Dilyehe、Rabbit Tracks等非 IAU 名称，且不会回退为现代国际星座名（fallback_to_international_names: false）；
• 选中任一星座查看信息面板，应出现基于description.md文本渲染的传说叙述（Legend 字段）。

4.3 命令行/日志验证

程序运行时日志中，若description.md缺失或格式错误，StelSkyCultureMgr会打印如下类型警告（源自源码）：

• Can't find description for skyculture navajo
• Failed to open sky culture description file ...
• Sky culture description file ... at line N has wrong format (expected a top-level header, got ...)

若你的安装中未出现上述警告，且文化名正确显示为 Navajo，即可确认文化包加载成功。

五、给星空文化设计者的实践要点

结合本仓库约定，若要编写类似navajo的民族志星空文化包，应遵循：

1. description.md结构规范：首行# 文化名；正文使用##二级小节组织内容；如需星座逐个讲解，可在## Constellations之后按星座 ID 编写小节（该节在 narration 转换时会被截断，仅用于界面索引）；[#N]引用标记会被自动转为引注上标。
2. index.json连线规范：lines中的数字必须是星表中存在的 HIP 编号；每个星座的abbreviation（缩写）需唯一；fallback_to_international_names决定是否回退 IAU 命名。
3. 可溯源：像description.md那样记录贡献者、主要文献与参考资料，保证民族志内容的可信度。

结语

纳瓦霍星空文化包是 Stellarium 民族志类（ethnographic）星空文化的典型样本：一份仅 23 行的 description.md 承载了文化名、神话叙述与考据来源，配合 index.json 中 8 个传统星座的连线定义，被 StelSkyCultureMgr.cpp 的 Markdown 解析与 narration 渲染引擎转化为真实可交互的星空叙事。理解这一链路，你就掌握了 Stellarium 全部数十种传统星空文化的通用工作方式。

• 桌面应用
• 图形学
• 科研