DKIST IDL READER
================

This directory contains the standalone IDL routines needed by READ_DKIST.
The current reader supports ordinary FITS images and reads supported RICE_1
tiled-image files natively in IDL.

SETUP
-----

Add this directory and its subdirectories to the IDL search path.  For
example, place the following in .idl_startup, with the path adjusted for your
installation:

  !path = expand_path('+/path/to/dkist_idl') + $ 
          path_sep(/search_path) + !path

No SSW_ONTOLOGY environment variable is needed for normal use.

READING DATA
------------

  read_dkist, filename, index, data

The same call is used for ViSP and VBI.  Supported RICE_1 files are decoded
in memory, so no temporary uncompressed FITS file is created and neither
/UNCOMP_DELETE nor /USE_SHARED_LIB is needed.

FITS real-valued header cards, including CRVALn, are stored as IDL DOUBLE
values to preserve the significant digits written in the FITS header.

NATIVE RICE_1 SUPPORT
---------------------

The pure-IDL path supports BYTEPIX values 1, 2, and 4, arbitrary rectangular
tile geometry, integer images, conventional unsigned BZERO mappings,
ZQUANTIZ='NO_DITHER', and per-image or per-tile ZSCALE/ZZERO.

SUBTRACTIVE_DITHER quantization, BYTEPIX=8, and the optional
UNCOMPRESSED_DATA tile fallback are not yet implemented natively.  For those
cases READ_DKIST reports the reason and attempts the legacy external path.

LEGACY COMPATIBILITY
--------------------

The historical readers remain available for validation while native support
is completed:

  read_dkist, filename, index, data, /use_shared_lib
  read_dkist, filename, index, data, /legacy_external

These modes require a compatible fitsio.so or imcopy binary.  If using a
bundled x86-64 macOS/Linux binary, set SSW_ONTOLOGY to this dkist_idl
directory.  New code should use the default native path.

TESTING
-------

See the top-level README.md and tests directory in the distribution.  The
included regression suite covers FITS-header precision, all Rice coding block
modes, tiled-FITS reading through READ_DKIST, and FITS headers larger than ten
2880-byte blocks.
