omdx 0.1.2

Open Meteor Data Exchange standard and tools

OMDX (Open Meteor Data Exchange) 数据标准与工具箱

omdx 是一个开源的流星观测数据交换标准及配套工具集，旨在解决流星监测领域的数据碎片化问题，促进多站点协作与科学数据的标准化流通。

开发背景

随着流星监测技术的普及，国内涌现出大量流星监测爱好者与观测站点。然而，长期以来生态较为分散，不同设备、不同软件（如 UFOCapture, RMS 等）生成的数据格式各异。流星科学研究——特别是高精度的轨迹计算与轨道定轨——往往需要多站点的协同观测数据配合。数据格式的不统一成为了数据共享与联合解算的巨大障碍。

omdx 标准基于国家天文台（NAOC）和中国科学院大学（UCAS）开发的 M3系统 的数据结构进行了通用化设计。我们的目标是：

1. 建立标准：定义一套包含流星视频、时间戳、天体测量（恒星/流星位置）、测光以及元数据的统一交换格式。
2. 打破壁垒：提供开源的 Python SDK，方便开发者将该格式集成到各自的流星监测软件中。
3. 连接生态：提供转换工具（MeteorConverter），支持将UFOCapture的历史数据转换为标准格式，激活沉睡的数据价值。

我们诚挚邀请流星监测软件的开发者与天文爱好者加入 omdx 生态，共同推动流星科学数据的标准化进程。

请阅读本项目其他文章：文档中心

---

开源协议与版权声明 (License & Copyright)

开源协议 (Open Source License)

本项目采用 MPL 2.0 (Mozilla Public License 2.0) 协议授权。

• 允许闭源： 你可以将 omdx 的库集成到你的商业或私有软件中，而无需开放你程序的主体代码。

• 文件级开源： 如果你修改了 omdx 本身的源文件，你必须公开这些文件的代码。

我们的愿望： omdx 旨在打破流星观测数据孤岛。如果你编写了将某种私有格式转换为 omdx 的转换器，请考虑将其开源并贡献给社区，以便全世界的科学家和爱好者都能共享观测成果。

第三方数据版权声明 (Data Credits)

本软件包含或引用了以下第三方数据源，其版权及最终解释权归原作者或机构所有：

• Hipparcos Catalog: 包含来自欧洲航天局 (ESA) 的星表数据。

• DE421 Ephemeris: 包含来自美国宇航局/喷气推进实验室 (NASA/JPL) 的行星历表数据。

---

核心类：MeteorObservation

MeteorObservation 是 omdx 库的核心 Python 类，用于在内存中表示一次完整的流星观测事件。它不仅存储原始图像数据，还通过属性承载了所有的科学元数据。

数据内容和定义

该类最关键的属性是 self.contents (List[str])。它是一个字符串列表，用于标记当前对象中包含了哪些有效的数据模块。下游程序应根据此属性判断数据的完整性。

标记 (contents)	含义	必须包含的非空属性
image	包含图像数据	data (视频帧), mask_frame (非探测区域遮罩), signal_frame (流星区域), max_frame, mean_frame
time	包含时间信息	mean_time (基准绝对时间), frame_time (每帧相对基准时间),frame_exposure (每帧曝光时间)
star	包含恒星定标信息	star_pixel_coord, star_eci_coord, star_name
meteor	包含流星测量信息	objects （流星对象列表, 包含meteor_index, meteor_pixel_coord 等）
calibration	包含相机校准模型	calibration_model, calibration_residual 等
photometry	包含测光模型	photometry_model, photometry_residual 等
database	包含数据库收录情况	station_id, meteor_id 等

详细信息请参照OMDX Python SDK API 参考手册

保存格式

MeteorObservation 类提供了两种数据持久化方案，以适应不同的使用场景：

1. FITS 格式 (to_fits)： 这是推荐的标准交换格式。它将视频图像、元数据、流星/恒星列表等所有信息封装在一个 .fits 文件中，适合科学归档与专业分析。

   FITS格式的详细内容情参照OMDX FITS 数据格式标准

2. 组合文件格式 (to_files)： 这是一种轻量级的拆分存储方案，将数据解包为通用的多媒体和文本文件，便于在 Web 端展示或使用常规媒体播放器查看。包含以下文件：

   • .json：存储所有非图像的属性、元数据及目标对象列表。
   • .mp4：存储核心视频图像数据 (data)。
   • .png：存储遮罩 (mask_frame) 与信号 (signal_frame) 的可视化混合图像。

   请注意，这种保存方式会导致视频画面被有损压缩，因此仅供展示使用，不应用来存储中间结果，尤其是多次读写。

---

工具：MeteorPlayer (观测数据浏览器)

omdx-player 是一个基于 tkinter 和 matplotlib 的可视化工具，用于查看和校验符合 omdx 标准的数据文件。

启动方式

omdx-player

界面功能详解

1. 顶部控制栏

• 文件操作：支持打开 .fits 文件或保存当前修改为 FITS。
• 内容状态指示：文件加载后，右侧会显示 contents 标签栏。
  • 🟩 绿色：表示数据包含该模块（如 image, time）。
  • 🟥 红色：表示数据缺失该模块。

2. 信息展示区

• 基本信息：显示流星名称、站点、相机、观测时间等摘要。
• 详细数据表：提供三个弹出式窗口查看底层数据：
  • 基本信息表：显示版本、位置、处理时间及校准残差等所有属性。
  • 帧/流星表：以表格形式展示每一帧的时间戳以及对应的流星坐标（Pixel/ECI）、流量、星等。
  • 恒星表：列出用于定标的恒星列表及其坐标数据。

3. 播放与可视化区

• 图层叠加控制：
  • ☑️ 流星区域：在画面中用蓝色轮廓描绘 signal_frame 边缘。
  • ☑️ 遮罩区域：将 mask_frame 定义的遮挡区域在画面中压暗显示。
  • ☑️ 恒星标记：在画面中用绿色圆圈（直径约5像素）标出恒星位置，并显示名称。
  • ☑️ 时间戳：左上角叠加当前帧的 ISOT 格式时间。
• 播放控制：
  • 包含时间/帧号显示、播放/暂停/停止按钮、进度条。
  • 速度控制：支持 1.0x, 0.5x, 0.1x 慢放。
  • 直方图/色阶：点击“直方图”勾选框，弹出色阶调整窗口。用户可调整黑场（Min）、白场（Max）和 Gamma 值，实时改变画面显示的对比度和亮度，便于看清暗弱流星。
• 交互式画面：
  • 滚轮：暂停状态下，滚动鼠标滚轮可逐帧前后切换。
  • 缩放与平移：按住 Ctrl + 滚轮进行以鼠标为中心的缩放；放大后按住鼠标左键/中键拖动画面。缩放时，叠加层（如恒星圈大小、字体）会智能适配，保持良好的可视性。

---

工具：MeteorConverter (数据转换器)

omdx-converter 旨在帮助用户将传统的 UFOCapture 观测数据转换为标准的 omdx 格式。

启动方式

omdx-converter

操作流程指南

第一步：加载视频与去重

• 点击“读取 UFO 视频”选择 .avi 或 .mp4 文件。
• 智能去重：由于原生帧率与软件设置帧率不同会导致出现重复帧，工具会自动比对相邻帧，去掉重复帧并估计原始帧率。
• 同时，工具会自动读取同目录下的 .xml 文件，自动填充站点、相机、经纬度等信息。

第二步：基础信息校对

• 用户可在左侧面板校对自动获取的元数据（流星名称、经纬度、海拔等）。相关信息建议UFO设置中填写完善。

第三步：时间校准

• XML 中的时间往往不够精确。用户需在播放器中找到秒数跳变的那一帧（即 System Time 秒数改变的瞬间）。应该有摄像头生成的时间戳，而不是UFOCapture生成的时间戳，后者通常有延迟。
• 在“校准帧”栏填写该帧的序号，并在下方时间框填写该时刻的精确时间。
• 结合去重后的有效帧率，系统将自动计算出每一帧的精确时间戳。完成后，数据将包含 time 标记。

第四步：遮罩与信号处理

• 遮罩绘制 (Mask)：切换到“绘制遮罩”模式（红色笔刷），涂抹画面中的地景、树木等遮挡区域。点击保存/加载按钮，可以将绘制的遮罩保存为 PNG 文件，处理后续同一个相机拍摄的流星时，可以点击加载按钮加载 PNG 遮罩文件。
• 流星区域绘制 (Signal)：工具会自动尝试读取同名的 *M.bmp 文件（UFOCapture 生成的轨迹图），从中获取流星出现的区域。
  • UFOCapture生成的图像经常不会覆盖整颗流星，用户也可以切换到“绘制流星区域”模式（蓝色笔刷）手动修补，将整个流星轨迹全部覆盖。
• 完成后，数据将包含 image 标记。

第五步：恒星标定（可选）

• 切换到“点选恒星”模式。
• 在画面中双击击恒星位置，
• 点击打开恒星表，并在弹出的列表中输入恒星名称（支持中文名或 HIP 编号）。
• 输入名称后，系统会自动计算该恒星在观测时刻的地心惯性坐标 (ECI)，并保存至数据中。
• 标记足够数量（建议5颗以上）后，数据将包含 star 标记。

第六步：导出

• 当状态指示灯（TIME, IMAGE, STAR）变绿时，点击“保存 FITS”即可生成标准文件。

---

安装

可以通过 pip 安装：

pip install omdx

或者从源码安装：

git clone https://github.com/quan787/omdx-project.git
cd omdx-project
pip install -e .

依赖项

• Python >= 3.9
• numpy
• opencv-python
• astropy
• pillow
• matplotlib
• skyfield