mShrink.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: mShrink\n",
    "\n",
    "mShrink allows us to shrink (or expand) an image by an arbitrary factor.  Often used in conjuction with visualization, shrinking images is also useful when making mosaics of very large areas at reduced visualization as the shrinking process is much faster than than reprojection and shrinking first saves time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on built-in function mShrink in module MontagePy.main:\n",
      "\n",
      "mShrink(...)\n",
      "    mShrink is a utility program for making smaller versions of a FITS file by averaging NxN blocks of pixels spatially.  N can be fractional.\n",
      "    \n",
      "    Parameters\n",
      "    ----------\n",
      "    infile : str\n",
      "        Input FITS file.\n",
      "    output_file : str\n",
      "        Subimage output FITS file.\n",
      "    shrinkFactor : float\n",
      "        Scale factor for spatial shrinking.  Can be any positive real number.\n",
      "    hdu : int, optional\n",
      "        Optional HDU offset for input file.\n",
      "    fixedSize : bool, optional\n",
      "        Alternate mode: shrink so the output fits in this many pixels.\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",
      "    time : float\n",
      "        Total processing time (sec).\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from MontagePy.main import mShrink, mViewer\n",
    "\n",
    "help(mShrink)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## mShrink Example\n",
    "\n",
    "The principle parameters for mShrink are the input and output files and the scale factor.  If the 'fixedSize' parameter is set, the shrinkFactor parameter instead represents the full output size in pixels."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'status': '0', 'time': 1.0}\n"
     ]
    }
   ],
   "source": [
    "rtn = mShrink('M17/mosaic.fits', 'work/M17/mosaic_small.fits', 3.5)\n",
    "\n",
    "print(rtn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Before and After\n",
    "\n",
    "The original image and the 3.5x shrunken one:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<table><tr><td><img src='work/mosaic_shrink.png'></td>                          <td><img src='work/mosaic_small.png'></td></tr></table>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from IPython.display import Image, display, HTML\n",
    "\n",
    "rtn = mViewer(\"-ct 1 -gray M17/mosaic.fits \\\n",
    "               -2s max gaussian-log -out work/mosaic_shrink.png\", \"\", mode=2)\n",
    "\n",
    "rtn = mViewer(\"-ct 1 -gray work/M17/mosaic_small.fits \\\n",
    "               -2s max gaussian-log -out work/mosaic_small.png\", \"\", mode=2)\n",
    "\n",
    "display(HTML(\"<table><tr><td><img src='work/mosaic_shrink.png'></td> \\\n",
    "                         <td><img src='work/mosaic_small.png'></td></tr></table>\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "&nbsp;<p/>\n",
    "\n",
    "## Error Handling\n",
    "\n",
    "If mShrink 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": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'status': '1', 'msg': b'Image file M17/unknown.fits missing or invalid FITS'}\n"
     ]
    }
   ],
   "source": [
    "rtn = mShrink('M17/unknown.fits', 'work/M17/mosaic_small.fits', 3.5)\n",
    "\n",
    "print(rtn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "&nbsp;\n",
    "\n",
    "\n",
    "\n",
    "# Using Montage Standalone\n",
    "\n",
    "\n",
    "### mShrink Unix/Windows Command-line Arguments\n",
    "\n",
    "<p>mShrink can also be run as a command-line tool in Linux, OS X, and Windows:</p>\n",
    "\n",
    "<p><tt>\n",
    "<b>Usage:</b> mShrink [-f(ixed-size)] [-d level] [-h hdu] [-s statusfile] in.fits out.fits factor\n",
    "</tt></p>\n",
    "<p>&nbsp;</p>\n",
    "<p>If you are writing in C/C++, mShrink can be accessed as a library function:</p>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<pre>\n",
    "/*-***********************************************************************/\n",
    "/*                                                                       */\n",
    "/*  mShrink                                                              */\n",
    "/*                                                                       */\n",
    "/*  Montage is a set of general reprojection / coordinate-transform /    */\n",
    "/*  mosaicking programs.  Any number of input images can be merged into  */\n",
    "/*  an output FITS file.                                                 */\n",
    "/*                                                                       */\n",
    "/*  This module, mShrink, is a utility program for making smaller        */\n",
    "/*  versions of a FITS file by averaging NxN blocks of pixels.           */\n",
    "/*                                                                       */\n",
    "/*   char  *infile         Input FITS file                               */\n",
    "/*   char  *output_file    Shrunken output FITS file                     */\n",
    "/*                                                                       */\n",
    "/*   double shrinkFactor   Scale factor for spatial shrinking.  Can be   */\n",
    "/*                         any positive real number                      */\n",
    "/*                                                                       */\n",
    "/*   int    hdu            Optional HDU offset for input file            */\n",
    "/*   int    fixedSize      Alternate mode: shrink so the output fits     */\n",
    "/*                         in this many pixels                           */\n",
    "/*                                                                       */\n",
    "/*   int    debug          Debugging output level                        */\n",
    "/*                                                                       */\n",
    "/*************************************************************************/\n",
    "\n",
    "struct mShrinkReturn *mShrink(char *input_file, char *output_file, double shrinkFactor, int hduin, int fixedSize, int debug)\n",
    "</pre>\n",
    "<p><b>Return Structure</b></p>\n",
    "<pre>\n",
    "struct mShrinkReturn\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 time;          // Run time (sec)   \n",
    "};\n",
    "</pre>"
   ]
  }
 ],
 "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
}