Skip to content

Latest commit

 

History

History
107 lines (92 loc) · 5.17 KB

README.md

File metadata and controls

107 lines (92 loc) · 5.17 KB
Raw

Rustronomy-fits - a Rustronomy tool for FITS file I/O

License: GPL v3 Crates.io

This crate is part of the Rustronomy Project

Rustronomy-fits provides I/O tools for reading, writing and parsing FITS files. It is currently still under heavy development.

Features/Roadmap

Features included in the latest release of rustronomy-fits are marked with ✔️. Features that are coming in the next release are marked with ✴️ (these might already be implemented in the main branch of this repo). Features that are coming some time in the future are marked with ❌.

Latest release: v0.1.0 - image support
Next feature-update: v0.2.0 - table support

Reading Fits Files

  • ✔️ Parsing FITS headers and keyword records
  • Parsing data in the primary HDU
    • ✔️ Images
    • ✴️ Tables
    • ❌ Binary Tables
    • ❌ Random Groups
  • Parsing Extensions
    • ✔️ Images
    • ✴️ Tables
    • ❌ Binary Tables

Writing Fits Files

  • Writing existing FITS files to disk
    • ✔️ Writing Headers to disk
    • ✔️ Writing Image HDU's to Disk
    • ✴️ Writing Table HDU's to Disk
    • ❌ Writing a primary HDU with Random Groups to Disk
    • ❌ Writing Binary Table HDU's to disk
  • ❌ Creating new (valid) FITS files

Quickstart

To use the latest release of Rustronomy-fits in a cargo project, add the rustronomy-fits crate as a dependency to your Cargo.toml file:

[dependencies]
rustronomy-fits = "0.1.0"

To use Rustronomy-fits in a Jupyter notebook, execute a cell containing the following code:

:dep rustronomy-fits = {version = "0.1"}

If you want to use the latest (unstable) development version of rustronomy-fits, you can do so by using the git field (which fetches the latest version from the repo) rather than the version field (which downloads the latest released version from crates.io).

{git = "https://github.com/smups/rustronomy-fits"}

Short example: Importing a FITS image as a ndarray

In this example, we create a Fits struct using the open() method, which takes the path to the file as an argument. Next, we get a reference to the second header-data-unit (HDU) in the file, wich contains an f64 encoded Image extension. We can get the Image from the HDU by matching the data contained in the HDU with the Extension::Image variant and then calling as_f64_array() on the unwrapped Image.

use rustronomy_fits::prelude::*;

let fits = Fits::open("somefile.fits")?;
let data_array = match fits.get_hdu(1).unwrap().get_data() {
  Extension::Image(img) => img.as_f64_array()?,
  _ => panic!()
};

Check out the examples folder in the repo root for Jupyter notebooks with more in-depth explanations and examples!

Contributing

Notes on testing

If you want to contribute to this module, please keep in mind the following points regarding testing:

  • all I/O tests make use of the resources/tests/ folder, located in the root of the rustronomy_fits/ folder.
  • rustronomy_fits uses the python package astropy as a reference to validate FITS files written during tests. Make sure to setup a python virtual environment with astropy and numpy installed to run these tests.
  • to test the reading functionalities of rustronomy_fits, a number of test FITS files are used during testing. These are too large to be uploaded to github. You can download them using this link: [TODO]. Be sure to place them in the resources/tests/ folder.

License

License: GPL v3

Rustronomy-fits is part of the Rustronomy project and inherits the gpl license from the overarching Rustronomy project

Rustronomy is explicitly not licensed under the dual Apache/MIT license common to the Rust ecosystem. Instead it is licensed under the terms of the GNU GPLv3.

Rustronomy is a science project and embraces the values of open science and free and open software. Closed and paid scientific software suites hinder the development of new technologies and research methods, as well as diverting much- needed public funds away from researchers to large publishing and software companies.

Rustronomy-fits is free software. It is licensed under the GNU GPL version 3 or later. That means you are free to use this program for any purpose; free to study and modify this program to suit your needs; and free to share this program or your modifications with anyone. If you share this program or your modifications you must grant the recipients the same freedoms. To be more specific: you must share the source code under the same license. For details see https://www.gnu.org/licenses/gpl-3.0.html or the LICENSE file in this github repository.