Go fitsio 怎样创建带关键字的FITS主HDU

用 Go 的 fitsio 创建带关键字的 FITS 主HDU，核心是先用 NewHeader 或 NewDefaultHeader 得到头信息，再把 fitsio.Card 追加到 Header，最后交给 NewPrimaryHDU 生成图像型主HDU。写文件时再用 Create、Write 和 Close 组成完整边界。

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

如果要控制图像的位深、轴长度和自定义关键字，优先显式构造 Header；如果只调用 NewPrimaryHDU(nil)，得到的是库的默认头，不能代替业务元数据。

先确定主HDU的图像参数

fitsio 的 Header 同时描述 HDU 类型、bitpix 和轴长度。创建主HDU前，先把这三个值和像素切片对应起来。例如使用 float64 像素时，官方示例采用 bitpix=-64；二维图像的 axes 可以写成 []int{2, 2}，像素数据则准备四个元素。

NewHeader(cards, htype, bitpix, axes) 适合一次性给出完整初始头。若只是从默认头开始再补字段，可以用 NewDefaultHeader 加 Append。这两个入口不要混成“关键字就是图像数据”：关键字在 Header 中，像素数组由 Image 写入。

用 Header 和 Card 组织主HDU关键字

FITS 关键字在 fitsio 中以 Card 表示，每张 Card 有 Name、Value 和 Comment。标准字段由库负责生成，自定义字段则可以追加 EXTNAME、DATE-OBS 等业务元数据。下面的示例只展示对象如何组合，不把运行输出当成文章证据。

package main

import (
    "log"

    "github.com/astrogo/fitsio"
)

func buildPrimaryHDU() (fitsio.Image, error) {
    header := fitsio.NewHeader(
        []fitsio.Card{
            // EXTNAME 标识主HDU的业务名称，便于后续按语义识别。
            {Name: "EXTNAME", Value: "SCIENCE", Comment: "科学观测主图像"},
            // DATE-OBS 保存观测日期，值的格式应由项目约定保持一致。
            {Name: "DATE-OBS", Value: "2026-10-31", Comment: "观测日期"},
        },
        fitsio.IMAGE_HDU,
        -64,
        []int{2, 2},
    )

    // 显式传入 Header，让主HDU携带上面的关键字与图像形状。
    img, err := fitsio.NewPrimaryHDU(header)
    if err != nil {
        return nil, err
    }
    return img, nil
}

func main() {
    // 示例只负责展示构造入口；真实写入时还要处理 Image 和 File 的关闭。
    if _, err := buildPrimaryHDU(); err != nil {
        log.Fatal(err)
    }
}

如果是在已有 Header 上补充字段，可以改用 header.Append(fitsio.Card{...})。Header.Set 的语义是修改已有名称对应的 Card；新增业务字段时优先使用 Append，并为字段写清注释。这样后续维护者能区分库生成的结构字段和业务元数据。

把主HDU写入文件并管理关闭边界

创建出 Image 还不等于文件已经落盘。完整写入至少有三层对象：底层的 os.File，由 fitsio.Create 返回的 *fitsio.File，以及要写入的主HDU。File.Write 接收 HDU，File.Close 负责关闭 fitsio 文件；官方文档还说明，File.Close 不会替调用方关闭底层 Reader 或 Writer，所以底层文件仍需单独关闭。

package main

import (
    "log"
    "os"

    "github.com/astrogo/fitsio"
)

func writeFITS(path string) error {
    out, err := os.Create(path)
    if err != nil {
        return err
    }
    defer out.Close() // fitsio.File 不负责关闭这个底层输出文件。

    fits, err := fitsio.Create(out)
    if err != nil {
        return err
    }
    defer fits.Close() // 释放 fitsio 文件容器持有的资源。

    header := fitsio.NewHeader([]fitsio.Card{
        // 关键字和像素数据属于同一个主HDU。
        {Name: "EXTNAME", Value: "SCIENCE", Comment: "科学观测主图像"},
    }, fitsio.IMAGE_HDU, -64, []int{2, 2})
    img, err := fitsio.NewPrimaryHDU(header)
    if err != nil {
        return err
    }
    defer img.Close() // 关闭主HDU，避免对象生命周期失控。

    pixels := []float64{0.1, 0.2, 0.3, 0.4}
    if err := img.Write(pixels); err != nil {
        return err
    }
    return fits.Write(img) // 将带 Header 的主HDU写入 FITS 文件。
}

func main() {
    if err := writeFITS("observations.fits"); err != nil {
        log.Fatal(err)
    }
}

这里的 axes=[]int{2,2} 与 pixels 的四个元素相互匹配。若改成 []int{3,2}，就应同步准备六个像素，并在项目层面明确行列方向；不要只改 Header 而保留旧数据长度。

从旧写法迁移到显式 Header

在只需要快速生成空白主HDU时，NewPrimaryHDU(nil) 足够使用；但一旦文件要被其他程序或团队成员消费，默认头通常缺少业务上下文。迁移时可以按下面的变更表处理：

这不是把所有字段都塞进 Header。只写能被下游稳定解释的元数据，尤其要避免同一名称在不同文章或服务中代表不同格式。

发布前的回归检查

1. 确认主HDU使用 fitsio.IMAGE_HDU，并检查 bitpix 是否与像素 Go 类型对应。
2. 逐项检查 EXTNAME、DATE-OBS 等 Card 的名称、值和注释，新增字段使用 Append。
3. 把轴长度相乘后与像素数量对照，避免 Header 描述的形状与数据切片不一致。
4. 分别处理 NewPrimaryHDU、img.Write、fits.Write 和关闭操作的错误。
5. 确认 os.File 与 fitsio.File 都有明确的关闭责任，不把资源释放交给隐含行为。

常见问题

可以只用 Header.Append，不调用 NewHeader 吗？

可以先调用 NewDefaultHeader 得到默认 Header，再追加 Card；但需要自己确认默认的 bitpix 和 axes 是否适合当前像素数据。

EXTNAME 能代替主HDU的类型声明吗？

不能。EXTNAME 是名称类元数据，HDU 类型、bitpix 和轴长度仍由 Header 的结构字段决定。

File.Close 会关闭 os.File 吗？

不会。fitsio 文档明确区分文件容器和底层 Reader/Writer，底层 os.File 需要调用方单独关闭。

总结来说，创建带关键字的 FITS 主HDU可以拆成四个稳定动作：用 Header 描述结构，用 Card 保存业务元数据，用 NewPrimaryHDU 生成 Image，再用 Create、Write 和 Close 管理文件边界。迁移或扩展时只要同时检查 bitpix、axes、像素数量和资源关闭，代码就不容易出现“头信息看似正确、数据形状却不匹配”的问题。