Implementation:NVIDIA DALI FITS Header

Knowledge Sources	NVIDIA_DALI
Domains	Utilities, File_IO
Last Updated	2026-02-08 16:00 GMT

Overview

Declares the public API for FITS file parsing including the HeaderData class, FitsHandle RAII wrapper, thread-safe FitsLock, and the FITS_CALL error-checking macro.

Description

The FITS header in dali/util/fits.h provides the public interface for reading FITS (Flexible Image Transport System) files in DALI. It defines the HeaderData class, which stores all metadata extracted from a FITS Header Data Unit (HDU), including the tensor shape, HDU type, datatype code, type information pointer, and a flag indicating whether the image is compressed. For compressed images, additional fields store Rice compression parameters: tile count, maximum tile length, zbitpix, bytes per pixel, block size, row count, scaling values (bscale/bzero), and per-dimension tile sizes.

The header defines the FitsLock class for thread-safe CFITSIO operations. When CFITSIO is compiled without reentrant support, FitsLock acquires a global mutex; otherwise, it is a no-op. The FITS_CALL macro wraps any CFITSIO call with automatic lock acquisition and error checking via HandleFitsError.

The FitsHandle class, derived from UniqueHandle, provides RAII management for CFITSIO fitsfile* pointers. It exposes a static OpenFile factory method that calls fits_open_file and returns an owned handle, and a DestroyHandle method that calls fits_close_file on destruction.

Usage

Include this header to access the FITS parsing API. Use FitsHandle::OpenFile to open FITS files with automatic resource management. Call ParseHeader to extract metadata into a HeaderData instance, and ExtractUndecodedData to read raw compressed tile data. Use the FITS_CALL macro when making any direct CFITSIO calls.

Code Reference

Source Location

• Repository: NVIDIA_DALI
• File: dali/util/fits.h
• Lines: 1-128

Signature

namespace dali {
namespace fits {

class DLL_PUBLIC FitsLock {
 public:
  FitsLock();
 private:
  std::mutex &mutex();
  std::unique_lock<std::mutex> lock_;
};

DLL_PUBLIC void HandleFitsError(int status);

#define FITS_CALL(code) \
  do {                  \
    fits::FitsLock lock; \
    fits::HandleFitsError(code); \
  } while (0)

class DLL_PUBLIC HeaderData {
 public:
  TensorShape<> shape;
  int hdu_type;
  int datatype_code;
  const TypeInfo *type_info = nullptr;
  bool compressed = false;
  int64_t tiles, maxtilelen, zbitpix, bytepix, blocksize, rows;
  double bscale, bzero;
  std::vector<int64_t> tile_sizes;

  DALIDataType type() const;
  size_t size() const;
  size_t nbytes() const;
};

DLL_PUBLIC void ParseHeader(HeaderData &parsed_header, fitsfile *src);

DLL_PUBLIC int ExtractUndecodedData(fitsfile *fptr, std::vector<uint8_t> &data,
                                    std::vector<int64_t> &tile_offset,
                                    std::vector<int64_t> &tile_size, int64_t rows, int *status);

class DLL_PUBLIC FitsHandle : public UniqueHandle<fitsfile *, FitsHandle> {
 public:
  constexpr FitsHandle() = default;
  static FitsHandle OpenFile(const char *path, int mode);
  static void DestroyHandle(fitsfile *ff);
};

}  // namespace fits
}  // namespace dali

Import

#include "dali/util/fits.h"

I/O Contract

Inputs

Name	Type	Required	Description
path	const char*	Yes (OpenFile)	Filesystem path to the FITS file
mode	int	Yes (OpenFile)	CFITSIO open mode (e.g., READONLY)
src / fptr	fitsfile*	Yes (ParseHeader / ExtractUndecodedData)	Open CFITSIO file pointer
status	int	Yes (HandleFitsError)	CFITSIO status code to check

Outputs

Name	Type	Description
return value (OpenFile)	FitsHandle	RAII handle wrapping the opened fitsfile*
HeaderData members	various	Populated shape, type, compression metadata after ParseHeader
type()	DALIDataType	DALI data type identifier
size()	size_t	Total number of elements in the image
nbytes()	size_t	Total byte size of the image data

Usage Examples

Opening and Reading a FITS File

#include "dali/util/fits.h"

// Open with RAII handle
auto handle = dali::fits::FitsHandle::OpenFile("/path/to/image.fits", READONLY);

// Parse header
dali::fits::HeaderData header;
dali::fits::ParseHeader(header, handle);

// Access metadata
auto type = header.type();
auto total_bytes = header.nbytes();
auto shape = header.shape;
bool is_compressed = header.compressed;

// handle automatically closes the file when it goes out of scope

Using FITS_CALL for Error Checking

#include "dali/util/fits.h"

fitsfile *fptr = nullptr;
int status = 0;

// FITS_CALL acquires the lock and checks for errors automatically
FITS_CALL(fits_open_file(&fptr, "data.fits", READONLY, &status));

Related Pages

• Environment:NVIDIA_DALI_CUDA_GPU_Environment