feat: 完善星表查询与跨版本回归验证
- 将星表名称数据收敛为 TSV/GZIP 单一数据源，补充中文名、别名、英文常用名及宿/垣区域字段 - 增加星表名称表加载校验、旧详情字段一致性校验和 GZIP 漂移检查 - 新增 StarDataByName、StarDataByNameAll、StarDataByNameIn ，统一中英文查询与重名消歧 - 优化日月食半影带、升落曲线和可见性回归测试，补充极区、拓扑及低精度场景覆盖 - 增加 Go 1.16/386 兼容门禁和测试案例，处理旧工具链的分配、拓扑、SVG字节及 ULP 差异 - 补充星表、坐标、日月食和低精度回归用例，完善测试文件与缓存忽略规则
This commit is contained in:
@@ -84,7 +84,7 @@ Both the angular separation of a planet and a star and star heliacal visibility
|
||||
|
||||
| Entry | Input |
|
||||
| --- | --- |
|
||||
| `StarCoordinateByName(name)` | catalog Chinese name, for example `"天狼星"` |
|
||||
| `StarCoordinateByName(name)` | catalog Chinese name/alias or English common name, for example `"天狼星"` or `"sirius"`; duplicate names return `ErrStarNameAmbiguous` |
|
||||
| `StarCoordinateByHR(hr)` | HR number |
|
||||
| `StarCoordinateFromStarData(star)` | a catalog record such as one obtained from `star.StarDataByHR` |
|
||||
|
||||
@@ -98,6 +98,19 @@ fmt.Println(err, star.ID, fmt.Sprintf("%.6f %.6f %.2f %.2f", star.RA, star.Dec,
|
||||
<nil> 天狼 101.287083 -16.716111 -553.00 -1205.00
|
||||
```
|
||||
|
||||
`StarCoordinateByName` returns `phenomena.ErrStarNameAmbiguous` for duplicate names and `phenomena.ErrStarNotFound` when nothing matches; both are usable with `errors.Is`. For duplicates, resolve the catalog record with `star.StarDataByNameIn(name, region)` first, then pass it to `StarCoordinateFromStarData`:
|
||||
|
||||
```go
|
||||
data, err := star.StarDataByNameIn("杵增一", "危宿")
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
coord, err := phenomena.StarCoordinateFromStarData(data)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
`RA` and `Dec` are in degrees, and `Epoch` and `Frame` are required; the proper-motion fields (`ProperMotionRACosDecMasPerYear` and friends) follow the catalog convention `dRA·cos(Dec)`, in milliarcseconds per year. `ParallaxMas` (or the equivalent `DistanceLightYear`) gives the distance, and `RadialVelocityKmPerSecond` gives the radial velocity; when the distance is missing the propagation is two-dimensional, and the radial velocity is included only when a distance is present.
|
||||
|
||||
## Heliacal visibility
|
||||
|
||||
+22
-5
@@ -117,7 +117,9 @@ Proper motion is propagated in **Julian years** (365.25 days), and `RaDecByDate`
|
||||
| Group | Entry points | Purpose | Units and convention |
|
||||
| --- | --- | --- | --- |
|
||||
| Constellation | `Constellation` / `ConstellationEN` / `ConstellationCode` | Chinese name / English name / IAU three-letter code | Corrected RA/Dec in degrees plus the instant |
|
||||
| Star catalog | `InitStarDatabase` / `StarDataByHR` / `StarDataByName` / `TopBrightStars` | Initialise the embedded catalog, look up by HR number or Chinese name, fetch the bright-star sample | HR `1-9110`; `Mag` is apparent magnitude |
|
||||
| Star catalog | `InitStarDatabase` / `StarDataByHR` / `StarDataByName` / `StarDataByNameAll` / `StarDataByNameIn` / `TopBrightStars` | Initialise the embedded catalog; look up by HR number, Chinese name/alias or English common name; disambiguate duplicates with `All` or `In`; fetch the bright-star sample | HR `1-9110`; `Mag` is apparent magnitude |
|
||||
| Name disambiguation | `StarDataByNameAll` / `StarDataByNameIn` | All candidates sharing a name / the unique star matching `ChineseRegion` | For example `StarDataByNameIn("杵增一", "危宿")` |
|
||||
| Error checks | `ErrStarNotFound` / `ErrStarNameAmbiguous` | Distinguish "not found" from "ambiguous name" with `errors.Is` | Exported by the `star` package |
|
||||
| Coordinate correction | `StarData.RaDecByDate` (`RaDecByJde` on the `basic` side) | Correct a J2000 position to the given instant | Returns RA/Dec in degrees |
|
||||
| Rise, set, culmination | `RiseTime` / `SetTime` / `CulminationTime` (`DownTime` is a deprecated alias of `SetTime`) | Rise, set and culmination instants | Civil instants; polar cases return sentinel errors |
|
||||
| Rise/set with weather | `RiseTimeWithAtmosphere` / `SetTimeWithAtmosphere` | Rise and set with measured pressure (hPa) and temperature (°C) | Refraction always applied |
|
||||
@@ -166,10 +168,25 @@ The catalog loads on first lookup; `InitStarDatabase()` only warms it up. It is
|
||||
| `RadVel` / `RotVel` | Radial and proper-motion velocity, km/s |
|
||||
| `Pc` | Distance in parsecs; `> 0` propagates proper motion as a 3D space motion |
|
||||
| `ChineseName` / `ChineseAlias` / `ChineseBayerName` | Chinese name, alias and Bayer designation |
|
||||
| `CommonName` / `CommonAliasName` | Common English name and alias |
|
||||
| `ChineseRegion` | Mansion/enclosure qualifier the name belongs to, for example `危宿` or `太微垣`; empty when not annotated, used to disambiguate shared names |
|
||||
| `CommonName` / `CommonAliasName` | Common English name and alias; `CommonName` is searchable with `StarDataByName` |
|
||||
| `Cst` / `CstChinese` | Constellation name in English and Chinese |
|
||||
|
||||
Lookup by name matches the catalog's Chinese names only (`天狼` for Sirius, `织女一` for Vega); English names are not matched. Use `StarDataByHR` to look up by number.
|
||||
Lookup by name matches the catalog's Chinese names, Chinese aliases and English common names (`天狼`, `织女一`, `Sirius`); English names are case-insensitive and ignore leading/trailing whitespace. Use `StarDataByHR` to look up by number.
|
||||
|
||||
Chinese names can repeat across mansions or enclosures; for example, `杵增一` appears in both `箕宿` and `危宿`. `StarDataByName` returns an ambiguity error when more than one star matches. Use `StarDataByNameIn(name, region)` with `ChineseRegion` to select one, or `StarDataByNameAll` to list all candidates. The `名[宿]` form (for example `"杵增一[危宿]"`) is also accepted, but structured arguments are preferred.
|
||||
|
||||
**Breaking change**: the old implementation silently returned one of the matching stars; it now returns `ErrStarNameAmbiguous`. Check it with `errors.Is(err, star.ErrStarNameAmbiguous)`, then disambiguate with `StarDataByNameAll` or `StarDataByNameIn`. An empty region in `StarDataByNameIn` is equivalent to `StarDataByName` and still reports ambiguity for duplicate names. Error text also changed from `no such star` to `star not found: ...`; use `errors.Is` instead of matching strings.
|
||||
|
||||
English common names use the same `StarDataByName` entry point, case-insensitively and ignoring leading/trailing whitespace, for example `"sirius"`, `"Vega"` or `"Polaris"`. It covers the built-in `CommonName` field only (about 218 entries), not full Bayer designations such as `Alpha Canis Majoris`; Bayer/Flamsteed designations remain in `Name`. English names can also be duplicated (for example, `Gienah` refers to two stars); that returns `ErrStarNameAmbiguous`, and `StarDataByNameAll` lists the candidates.
|
||||
|
||||
```go
|
||||
s, err := star.StarDataByName("sirius") // HR 2491
|
||||
```
|
||||
|
||||
```go
|
||||
s, err := star.StarDataByNameIn("杵增一", "危宿") // HR 8449, s.ChineseRegion == "危宿"
|
||||
```
|
||||
|
||||
### Rise, set and culmination
|
||||
|
||||
@@ -351,7 +368,7 @@ if errors.Is(err, star.ERR_STAR_NEVER_RISE) || errors.Is(err, star.ERR_STAR_NEVE
|
||||
|
||||
`ERR_STAR_NEVER_DOWN` is a deprecated alias of `ERR_STAR_NEVER_SET`, and `DownTime` is a deprecated alias of `SetTime`.
|
||||
- **Refraction range**: the Saemundsson approximation only applies for true altitudes inside `(-5, 90)` degrees and contributes zero outside, so well below the horizon the apparent altitude equals the geometric one.
|
||||
- **Catalog conventions**: BSC / HR `1-9110`, apparent magnitudes `-1.46` to `7.96`; name lookup matches the built-in Chinese names only (`天狼`, `织女一`), never English names.
|
||||
- **Catalog conventions**: BSC / HR `1-9110`, apparent magnitudes `-1.46` to `7.96`; Name lookup matches built-in Chinese names, aliases and English common names (`天狼`, `织女一`, `Sirius`); duplicate names require `StarDataByNameIn` or `StarDataByNameAll`.
|
||||
- **Cross-checking against external catalogs**: positions here are J2000 mean places with proper motion plus precession and nutation; when comparing term by term, bring both sides to the same instant with `RaDecByDate` first.
|
||||
|
||||
## Parameter and result conventions
|
||||
@@ -366,7 +383,7 @@ if errors.Is(err, star.ERR_STAR_NEVER_RISE) || errors.Is(err, star.ERR_STAR_NEVE
|
||||
|
||||
Pressure must be positive and temperature above absolute zero, otherwise the result is `NaN`.
|
||||
- **`aero` semantics**: a true value solves rise/set against the horizon corrected by standard refraction, a false value uses the geometric horizon; the difference is about 2-3 minutes at low latitudes and grows noticeably at high latitudes.
|
||||
- **Catalog range**: HR `1-9110`, apparent magnitudes `-1.46` to `7.96`; name lookup matches the built-in Chinese names only.
|
||||
- **Catalog range**: HR `1-9110`, apparent magnitudes `-1.46` to `7.96`; name lookup matches built-in Chinese names, Chinese aliases and English common names (case-insensitive); duplicate names require `StarDataByNameIn` or `StarDataByNameAll`.
|
||||
|
||||
## Related manuals
|
||||
|
||||
|
||||
+14
-1
@@ -84,7 +84,7 @@ fmt.Println(crossings[0].Time.UTC().Format("2006-01-02 15:04"))
|
||||
|
||||
| 入口 | 输入 |
|
||||
| --- | --- |
|
||||
| `StarCoordinateByName(name)` | 星表中文名，例如 `"天狼星"` |
|
||||
| `StarCoordinateByName(name)` | 星表中文名/别名或英文常用名，例如 `"天狼星"`、`"sirius"`；同名多星返回 `ErrStarNameAmbiguous` |
|
||||
| `StarCoordinateByHR(hr)` | HR 编号 |
|
||||
| `StarCoordinateFromStarData(star)` | `star.StarDataByHR` 等取到的星表记录 |
|
||||
|
||||
@@ -98,6 +98,19 @@ fmt.Println(err, star.ID, fmt.Sprintf("%.6f %.6f %.2f %.2f", star.RA, star.Dec,
|
||||
<nil> 天狼 101.287083 -16.716111 -553.00 -1205.00
|
||||
```
|
||||
|
||||
`StarCoordinateByName` 遇到同名多星会返回 `phenomena.ErrStarNameAmbiguous`，未找到返回 `phenomena.ErrStarNotFound`；两者都可用 `errors.Is` 判断。重名时先用 `star.StarDataByNameIn(name, region)` 取到唯一星表记录，再交给 `StarCoordinateFromStarData`：
|
||||
|
||||
```go
|
||||
data, err := star.StarDataByNameIn("杵增一", "危宿")
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
coord, err := phenomena.StarCoordinateFromStarData(data)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
`RA`、`Dec` 为度，`Epoch` 与 `Frame` 必填；自行字段（`ProperMotionRACosDecMasPerYear` 等）按星表常见的 `dRA·cos(Dec)` 约定，单位毫角秒/年。`ParallaxMas`（或等价的 `DistanceLightYear`）给出距离，`RadialVelocityKmPerSecond` 给出视向速度；距离缺失时按二维自行传播，有距离时才计入视向速度。
|
||||
|
||||
## 偕日可见
|
||||
|
||||
+22
-5
@@ -117,7 +117,9 @@ func main() {
|
||||
| 分组 | 入口 | 用途 | 单位与口径 |
|
||||
| --- | --- | --- | --- |
|
||||
| 星座判定 | `Constellation` / `ConstellationEN` / `ConstellationCode` | 星座中文名 / 英文名 / IAU 三字母代码 | 输入当日赤经赤纬（度）与时刻 |
|
||||
| 恒星库 | `InitStarDatabase` / `StarDataByHR` / `StarDataByName` / `TopBrightStars` | 初始化内置星表、按 HR 编号或中文名取星、取最亮恒星样本 | HR `1–9110`；`Mag` 为视星等 |
|
||||
| 恒星库 | `InitStarDatabase` / `StarDataByHR` / `StarDataByName` / `StarDataByNameAll` / `StarDataByNameIn` / `TopBrightStars` | 初始化内置星表；按 HR 编号、中文名/别名或英文常用名取星；重名时用 `All` 取候选、用 `In` 按宿/垣消歧；取最亮恒星样本 | HR `1–9110`；`Mag` 为视星等 |
|
||||
| 星名消歧 | `StarDataByNameAll` / `StarDataByNameIn` | 返回同名全部候选 / 按 `ChineseRegion` 取唯一星 | 例如 `StarDataByNameIn("杵增一", "危宿")` |
|
||||
| 错误判定 | `ErrStarNotFound` / `ErrStarNameAmbiguous` | 用 `errors.Is` 区分“未找到”与“同名歧义” | `star` 包直接导出这两个哨兵错误 |
|
||||
| 坐标修正 | `StarData.RaDecByDate`（`basic` 侧对应 `RaDecByJde`） | 把 J2000 位置修正到指定时刻 | 返回赤经赤纬，单位度 |
|
||||
| 升落与中天 | `RiseTime` / `SetTime` / `CulminationTime`（`DownTime` 是 `SetTime` 的废弃别名） | 升起、落下、中天时刻 | 返回民用时刻；极区返回哨兵错误 |
|
||||
| 带气象升落 | `RiseTimeWithAtmosphere` / `SetTimeWithAtmosphere` | 按实测气压（hPa）、气温（℃）计算升落 | 恒带大气折射 |
|
||||
@@ -164,10 +166,25 @@ fmt.Println(len(bright), bright[0].HR) // 最亮恒星样本条数与首项 HR
|
||||
| `RadVel` / `RotVel` | 径向速度与自行速度，单位 km/s |
|
||||
| `Pc` | 距离，单位秒差距；`> 0` 时自行按三维空间运动推进 |
|
||||
| `ChineseName` / `ChineseAlias` / `ChineseBayerName` | 中文名、别名、中文拜耳名 |
|
||||
| `CommonName` / `CommonAliasName` | 英文常用名与别名 |
|
||||
| `ChineseRegion` | 星名所属的宿/垣限定，例如 `危宿`、`太微垣`；未标注时为空，同名星官查询时用于消歧 |
|
||||
| `CommonName` / `CommonAliasName` | 英文常用名与别名；`CommonName` 可用 `StarDataByName` 查询 |
|
||||
| `Cst` / `CstChinese` | 星座英文名与中文名 |
|
||||
|
||||
按中文名查询只匹配库内中文名（如 `天狼`、`织女一`），英文名不参与匹配；需要按编号取星用 `StarDataByHR`。
|
||||
按名称查询同时匹配库内中文名、中文别名和英文常用名（如 `天狼`、`织女一`、`Sirius`）；英文名大小写和首尾空白不敏感。按编号取星用 `StarDataByHR`。
|
||||
|
||||
中文星名在不同星官/宿下可能重名，例如 `杵增一` 同时出现在箕宿与危宿。`StarDataByName` 只返回唯一结果，重名时返回歧义错误；此时用 `StarDataByNameIn(name, region)` 指定 `ChineseRegion`，或用 `StarDataByNameAll` 取全部候选。也支持 `名[宿]` 写法（如 `"杵增一[危宿]"`），但新代码建议用结构化参数。
|
||||
|
||||
**Breaking change**：旧实现遇到同名会静默返回其中一颗；现在返回 `ErrStarNameAmbiguous`。可用 `errors.Is(err, star.ErrStarNameAmbiguous)` 判断，再用 `StarDataByNameAll` / `StarDataByNameIn` 消歧。`StarDataByNameIn` 的 region 为空时等价于 `StarDataByName`，重名仍返回歧义错误。错误文本也从 `no such star` 改为 `star not found: ...`，请用 `errors.Is` 判断，不要匹配文本。
|
||||
|
||||
英文常用名同样走 `StarDataByName`，大小写和首尾空白不敏感，例如 `"sirius"`、`"Vega"`、`"Polaris"`。它只覆盖内置的 `CommonName`（约 218 条），不包含完整拜耳名（如 `Alpha Canis Majoris`）；Bayer/Flamsteed 仍在 `Name` 字段。英文名也可能重名（如 `Gienah` 对应两颗星），此时返回 `ErrStarNameAmbiguous`，用 `StarDataByNameAll` 取候选。
|
||||
|
||||
```go
|
||||
s, err := star.StarDataByName("sirius") // HR 2491
|
||||
```
|
||||
|
||||
```go
|
||||
s, err := star.StarDataByNameIn("杵增一", "危宿") // HR 8449，s.ChineseRegion == "危宿"
|
||||
```
|
||||
|
||||
### 升落与中天
|
||||
|
||||
@@ -341,7 +358,7 @@ if errors.Is(err, star.ERR_STAR_NEVER_RISE) || errors.Is(err, star.ERR_STAR_NEVE
|
||||
|
||||
- **极区哨兵错误**：`RiseTime` 在极夜返回 `star.ERR_STAR_NEVER_RISE`（该日永远在地平线下），`SetTime` 在极昼返回 `star.ERR_STAR_NEVER_SET`（该日永远在地平线上），用 `errors.Is` 判定；`ERR_STAR_NEVER_DOWN` 是 `ERR_STAR_NEVER_SET` 的废弃别名，`DownTime` 是 `SetTime` 的废弃别名。
|
||||
- **蒙气差模型的区间**：Saemundsson 近似只在真高度角 `(-5°, 90°)` 内生效，区间外修正量为 0——深在地平线以下时视高度角与几何高度角完全相等。
|
||||
- **星表口径**：BSC / HR `1–9110`，视星等 `-1.46`～`7.96`；按名字查询只匹配库内中文名（如 `天狼`、`织女一`），英文名不参与。
|
||||
- **星表口径**：BSC / HR `1–9110`，视星等 `-1.46`～`7.96`；按中文名/别名/英文常用名查询匹配库内中文名、别名与 `CommonName`（如 `天狼`、`织女一`、`Sirius`）；重名时用 `StarDataByNameIn` 或 `StarDataByNameAll`。
|
||||
- **与外部星表对表**：库内位置是 J2000 平位置叠加自行与岁差章动；与外部星表逐位对表时先用 `RaDecByDate` 统一到同一时刻，再比较。
|
||||
|
||||
## 参数与返回值约定
|
||||
@@ -352,7 +369,7 @@ if errors.Is(err, star.ERR_STAR_NEVER_RISE) || errors.Is(err, star.ERR_STAR_NEVE
|
||||
- **观测点高度**：`height` 是椭球高（大地高），单位米；手上只有海拔正高时要先加大地水准面差距，约定见「观测点高度约定」。
|
||||
- **蒙气差模型的有效区间**：`ApparentAltitude`/`ApparentZenith` 用的 Saemundsson 近似只在真高度角 `(-5°, 90°)` 内生效，区间外修正量为 0——所以深在地平线以下时视高度角与几何高度角完全相等（示例里天狼星 `alt=-30.180` 与 `Altitude` 同值就是这个原因）。气压必须为正、气温必须高于绝对零度，否则返回 `NaN`。
|
||||
- **`aero` 语义**：真值按标准蒙气差修正后的地平求升落，假值走几何地平；两者的差值在低纬度约 2–3 分钟，高纬度会明显放大。
|
||||
- **星表范围**：HR `1–9110`、视星等 `-1.46`～`7.96`，按中文名查询只匹配库内中文名。
|
||||
- **星表范围**：HR `1–9110`、视星等 `-1.46`～`7.96`；按中文名、中文别名或英文常用名查询（英文名大小写不敏感），重名时用 `StarDataByNameIn` 或 `StarDataByNameAll`。
|
||||
|
||||
## 相关手册
|
||||
|
||||
|
||||
Reference in New Issue
Block a user