#MoonTopoLens · 月拓镜

#能做什么

#安装与运行

git clone https://github.com/wdgodghl/moontopolens.git
cd moontopolens
moon version --all
moon check --target js
moon build --target js
moon test --target js
moon run --target js cmd/demo

moon check --target wasm-gc
moon build --target wasm-gc
moon test --target wasm-gc
moon run --target wasm-gc cmd/demo

#三个完整使用场景

#1. 识别点云环路并比较形状变化

moon run --target js cmd/main -- analyze examples/square.json --out out-square
moon run --target js cmd/main -- compare examples/square.json examples/rectangle.json
moon run --target js cmd/main -- summary examples/square.json

#2. 从采样信号提取周期结构

moon run --target js cmd/main -- analyze examples/periodic-series.json --out out-series

#3. 检测二值图案中的洞及填充过程

moon run --target js cmd/main -- analyze examples/ring-grid.json --out out-grid

moon run --target js cmd/main -- analyze examples/two-holes-grid.json --out out-two-holes

• report.json：所有区间、细胞、边界、代表链与约化统计。
• barcode.svg：最多显示前 80 个区间；完整数据保留在 JSON 中。
• diagram.svg：出生/死亡散点图；顶部表示在输入截止处仍存在的类。
• intervals.csv：所有区间、死亡状态、观察寿命和代表细胞索引。
• betti.csv：101 个尺度上的 H0/H1，包含截止尺度。
• betti-events.csv：全部出生/死亡尺度的精确 H0/H1，合并同尺度事件。
• recommendations.json / recommendations.csv：建议查看的尺度、依据、区间编号和该尺度 H0/H1。
• report.html：可离线打开的完整交互报告。

#离线报告怎么用

1. 拖动尺度滑块，观察当前 H0/H1 数量、进入复形的顶点和边。
2. 选择维度、最小观察寿命或“仅当前存活”，筛选并逐页查看全部区间排名。
3. 点击区间编号，在该环路存活的尺度上查看橙色代表边。
4. 查看 Betti 曲线，或将 CSV 导入表格/绘图工具继续分析。

#0.3.0：尺度快照与持久景观

moon run --target js cmd/main -- slice examples/square.json 1
moon run --target js cmd/main -- slice examples/clusters.json 0.5

moon run --target js cmd/main -- landscape examples/two-holes-grid.json 1 0 1 --out out-landscape

#0.4.0：解释比较结果并导出尺度图

moon run --target js cmd/main -- compare examples/square.json examples/rectangle.json --out out-comparison
moon run --target js cmd/main -- slice examples/clusters.json 0.5 --out out-clusters-slice
moon run --target js cmd/main -- slice examples/square.json 1 --out out-loop-slice --interval 4

#0.5.0：直接读取 PGM 图像与批量分析

moon run --target js cmd/main -- image examples/ring-image.pgm 1 --out out-ring-image

moon run --target js cmd/main -- batch examples/batch-study.json --out out-study

#0.6.0：自动阈值与亮色前景

moon run --target js cmd/main -- image examples/bright-ring.pgm auto --invert --out out-bright-ring

#0.7.0：批量全对距离热图

moon run --target js cmd/main -- batch examples/batch-study.json --out out-study

#0.8.0：推荐值得查看的尺度

moon run --target js cmd/main -- recommend examples/ring-grid.json
moon run --target js cmd/main -- recommend examples/clusters.json --out out-recommend-clusters
moon run --target js cmd/main -- slice examples/ring-grid.json 0.5 --out out-recommended-slice

#0.9.0：检查时间序列嵌入参数的影响

moon run --target js cmd/main -- sweep examples/periodic-sweep.json --out out-periodic-sweep

#自定义输入

{
  "kind": "points",
  "threshold": 2,
  "max_cells": 4000,
  "points": [[0, 0], [1, 0], [1, 1], [0, 1]]
}

#MoonBit 库用法

import {
  "wdgodghl/moontopolens" @topo,
}

let points = [[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0]]
let filtration = @topo.rips(points, threshold=2.0)
let analysis = @topo.analyze(filtration)
let loops = @topo.betti(analysis, 1, 1.0) // 1
let finite_diagram = @topo.diagram(analysis, 1)
let json = @topo.report_json(analysis)
let strongest = @topo.ranked_intervals(analysis, dimension=1, min_lifetime=0.1)
let summary = @topo.summary_json(analysis)
let html = @topo.html_report(analysis)
let events = @topo.betti_events(analysis)
let groups = @topo.connected_components(analysis, 1.0)
let snapshot = @topo.snapshot_json(analysis, 1.0)
let landscape = @topo.persistence_landscape(
  analysis, dimension=1, start=0.0, end=2.0, samples=101, layers=3,
)
let matching = @topo.interval_matching(analysis, analysis, dimension=1)
let comparison = @topo.comparison_json(analysis, analysis)
let scale_picture = @topo.scale_svg(analysis, scale=1.0)

#算法约定与边界

• Rips 使用直径约定：距离 d 的边在 d 出现，无半径除二。
• 矩阵要求严格对称、对角线为零；无需满足三角不等式，不偷偷修正输入。
• 计算系数域为 GF(2)，实现 H0/H1，不宣称完整 H2 或整数同调。
• death: null 表示在输入截止处仍存在，不能据此证明在完整过滤中无限存活。
• 区间为 [birth,death)，默认省略零长度区间；代表环路在出生时有效，不保证最短。
• 比较包含有限区间和未死亡区间；后者数量不等时结果为 null。 输入的尺度、单位与截止条件应具有可比性。
• 点云/矩阵最多 128 个点，维度最多 32；网格最多 64×64；有限图匹配各最多 64 个区间。
• 最大细胞数默认 4000、硬上限 10000；约化默认最多 2,000,000 次列加法， 存储最多 2,000,000 个稀疏条目。Rips 三角形数量可快速增长，超过预算时明确报错。
• 持续熵仅统计有限区间，使用自然对数；无正寿命有限区间时约定为 0。 未死亡类的观察寿命为 cutoff-birth 下界，不能当作完整寿命。
• 持久景观限 2–1001 个采样点、1–16 层，并限制 有限区间数×采样点数×层数 ≤ 2,000,000。 参数扫描固定 101 点、3 层；最多 12 组参数和 16000 个总细胞。 连通分组要求零细胞/边保留一/两个原始顶点 ID；不支持缺失该编码的自定义过滤。
• 只处理小规模内存数据，未做大数据性能承诺；完整 H2、最短环路和在线上传应用仍属后续计划。

#测试与持续集成

moon fmt --check
moon check --target js
moon check --target wasm-gc
moon build --target js
moon build --target wasm-gc
moon coverage clean
moon test --target js --enable-coverage
moon test --target wasm-gc
moon coverage report -f summary
node scripts/check-source.mjs
node scripts/smoke.mjs
python -m pip install numpy==2.3.5 gudhi==3.13.0
python scripts/reference_gudhi.py
node scripts/benchmark.mjs
moon package --list

#项目来源与许可证