How It Works - An ExampleΒΆ

While the Python wrappers <wrappers> explains the formation of the modules and the pyGnuastro package, to get a more clear idea of how the interfacing between the Gnuastro Library and pyGnuastro we take the example of one of the most frequent use cases of an astronomy library i.e. Reading and Writing with a FITS image.

A basic example of an I/O operation is to read data from a FITS(.fits) image and writing the same data to an output FITS image. We can perform this task using pygnuastro as follows:

import pygnuastro.Fits

###################### READING ######################
# Here 'in' will be a NumPy array.
in = pygnuastro.fits.img_read(filename = "input.fits",
                              hdu = 0)

###################### WRITING ######################
if gnuastro.fits.img_write(in, "output.fits"):
  print("Write successful.")
else:
  print("Error in writing file")

The flow of the operations here and their interaction with Gnuastro can be described as follows:

  1. Call the pygnuastro.fits.img_read() function from Python, passing the filename and hdu as arguments.

  2. The C wrapper function parses these arguments and stores them in C variables of appropriate data type (here filename and hdu are strings).`

  3. Call the gal_fits_img_read() with these parsed arguments. This function returns a gal_data_t type.

  4. Convert the returned value to a PyArrayObject using one of the NumPy array creation functions and return it.

  5. Send the received numpy.array object as an argument to pygnuastro.fits.img_write() alongwith the output FITS image filename.

  6. The C wrapper function for the write method parses these arguments like in the case of reading, this time storing the NumPy array as a PyArrayObject.

  7. Use gal_data_alloc() to convert the input data-array from a PyArrayObject to gal_data_t.

  8. Use gal_fits_img_write() to then write this data to the output FITS filename and return the status of the write.