Go fitsio 怎样读取图像HDU的像素数组

Go fitsio 读取图像HDU时，先从文件中选出实现 fitsio.Image 的HDU，再读取头部的轴长度和 BITPIX，创建类型及容量匹配的切片，最后调用 img.Read(&pixels)。不要把空切片直接交给它，也不要默认第一个HDU就含有二维图像。

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

下面以已有科学数据接入程序为例，读取一个二维、BITPIX=-32 的图像，返回宽、高和 []float32 存储值。示例固定使用 v0.3.0 的接口；该仓库已归档，适合维护已有依赖时参考，接入新的长期项目还需考虑维护安排。

先确定目标HDU和像素存储类型

FITS文件由多个 Header/Data Unit 组成，每个HDU拥有自己的头部和数据。主HDU位于索引0，后续扩展也可能是图像，或者是ASCII表、二进制表。主HDU允许没有图像数据，所以不能仅凭文件扩展名或索引猜测内容。

代码先取得 f.HDUs()，对索引做范围判断，然后使用带布尔结果的类型断言。图像对象的 Header() 提供 Axes() 和 Bitpix()；前者表示各轴长度，后者描述存储值的位宽及数值类型。

负号表示浮点存储，不是负的像素值。不要因为业务最后需要 float64，就给32位整数图像直接分配 []float64；应先用匹配的具体类型读取，再显式转换。

在解析前限制输入规模并固定依赖

在维护项目的独立工作目录中添加依赖，再把下节代码保存为 main.go。已有Go模块无需再次初始化。

# 新建示例模块；已有项目跳过这一行
go mod init example.org/fits-plane
# 固定示例所采用的库接口，避免依赖解析结果漂移
go get github.com/astrogo/fitsio@v0.3.0
# observation.fits需为自行准备的受信任二维浮点图像
go run .

fitsio.Open 会在打开时解码文件中的HDU，并不是等到访问选定图像时才读取全部内容。因此，仅在 Read 前限制像素数量，不能限制打开文件阶段的内存。示例在调用 Open 之前要求输入为不超过64MiB的普通文件，再对选定图像额外限制最多8,388,608个像素。这些数字是示例的接入策略，不是库的格式上限，也不代表整体内存只会占用这些字节。

该实现面向受信任且读取期间不会被改写的本地文件。文件大小约束不能保证损坏头部中的尺寸声明合理；如果要接收外部上传，应把解析放在具有独立内存和时间限制的工作进程中，而不是将此函数当作完整的恶意文件防护层。

实现只读二维float32读取函数

函数把HDU索引作为显式参数，避免主图像与科学图像扩展混淆。先限制尺寸，再计算元素总数和分配切片。这里使用内置 float32，不依赖自定义数值类型的隐式转换。

package main

import (
    "fmt"
    "os"

    "github.com/astrogo/fitsio"
)

type Plane32 struct {
    Width, Height int
    Pixels []float32
}

// ReadPlane32 只读取受信任本地文件中的二维浮点存储值，不做物理量标定。
func ReadPlane32(path string, index int) (*Plane32, error) {
    src, err := os.Open(path)
    if err != nil { return nil, fmt.Errorf("打开输入: %w", err) }
    defer src.Close()

    info, err := src.Stat()
    if err != nil { return nil, fmt.Errorf("读取文件属性: %w", err) }
    // Open 会解码全部HDU；在解析前先限制普通文件大小。
    if !info.Mode().IsRegular() || info.Size() > 64= len(hdus) {
        return nil, fmt.Errorf("HDU索引%d越界，数量%d", index, len(hdus))
    }
    img, ok := hdus[index].(fitsio.Image)
    if !ok { return nil, fmt.Errorf("HDU %d不是图像", index) }
    hdr := img.Header()
    if hdr.Bitpix() != -32 {
        return nil, fmt.Errorf("此入口仅接受BITPIX=-32，实际%d", hdr.Bitpix())
    }
    axes := hdr.Axes()
    if len(axes) != 2 || axes[0]  maxPixels/h { return nil, fmt.Errorf("像素数超过上限") }
    count := w*h
    if len(img.Raw()) != count*4 {
        return nil, fmt.Errorf("像素字节长度与图像尺寸不一致")
    }
    pixels := make([]float32, count)
    // Read需要切片指针，并依赖现有容量，不应传入nil切片。
    if err := img.Read(&pixels); err != nil {
        return nil, fmt.Errorf("读取HDU %d像素: %w", index, err)
    }
    return &Plane32{Width:w, Height:h, Pixels:pixels}, nil
}

func main() {
    // 修改索引可选择扩展HDU；这里明确选择主HDU。
    plane, err := ReadPlane32("observation.fits", 0)
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    // 此处是存储值；是否需要标定由业务根据头关键字决定。
    fmt.Printf("宽=%d 高=%d 像素数=%d 首值=%g\n",
        plane.Width, plane.Height, len(plane.Pixels), plane.Pixels[0])
}

Read 的参数应为指向切片的指针。该版本内部会把切片长度设置为元素数量，但不会替调用者创建足够的底层容量，所以 var pixels []float32 后直接读取并不合适；用 make([]float32, count) 明确承担分配更容易控制资源。

w > maxPixels/h 在乘法前拒绝超限尺寸，且之前已排除零高度。对于这条只接受 -32 的入口，像素数据字节数应为 count*4，从而能在调用解码前发现选中图像的长度与维度不一致。表HDU、空主HDU、三维数据立方体和其他位深都会明确返回错误，不会被当成二维浮点图像勉强读取。

按第一轴优先访问像素，另行处理标定值

对于普通二维FITS数组，第一轴变化最快。把第一轴长度作为宽度，第二轴长度作为高度，零起点坐标 (x,y) 的平铺位置就是 y*width+x。FITS科学坐标描述常使用从1开始的像素坐标，不要直接把它代入Go切片。

// 在获得plane后，读取零起点坐标；不把坐标检查留给切片越界panic。
x, y := 2, 1
if x >= 0 && x = 0 && y 

例如，宽为3、高为2，平铺存储值为 [7,8,9,20,21,22] 时，坐标 (2,1) 对应索引5，值为22。这是按索引公式手算的示例，不是本机读取某个文件的结果。显示为图片时是否上下翻转，属于显示坐标和科学坐标之间的选择，读取数组本身不替你决定。

还应区分存储值与物理量。FITS可通过 BSCALE 与 BZERO 描述线性变换：物理量等于 BZERO + BSCALE × 存储值，默认分别是0和1。本例调用的是 Image.Read，该版本这条读取路径不自动执行这组标定；应另外读取头关键字，经过业务确认后再转换。不要把用于显示的 Image() 方法与数值切片读取视作完全相同的接口。

后续求均值、归一化或绘图时，也要为浮点像素中的NaN、无穷值制定处理规则；不能因为读取成功就认为全部像素适合参加统计。

把错误与资源所有权交给调用方

fitsio.File.Close() 不负责关闭底层 io.Reader。示例因此分别关闭库对象与 os.File，并把错误返回给调用者，而不是在读取函数内结束整个进程。后续接入服务时，调用者可以把同一错误映射为任务失败或文件不适用。

接入日志可记录业务文件标识、HDU索引、轴长度、BITPIX及错误类别，不必输出整幅像素数组或内部绝对路径。读取器不应修改输入文件，也不应悄悄把不支持的HDU替换成另一个HDU；是否改选扩展由调用方明确决定。

只有一维光谱也能用吗？

FITS图像HDU不局限于二维，本例为了返回宽高而主动限定二维。一维光谱应按各轴长度乘积创建切片，并使用适合光谱的坐标解释，不能强补一个高度假装二维。

能直接读取压缩图像扩展吗？

不能仅凭文件名保证这个入口支持。压缩图像可能以二进制表约定存储，本例会因图像类型不匹配而拒绝；应使用明确支持对应压缩约定的实现或先转为普通图像HDU。

需要把字节顺序手工翻转吗？

使用库的 Read 读取匹配类型时由解码器处理FITS的存储字节序。Raw() 返回的是原始数据字节，不能直接将其当成本机浮点切片重解释。

参考：fitsio接口文档、图像读取实现、文件与资源所有权实现、NASA FITS标准入口。