Go fitsio 主HDU与扩展HDU有什么区别

在 Go fitsio 里，主HDU和扩展HDU不是两套互不相干的对象：它们都属于 Header-Data Unit，都能通过统一的 HDU 接口读取头信息；真正的区别在于它们在 FITS 文件中的位置、允许承载的数据类型，以及后续应该调用的读取 API。

最容易记住的判断是：f.HDU(0) 是文件的主HDU，f.HDU(1) 及后面的对象是扩展HDU。扩展可以继续承载图像，也可以承载 ASCII 表或二进制表，所以不能看到“扩展”两个字就直接断言它一定是表。

官方地址：https://pkg.go.dev/github.com/astrogo/fitsio

主HDU和扩展HDU先看哪三个差异

因此，“主HDU一定是图像、扩展HDU一定是表”是一个不可靠的简化。fitsio 的 IMAGE_HDU 同时覆盖主数组或图像 HDU；表格则用 ASCII_TBL 和 BINARY_TBL 表示。

先枚举 HDU，再决定如何读取

实际项目不要把“第一个扩展就是表”写死。fitsio 的 File.HDUs() 会返回文件中的全部 HDU，配合 Name()、Version()、Type() 和头信息，可以先建立文件清单。

package main

import (
    "fmt"
    "log"
    "os"

    fits "github.com/astrogo/fitsio"
)

func listHDUs(path string) error {
    r, err := os.Open(path)
    if err != nil {
        return fmt.Errorf("打开 FITS 文件失败: %w", err)
    }
    defer r.Close() // fits.File.Close 不负责关闭底层 Reader，这里单独释放文件句柄

    f, err := fits.Open(r)
    if err != nil {
        return fmt.Errorf("解析 FITS 文件失败: %w", err)
    }
    defer f.Close() // 释放 fitsio 自己持有的 HDU 资源

    for i, hdu := range f.HDUs() {
        if hdu == nil {
            continue // 避免异常文件中的空项影响后续清单输出
        }
        fmt.Printf("index=%d name=%q type=%s version=%d\\n",
            i, hdu.Name(), hdu.Type(), hdu.Version())
    }
    return nil
}

func main() {
    if err := listHDUs("science.fits"); err != nil {
        log.Fatal(err) // 在命令行工具中保留原始错误，便于定位输入文件问题
    }
}

清单中的 index=0 就是主HDU。后续条目是扩展，但扩展的具体载荷仍要看 Type() 或 Go 类型。Name() 读取的是扩展名称，Version() 对应扩展版本；名称为空或版本缺省时，不应把它们当成稳定业务标识。

图像扩展和表格扩展要走不同 API

当 HDU 是图像时，可以断言为 fits.Image，然后调用 Read 读取像素数据；当 HDU 是表格时，断言为 *fits.Table，通过 Read 获得行游标，再用 Rows.Scan 扫描列。两条路径共享文件枚举入口，但数据读取对象不同。

func readHDU(f *fits.File, index int) error {
    hdu := f.HDU(index)
    if hdu == nil {
        return fmt.Errorf("HDU(%d) 不存在", index)
    }

    switch hdu.Type() {
    case fits.IMAGE_HDU:
        imageHDU, ok := hdu.(fits.Image)
        if !ok {
            return fmt.Errorf("HDU(%d) 标记为图像但没有 Image 接口", index)
        }
        var pixels []float32
        if err := imageHDU.Read(&pixels); err != nil {
            return fmt.Errorf("读取图像 HDU(%d) 失败: %w", index, err)
        }
        fmt.Printf("图像轴=%v，像素容器长度=%d\\n", imageHDU.Header().Axes(), len(pixels))
    case fits.ASCII_TBL, fits.BINARY_TBL:
        table, ok := hdu.(*fits.Table)
        if !ok {
            return fmt.Errorf("HDU(%d) 标记为表格但没有 Table 类型", index)
        }
        rows, err := table.Read(0, -1)
        if err != nil {
            return fmt.Errorf("创建表格游标失败: %w", err)
        }
        defer rows.Close() // 行游标也要关闭，避免长时间任务持有资源
        for rows.Next() {
            var id int64
            var value float64
            if err := rows.Scan(&id, &value); err != nil {
                return fmt.Errorf("扫描表格行失败: %w", err)
            }
            fmt.Printf("id=%d value=%v\\n", id, value)
        }
        if err := rows.Err(); err != nil {
            return fmt.Errorf("遍历表格行失败: %w", err)
        }
    default:
        return fmt.Errorf("HDU(%d) 的类型 %v 暂不支持", index, hdu.Type())
    }
    return nil
}

这个分支的重点不是把所有文件都转换成同一种结构，而是先尊重 HDU 的载荷类型。图像的轴信息从 Header().Axes() 读取；表格的列数、行数和列值则由 Table 与 Rows 处理。

为什么不能只用 HDU 索引判断业务含义

索引适合定位文件结构，不适合单独表达业务含义。一个文件可能只有主图像，也可能在主HDU后追加多个图像、表格或不同版本的同名扩展。只写 f.HDU(1).(*fits.Table) 会把文件布局假设藏进代码，一旦输入文件换了扩展顺序，就会出现类型断言失败或读取了错误数据。

更稳妥的做法是先枚举，再按名称和类型筛选：

func findTable(f *fits.File, name string) (*fits.Table, error) {
    if !f.Has(name) {
        return nil, fmt.Errorf("找不到名为 %q 的 HDU", name)
    }
    hdu := f.Get(name)
    table, ok := hdu.(*fits.Table)
    if !ok {
        return nil, fmt.Errorf("HDU %q 存在，但它不是表格", name)
    }
    return table, nil
}

Get 和 Has 解决的是按名称查找；如果文件中存在多个同名扩展，就要结合 Version() 或遍历 HDUs() 自己定义选择规则。不要把扩展名查找到就等同于已经确认了载荷类型。

一个可复用的判断清单

1. 先确认 f.HDUs() 的总数，记住主HDU固定在索引 0。
2. 对目标 HDU 同时查看 Type()、Name()、Version() 和 Header()。
3. IMAGE_HDU 走 fits.Image；ASCII_TBL 或 BINARY_TBL 走 *fits.Table。
4. 表格遍历后检查 rows.Err()，不要只依赖 Next() 返回 false。
5. 退出时分别关闭 Rows、fits.File 和底层 os.File。

常见追问

扩展HDU一定从索引 1 开始吗？

对一个合法的 FITS HDU 列表，主HDU在索引 0，扩展从索引 1 开始。真正的扩展数量和类型仍应以 HDUs() 枚举结果为准。

主HDU能不能是表格？

本文按 fitsio 的 API 语义讨论：主HDU通常通过主数组/图像接口表达，表格使用表格 HDU 类型。遇到非标准输入时，应以解析出的 Type() 和头信息为准，而不是凭文件名推断。

为什么表格读取后还要调用 Rows.Err？

Next() 只表示是否还有下一行；迭代过程中的底层读取错误需要通过 Err() 取得。生产代码应在循环结束后补这一层检查。

总结

Go fitsio 中，主HDU与扩展HDU的第一层区别是位置：HDU(0) 对应主HDU，之后才是扩展。第二层区别是载荷：扩展既可能是图像，也可能是 ASCII 表或二进制表。实际代码应以 HDUs 枚举结构、用 Type 选择 fits.Image 或 *fits.Table，再配合名称、版本和资源清理完成可靠读取。