Skip to content
tollenceldPublic

About

A local-first SwiftUI instrument for observing real artificial satellites in the sky.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

StarCatch — 人造天体观察器

一台安静、深邃、克制、精密的深空仪器。举起手机指向真实天空,那个方向上真实存在的人造物(卫星、退役航天器、火箭残骸)会从黑暗中缓慢浮现,以遥测档案的形式呈现。

完整功能、数据规模、用户流程、技术架构与上架状态见 Documentation/PROJECT_OVERVIEW.md。

新对话先读 AGENTS.md 与 PROJECT_CONTEXT.md,再核对 Git。 本轮视觉、档案、指向与性能改动的交接记录见 Documentation/VISUAL_REFINEMENT_2026-10.md。

运行

brew install xcodegen   # 首次
xcodegen generate
open StarCatch.xcodeproj
  • 真机(推荐):Xcode Signing 面板选择你的 Team → 运行。使用 CoreMotion 真北姿态 + 定位,指向真实天空。
  • 模拟器:直接运行。拖拽模拟指向(水平 = 方位角,竖直 = 仰角)。初始指向东南方仰角 30°,向左/右轻拖即可遇到 GEO 带对象(北斗 G8、Himawari-9 等)。

体验链路

轻量文字等待离线目录就绪 → 首启观测手册 → 探索 → 准星选中候选并显示轻量身份 → 按下中央 Capture 立即锁定、记录一次观测 → 约 340ms 成像反馈与两段短触觉后直接打开完整档案。返回天空后锁定仍保留,移动视线不会换星;从档案返回后身份条才显示并提供明确释放,释放后可立即主动捕获同一目标。

主天空底部为“筛选/记录”玻璃胶囊、中央 Capture(回位按需位于其上方)和“全球/设置”玻璃胶囊。拖动进入手动浏览;回位停止惯性、恢复默认缩放并转向手机此刻的方向。下部固定浅弧和蓝灰渐变是氛围地平线,不是实际地平线。背景为更小更暗的圆点,卫星为清楚的菱形核,少量真实移动卫星带微弱光圈;聚焦/锁定时收起天空轨迹。

捕获后直接进入单页卫星档案,以冷青终端、等宽字段和薄直线组织内容,不再分三页导航。3D 地球与关键轨道读数位于上方,通用卫星形态样本以独立卡片放在任务与相遇摘要之后,两者分别旋转、缩放和复位。长文、目录与来源按需展开,默认只展示一个相遇窗口。返回天空仍保留锁定,中央控件重开档案,身份条提供释放;联系线和离屏信标保持真实目标关系。

时间维度:点按底部“全球”或缩小主天空进入全球轨道页,屏幕下缘出现 TimeDial。左右拨动改变观测时刻(±24h);点按中央偏移读数返回此刻。从历史状态退出全球时先回 LIVE,再沿空间旅程返回天空。

每次锁定自动写入本地 UserDefaults 观测日志,保存当时的时间与轨道读数。底部“记录”直接打开日期分组列表,可查看详情或使用原生左滑删除;批量清除需要确认。

隐私:位置、姿态、设置与观测记录只在设备上使用或保存;应用不含账户、广告、分析或跟踪。设置页提供完整隐私说明,记录页可清除本地观测记录。

数据

StarCatch/Resources/catalog.json 是随包发布的 schema v2 CelesTrak GP/OMM 离线快照,当前包含 16,635 个轨道目标;不在 active GP 分组中的少量历史目标以同一 schema 内的策展 TLE 载荷保留,运行时不再兼容旧版整份小目录文档。构建测试核对唯一 NORAD/COSPAR 标识、元素历元时效、代表性物理量和档案覆盖是否确实存在于目录;这不等同于替代官方运营方对任务状态的持续公告。SGP4(SatelliteKit)在本地推算方位、高度、速度与距离,APP 运行时不请求轨道网络数据。

人工编写的逐星档案位于 SatelliteKnowledge。它是可直接用 Obsidian 打开的 Markdown 资料库;Xcode 构建会自动校验并编译为紧凑 JSON,APP 运行时按 NORAD 编号读取。数千份源笔记不会进入安装包,也不会拖慢启动时的文件扫描。

轨道元素会随时间漂移,随包快照必须作为发布资产维护。统一使用 Scripts/update_catalog.py 更新并校验目录,不要手工替换单个对象;完整流程与时效约束见 Scripts/README.md。

开源与第三方声明

StarCatch 的原创代码和项目材料采用 MIT License 发布。项目使用采用 MIT License 的 SatelliteKit 在设备本地执行 SGP4 轨道传播。

随包轨道目录由 CelesTrak GP/OMM 数据生成。更新数据时请遵循其 Usage Policy 与查询频率要求;完整归属说明见 NOTICE。

测试

xcodebuild -project StarCatch.xcodeproj -scheme StarCatch \
  -destination 'platform=iOS Simulator,name=iPhone 17' test

含轨道推算的物理合理性检验(ISS 高度/速度、GEO 静止性)。testPrintCurrentSky 可打印当前北京视角全部对象 az/el,便于调试指向。

结构

.
├── Documentation/       架构、完整项目说明与 App Store 提交清单
├── SatelliteKnowledge/  Obsidian 可编辑的逐星与星座 Markdown
├── Scripts/             发布期目录生成、资料校验与编译
├── StarCatch/
│   ├── App/             App 生命周期、启动与隐私页面
│   ├── Archive/         即时信息、深入档案、设置与观测记录
│   ├── Design/          Palette、Typography、Motion
│   ├── Engagement/      CaptureStateMachine
│   ├── Orbits/          目录、SGP4 调度、轨迹、过境与观测日志
│   ├── Pointing/        真机姿态、模拟器指向与观察者位置
│   ├── Sky/             主天空、投影、绘制、筛选、全局星图与时间轴
│   ├── Resources/       构建后的 catalog.json 与 satellite_profiles.json
│   └── Shaders/         Grain.metal
├── StarCatchTests/      轨道、状态、时间和资料完整性测试
└── project.yml          XcodeGen 工程结构唯一来源

更具体的状态所有权、并发边界、工程生成与验证约束见 Documentation/ARCHITECTURE.md。

设计原则(改动时对表)

  • 暖黑、暖灰文字与暗琥珀交互信号;低饱和蓝灰只用于氛围光、玻璃与微弱观测提示
  • 阅读文字使用 Palette.Text 语义层级,避免重复叠透明度;装饰图层可用透明度组织
  • 细线按用途区分;玻璃集中于悬浮操作层,正文保持稳定阅读底色;沿用共享动效与无障碍降级
  • 信息渐显不弹出;不做打字机/乱码效果;不游戏化

About

A local-first SwiftUI instrument for observing real artificial satellites in the sky.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages