.. SPDX-FileCopyrightText: 1992-2026 NWO-I/SRON Space Research Organisation Netherlands
..
.. SPDX-License-Identifier: CC-BY-4.0

FITS File Operations (fitsutils)
==================================

**Module**: ``utils_fits``

Overview
--------

Provides utilities for working with FITS (Flexible Image Transport System) files, the standard astronomical data format. Includes functions for checking FITS files and managing logical units.

Key Features
------------

- FITS file existence checking
- FITS file type verification
- Logical unit management
- Error handling and reporting

API Reference
-------------

Subroutines
~~~~~~~~~~~

**fitsgetlun**

.. function:: fitsgetlun(unit, status)

   Get a free logical unit number

   :param unit: Logical unit number (integer, out)
   :param status: Error status (integer, out)
   :return: None
   
   Finds and returns a free logical unit number between 80 and 140.
   
   **Status Codes**:
   - ``status = 0``: Success
   - ``status = 1``: Failure (too many files open)

**fitsexist**

.. function:: fitsexist(fnam, status)

   Check if FITS file exists

   :param fnam: FITS filename (character(*), in)
   :param status: Error status (integer, out)
   :return: None
   
   Tests whether the specified FITS file exists.
   
   **Status Codes**:
   - ``status = 0``: File exists
   - ``status = 1``: File does not exist

**fitstype**

.. function:: fitstype(fnam, hdutype, status)

   Check FITS file type

   :param fnam: FITS filename (character(*), in)
   :param hdutype: HDU type (integer, out)
   :param status: Error status (integer, out)
   :return: None
   
   Tests whether the FITS file is of the desired type.
   
   **Status Codes**:
   - ``status = 0``: Success
   - ``status = 1``: Failure

**printerror**

.. function:: printerror(status)

   Print FITS error message

   :param status: Error status (integer, in)
   :return: None
   
   Prints the FITSIO error message corresponding to the status code.

Usage Examples
--------------

**Getting Logical Unit**

.. code-block:: fortran

   use utils_fits
   integer :: unit, status
   
   ! Get free logical unit
   call fitsgetlun(unit, status)
   
   if (status == 0) then
      write(*,*) 'Free logical unit:', unit
   else
      write(*,*) 'Error: Too many files open'
   endif

**Checking FITS File Existence**

.. code-block:: fortran

   use utils_fits
   integer :: status
   
   ! Check if FITS file exists
   call fitsexist('observation.fits', status)
   
   if (status == 0) then
      write(*,*) 'FITS file exists'
   else
      write(*,*) 'FITS file not found'
   endif

**Checking FITS File Type**

.. code-block:: fortran

   use utils_fits
   integer :: status, hdutype
   
   ! Check FITS file type
   call fitstype('spectrum.fits', hdutype, status)
   
   if (status == 0) then
      write(*,*) 'FITS file type:', hdutype
   else
      write(*,*) 'Error checking FITS file type'
   endif

**Error Handling**

.. code-block:: fortran

   use utils_fits
   integer :: status
   
   ! Simulate an error
   status = 107  ! File not found error
   
   ! Print error message
   call printerror(status)

Notes
-----

**Logical Unit Management**

- Finds free units in range 80-140
- Prevents unit conflicts
- Automatic unit selection

**File Checking**

- Tests file existence
- Verifies file accessibility
- Checks file types

**Error Handling**

- Standard FITS status codes
- ``status = 0`` indicates success
- Non-zero values indicate errors
- Descriptive error messages

**Performance**

- Fast file system operations
- Minimal overhead
- Suitable for frequent checks

**Best Practices**

1. **Check file existence** before operations
2. **Get logical units** dynamically
3. **Handle errors** gracefully
4. **Use for file validation**

**Common Use Cases**

.. list-table::
   :widths: 20 30 50
   :header-rows: 1

   * - Use Case
     - Description
     - Example
   * - **File Validation**
     - Check files before processing
     - Verify input files exist
   * - **Unit Management**
     - Get free units dynamically
     - Prevent unit conflicts
   * - **Error Reporting**
     - Display FITS error messages
     - Debugging assistance
   * - **File Type Checking**
     - Verify file compatibility
     - Validate input formats

See Also
--------

- :doc:`files` - General file operations
- :doc:`../core/messages` - Error reporting
- FITS Standard Documentation (NASA)
- CFITSIO Library Documentation