# starlight

**Repository Path**: smallblackqaq/starlight

## Basic Information

- **Project Name**: starlight
- **Description**: starlight “星光” gnss/ins捷联惯性导航算法试验
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-04-01
- **Last Updated**: 2026-05-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# starlight “星光” gnss/ins捷联惯性导航算法试验
为本科毕业论文而设计

## 跨平台安装与构建（macOS / Linux / Windows）

建议使用 Python 3.10+ 虚拟环境，并按子项目顺序安装（先本地依赖，再主包）：

```bash
python -m pip install -U pip
python -m pip install -e ./filter_box_py
python -m pip install -e ./gnss_ins_sim
python -m pip install -e .
```

如果只需要按文本依赖安装：

```bash
python -m pip install -r requirements.txt
```

构建 wheel/sdist（用于发布前检查）：

```bash
python -m pip install -U build
python -m build
```

## 仿真结果分析组件（starlight.analyser）

支持论文常见实验展示：

- 3D轨迹对比（交互）
- 位置/速度/姿态误差时序对比（交互）
- RMSE对比柱状图与统计表
- 静态图片导出（PNG）
- 单文件离线HTML报告（弱网可访问）

直接对 `sim_results` 目录运行：

```bash
python -m starlight.analyser \
    --results-dir output/sim_results \
    --out-dir output/analyser_output \
    --algo-label 0=Direct \
    --algo-label 1=EKF \
    --algo-label 2=MCKF \
    --plotly-js-mode inline
```

参数说明：

- `--plotly-js-mode inline`：将Plotly脚本内嵌到HTML，适合弱网络或完全离线环境。
- `--plotly-js-mode cdn`：减小HTML体积，适合本地开发网络环境。
- `--algo-label IDX=NAME`：为算法编号指定显示名，可重复传参。
    - 例如 `algo1_2` 中，`1` 是算法编号，`2` 是第2轮生成数据（run）。
    - 图示、HTML和CSV会显示 `NAME (algo1, run2)`，同时保留原始键 `algo1_2` 便于追溯。

输出内容：

- `analysis_report.html`：可交互报告（支持鼠标缩放、平移、悬停）。
- `metrics_position.csv`：位置指标统计。
- `metrics_velocity.csv`：速度指标统计。
- `metrics_attitude.csv`：姿态指标统计。
- `metrics_rmse_breakdown.csv`：位置/速度/姿态分组RMSE统计。
- `figures/*.png`：论文插图可用的静态图。

## 库引用思路
- 矩阵运算目前非常轻量化 只引用了scipy和numpy进行简单运算
- 发现ins py相关库
    - 单位转换 数据类型 误差模型 直接方法 简单数据生成
    - 其实是可以直接用他的算法的 如果封装的比较差劲就再套一层
- 发现gnss py相关库
    - all in one gnss领域库
    - 包含非常多的公开数据集导入方式
    - 多种算法
    - 多种分析工具
    - 算法/模型部分略有点草率
    - 是一个弱接口设计
- 发现gnss ins sim相关库
    - 数据生成 分析工具 甚至可以保存结果
    - 但是好像缺乏一些自带的benchmark算法

- 没有发现mckf优质仓库
    - 几十star的小仓库不是很敢用
    - 虽然matlab或者cpp有 甚至也有成熟的接口 但是我感觉这样太复杂了 增加了项目复杂度

### 数据集库进阶检索
- 现在那个简单的gnss ins sim已经不满足我们的需求了
- 现在搜索
    - 没有软件设施的基础数据集
    - 论文中用到的数据集
    - 某些数据集提到了IE 

- gnss的基础设施比gnss/ins结合领域丰富多了
    - https://rtklib.com

- 大多数论文的数据集都使用了自己采集的数据
    - 并且也不开源 只能认为是他们不太想让别人复现了
- 那我们随便采用一个设施完善的数据集

- 可用候选
    - https://github.com/i2Nav-WHU/awesome-gins-datasets
        - 没法用 gnss rtk数据信息不全面
    - https://www.kaggle.com/datasets/fengzhusgg/smartpnt-pos/discussion/545898
        - 看起来很简陋
    - https://github.com/chichengcn/gici-open-dataset
        - 验证中 看起来有代码设施
    - https://github.com/chichengcn/gici-open
        - 上面那个dataset对应的软件项目 疑似有点太权威了

## 第三方库设施的应用哲学
- 对于可以减小重复工作的量的 进行使用
- 对于设计哲学有所差异的
    - 视整改难度 完全重写 改进 或者进行包装
- 是否使用其接口
    - 当你对相关领域还不完全理解时 可以尝试阅读
    - 择优而从 但是不必为了使用而使用


## 接口原则
- 中等强度接口
    - 有接口的内容提示，但是对接口内容不做检查和判断
    - 关于接口的兼容性？
        - 保证兼容np 其他不做保证 请在接口对接时进行合适的转换
    - 元素分割原则
        - 对于一个数学向量类似物变量
            - 组合定义 一种向量
                - 要有
            - 分组定义 某些子向量
                - 其本身
            - 单独定义 子向量的名称
                - 这部分可以约定俗成 不做说明
            
            - 当作为滤波器的一部分强调数学状态量语义时 我允许基本单位是一个大数组

- py接口的非强制性
    - 都不强制 写个名字提示你一下就算功德圆满了 内部检查我真是欠你的
    - 好像没有吧numpy用到极致
        - 了解一下py连续数据的底层原理吧
    - 其实我感觉用的还好
        - py永远不靠类型进行硬规定

## 子模块的序列运算支持原则
- 部分库自带序列运算支持 
    - 对于直接算法
    - 好像路径确实需要一些历史信息？
        - 交给他来维护有什么坏处吗
        - 套一层接口 让他来维护

## 项目的知识储备要求
- 虽然力求做到完善
    - 但是本人的算法水平有限目前属于一个边写边学的过程
    - python工程化编程的水平也比较有限
- 因此部分能调库却选择手搓也是可以理解的




# 符号规定
- 死脑子快记啊
    - 旋转向量
        - 两个坐标系会发生相对运动
        - 下标左到右：左边坐标系相对右边坐标系的移动
        - 上标：投影在某个坐标系下

- n = navigation frame 
    - use ned: north east down, which is an right hand coord


# 重力模型
- ![公式](./doc/gravity_module.png)


# 关于ins error module工程中更新频率
- 只有对于ins gnss 一起来时 才可以做更新
- 只有ins的情况 可以做预测
- 没有任何数据 则什么都做不了

- 如果我能做到 那为什么不呢

- 什么时候需要数据 algo中可以保持算法滤波器特性引出的predict属性和update属性
    - 在需要进行不同应用情景的调用时 可以再包装一个应用层


# 标准单位
- 经 纬 海拔（LLA） = rad rad m
- 欧拉角（RPH roll pitch heading） = rad rad rad
- 北东地 （north east down ned） = m/s m/s m/s 
    - 仅在状态量中 为了和书中保持一致 使用了东北天
- 原则依然是 除非有特殊说明 否则都是弧度

- 坐标系明确（记住）
    - e （ecef） 地心地固坐标系 地球本身 随着地球旋转
    - i （eci） 地球惯性系 坐标轴指向恒星（太阳） 其他所有系都相对其产生了运动
    - n navigation
    - b body 载体 传感器安装位置

# 算法 分类 改进 与 命名原则
- 时间演进顺序 和 分类法的区别之处
- lc和tc本质上并不能算是并列关系
- 按照避免重复造轮的原则 应该在之前的模块基础上进行拓展

# error module algo的方法
- 补偿 机械化组织 更新 预测
- 单迭代 双迭代
- 因为该算法的特殊性 为了保证用户操作的安全性 
    - 采用 predict 和 predict_and_update
    - 在单传感器时使用predict 在双传感器时使用predict_and_update