fitsio

• 主要文档
• 更改日志

lib.rs:

fitsio - 对 C 库 [cfitsio][cfitsio] 的薄包装。

• 文件访问
• 格式化打印
• HDU 访问
• 创建新的 HDU
• 创建新的图像
• 创建新的表格
• 列描述
• 将 HDU 复制到另一个文件
• 删除 HDU
• 遍历文件中的 HDU
• 一般调用行为
• 头部键
• 读取文件数据
• 读取图像
• ndarray 支持
• 读取表格
• 读取单元格值
• 读取行
• 遍历列
• 写入文件数据
• 写入图像
• 调整图像大小
• 写入表格
• 写入表格数据
• 插入列
• 删除列
• 原始 FITS 文件访问
• 线程安全访问

此库包装了低级 cfitsio 绑定：[fitsio-sys][fitsio-sys]，并为 Rust 用户提供了更本地的体验。

FITS 文件的主接口是 [FitsFile][fits-file]。所有文件操作和读取都从这个类开始。

文件访问

要打开现有文件，请使用 [open][fitsfile-open] 方法。

use fitsio::FitsFile;

// let filename = ...;
let fptr = FitsFile::open(filename)?;

或者，可以使用配套方法 [create][fits-file-create] 在磁盘上创建新文件

use fitsio::FitsFile;

// let filename = ...;
let fptr = FitsFile::create(filename).open()?;

[[code][src-rs]create[fits-file-create]] 方法返回一个 [[code][src-rs]NewFitsFile[新-fits-file]]，它是磁盘上临时 FITS 文件的内部表示，在文件完全创建之前。

这种表示方法有两种方法：[open][new-fits-file-open] 和 [with_custom_primary][new-fits-file-with-custom-primary]。实际上，[open][new-fits-file-open] 方法会在磁盘上创建文件，但在调用此方法之前，可以使用 [with_custom_primary][new-fits-file-with-custom-primary] 方法添加自定义的 primary HDU。这对于图像来说非常有用。否则，会创建一个默认的 primary HDU。上面展示了不添加自定义 primary HDU 的示例。下面我们看到 [with_custom_primary][new-fits-file-with-custom-primary] 的示例。

use fitsio::FitsFile;
use fitsio::images::{ImageType, ImageDescription};

// let filename = ...;
let description = ImageDescription {
data_type: ImageType::Double,
dimensions: &[52, 103],
};

let fptr = FitsFile::create(filename)
.with_custom_primary(&description)
.open()?;

从这一点开始，可以查询和更改当前 HDU，或者读取 fits 头卡或文件内容。

要以读/写模式打开 fits 文件（以允许更改文件），必须使用 [edit][fits-file-edit]。这将打开一个已存在于磁盘上的文件以进行编辑。

use fitsio::FitsFile;

// let filename = ...;
let fptr = FitsFile::edit(filename)?;

格式化打印

可以使用 [pretty_print][pretty-print] 或其更强大的同类 [pretty_write][pretty-write] 来进行 fits 文件的 pretty-print。

use fitsio::FitsFile;

let mut fptr = FitsFile::open(filename)?;
fptr.pretty_print()?;
// or
fptr.pretty_write(&mut io::stdout())?;

遵循每次发布 fits 库时都发布 fits 摘要程序的传统，这个库包含一个二进制程序 fitssummary，可以使用 cargo install 安装。它接受命令行上的 fits 文件并打印它们的摘要到 stdout。

$ fitssummary ../testdata/full_example.fits

file: ../testdata/full_example.fits
mode: READONLY
extnum hdutype      hduname    details
0      IMAGE_HDU               dimensions: [100, 100], type: Long
1      BINARY_TBL   TESTEXT    num_cols: 4, num_rows: 50

HDU 访问

HDU 信息属于 [FitsHdu][fits-hdu] 对象。可以通过 String/str 或整数（0 索引）使用 [hdu][fitsfile-hdu] 方法获取 HDU。《HduInfo》对象包含有关当前 HDU 的信息。

#
use fitsio::hdu::HduInfo;

let hdu = fptr.hdu(0)?;
// image HDU
if let HduInfo::ImageInfo { shape, .. } = hdu.info {
println!("Image is {}-dimensional", shape.len());
println!("Found image with shape {:?}", shape);
}

// tables
if let HduInfo::TableInfo { column_descriptions, num_rows, .. } = hdu.info {
println!("Table contains {} rows", num_rows);
println!("Table has {} columns", column_descriptions.len());
}

始终可以使用 FitsFile::primary_hdu 方法访问主 HDU。

创建新的 HDU

创建新的图像

使用 [create_image][fits-file-create-image] 方法创建新的 fits 图像。此方法需要扩展名和一个 [ImageDescription][image-description] 对象，该对象定义所需图像的形状和类型。

use fitsio::images::{ImageDescription, ImageType};

let image_description = ImageDescription {
data_type: ImageType::Float,
dimensions: &[100, 100],
};
let hdu = fptr.create_image("EXTNAME".to_string(), &image_description)?;

与 cfitsio 不同，new_size 的维度顺序遵循 C 规范，即 行主序。

创建新的表格

与创建新图像类似，使用 [create_table][fits-file-create-table] 方法创建新表。这需要扩展名和 [ColumnDescription][column-description]s 的切片。

use fitsio::tables::{ColumnDescription, ColumnDataType};

let first_description = ColumnDescription::new("A")
.with_type(ColumnDataType::Int)
.create()?;
let second_description = ColumnDescription::new("B")
.with_type(ColumnDataType::Long)
.create()?;
let descriptions = [first_description, second_description];
let hdu = fptr.create_table("EXTNAME".to_string(), &descriptions)?;

列描述

列使用 [ColumnDescription][column-description] 结构描述。这封装了：列的名称和数据格式。

fits 规范允许标量或向量列，数据格式由 [ColumnDataDescription][column-data-description] 结构描述，该结构又封装了每行元素的数量（通常是 1）、列的宽度（对于字符串）和数据类型，数据类型是 [ColumnDataType][column-data-type] 成员之一。

对于标量列的常见情况，可以使用 scalar 方法构造 ColumnDataDescription 对象。

use fitsio::tables::{ColumnDescription, ColumnDataDescription, ColumnDataType};

let desc = ColumnDataDescription::scalar(ColumnDataType::Int);
assert_eq!(desc.repeat, 1);
assert_eq!(desc.width, 1);

可以使用 vector 方法构造向量列。

use fitsio::tables::{ColumnDataDescription, ColumnDescription, ColumnDataType};

let desc = ColumnDataDescription::vector(ColumnDataType::Int, 100);
assert_eq!(desc.repeat, 100);
assert_eq!(desc.width, 1);

这些实现 From<...> for String，以便获得传统的 fits 列描述字符串。

use fitsio::tables::{ColumnDataDescription, ColumnDescription, ColumnDataType};

let desc = ColumnDataDescription::scalar(ColumnDataType::Int);
assert_eq!(String::from(desc), "1J".to_string());

将 HDU 复制到另一个文件

可以使用 [copy_to][fits-hdu-copy-to] 方法将 HDU 复制到另一个打开的文件。这需要一个打开的 [FitsFile][fits-file] 对象来复制到。

#
#
hdu.copy_to(&mut src_fptr, &mut dest_fptr)?;

删除 HDU

当前HDU可以使用[delete][fits-hdu-delete]方法进行删除。注意：此方法会接管self的所有权，因此在此调用之后，[FitsHdu][fits-hdu]对象将无法使用。

// let fptr = FitsFile::open(...)?;
// let hdu = fptr.hdu(0)?;
hdu.delete(&mut fptr)?;
// Cannot use hdu after this

for hdu in fptr.iter() {
// Do something with hdu
}

let int_value: i64 = fptr.hdu(0)?.read_key(&mut fptr, "INTTEST")?;

// Alternatively
let int_value = fptr.hdu(0)?.read_key::<i64>(&mut fptr, "INTTEST")?;


// Or let the compiler infer the types (if possible)

let int_value_with_comment: HeaderValue<i64> = fptr.hdu(0)?.read_key(&mut fptr, "INTTEST")?;
let HeaderValue { value, comment } = int_value_with_comment;

fptr.hdu(0)?.write_key(&mut fptr, "foo", 1i64)?;
assert_eq!(fptr.hdu(0)?.read_key::<i64>(&mut fptr, "foo")?, 1i64);

// with comments
fptr.hdu(0)?.write_key(&mut fptr, "bar", (1i64, "bar comment"))?;

let HeaderValue { value, comment } = fptr.hdu(0)?.read_key::<HeaderValue<i64>>(&mut fptr, "bar")?;
assert_eq!(value, 1i64);
assert_eq!(comment, Some("bar comment".to_string()));

// Read the first 100 pixels
let first_row: Vec<i32> = hdu.read_section(&mut fptr, 0, 100)?;

// Read a square section of the image
let xcoord = 0..10;
let ycoord = 0..10;
let chunk: Vec<i32> = hdu.read_region(&mut fptr, &[&ycoord, &xcoord])?;

let start_row = 0;
let num_rows = 10;
let first_few_rows: Vec<f32> = hdu.read_rows(&mut fptr, start_row, num_rows)?;

// 10 rows of 100 columns
assert_eq!(first_few_rows.len(), 1000);

let image_data: Vec<f32> = hdu.read_image(&mut fptr, )?;

// 100 rows of 100 columns
assert_eq!(image_data.len(), 10_000);

use fitsio::FitsFile;
use ndarray::ArrayD;

let mut f = FitsFile::open("../testdata/full_example.fits").unwrap();
let hdu = f.primary_hdu().unwrap();

let data: ArrayD<u32> = hdu.read_image(&mut f).unwrap();
let dim = data.dim();
assert_eq!(dim[0], 100);
assert_eq!(dim[1], 100);
assert_eq!(data[[20, 5]], 152);
#

let integer_data: Vec<i32> = hdu.and_then(|hdu| hdu.read_col(&mut fptr, "intcol"))?;

let result: i64 = tbl_hdu.read_cell_value(&mut f, "intcol", 4)?;
assert_eq!(result, 16);

let result: String = tbl_hdu.read_cell_value(&mut f, "strcol", 4)?;
assert_eq!(result, "value4".to_string());

use fitsio::tables::FitsRow;
use fitsio_derive::FitsRow;

#[derive(Default, FitsRow)]
struct Row {
#[fitsio(colname = "intcol")]
intfoo: i32,
#[fitsio(colname = "strcol")]
foobar: String,
}
#

// Pick the 4th row
let row: Row = hdu.row(&mut f, 4)?;
assert_eq!(row.intfoo, 16);
assert_eq!(row.foobar, "value4");

for column in hdu.columns(&mut fptr) {
// Do something with column
}

#
let data_to_write: Vec<f64> = vec![1.0, 2.0, 3.0];
hdu.write_section(&mut fptr, 0, data_to_write.len(), &data_to_write)?;

#
let data_to_write: Vec<f64> = vec![1.0, 2.0, 3.0, 4.0];
let ranges = [&(0..1), &(0..1)];
hdu.write_region(&mut fptr, &ranges, &data_to_write)?;

#
// Image is 3x1
assert!(hdu.write_image(&mut fptr, &[1.0, 2.0, 3.0]).is_ok());
assert!(hdu.write_image(&mut fptr, &[1.0, 2.0, 3.0, 4.0]).is_err());

use fitsio::hdu::HduInfo;

hdu.resize(&mut fptr, &[1024, 1024])?;

// Have to get the HDU again, to reflect the latest changes
let hdu = fptr.hdu(0)?;
match hdu.info {
HduInfo::ImageInfo { shape, .. } => {
assert_eq!(shape, [1024, 1024]);
}
_ => panic!("Unexpected hdu type"),
}

let data_to_write: Vec<i32> = vec![10101; 5];
hdu.write_col(&mut fptr, "bar", &data_to_write)?;
let data: Vec<i32> = hdu.read_col(&mut fptr, "bar")?;
assert_eq!(data, vec![10101, 10101, 10101, 10101, 10101]);

let data_to_write: Vec<i32> = vec![10101; 10];
hdu.write_col_range(&mut fptr, "bar", &data_to_write, &(0..5))?;
let data: Vec<i32> = hdu.read_col(&mut fptr, "bar")?;
assert_eq!(data, vec![10101, 10101, 10101, 10101, 10101]);

use fitsio::tables::{ColumnDescription, ColumnDataType};

let column_description = ColumnDescription::new("abcdefg")
.with_type(ColumnDataType::Int)
.create()?;
hdu.append_column(&mut fptr, &column_description)?;

let newhdu = hdu.delete_column(&mut fptr, "bar")?;
// or
let newhdu = hdu.delete_column(&mut fptr, 0)?;

use fitsio::FitsFile;

let mut fptr = FitsFile::open(filename)?;

/* Find out the number of HDUs in the file