Welcome to the MISR Toolkit
---------------------------

The MISR Toolkit is a simplified programming interface to access MISR L1B2, L2, and MISR-HR,
conventional and ancillary data products. It is an interface built upon HDF-EOS
that knows about MISR data products. It has the ability to:

   - Specify regions to read based on geographic location and extent or the
     more traditional path and block range
   - Map between path, orbit, block, time range and geographic location
   - Automatically stitch, unpack and unscale MISR data while reading
   - Perform coordinate conversions between lat/lon, SOM x/y, block/line/sample
     and line/sample of a data plane, which means geolocation can be computed
     instantly without referring to an ancillary data set lookups
   - Retrieve pixel acquistion time from L1B2 product files
   - Read a slice of a multi-dimensional field into an 2-D data plane (eg. RetrAppMask[0][5])
   - Convert MISR product files to IDL ENVI files

The MISR Toolkit has been tested on Linux CentOS 7, Mac OS X 10.14.6 and Windows 10. 
It's core interface is C. There are also bindings for Python (2.7 and 3.x supported) and IDL.
Note that Python 2.7 is end of life and deprecated in MISR Toolkit.


Complete documentation and function reference
---------------------------------------------

Use a browser to view online documentation: https://nasa.github.io/MISR-Toolkit/html/index.html

Offline documentation packages are also available for download on the github releases page.


Third Party Library Dependencies
--------------------------------

The MISR Toolkit depends on the following libraries. Download links are provide
for your reference, but it is preferred to use the script "download_libraries"
in the source bundle "scripts" directory. Python users will still need to
download NumPy and install it according to NumPy instructions.

   - HDF-EOS2.18v1.00 (https://observer.gsfc.nasa.gov/ftp/edhs/hdfeos/previous_releases)
   - HDF4.2.10        (https://support.hdfgroup.org/ftp/HDF/releases/HDF4.2.10/src)
   - hdf5-1.8.16      (https://support.hdfgroup.org/ftp/HDF5/releases/hdf5-1.8/hdf5-1.8.16/src)
   - netcdf-4.4.0     (ftp://ftp.unidata.ucar.edu/pub/netcdf/)
   - jpegsrc.v6b      (https://observer.gsfc.nasa.gov/ftp/edhs/hdfeos/previous_releases)
   - zlib-1.2.5       (https://observer.gsfc.nasa.gov/ftp/edhs/hdfeos/previous_releases)
   - NumPy 1.15 or later Python module (http://www.numpy.org/)


Binary Installation Instructions
--------------------------------

Binary installations that do not require compilation are now available for Python 3.6, IDL, and C library users
on Linux, Mac OS X, and Windows.
Python 2.7 binaries are also available but deprecated on Linux and Mac OS X.

For Python users, the most convenient option is downloading MISR Toolkit directly from PyPI using pip.
- python -m pip install -U pip
- python -m pip install -U wheel numpy
- python -m pip install -U MisrToolkit

A downloadable python binary wheel distribution is also available on the releases page.

For IDL users, a IDL Dynamically Loadable Module (DLM) distribution is available on the releases page.
To use it, download the package, extract it to a convenient location, and then follow the instructions in the README
to set the IDL_DLM_PATH enviornment variable or use IDL's PREF_SET to tell IDL where you extracted the package.


Source Installation Instructions
--------------------------------

Linux and MacOS X

The recommended location for the HDF-EOS/HDF libraries and the MISR Toolkit is /usr/local/hdfeoslibs
and /usr/local/Mtk-1.5.X respectively, because this location provides convenient access for multiple user
accounts.  It is not necessary, however, to install in /usr/local. The MISR Toolkit and HDF-EOS can be
installed anywhere.  Of course installing in /usr/local requires root or sudo privileges. Use the sudo
commands below if you are a sudoer or simply become root before installing the HDF-EOS/HDF libraries
and before the "make install" step for the MISR Toolkit.

1) Create a working directory

   mkdir Mtk_tmp
   cd Mtk_tmp

2) Extract Mtk-src-1.5.X.tar.gz

   tar xzvf Mtk-src-1.5.X.tar.gz      (if not done already)

3) Extract Mtk testdata (substitute Mtk-testdata-1.5.X with your version)

   tar xzvf Mtk-testdata-1.5.X.tar.gz

4) Download HDF-EOS/HDF, JPEG and ZLIB libraries

   cd Mtk-src-1.5.X
   scripts/download_libraries

   <Hit "return" for defaults>

5) Install HDF-EOS/HDF, JPEG and ZLIB libraries (using the following script
   is necessary because it applies patches which are required for some systems,
   like Mac Universal Binaries, Linux and Linux64)

   ** The next step requires root privileges to install into 
   /usr/local/hdfeoslibs, otherwise choose another location and disregard sudo

   sudo scripts/install_hdf+hdfeos

   <Hit "return" for defaults (/usr/local/hdfeoslibs)>

6) Build, test and install Mtk (substitute Mtk-src-1.5.X with your version)

    Setup your HDF/HDFEOS environment
    for csh:

       source <your-step5-path>/bin/hdfeos_env.csh

    for bash:

      source <your-step5-path>/bin/hdfeos_env.sh

    Set MTK_INSTALLDIR environment variable (ex. /usr/local/Mtk-1.5.X)
    for csh:

       setenv MTK_INSTALLDIR <your-path>/Mtk-1.5.X

    for bash:

       export MTK_INSTALLDIR=<your-path>/Mtk-1.5.X

    Set IDL_DIR environment variable (if applicable)
    for csh:

       setenv IDL_DIR <path-to-idl>/harris/idl

    for bash:

      export IDL_DIR=<path-to-idl>/harris/idl

    To build, test and install (choose which libraries to build)

       Everything - C, command-line utilities, IDL and Python

          make
          make testall (If you have Mtk testdata installed and would like
                        to test C, IDL and Python)

          ** The next step requires root privileges to install into
             /usr/local/Mtk-1.5.X, otherwise choose another location
             and disregard sudo

          sudo MTK_INSTALLDIR=$MTK_INSTALLDIR make install

       Or - C library and command-line utilites

          make lib
          make cmdutil
          make test (If you have Mtk testdata installed and would like to
                     test only C routines)

          ** The next step requires root privileges to install into
             /usr/local/Mtk-1.5.X, otherwise choose another location
             and disregard sudo

          sudo make install

       Or - IDL library

          make idl
          make testidl (If you have Mtk testdata installed and would like to
                        test only IDL routines - requires user interaction)

          ** The next step requires root privileges to install into
             /usr/local/Mtk-1.5.X, otherwise choose another location
             and disregard sudo

          sudo make install

       Or - Python library

          make python
          make testpython (If you have Mtk testdata installed and would like to
                           test only Python routines)

          ** The next step requires root privileges to install into
             /usr/local/Mtk-1.5.X, otherwise choose another location
             and disregard sudo

          sudo make install

       Other build targets and options

          make help (for other build targets)
          make clean (to clean everything)

       If the build complains about .d files ( This occurs when the HDF-EOS
       environment is not set)

          scripts/rmdepend.sh (to remove dependency files)
          make

7) To use Mtk

   The HDF/HDFEOS environment is already set above

   Setup your Mtk environment (pick any):

      For csh:
         source $MTK_INSTALLDIR/bin/Mtk_c_env.csh       for C
         source $MTK_INSTALLDIR/bin/Mtk_idl_env.csh     for IDL
         source $MTK_INSTALLDIR/bin/Mtk_python_env.csh  for Python (Don't need
            to do if installed in site-packages (see step 8))

      For bash:
         . $MTK_INSTALLDIR/bin/Mtk_c_env.sh       for C
         . $MTK_INSTALLDIR/bin/Mtk_idl_env.sh     for IDL
         . $MTK_INSTALLDIR/bin/Mtk_python_env.sh  for Python (Don't need to do
            if installed in site-packages (see step 8))

   For C examples: $MTK_INSTALLDIR/examples/C
   For IDL examples: $MTK_INSTALLDIR/examples/idl
   For Python examples: $MTK_INSTALLDIR/examples/python
   For C command-line utilities source code: Mtk-src-1.5.X/src
   For IDL tests source code: Mtk-src-1.5.X/wrappers/idl

8) Optional - You may want to install the MisrToolkit into you Python
   site-packages directory

   cd Mtk-src-1.5.X/wrappers/python
   sudo python setup.py install
   setenv LD_LIBRARY_PATH $MTK_INSTALLDIR/lib

9) Optional - After installing the Mtk_tmp directory, it's contents is
   not needed, unless for reference and may be removed

   cd ../..
   rm -rf Mtk_tmp

Windows

See win64/README.txt in the source or binary bundle.

Known Problems
--------------

The IDL routine MTK_FIND_FILELIST() does not work properly.
By default OS X swallows click-events on change of focus.
  If IDL test windows on MacOS X 10.14 don't respond to clicks, do this command 
    "defaults write org.x.x11 wmclickthrough -bool true"
  Then, once at a shell prompt, restart X11/XQuartz and retry
  "make testidl".

IDL is not compatible with XQuartz versions greater than 2.7.9
  If IDL tests return an error of "Error: attempt to add non-widget child "dsm" 
    to parent "idl" which supports only widgets"" then you can either downgrade
	to XQuartz 2.7.9 or follow the procedure described at goo.gl/RvXOXy to add
	/opt/X11/lib/flat_namespace to the DYLD_LIBRARY_PATH set by your idl
	launcher script (e.g. /Applications/harris/idl87/bin/idl)