\input texinfo @c -*-texinfo-*-
@c Copyright (c) 2019-2026, John Donoghue <john.donoghue@ieee.org>
@c Octave cfitsio - Octave FITS file I/O.

@c For manually generating the documentation use
@c   LANGUAGE=en makeinfo --html --no-split octave-cfitsio.texi

@c %*** Start of HEADER
@setfilename octave-cfitsio.info
@settitle Octave CFITSIO - FITS File I/O Toolkit for GNU octave
@afourpaper
@paragraphindent 0
@finalout
@c @afourwide
@c %*** End of the HEADER

@include version.texi
@include macros.texi

@c %*** Start of TITLEPAGE
@titlepage
@title Octave CFITSIO Toolkit @value{VERSION}
@subtitle FITS file functionality for @acronym{GNU} Octave.
@author John Donoghue
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2019-@value{YEAR} John Donoghue

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the same conditions as for modified versions.

@page
@heading Distribution
The @acronym{GNU} Octave CFITSIO package is @dfn{free} software.
Free software is a matter of the users' freedom to run, copy, distribute,
study, change and improve the software.
This means that everyone is free to use it and free to redistribute it
on certain conditions.  The @acronym{GNU} Octave CFITSIO package
is not, however, in the public domain.  It is copyrighted and there are
restrictions on its distribution, but the restrictions are designed to
ensure that others will have the same freedom to use and redistribute
Octave that you have.  The precise conditions can be found in the
@acronym{GNU} General Public License that comes with the @acronym{GNU}
Octave CFITSIO package and that also appears in @ref{Copying}.

To download a copy of the @acronym{GNU} Octave CFITSIO package, please visit
@url{https://gnu-octave.github.io/octave-@value{PACKAGE}/index}.

@end titlepage
@c %*** End of TITLEPAGE

@dircategory Math
@direntry
* Octave CFITSIO: (octave-@value{PACKAGE}).          CFITSIO Toolkit for Octave
@end direntry

@c %*** Start of BODY
@contents
@ifnottex
@node Top
@top Introduction
The @acronym{GNU} Octave CFITSIO toolkit is a set of functions for manipulating Flexible Image Transport
System (FITS) files for GNU Octave.
@end ifnottex

@menu
* Installing and loading::    Installing and loading the toolkit
* Basic Usage Overview::      Basic Usage Overview
* Function Reference::        CFITSIO toolkit functions
* Copying::                   Copying
* Index::                     Index
@end menu

@c -------------------------------------------------------------------------
@node Installing and loading
@chapter Installing and loading
@cindex Installing and loading

The @acronym{GNU} Octave CFITSIO toolkit must be installed and then loaded to be used.

It can be installed in @acronym{GNU} Octave directly from octave-@value{PACKAGE},
or can be installed in an off-line mode via a downloaded tarball.


The toolkit has a dependency on the cfitsio library (@url{https://heasarc.gsfc.nasa.gov/fitsio/}), so it must be installed in order
to successfully install the @acronym{GNU} Octave toolkit.

For Fedora: @code{yum install cfitsio-devel} 

The toolkit must be then be loaded once per each @acronym{GNU} Octave session in order to use its functionality.

@section Windows install
@cindex Windows install
If running in Windows, the package may already be installed, to check run:

@example
pkg list cfitsio
@end example

Otherwise it can be installed by installing the requirements and then using the online or offline install method.

@section Online Direct install
@cindex Online install
With an internet connection available, the package can be installed from
octave-@value{PACKAGE} using the following command within @acronym{GNU} Octave:

@example
pkg install "https://github.com/gnu-octave/octave-/@value{PACKAGE}releases/download/v@value{VERSION}/octave-@value{PACKAGE}-@value{VERSION}.tar.gz"
@end example

On @acronym{GNU} Octave 7 and higher, the package can be installed in the simpler form of:

@example
pkg install -forge @value{PACKAGE}
@end example

The latest released version of the toolkit will be downloaded and installed.

@section Off-line install
@cindex Off-line install
With the toolkit package already downloaded, and in the current directory when running
@acronym{GNU} Octave, the package can be installed using the following command within @acronym{GNU} Octave:

@example
pkg install octave-@value{PACKAGE}-@value{VERSION}.tar.gz
@end example

@section Loading
@cindex Loading
Regardless of the method of installing the toolkit, in order to use its functions
the toolkit must be loaded using the pkg load command:

@example
pkg load @value{PACKAGE}
@end example

The toolkit must be loaded on each @acronym{GNU} Octave session.

@c -------------------------------------------------------------------------
@node Basic Usage Overview
@chapter Basic Usage Overview
@cindex Basic Usage Overview

@section Overview
@cindex Overview
The octave-@value{PACKAGE} toolkit provides high and low level functionality for reading and
writing FITS format files.

The high level functions provide base read and write of data to octave using the functions
fitsdisp, fitsinfo, fitsread and fitswrite.  The low level functions provide direct access to the cfitsio API and 
are provided under the matlab.io.fits namespace. The low level functions provide access to the low level
API of the CFITSIO C library (@url{https://heasarc.gsfc.nasa.gov/fitsio/}).

Since @acronym{GNU} Octave does not support the matlab import command, an import_fits function
is provided.

Running the statement:
@example
import_fits
@end example

Is the equivalent of running in matlab:
@example
import matlab.io.fits;
@end example


@section Using the toolkit
@cindex Using the toolkit

The package must be loaded each time a @acronym{GNU} Octave session is started:
@example
pkg load @value{PACKAGE}
@end example

After loading the toolkit, the toolkit functions are available.

@subsection Reading Data
@cindex  Reading Data
To read the primary image data of a fits file, use the fitsread function:


@example
  imagedata = fitsread("thefitsfile.fits");
@end example

@subsection Reading Information
@cindex  Reading Information
To read information about the content in a fits file, use the fitsinfo functions.


@example
  info = fitsinfo("thefitsfile.fits");
@end example

@subsection Low level functionality
@cindex  Low level functionality
Where functionality is required that is not met by the high level functions, 
most of the cfitsio functions are available in the matlab.io.fits namespace.

Knowledge of the @url{https://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c_user/cfitsio.html, CFITSIO c library}
is beneficial in using the low level functions.

Low level functions can be accessed using thier full package name name:

@example
  fd = matlab.io.fits.openFile('tst0012.fits');
@end example

Using import_fits, functions can be used using the fits name:

@example
  import_fits;
  fd = fits.openFile('tst0012.fits');
@end example

The following example will open a FITS file and display each HDU Type:

@example
  # import the fits functions so don't have to use the full namespace each time
  import_fits;

  # open the file
  fd = fits.openFile('tst0012.fits');

  # get number of hdus in the file
  n = fits.getNumHDUs (fd);

  # for each hdu, go to it, print out the type
  for j = 1:n
    hdutype = fits.movAbsHDU (fd, j);
    printf ('HDU %d:  "%s"\n', j, hdutype);
  endfor

  # close the file
  fits.closeFile (fd);
@end example

@c -------------------------------------------------------------------------
@node Function Reference
@chapter Function Reference
@cindex Function Reference

The functions currently available in the toolkit are described below:

@include functions.texi

@c -------------------------------------------------------------------------

@include gpl.texi

@c -------------------------------------------------------------------------
@node Index 
@unnumbered Index 
 
@printindex cp
 
@bye
