Go fitsio 图像轴长度为何不等于总像素数

Go fitsio 里，图像的轴数量和像素总数是两个概念。Header.Axes() 返回的是每一条轴的长度，例如 [4, 3] 表示两条轴，分别长 4 和 3；len(axes) 得到的只是 2，而真正的像素数量是 4 × 3 = 12。三维图像同样要把三条轴全部相乘。

如果用 len(axes) 分配 Image.Read 的目标切片，得到的缓冲区通常会比图像实际像素少。正确做法是先读取轴长度，再计算乘积，最后让切片元素类型与图像数据类型匹配。

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

先区分轴的数量与每条轴的长度

FITS 图像头部把维度拆成了两层信息：NAXIS 表示轴的数量，NAXIS1、NAXIS2 等分别表示对应轴的长度。在 fitsio 中，这组轴长度通过 Header.Axes() 暴露出来，因此返回值的长度对应维度数量，返回值中的每个整数才是对应维度的大小。

例如，axes := []int{4, 3} 可以理解为一个 4×3 的二维图像。这里有三个容易混淆的数字：

用各轴长度的乘积计算像素总数

不要为二维图像单独写一套规则，再为三维图像补一个乘法。把“各轴长度求乘积”抽成一个小函数，遇到不同维度的 FITS 图像时仍然使用同一条规则。空轴列表和非正轴长度也应该尽早报告，避免后面出现难以解释的切片长度问题。

package main

import "fmt"

// pixelCount 将每条轴的长度相乘，得到扁平像素缓冲区所需的元素数。
func pixelCount(axes []int) (int, error) {
	if len(axes) == 0 {
		return 0, fmt.Errorf("FITS 图像没有轴")
	}

	// 用无符号位移得到当前平台的最大 int，避免乘法溢出后静默得到错误长度。
	maxInt := int(^uint(0) >> 1)
	total := 1
	for i, size := range axes {
		if size  maxInt/size {
			return 0, fmt.Errorf("像素总数超出 int 范围")
		}
		total *= size
	}
	return total, nil
}

func main() {
	// 二维图像有两条轴，但像素元素数量是两条轴长度的乘积。
	count, err := pixelCount([]int{4, 3})
	if err != nil {
		panic(err)
	}
	fmt.Println(count) // 12
}

上面的函数返回的是扁平切片的元素数，不是字节数。若每个元素是 float64，底层字节规模还要结合元素大小考虑；但给 Image.Read 的目标通常首先要保证元素数量和数据类型正确。

让 Image.Read 的目标切片匹配图像数据

fitsio 的图像接口提供 Read(ptr interface{}) error。官方示例先从头部拿到 axes，再按二维轴的乘积分配 []float64，随后把切片地址传给 Read。这说明读取问题至少有两道边界：长度边界来自所有轴的乘积，类型边界来自 FITS 图像的像素编码和 Go 目标类型。

下面的示例只演示读取链路。它假设输入图像的像素适合用 float64 接收；如果文件的 BITPIX 与目标类型不匹配，应按实际数据类型调整目标切片，而不是只把切片长度改大。

package main

import (
	"fmt"
	"io"

	"github.com/astrogo/fitsio"
)

// readPrimaryImage 从第一个 HDU 读取扁平的浮点像素切片。
func readPrimaryImage(r io.Reader) ([]float64, error) {
	f, err := fitsio.Open(r)
	if err != nil {
		return nil, fmt.Errorf("打开 FITS 失败: %w", err)
	}
	defer f.Close() // 释放 FITS 文件对象持有的读取资源

	hdu := f.HDU(0)
	img, ok := hdu.(fitsio.Image)
	if !ok {
		return nil, fmt.Errorf("第一个 HDU 不是图像")
	}

	axes := hdu.Header().Axes()
	count, err := pixelCount(axes)
	if err != nil {
		return nil, err
	}

	// 目标切片长度等于所有轴长度的乘积，不是 len(axes)。
	data := make([]float64, count)
	if err := img.Read(&data); err != nil {
		return nil, fmt.Errorf("读取图像像素失败: %w", err)
	}
	return data, nil
}

这里的 data 是一维切片，适合先把 FITS 图像作为连续像素序列接收。若业务需要二维或更高维访问，可以在拿到数据后依据 axes 自己映射坐标；映射时仍要保留“每条轴的长度”和“总元素数”这两个不同概念。

按表格排查常见误读

当读取结果为空、长度不符或 Read 报错时，可以按下面的顺序核对。先看元数据是否被正确解释，再看目标切片，不要一开始就怀疑文件里少了像素。

如果文件可能来自不同来源，还要注意某些 FITS 图像的轴数并不固定。读取逻辑应以当前 HDU 的 Header.Axes() 为准，而不是把某个样本文件的宽高写死在程序里。这样既能避免缓冲区不足，也不会因为维度变化而错误地把元数据解释成像素数量。

相关问题

为什么 axes 的长度不是图像长度？

因为 axes 保存的是“每条轴的长度”这组元数据。它的切片长度代表轴的数量，像素总数要对切片中的数值求乘积。

三维图像是不是要分配三维 Go 数组？

不一定。fitsio 的读取示例使用扁平切片接收像素，关键是元素数量和类型匹配。需要按坐标访问时，再依据轴长度把扁平索引映射到业务结构。

只把切片分配得更大能解决读取错误吗？

不能。切片长度、元素类型和当前 HDU 的图像数据都要对应；长度更大并不能替代对 BITPIX 和读取错误的检查。