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

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

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. By default, READ_DKIST uses the
matching bundled imcopy executable when one is available for the current OS
and architecture. Otherwise it decodes supported RICE_1 data directly in IDL.
No selection flag or SSW_ONTOLOGY setting is needed.

Automatic imcopy reads remove their temporary uncompressed file after reading.
Use /KEEP_UNCOMPRESSED to retain it, or /NO_BINARIES (equivalently
/NATIVE_RICE) to force the pure-IDL path:

  read_dkist, filename, index, data, /no_binaries
  read_dkist, filename, index, data, /keep_uncompressed

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.

The decoder uses an inline bit reservoir, vectorized predictor reconstruction,
and a single read of the compressed table heap to reduce native decode time.

SUBTRACTIVE_DITHER quantization, BYTEPIX=8, and the optional
UNCOMPRESSED_DATA tile fallback are not yet implemented natively. The default
automatic path handles them with imcopy on supported platforms.

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

The historical paths can also be selected explicitly for validation:

  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. The shared
library stays opt-in because an incompatible library can crash IDL. Binary
lookup is restricted to the same installation that supplied READ_DKIST, so
multiple packages on !PATH cannot silently mix source and executables.

If automatic imcopy execution fails for supported Rice data, READ_DKIST cleans
up the incomplete output and retries with native IDL.

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, automatic binary selection and
fallback, and FITS headers larger than ten 2880-byte blocks.
