Metadata-Version: 2.4
Name: omdx
Version: 0.1.2
Summary: Open Meteor Data Exchange standard and tools
Home-page: https://github.com/quan787/omdx-project
Author: quan787
Author-email: quan787@qq.com
License: MPL 2.0
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: opencv-python
Requires-Dist: astropy
Requires-Dist: pillow
Requires-Dist: skyfield
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

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

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

## 开发背景

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

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

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

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

_请阅读本项目其他文章：[文档中心](https://blog.meteoroid.fit/)_

---

## 开源协议与版权声明 (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 参考手册](https://blog.meteoroid.fit/omdx/fits.html)_

### 保存格式

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

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

    _FITS格式的详细内容情参照[OMDX FITS 数据格式标准](https://blog.meteoroid.fit/omdx/fits.html)_

2.  **组合文件格式 (`to_files`)**：
    这是一种轻量级的拆分存储方案，将数据解包为通用的多媒体和文本文件，便于在 Web 端展示或使用常规媒体播放器查看。包含以下文件：
    - **`.json`**：存储所有非图像的属性、元数据及目标对象列表。
    - **`.mp4`**：存储核心视频图像数据 (`data`)。
    - **`.png`**：存储遮罩 (`mask_frame`) 与信号 (`signal_frame`) 的可视化混合图像。

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

---

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

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

### 启动方式

```bash
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 格式。

### 启动方式

```bash
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 安装：

```bash
pip install omdx
```

或者从源码安装：

```bash
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
