mHistogram.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<font style=\"font-size:96px; font-weight:bolder; color:#0040a0\"><img src=\"http://montage.ipac.caltech.edu/docs/M51_logo.png\" alt=\"M\" style=\"float: left; padding: 25px 30px 25px 0px;\" /></font>\n",
    "\n",
    "<i><b>Montage</b> Montage is an astronomical image toolkit with components for reprojection, background matching, coaddition and visualization of FITS files. It can be used as a set of command-line tools (Linux, OS X and Windows), C library calls (Linux and OS X) and as Python binary extension modules.\n",
    "\n",
    "The Montage source is written in ANSI-C and code can be downloaded from GitHub ( https://github.com/Caltech-IPAC/Montage ). The Python package can be installed from PyPI (\"</i>pip install MontagePy<i>\"). The package has no external dependencies. See http://montage.ipac.caltech.edu/ for details on the design and applications of Montage.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# MontagePy.main modules: mHistogram\n",
    "\n",
    "The Montage image visualizer mViewer uses a histogram of the image values to determine the best stretch for display.  However, if we wish to use the same stretch for a set of images (<i>e.g.</i>, for tiled displays) we need to tie them all to the same histogram.  mHistogram uses the same code as mViewer to generate the histogram and color stretch bins and mViewer has an option to import this data instead of calculating it itself."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on built-in function mHistogram in module MontagePy.main:\n",
      "\n",
      "mHistogram(...)\n",
      "    mHistogram generates a histogram from an image (to be used by mViewer mostly).\n",
      "    \n",
      "    Parameters\n",
      "    ----------\n",
      "    imgFile : str\n",
      "        Input FITS file.\n",
      "    histFile : str\n",
      "        Output histogram file.\n",
      "    minString : str\n",
      "        Data range minimum as a string (to allow '%' and 's' suffix.\n",
      "    maxString : str\n",
      "        Data range maximum as a string (to allow '%' and 's' suffix.\n",
      "    stretchType : str\n",
      "        Stretch type (linear, power(log**N), sinh, gaussian or gaussian-log)\n",
      "    grayLogPower : int, optional\n",
      "        If the stretch type is log to a power, the power value.\n",
      "    betaString : str, optional\n",
      "        If the stretch type is asinh, the transition data value.\n",
      "    debug : int, optional\n",
      "        Debugging output level.\n",
      "    \n",
      "    \n",
      "    Returns\n",
      "    -------\n",
      "    status : int\n",
      "        Return status (0: OK, 1:ERROR).\n",
      "    msg : str\n",
      "        Return message (for errors).\n",
      "    minval : float\n",
      "        Data value associated with histogram minimum.\n",
      "    minpercent : float\n",
      "        Percentile value of histogram minimum.\n",
      "    minsigma : float\n",
      "        'Sigma' level of histogram minimum.\n",
      "    maxval : float\n",
      "        Data value associated with histogram maximum.\n",
      "    maxpercent : float\n",
      "        Percentile value of histogram maximum.\n",
      "    maxsigma : float\n",
      "        'Sigma' level of histogram maximum.\n",
      "    datamin : float\n",
      "        Minimum data value in file.\n",
      "    datamax : float\n",
      "        Maximum data value in file.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from MontagePy.main import mHistogram, mViewer\n",
    "\n",
    "help(mHistogram)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## mHistogram Example:\n",
    "\n",
    "mViewer does not use the histogram directly but rather a set of stretch levels based on the histogram and the type of stretch the user wants.  There are several different stretches, from simple linear to a couple of gaussian-weighted histogram equalization techniques.  Even the starting and ending levels may be histogram-based and couched in terms of the distribution \"sigma\" values.\n",
    "\n",
    "We will use the latter approach for this example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'status': '0', 'minval': 149.5791825248529, 'minpercent': 0.0, 'minsigma': -2.0, 'maxval': 10639.0999189825, 'maxpercent': 100.0, 'maxsigma': 2240.4651757359084, 'datamin': 150.8148507701094, 'datamax': 10639.0999189825}\n"
     ]
    }
   ],
   "source": [
    "rtn = mHistogram(\"M17/mosaic.fits\", \"work/M17/M17.hist\", \"-2s\", \"max\", \"gaussian-log\")\n",
    "\n",
    "print(rtn)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "# HISTOGRAM DATA\n",
      "# \n",
      "# The following data is strictly formatted (after these initial comments).\n",
      "# The first line is the type of stretch, i.e., power law (linear/log/etc.):0,\n",
      "# gaussian:1, gaussian-log:2 or asinh:3.\n",
      "# \n",
      "# The second are the data ranges the user gave in the various units (data value,\n",
      "# percentiles, 'sigma' levels) plus the file data min, max, median and 'sigma'.\n",
      "# \n",
      "# The third (a little repetitive) are the file statistics used in the histogram\n",
      "# calculation: data min, max, the width of the bins ((max-min)/NBIN) and the \n",
      "# total number of pixels in the file.\n",
      "# \n",
      "# Then the conclusions, starting with the 256 data values that correspond to \n",
      "# the lowest data value associated with a 'grayscale' output value.\n",
      "# \n",
      "# Finally, the NBIN histogram values.  The first column is the bin number.\n",
      "# The second is the lowest data value that will go into that bin.  This is\n",
      "# the part that is stretch type dependent.  Next is the count of pixels that\n",
      "# ended up in that bin followed by the cumulative count, and finally the \n",
      "# chi^2 and sigma levels for the bin.\n",
      "# \n",
      "Type 2\n",
      "\n",
      "Ranges\n",
      "Value 149.579 10639.1\n",
      "Percentile 0 100\n",
      "Sigma -2 2240.47\n",
      "Min/Max 150.815 10639.1\n",
      "Median/Sigma 158.935 4.67767\n",
      "\n",
      "rmin 150.815\n",
      "rmax 10639.1\n",
      "delta 0.0524417\n",
      "npix 12963600\n",
      "\n",
      "Stretch Lookup\n",
      "0  1.508149e+02\n",
      "1  1.508149e+02\n",
      "2  1.510964e+02\n",
      "3  1.511155e+02\n",
      "4  1.512508e+02\n",
      "5  1.513445e+02\n",
      "6  1.514045e+02\n",
      "7  1.515063e+02\n",
      "8  1.516263e+02\n",
      "9  1.517276e+02\n",
      "10  1.518651e+02\n",
      "11  1.519576e+02\n",
      "12  1.520803e+02\n",
      "13  1.521914e+02\n",
      "14  1.523069e+02\n",
      "15  1.523984e+02\n",
      "16  1.524951e+02\n",
      "17  1.525956e+02\n",
      "18  1.527022e+02\n",
      "19  1.527834e+02\n",
      "20  1.528725e+02\n",
      "21  1.529632e+02\n",
      "22  1.530508e+02\n",
      "23  1.531367e+02\n",
      "24  1.532256e+02\n",
      "25  1.533119e+02\n",
      "26  1.533952e+02\n",
      "27  1.534781e+02\n",
      "28  1.535623e+02\n",
      "29  1.536470e+02\n",
      "30  1.537287e+02\n",
      "31  1.538109e+02\n",
      "32  1.538929e+02\n",
      "33  1.539748e+02\n",
      "34  1.540564e+02\n",
      "35  1.541380e+02\n",
      "36  1.542198e+02\n",
      "37  1.543021e+02\n",
      "38  1.543847e+02\n",
      "39  1.544674e+02\n",
      "40  1.545500e+02\n",
      "41  1.546334e+02\n",
      "42  1.547176e+02\n",
      "43  1.548025e+02\n",
      "44  1.548874e+02\n",
      "45  1.549736e+02\n",
      "46  1.550606e+02\n",
      "47  1.551490e+02\n",
      "48  1.552385e+02\n",
      "49  1.553291e+02\n",
      "50  1.554213e+02\n",
      "51  1.555154e+02\n",
      "52  1.556110e+02\n",
      "53  1.557083e+02\n",
      "54  1.558075e+02\n",
      "55  1.559087e+02\n",
      "56  1.560119e+02\n",
      "57  1.561173e+02\n",
      "58  1.562257e+02\n",
      "59  1.563371e+02\n",
      "60  1.564513e+02\n",
      "61  1.565682e+02\n",
      "62  1.566884e+02\n",
      "63  1.568124e+02\n",
      "64  1.569406e+02\n",
      "65  1.570722e+02\n",
      "66  1.572086e+02\n",
      "67  1.573501e+02\n",
      "68  1.574970e+02\n",
      "69  1.576492e+02\n",
      "70  1.578066e+02\n",
      "71  1.579691e+02\n",
      "72  1.581357e+02\n",
      "73  1.583078e+02\n",
      "74  1.584834e+02\n",
      "75  1.586635e+02\n",
      "76  1.588475e+02\n",
      "77  1.590357e+02\n",
      "78  1.592278e+02\n",
      "79  1.594241e+02\n",
      "80  1.596258e+02\n",
      "81  1.598325e+02\n",
      "82  1.600440e+02\n",
      "83  1.602619e+02\n",
      "84  1.604856e+02\n",
      "85  1.607176e+02\n",
      "86  1.609576e+02\n",
      "87  1.612066e+02\n",
      "88  1.614673e+02\n",
      "89  1.617404e+02\n",
      "90  1.620277e+02\n",
      "91  1.623297e+02\n",
      "92  1.626484e+02\n",
      "93  1.629869e+02\n",
      "94  1.633461e+02\n",
      "95  1.637268e+02\n",
      "96  1.641344e+02\n",
      "97  1.645683e+02\n",
      "98  1.650284e+02\n",
      "99  1.655223e+02\n",
      "100  1.660450e+02\n",
      "101  1.666044e+02\n",
      "102  1.672038e+02\n",
      "103  1.678493e+02\n",
      "104  1.685454e+02\n",
      "105  1.692910e+02\n",
      "106  1.700888e+02\n",
      "107  1.709411e+02\n",
      "108  1.718516e+02\n",
      "109  1.728269e+02\n",
      "110  1.738623e+02\n",
      "111  1.749651e+02\n",
      "112  1.761513e+02\n",
      "113  1.774014e+02\n",
      "114  1.787463e+02\n",
      "115  1.801852e+02\n",
      "116  1.817219e+02\n",
      "117  1.833597e+02\n",
      "118  1.850994e+02\n",
      "119  1.869452e+02\n",
      "120  1.889231e+02\n",
      "121  1.910254e+02\n",
      "122  1.932573e+02\n",
      "123  1.956243e+02\n",
      "124  1.980480e+02\n",
      "125  2.006412e+02\n",
      "126  2.034063e+02\n",
      "127  2.063215e+02\n",
      "128  2.094377e+02\n",
      "129  2.127054e+02\n",
      "130  2.161289e+02\n",
      "131  2.196448e+02\n",
      "132  2.233299e+02\n",
      "133  2.272735e+02\n",
      "134  2.314692e+02\n",
      "135  2.359579e+02\n",
      "136  2.407879e+02\n",
      "137  2.459218e+02\n",
      "138  2.516332e+02\n",
      "139  2.580153e+02\n",
      "140  2.648206e+02\n",
      "141  2.720442e+02\n",
      "142  2.798992e+02\n",
      "143  2.882932e+02\n",
      "144  2.974685e+02\n",
      "145  3.073620e+02\n",
      "146  3.179760e+02\n",
      "147  3.293642e+02\n",
      "148  3.414476e+02\n",
      "149  3.542778e+02\n",
      "150  3.683021e+02\n",
      "151  3.834543e+02\n",
      "152  3.992591e+02\n",
      "153  4.159479e+02\n",
      "154  4.341534e+02\n",
      "155  4.530714e+02\n",
      "156  4.742635e+02\n",
      "157  4.961542e+02\n",
      "158  5.196411e+02\n",
      "159  5.450195e+02\n",
      "160  5.715713e+02\n",
      "161  5.997419e+02\n",
      "162  6.289275e+02\n",
      "163  6.617811e+02\n",
      "164  6.952321e+02\n",
      "165  7.330670e+02\n",
      "166  7.705981e+02\n",
      "167  8.126808e+02\n",
      "168  8.559094e+02\n",
      "169  9.027919e+02\n",
      "170  9.522011e+02\n",
      "171  1.004749e+03\n",
      "172  1.057427e+03\n",
      "173  1.113166e+03\n",
      "174  1.179172e+03\n",
      "175  1.245265e+03\n",
      "176  1.314498e+03\n",
      "177  1.388396e+03\n",
      "178  1.464327e+03\n",
      "179  1.545328e+03\n",
      "180  1.639590e+03\n",
      "181  1.730151e+03\n",
      "182  1.831444e+03\n",
      "183  1.939710e+03\n",
      "184  2.041427e+03\n",
      "185  2.143307e+03\n",
      "186  2.256357e+03\n",
      "187  2.357812e+03\n",
      "188  2.490148e+03\n",
      "189  2.611053e+03\n",
      "190  2.742141e+03\n",
      "191  2.881958e+03\n",
      "192  3.011741e+03\n",
      "193  3.161597e+03\n",
      "194  3.311547e+03\n",
      "195  3.458089e+03\n",
      "196  3.618536e+03\n",
      "197  3.779860e+03\n",
      "198  3.925570e+03\n",
      "199  4.098863e+03\n",
      "200  4.242097e+03\n",
      "201  4.449043e+03\n",
      "202  4.601293e+03\n",
      "203  4.737831e+03\n",
      "204  4.886423e+03\n",
      "205  5.034195e+03\n",
      "206  5.185102e+03\n",
      "207  5.348814e+03\n",
      "208  5.503955e+03\n",
      "209  5.693598e+03\n",
      "210  5.829816e+03\n",
      "211  5.965958e+03\n",
      "212  6.118925e+03\n",
      "213  6.280558e+03\n",
      "214  6.458082e+03\n",
      "215  6.599093e+03\n",
      "216  6.751631e+03\n",
      "217  6.892211e+03\n",
      "218  6.997770e+03\n",
      "219  7.111896e+03\n",
      "220  7.235855e+03\n",
      "221  7.353085e+03\n",
      "222  7.422322e+03\n",
      "223  7.528265e+03\n",
      "224  7.662740e+03\n",
      "225  7.763873e+03\n",
      "226  7.886155e+03\n",
      "227  7.972012e+03\n",
      "228  8.046673e+03\n",
      "229  8.154193e+03\n",
      "230  8.242397e+03\n",
      "231  8.314122e+03\n",
      "232  8.395855e+03\n",
      "233  8.464314e+03\n",
      "234  8.521915e+03\n",
      "235  8.570446e+03\n",
      "236  8.672156e+03\n",
      "237  8.724526e+03\n",
      "238  8.796151e+03\n",
      "239  8.875550e+03\n",
      "240  8.908605e+03\n",
      "241  8.979853e+03\n",
      "242  9.039006e+03\n",
      "243  9.071906e+03\n",
      "244  9.139755e+03\n",
      "245  9.170551e+03\n",
      "246  9.220986e+03\n",
      "247  9.249737e+03\n",
      "248  9.295350e+03\n",
      "249  9.314204e+03\n",
      "250  9.347545e+03\n",
      "251  9.375211e+03\n",
      "252  9.392947e+03\n",
      "253  9.405052e+03\n",
      "254  9.441946e+03\n",
      "255  9.461045e+03\n",
      "\n",
      "200000 Histogram Bins\n",
      "0  1.508149e+02 1  0.000000e+00 -5.247367e+00\n",
      "1  1.508673e+02 0  1.000000e+00 -5.247367e+00\n",
      "2  1.509197e+02 0  1.000000e+00 -5.247367e+00\n",
      "3  1.509722e+02 0  1.000000e+00 -5.247367e+00\n",
      "4  1.510246e+02 0  1.000000e+00 -5.247367e+00\n",
      "5  1.510771e+02 0  1.000000e+00 -5.247367e+00\n",
      "6  1.511295e+02 3  1.000000e+00 -4.985768e+00\n",
      "7  1.511819e+02 0  4.000000e+00 -4.985768e+00\n",
      "8  1.512344e+02 0  4.000000e+00 -4.985768e+00\n",
      "9  1.512868e+02 2  4.000000e+00 -4.906799e+00\n",
      "10  1.513393e+02 1  6.000000e+00 -4.876464e+00\n",
      "11  1.513917e+02 4  7.000000e+00 -4.786492e+00\n",
      "12  1.514442e+02 3  1.100000e+01 -4.737838e+00\n",
      "13  1.514966e+02 4  1.400000e+01 -4.686639e+00\n",
      "14  1.515490e+02 2  1.800000e+01 -4.665019e+00\n",
      "15  1.516015e+02 5  2.000000e+01 -4.618923e+00\n",
      "16  1.516539e+02 8  2.500000e+01 -4.560972e+00\n",
      "17  1.517064e+02 7  3.300000e+01 -4.520416e+00\n",
      "18  1.517588e+02 10  4.000000e+01 -4.472949e+00\n",
      "19  1.518112e+02 9  5.000000e+01 -4.437440e+00\n",
      "20  1.518637e+02 7  5.900000e+01 -4.413238e+00\n",
      "21  1.519161e+02 19  6.600000e+01 -4.358172e+00\n",
      "22  1.519686e+02 19  8.500000e+01 -4.313803e+00\n",
      "23  1.520210e+02 21  1.040000e+02 -4.272985e+00\n",
      "24  1.520735e+02 20  1.250000e+02 -4.239785e+00\n",
      "25  1.521259e+02 24  1.450000e+02 -4.205274e+00\n",
      "26  1.521783e+02 39  1.690000e+02 -4.158072e+00\n",
      "27  1.522308e+02 39  2.080000e+02 -4.118635e+00\n",
      "28  1.522832e+02 40  2.470000e+02 -4.083908e+00\n",
      "29  1.523357e+02 66  2.870000e+02 -4.035576e+00\n",
      "30  1.523881e+02 82  3.530000e+02 -3.986265e+00\n",
      "31  1.524405e+02 100  4.350000e+02 -3.936867e+00\n",
      "32  1.524930e+02 105  5.350000e+02 -3.893632e+00\n",
      "33  1.525454e+02 117  6.400000e+02 -3.852729e+00\n",
      "34  1.525979e+02 158  7.570000e+02 -3.806076e+00\n",
      "35  1.526503e+02 157  9.150000e+02 -3.766706e+00\n",
      "36  1.527028e+02 196  1.072000e+03 -3.724555e+00\n",
      "37  1.527552e+02 301  1.268000e+03 -3.670467e+00\n",
      "38  1.528076e+02 350  1.569000e+03 -3.618674e+00\n",
      "39  1.528601e+02 374  1.919000e+03 -3.572323e+00\n",
      "40  1.529125e+02 455  2.293000e+03 -3.524651e+00\n",
      "41  1.529650e+02 517  2.748000e+03 -3.478717e+00\n",
      "42  1.530174e+02 646  3.265000e+03 -3.430034e+00\n",
      "43  1.530698e+02 734  3.911000e+03 -3.383083e+00\n",
      "44  1.531223e+02 896  4.645000e+03 -3.334336e+00\n",
      "45  1.531747e+02 1066  5.541000e+03 -3.285081e+00\n",
      "46  1.532272e+02 1116  6.607000e+03 -3.240849e+00\n",
      "47  1.532796e+02 1393  7.723000e+03 -3.193273e+00\n",
      "48  1.533321e+02 1603  9.116000e+03 -3.146202e+00\n",
      "49  1.533845e+02 1947  1.071900e+04 -3.097061e+00\n",
      "50  1.534369e+02 2250  1.266600e+04 -3.048262e+00\n",
      "51  1.534894e+02 2565  1.491600e+04 -3.000261e+00\n",
      "52  1.535418e+02 2890  1.748100e+04 -2.953353e+00\n",
      "53  1.535943e+02 3362  2.037100e+04 -2.905882e+00\n",
      "54  1.536467e+02 3725  2.373300e+04 -2.859959e+00\n",
      "55  1.536991e+02 4443  2.745800e+04 -2.812062e+00\n",
      "56  1.537516e+02 5025  3.190100e+04 -2.764683e+00\n",
      "57  1.538040e+02 5660  3.692600e+04 -2.717834e+00\n",
      "58  1.538565e+02 6501  4.258600e+04 -2.670490e+00\n",
      "59  1.539089e+02 7152  4.908700e+04 -2.624507e+00\n",
      "60  1.539614e+02 8154  5.623900e+04 -2.578071e+00\n",
      "61  1.540138e+02 9143  6.439300e+04 -2.531864e+00\n",
      "62  1.540662e+02 10231  7.353600e+04 -2.485858e+00\n",
      "63  1.541187e+02 11409  8.376700e+04 -2.440088e+00\n",
      "64  1.541711e+02 12583  9.517600e+04 -2.394911e+00\n",
      "65  1.542236e+02 13993  1.077590e+05 -2.349823e+00\n",
      "66  1.542760e+02 15390  1.217520e+05 -2.305197e+00\n",
      "67  1.543284e+02 16810  1.371420e+05 -2.261191e+00\n",
      "68  1.543809e+02 18464  1.539520e+05 -2.217426e+00\n",
      "69  1.544333e+02 20325  1.724160e+05 -2.173709e+00\n",
      "70  1.544858e+02 21974  1.927410e+05 -2.130702e+00\n",
      "71  1.545382e+02 24213  2.147150e+05 -2.087478e+00\n",
      "72  1.545907e+02 26128  2.389280e+05 -2.044842e+00\n",
      "73  1.546431e+02 28001  2.650560e+05 -2.002941e+00\n",
      "74  1.546955e+02 30099  2.930570e+05 -1.961516e+00\n",
      "75  1.547480e+02 32700  3.231560e+05 -1.920035e+00\n",
      "76  1.548004e+02 34416  3.558560e+05 -1.879687e+00\n",
      "77  1.548529e+02 36897  3.902720e+05 -1.839084e+00\n",
      "78  1.549053e+02 39660  4.271690e+05 -1.798982e+00\n",
      "79  1.549577e+02 41878  4.668290e+05 -1.759560e+00\n",
      "80  1.550102e+02 43913  5.087070e+05 -1.720965e+00\n",
      "81  1.550626e+02 47150  5.526200e+05 -1.682193e+00\n",
      "82  1.551151e+02 49111  5.997700e+05 -1.644330e+00\n",
      "83  1.551675e+02 51703  6.488810e+05 -1.606861e+00\n",
      "84  1.552200e+02 54137  7.005840e+05 -1.569906e+00\n",
      "85  1.552724e+02 56296  7.547210e+05 -1.533624e+00\n",
      "86  1.553248e+02 59228  8.110170e+05 -1.497513e+00\n",
      "87  1.553773e+02 61286  8.702450e+05 -1.462096e+00\n",
      "88  1.554297e+02 63626  9.315310e+05 -1.427170e+00\n",
      "89  1.554822e+02 65545  9.951570e+05 -1.392923e+00\n",
      "90  1.555346e+02 68004  1.060702e+06 -1.359038e+00\n",
      "91  1.555870e+02 69890  1.128706e+06 -1.325766e+00\n",
      "92  1.556395e+02 72207  1.198596e+06 -1.292867e+00\n",
      "93  1.556919e+02 74081  1.270803e+06 -1.260508e+00\n",
      "94  1.557444e+02 76024  1.344884e+06 -1.228618e+00\n",
      "95  1.557968e+02 77836  1.420908e+06 -1.197213e+00\n",
      "96  1.558493e+02 79373  1.498744e+06 -1.166360e+00\n",
      "97  1.559017e+02 81402  1.578117e+06 -1.135831e+00\n",
      "98  1.559541e+02 82709  1.659519e+06 -1.105859e+00\n",
      "99  1.560066e+02 84389  1.742228e+06 -1.076269e+00\n",
      "100  1.560590e+02 85926  1.826617e+06 -1.047078e+00\n",
      "101  1.561115e+02 87001  1.912543e+06 -1.018404e+00\n",
      "102  1.561639e+02 88174  1.999544e+06 -9.901737e-01\n",
      "103  1.562163e+02 88367  2.087718e+06 -9.626517e-01\n",
      "104  1.562688e+02 89297  2.176085e+06 -9.355617e-01\n",
      "105  1.563212e+02 90423  2.265382e+06 -9.088123e-01\n",
      "106  1.563737e+02 91073  2.355805e+06 -8.825124e-01\n",
      "107  1.564261e+02 91716  2.446878e+06 -8.566297e-01\n",
      "108  1.564786e+02 91956  2.538594e+06 -8.312430e-01\n",
      "109  1.565310e+02 93489  2.630550e+06 -8.059709e-01\n",
      "110  1.565834e+02 92633  2.724039e+06 -7.814279e-01\n",
      "111  1.566359e+02 93414  2.816672e+06 -7.571456e-01\n",
      "112  1.566883e+02 93807  2.910086e+06 -7.332024e-01\n",
      "113  1.567408e+02 93913  3.003893e+06 -7.096459e-01\n",
      "114  1.567932e+02 93640  3.097806e+06 -6.865437e-01\n",
      "115  1.568456e+02 93063  3.191446e+06 -6.639412e-01\n",
      "116  1.568981e+02 92921  3.284509e+06 -6.417068e-01\n",
      "117  1.569505e+02 93205  3.377430e+06 -6.197186e-01\n",
      "118  1.570030e+02 93096  3.470635e+06 -5.980512e-01\n",
      "119  1.570554e+02 92886  3.563731e+06 -5.767090e-01\n",
      "120  1.571079e+02 92045  3.656617e+06 -5.558161e-01\n",
      "121  1.571603e+02 91485  3.748662e+06 -5.352880e-01\n",
      "122  1.572127e+02 91338  3.840147e+06 -5.150155e-01\n",
      "123  1.572652e+02 90652  3.931485e+06 -4.951025e-01\n",
      "124  1.573176e+02 89491  4.022137e+06 -4.756352e-01\n",
      "125  1.573701e+02 89029  4.111628e+06 -4.564457e-01\n",
      "126  1.574225e+02 87879  4.200657e+06 -4.376675e-01\n",
      "127  1.574749e+02 88036  4.288536e+06 -4.190093e-01\n",
      "128  1.575274e+02 86948  4.376572e+06 -4.007237e-01\n",
      "129  1.575798e+02 85929  4.463520e+06 -3.827832e-01\n",
      "130  1.576323e+02 85561  4.549449e+06 -3.650412e-01\n",
      "131  1.576847e+02 84654  4.635010e+06 -3.475995e-01\n",
      "132  1.577372e+02 83975  4.719664e+06 -3.304017e-01\n",
      "133  1.577896e+02 83552  4.803639e+06 -3.133869e-01\n",
      "134  1.578420e+02 82710  4.887191e+06 -2.966326e-01\n",
      "135  1.578945e+02 81676  4.969901e+06 -2.801690e-01\n",
      "136  1.579469e+02 81586  5.051577e+06 -2.637990e-01\n",
      "137  1.579994e+02 80984  5.133163e+06 -2.476194e-01\n",
      "138  1.580518e+02 80106  5.214147e+06 -2.316788e-01\n",
      "139  1.581042e+02 79738  5.294253e+06 -2.158697e-01\n",
      "140  1.581567e+02 79360  5.373991e+06 -2.001890e-01\n",
      "141  1.582091e+02 77863  5.453351e+06 -1.848517e-01\n",
      "142  1.582616e+02 76913  5.531214e+06 -1.697441e-01\n",
      "143  1.583140e+02 77143  5.608127e+06 -1.546302e-01\n",
      "144  1.583665e+02 76348  5.685270e+06 -1.397068e-01\n",
      "145  1.584189e+02 75941  5.761618e+06 -1.248937e-01\n",
      "146  1.584713e+02 75687  5.837559e+06 -1.101574e-01\n",
      "147  1.585238e+02 74897  5.913246e+06 -9.559842e-02\n",
      "148  1.585762e+02 73722  5.988143e+06 -8.128763e-02\n",
      "149  1.586287e+02 73316  6.061865e+06 -6.707215e-02\n",
      "150  1.586811e+02 72992  6.135181e+06 -5.293294e-02\n",
      "151  1.587335e+02 72280  6.208173e+06 -3.894209e-02\n",
      "152  1.587860e+02 71617  6.280453e+06 -2.508709e-02\n",
      "153  1.588384e+02 70908  6.352070e+06 -1.137401e-02\n",
      "154  1.588909e+02 70654  6.422978e+06  2.287825e-03\n",
      "155  1.589433e+02 69730  6.493632e+06  1.577140e-02\n",
      "156  1.589958e+02 69022  6.563362e+06  2.912088e-02\n",
      "157  1.590482e+02 68558  6.632384e+06  4.238576e-02\n",
      "158  1.591006e+02 68372  6.700942e+06  5.562208e-02\n",
      "159  1.591531e+02 67336  6.769314e+06  6.866735e-02\n",
      "160  1.592055e+02 66656  6.836650e+06  8.159240e-02\n",
      "161  1.592580e+02 65884  6.903306e+06  9.438116e-02\n",
      "162  1.593104e+02 65443  6.969190e+06  1.070996e-01\n",
      "163  1.593628e+02 65016  7.034633e+06  1.197522e-01\n",
      "164  1.594153e+02 64364  7.099649e+06  1.322969e-01\n",
      "165  1.594677e+02 63448  7.164013e+06  1.446834e-01\n",
      "166  1.595202e+02 62512  7.227461e+06  1.569090e-01\n",
      "167  1.595726e+02 62098  7.289973e+06  1.690768e-01\n",
      "168  1.596251e+02 61449  7.352071e+06  1.811422e-01\n",
      "169  1.596775e+02 60709  7.413520e+06  1.930882e-01\n",
      "170  1.597299e+02 59742  7.474229e+06  2.048709e-01\n",
      "171  1.597824e+02 59222  7.533971e+06  2.165791e-01\n",
      "172  1.598348e+02 59176  7.593193e+06  2.283080e-01\n",
      "173  1.598873e+02 58074  7.652369e+06  2.398491e-01\n",
      "174  1.599397e+02 57856  7.710443e+06  2.513787e-01\n",
      "175  1.599921e+02 56878  7.768299e+06  2.627461e-01\n",
      "176  1.600446e+02 56081  7.825177e+06  2.739875e-01\n",
      "177  1.600970e+02 55559  7.881258e+06  2.851585e-01\n",
      "178  1.601495e+02 54525  7.936817e+06  2.961564e-01\n",
      "179  1.602019e+02 54062  7.991342e+06  3.070963e-01\n",
      "180  1.602544e+02 53450  8.045404e+06  3.179486e-01\n",
      "181  1.603068e+02 52869  8.098854e+06  3.287199e-01\n",
      "182  1.603592e+02 52508  8.151723e+06  3.394556e-01\n",
      "183  1.604117e+02 51619  8.204231e+06  3.500477e-01\n",
      "184  1.604641e+02 50697  8.255850e+06  3.604891e-01\n",
      "185  1.605166e+02 49965  8.306547e+06  3.708182e-01\n",
      "186  1.605690e+02 49314  8.356512e+06  3.810517e-01\n",
      "187  1.606214e+02 48630  8.405826e+06  3.911825e-01\n",
      "188  1.606739e+02 48131  8.454456e+06  4.012491e-01\n",
      "189  1.607263e+02 47319  8.502587e+06  4.111856e-01\n",
      "190  1.607788e+02 46732  8.549906e+06  4.210388e-01\n",
      "191  1.608312e+02 45839  8.596638e+06  4.307436e-01\n",
      "192  1.608837e+02 45609  8.642477e+06  4.404402e-01\n",
      "193  1.609361e+02 44937  8.688086e+06  4.500346e-01\n",
      "194  1.609885e+02 44210  8.733023e+06  4.595143e-01\n",
      "195  1.610410e+02 43586  8.777233e+06  4.689008e-01\n",
      "196  1.610934e+02 43185  8.820819e+06  4.782419e-01\n",
      "197  1.611459e+02 42361  8.864004e+06  4.874455e-01\n",
      "198  1.611983e+02 41515  8.906365e+06  4.965055e-01\n",
      "199  1.612507e+02 40755  8.947880e+06  5.054395e-01\n",
      "200  1.613032e+02 40377  8.988635e+06  5.143306e-01\n",
      "201  1.613556e+02 40033  9.029012e+06  5.231862e-01\n",
      "202  1.614081e+02 38745  9.069045e+06  5.317962e-01\n",
      "203  1.614605e+02 38501  9.107790e+06  5.403912e-01\n",
      "204  1.615130e+02 37902  9.146291e+06  5.488916e-01\n",
      "205  1.615654e+02 36946  9.184193e+06  5.572159e-01\n",
      "\n",
      "(Truncated at 500 lines)\n"
     ]
    }
   ],
   "source": [
    "lncnt = 0\n",
    "with open(\"work/M17/M17.hist\", \"r\") as file:\n",
    "    for line in file:  \n",
    "        print(line, end='')\n",
    "        lncnt = lncnt + 1\n",
    "        if lncnt > 500:\n",
    "            print('\\n(Truncated at 500 lines)')\n",
    "            break"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "&nbsp;<p/>\n",
    "\n",
    "## Error Handling\n",
    "\n",
    "If mHistogram encounters an error, the return structure will just have two elements: a status of 1 (\"error\") and a message string that tries to diagnose the reason for the error.\n",
    "\n",
    "For instance, if the user specifies an image that doesn't exist: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'status': '1', 'msg': b'Image file M17/unknown.fits invalid FITS'}\n"
     ]
    }
   ],
   "source": [
    "rtn = mHistogram(\"M17/unknown.fits\", \"work/M17/M17.hist\", \"-2s\", \"max\", \"gaussian-log\")\n",
    "\n",
    "print(rtn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "&nbsp;\n",
    "\n",
    "## Classic Montage: mHistogram as a Stand-Alone Program\n",
    "\n",
    "### mHistogram Unix/Windows Command-line Arguments\n",
    "\n",
    "<p>mHistogram can also be run as a command-line tool in Linux, OS X, and Windows:</p>\n",
    "\n",
    "<p><tt>\n",
    "<b>Usage:</b> mHistogram [-d] -file in.fits minrange maxrange [logpower/gaussian/gaussian-log/asinh [asinh-beta]] -out out.hist\n",
    "</tt></p>\n",
    "<p>&nbsp;</p>\n",
    "<p>If you are writing in C/C++, mHistogram can be accessed as a library function:</p>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<pre>\n",
    "/*-*********************************************************************************************/\n",
    "/*                                                                                             */\n",
    "/*  mHistogram                                                                                 */\n",
    "/*                                                                                             */\n",
    "/*  This program is essentially a subset of mViewer containing the code that determines        */\n",
    "/*  the stretch for an image.  With it we can generate stretch information for a whole         */\n",
    "/*  file (or one reference file), then use it when we create a set of JPEG/PNG files           */\n",
    "/*  from a set of other subsets/files.                                                         */\n",
    "/*                                                                                             */\n",
    "/*  Only one file is processed, so if we want color we need to run this program three          */\n",
    "/*  times.  The only arguments needed are the image / stretch min / stretch max / mode.        */\n",
    "/*                                                                                             */\n",
    "/*   char *imgFile       Input FITS file.                                                      */\n",
    "/*   char *histFile      Output histogram file.                                                */\n",
    "/*   char *minString     Data range minimum as a string (to allow '%' and 's' suffix.          */\n",
    "/*   char *maxString     Data range maximum as a string (to allow '%' and 's' suffix.          */\n",
    "/*   char *stretchType   Stretch type (linear, power(log**N), sinh, gaussian or gaussian-log)  */\n",
    "/*                                                                                             */\n",
    "/*   int   grayLogPower  If the stretch type is log to a power, the power value.               */\n",
    "/*   char *betaString    If the stretch type is asinh, the transition data value.              */\n",
    "/*                                                                                             */\n",
    "/*   int   debug         Debugging output level.                                               */\n",
    "/*                                                                                             */\n",
    "/***********************************************************************************************/\n",
    "\n",
    "struct mHistogramReturn *mHistogram(char *grayfile, char *histfile, \n",
    "                                    char *grayminstr, char *graymaxstr, char *graytype, int graylogpower, char *graybetastr, int debugin)\n",
    "</pre>\n",
    "<p><b>Return Structure</b></p>\n",
    "<pre>\n",
    "struct mHistogramReturn\n",
    "{\n",
    "   int    status;        // Return status (0: OK, 1:ERROR)\n",
    "   char   msg [1024];    // Return message (for error return)\n",
    "   char   json[4096];    // Return parameters as JSON string\n",
    "   double minval;        // Data value associated with histogram minimum.\n",
    "   double minpercent;    // Percentile value of histogram minimum.\n",
    "   double minsigma;      // 'Sigma' level of histogram minimum.\n",
    "   double maxval;        // Data value associated with histogram maximum.\n",
    "   double maxpercent;    // Percentile value of histogram maximum.\n",
    "   double maxsigma;      // 'Sigma' level of histogram maximum.\n",
    "   double datamin;       // Minimum data value in file.\n",
    "   double datamax;       // Maximum data value in file.\n",
    "};\n",
    "</pre>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}