MSSS ORIGINAL DATA RECORD MINI HEADER AND MSSS ORIGINAL DATA RECORD PAYLOAD DATA

==============================================================================
INTRODUCTION
==============================================================================

This project provides Python tools for decoding and decompressing data files
generated by the Mastcam, MARDI, and MAHLI scientific imaging instruments
onboard the Mars Science Laboratory Curiosity Rover. These instruments relay
data through the rover to ground data systems, encapsulated in files with the
.DAT extension. These are referred to as Original Data Record (ODR) files,
containing unprocessed and unmodified data. ODR .DAT files are considered
NASA Packet and CODMAC level 1 (Raw).

==============================================================================
PURPOSE
==============================================================================

The primary purpose of this project is to provide a reference implementation
for handling MSSS ODR files. Each .DAT file begins with a 64-byte MSSS ODR
Mini Header, followed by MSSS ODR Payload Data. The provided Python scripts
facilitate the interpretation and extraction of this data, enabling further
processing of the raw image information.

==============================================================================
FILES AND THEIR PURPOSE
==============================================================================

msss_odr.py
    Python tool designed to decode and decompress .DAT files. It handles
    various payload types, including JPEG, predictive lossless, and
    uncompressed raster data.

huffman.py
    Contains the Huffman tables utilized by msss_odr.py for decompression of
    specific data formats.

stream_to_bayer.py
    Python tool to interleave line frame output from msss_odr.py into Bayer
    sensor pixel order, useful for further image processing and interpolation.

------------------------------------------------------------------------------
REQUIREMENTS
------------------------------------------------------------------------------

To use these tools, you will need:
  * Python 3 interpreter
  * "bitstring" module
  * "numpy" module

You can install the required Python modules using pip:

    pip3 install bitstring numpy

==============================================================================
USAGE
==============================================================================

------------------------------------------------------------------------------
msss_odr.py
------------------------------------------------------------------------------

Usage:
    msss_odr.py filename.dat

Expected Output(s):
  * For JPEG payloads: One or more JPEG files will be written, named
    img_<n>.jpg.
  * For predictive lossless and uncompressed raster payloads: A headerless
    file containing all pixel values will be written, ordered as defined for
    uncompressed raster payload, named either img_8bit.raw or img_16bit.raw.

------------------------------------------------------------------------------
stream_to_bayer.py
------------------------------------------------------------------------------

Usage:
    stream_to_bayer.py infile outfile width height

Expected Output:
    This tool processes headerless files containing pixel values (e.g.,
    img_8bit.raw or img_16bit.raw generated by msss_odr.py) and reforms the
    data into Bayer sensor order. The output is a new headerless file
    containing pixels in CCD natural order, which is useful for interpolation
    and further image analysis.

------------------------------------------------------------------------------
CONVERTING BAYER.RAW TO STANDARD IMAGE FORMATS
------------------------------------------------------------------------------

The bayer.raw files produced by stream_to_bayer.py are headerless raw pixel
data. To view or work with these files in a standard image format (e.g.,
PNG), you will need to use external image processing libraries or tools.

Users are directed to libraries such as Pillow (https://python-pillow.org/)
or imageio (https://imageio.readthedocs.io/) for Python-based conversion.

For command-line conversion, ImageMagick (https://imagemagick.org/) could be
used as follows:

    convert -depth 8 -size 1648x1200 gray:bayer.raw bayer.png