docs/notebooks/image_visualization.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "name": "image_visualization.ipynb",
      "provenance": [],
      "collapsed_sections": [],
      "toc_visible": true
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "h14Ma5ydkunX"
      },
      "source": [
        "# Image Cube Visualization \n",
        "\n",
        "<div class=\"alert alert-warning\">\n",
        "The task **viewer** is deprecated in lieu of **imview** and **msview**, which contain the same functionality. Please invoke the **imview** (**msview**) task for running the CASA Viewer to visualize images or image cubes (visibility data).\n",
        "</div>\n",
        "\n",
        "This documentation describes how to use the CASA Viewer to display data. The Viewer can be started as a stand-alone executable or by the tasks **imview** and **msview** inside a CASA shell. The **imview** task displays images, while the **msview** task is for visualizing MeasurementSets. These tasks offer scriptability, giving command line access to many of the viewer features.\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**Note:** This section describes the CASA Image Viewer (imview). The Viewer is being phased out in favor of CARTA and is no longer in active development. This information is provided for reference in instances where desired capability is not yet ready in CARTA.\n",
        "</div>\n",
        "\n",
        "For help on the image viewer, please see the subpages shown in the tabs to the left. For the Visibility visualization, please see [2-D Visualization and Flagging of Visibility Data](data_examination.ipynb).\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "a5z2VhnukunZ"
      },
      "source": [
        "## Viewer Basics \n",
        "\n",
        "\n",
        "![08fb3afec0b21c1c8afa30e15b80617972df1d4f](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/08fb3afec0b21c1c8afa30e15b80617972df1d4f.png?raw=1)\n",
        "\n",
        ">Initial Viewer Panels: The Viewer Display Panel (left) and the Data Manager Panel (right) for a regular image or data cube.\n",
        "\n",
        "\n",
        "Within the CASA environment, the imview task can be used to start the CASA Viewer for displaying images or image cubes. The inputs are:\n",
        "\n",
        "```\n",
        "#imview :: View an image \n",
        "\n",
        "raster  = {}                      # (Optional) Raster filename (string) or\n",
        "                                  # complete raster config dictionary. The\n",
        "                                  # allowed dictionary keys are file (string),\n",
        "                                  # scaling (numeric), range (2 element numeric\n",
        "                                  # vector), colormap (string), and colorwedge\n",
        "                                  # (bool).\n",
        "contour = {}                      # (Optional) Contour filename (string) or\n",
        "                                  # complete contour config dictionary. The\n",
        "                                  # allowed dictionary keys are file (string),\n",
        "                                  # levels (numeric vector), unit (float), and\n",
        "                                  # base (float).\n",
        "zoom    = 1                       # (Optional) zoom can specify intermental zoom\n",
        "                                  # (integer), zoom region read from a file\n",
        "                                  # (string) or dictionary specifying the zoom\n",
        "                                  # region. The dictionary can have two forms.\n",
        "                                  # It can be either a simple region specified\n",
        "                                  # with blc (2 element vector) and trc (2\n",
        "                                  # element vector) [along with an optional\n",
        "                                  # coord key (\"pixel\" or \"world\"; pixel is the\n",
        "                                  # default) or a complete region rectangle e.g.\n",
        "                                  # loaded with \"rg.fromfiletorecord( )\". The\n",
        "                                  # dictionary can also contain a channel\n",
        "                                  # (integer) field which indicates which\n",
        "                                  # channel should be displayed.\n",
        "axes    = {}                      # (Optional) this can either be a three\n",
        "                                  # element vector (string) where each element\n",
        "                                  # describes what should be found on each of\n",
        "                                  # the x, y, and z axes or a dictionary\n",
        "                                  # containing fields \"x\", \"y\" and \"z\" (string).\n",
        "out     = ''                      # (Optional) Output filename or complete\n",
        "                                  # output config dictionary. If a string is\n",
        "                                  # passed, the file extension is used to\n",
        "                                  # determine the output type (jpg, pdf, eps,\n",
        "                                  # ps, png, xbm, xpm, or ppm). If a dictionary\n",
        "                                  # is passed, it can contain the fields, file\n",
        "                                  # (string), scale (float), dpi (int), or\n",
        "                                  # orient (landscape or portrait). The scale\n",
        "                                  # field is used for the bitmap formats (i.e.\n",
        "                                  # not ps or pdf) and the dpi parameter is used\n",
        "                                  # for scalable formats (pdf or ps).\n",
        "```\n",
        "\n",
        "Examples of starting the CASA Viewer using **imview**:\n",
        "\n",
        "```\n",
        "CASA <1>: imview()\n",
        "\n",
        "CASA <3>: viewer('ngc5921.demo.cleanimg.image')\n",
        "\n",
        "CASA <3>: viewer(contour='ngc5921.demo.cleanimg.image')\n",
        "```\n",
        "\n",
        "The first command creates an empty *Viewer Display Panel* and a *Load Data Window*. The second command starts the viewer with a loaded MeasurementSet. The third command starts the viewer and opens an image data cube.\n",
        "\n",
        "Note that the viewer can open FITS files, CASA image files (**imview**), MeasurementSets (**msview**), and saved viewer states. The viewer determines the type of file being opened automatically.\n",
        "\n",
        "For additional scripting options when opening the viewer, see the discussion of the **imview** and **msview** tasks.\n",
        "\n",
        "\n",
        "**Running the Viewer Outside CASA**\n",
        "\n",
        "If you have CASA installed, then the CASA Viewer is available as a stand-alone application called casaviewer. From the operating system prompt, the following commands work the same as the casa task commands given in the previous section:\n",
        "\n",
        "```\n",
        "casaviewer &\n",
        "\n",
        "casaviewer ms_filename &\n",
        " \n",
        "casaviewer image_filename &\n",
        " \n",
        "casaviewer image_filename contour &\n",
        " \n",
        "casaviewer '\"image_filename\"^2' lel &\n",
        "```\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "0WZPesBrkunZ"
      },
      "source": [
        "**The Viewer Display Panel**\n",
        "\n",
        "The CASA Viewer consists of a number of graphical user interface (GUI) windows. The main *Viewer Display Panel* is used for both image and MeasurementSet viewing. It is shown in the left panels of *Initial Viewer Panels* and *Data Display Options* and appears the same whether an image or MeasurementSet is being displayed.\n",
        "\n",
        "![e8cf3cee163da8e2a22ef120a841581226610667](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/e8cf3cee163da8e2a22ef120a841581226610667.png?raw=1)\n",
        "\n",
        "At the top of the Viewer Display Panel are drop down menus:\n",
        "\n",
        "-   DATA\n",
        "    -   Open --- open the *Data Manager* window.\n",
        "    -   Manage Images --- open the *Image Manager* which contains functionality for managing the image stack.\n",
        "    -   Adjust Data Display --- open the *Data Display Options* (\\'Adjust\\') window.\n",
        "    -   Save as\\... --- save/export data to a file.\n",
        "    -   Print --- print the displayed image.\n",
        "    -   Save Panel State --- to a 'restore' file (xml format).\n",
        "    -   Restore Panel State --- from a restore file.\n",
        "    -   Preferences --- manually edit the viewer configuration.\n",
        "    -   Close panel--- close this Viewer Display Panel. If this is the last display panel open, this will exit the viewer.\n",
        "    -   Quit Viewer --- close all display panels and exit.\n",
        "-   DISPLAY PANEL    -   New Panel--- create a new, empty Viewer Display Panel.\n",
        "    -   Panel Options --- open the Viewer Canvas Manager (see the [Viewing Images and Cubes](image_visualization.ipynb#viewing-images-and-cubes) page) window to edit margins, the number of panels, and the background.\n",
        "    -   Save Panel State --- save the current state of the viewer as a file that can later be reloaded.\n",
        "    -   Restore Panel State --- restore the viewer to a state previously saved as a file.\n",
        "    -   Print --- print displayed image.\n",
        "    -   Close Panel --- close this Viewer Display Panel. If this is the last display panel open, this will exit the viewer.\n",
        "-   TOOLS\n",
        "    -   Spectral Profile --- open the [Spectral Profile Browser](image_visualization.ipynb#spectral-profiler) window to look at intensity as a function of frequency for part of an image.\n",
        "    -   Collapse/Moments --- open the *Collapse/Moments* window, which allows you to create new images from a data cube by integrating along the spectral axis.\n",
        "    -   Histogram --- open the *Histogram* inspection window, which allows you to graphically examine the distribution of pixel values in a data cube.\n",
        "    -   Fit --- open the *Two-Dimensional Fitting* window, which can be used to fit Gaussians to two dimensional intensity distributions.\n",
        "    -   Interactive Clean --- open a window to look at ongoing interactive clean processes.\n",
        "-   VIEW\n",
        "    -   Main Toolbar --- show/hide the top row of icons.\n",
        "    -   Mouse Toolbar --- show/hide the second row of mouse-button action selection icons.\n",
        "    -   Animators--- show/hide tapedeck control panel attachment to the main *Viewer Display Panel*.\n",
        "    -   Cursors --- show/hide the position tracking attachment to the main *Viewer Display Panel*.\n",
        "    -   Regions --- show/hide the region manager attachment to the main *Viewer Display Panel*.\n",
        "\n",
        "\n",
        "**The Main Toolbar**\n",
        "\n",
        "![8b57d404c74488f1107e2ebf839c0f60faeb3c71](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/8b57d404c74488f1107e2ebf839c0f60faeb3c71.png?raw=1)\n",
        "\n",
        ">Main Toolbar: The Display Panel's Main Toolbar appears directly below the menus and contains \\'shortcut\\' buttons for most of the frequently-used menu items.\n",
        "  \n",
        "\n",
        "Below the drop down menus is the Main Toolbar. This top row of icons offers fast access to these menu items:\n",
        "\n",
        "-   FOLDER (Data\\\\:Open shortcut) --- open the *Data Manager* window.\n",
        "-   WRENCH (Data\\\\:Adjust shortcut) --- open the *Data Display Options* ('Adjust') window.\n",
        "-   MANAGE IMAGES (Data\\\\: Manage Images shortcut) - open the *Image Manager* window.\n",
        "-   DELETE (Data\\\\:Close shortcut) --- close (unload) the selected data file. The menu expands to the right showing all loaded data.\n",
        "-   SAVE DATA (Data\\\\:Save as) --- save the current data to a file.\n",
        "-   NEW PANEL (Display Panel:New Panel) --- create a new, empty Viewer Display Panel.\n",
        "-   PANEL WRENCH (Display Panel:Panel Options) --- open the Viewer Canvas Manager (see the [Viewing Images and Cubes](image_visualization.ipynb#viewing-images-and-cubes) page) window to edit margins, the number of panels, and the background.\n",
        "-   SAVE PANEL (Display Panel: Save Panel State) --- save panel state to a 'restore' file.\n",
        "-   RESTORE PANEL (Display Panel: Restore Panel State) --- restore panel state from a restore file.\n",
        "-   SPECTRAL PROFILE (Tools: Spectral Profile) --- Open the [Spectral Profile](image_visualization.ipynb#spectral-profiler) window to look at intensity as a function of frequency for part of an image.\n",
        "-   COLLAPSE/MOMENTS (Tools: Collapse/Moments) --- Open the *Collapse/Moments* window, which allows you to create new images from a data cube by integrating along the spectral axis.\n",
        "-   HISTOGRAM (Tools:Histogram) --- Open the *Histogram* inspection window, which allows you to graphically examine the distribution of pixel values in a data cube.\n",
        "-   TWO-DIMENSIONAL FITTING (Tools:Fit) -- Open the *Two-Dimensional Fitting* window, which can be used to fit Gaussians to two dimensional intensity distributions.\n",
        "-   PRINT (Display Panel:Print) --- print the current display.\n",
        "-   MAGNIFIER BOX --- zoom out all the way.\n",
        "-   MAGNIFIER PLUS --- zoom in (by a factor of 2).\n",
        "-   MAGNIFIER MINUS --- zoom out (by a factor of 2).     \n",
        "\n",
        "\n",
        "*The Mouse Toolbar*\n",
        "\n",
        "![aa5ec91c272ee59cd0bef0a8d695ca7872058795](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/aa5ec91c272ee59cd0bef0a8d695ca7872058795.png?raw=1)\n",
        "\n",
        ">Mouse Toolbar: The \\'Mouse Tool\\' Bar allows you to assign how mouse buttons behave in the image display area. Initially, zooming, color adjustment, and rectangular regions are assigned to the left, middle and right mouse buttons, respectively. Click on a tool with a mouse button to assign that tool to that mouse button.\n",
        "\n",
        "Below the Main Toolbar are eleven Mouse Tool buttons (see [Mouse Toolbar](#the-mouse-toolbar)). These allow you to assign what behavior the three mouse buttons have when clicked in the display area. Clicking a mouse tool icon will \\[re-\\]assign the mouse button that was clicked to that tool. Black and white squares beneath the icons show which mouse button is currently assigned to which tool.The mouse tools available from the toolbar are:\n",
        "\n",
        "-   ZOOMING (magnifying glass icon): To zoom into a selected area, press the zoom tool's mouse button (the left button by default) on one corner of the desired rectangle and drag to the desired opposite corner. Once the button is released, the zoom rectangle can still be moved or resized by dragging. To complete the zoom, double-click inside the selected rectangle. If you instead double-click outside the rectangle, you will zoom out.\n",
        "-   PANNING (hand icon): Press the panning tool's mouse button on a point you wish to move, drag it to the position where you want it moved, and release. Note: The arrow keys, Page Up, Page Down, Home and End keys can also be used to pan through your data any time you are zoomed in. (Click on the main display area first, to be sure the keyboard is 'focused' there).\n",
        "-   STRETCH-SHIFT COLORMAP FIDDLING (crossed arrows): This is usually the handiest color adjustment; it is assigned to the middle mouse button by default. Hold down the tool\\'s mouse button and drag across the display window to adjust the stretch and color. Note that you can also adjust the color table quantitatively inside the *Data Display Options* window.\n",
        "-   BRIGHTNESS-CONTRAST COLORMAP FIDDLING (light/dark sun): Another tool to adjust the color stretch.\n",
        "-   POSITIONING (plus): This tool can place a point marker on the display to select a position. It is used to flag MeasurementSet data or to select an image position for spectral profiles. Click on the desired position with the tool's mouse button to place the point; once placed you can drag it to other locations. You can also place multiple points on the display (e.g. for different spectral profile positions) -- remove them by hovering over and hitting ESC. Double-click is not needed for this tool. See *Viewer Region Positioning* for more detail.\n",
        "-   RECTANGLE, ELLIPSE, and POLYGON REGION DRAWING: The rectangle region tool is assigned to the right mouse button by default. As with the zoom tool, a rectangle region is generated by dragging with the assigned mouse button; the selection is confirmed by double-clicking within the rectangle. An ellipse regions is created by dragging with the assigned mouse button. In the case of an elliptical region, both the elliptical region and its surrounding rectangle are shown on the display. The selection is confirmed by double-clicking within the ellipse. Polygon regions are created by clicking the assigned mouse button at the desired vertices and then clicking the final location twice to finish. Once created, a polygon can be moved by dragging from inside, or reshaped by dragging the handles at the vertices. See *Viewer Region Positioning* for the uses of this tool.\n",
        "-   POLYLINE DRAWING: A polyline can be created by selecting this tool. It is manipulated similarly to the polygon region tool: create segments by clicking at the desired positions and then double-click to finish the line.\n",
        "-   DISTANCE TOOL (ruler): After selecting the distance tool by assigning a mouse button to it, distances on the image can conveniently be measured by dragging the mouse with the assigned button pressed. The tool measures the distances along the world coordinate axes and along the hypotenuse. If the units in both axes are \\[deg\\], the distances are displayed in \\[arcsec\\].\n",
        "-   POSITION-VELOCITY DIAGRAM: Use this mouse tool to drag out a position axis that can be used to generate a position velocity diagram in a new viewer panel from the region manager dock.\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: The 'escape' key can be used to cancel any mouse tool operation that was begun but not completed, and to erase a region, point, or other tool showing in the display area.\n",
        "</div>\n",
        "\n",
        "\n",
        "**The Main Display Area**\n",
        "\n",
        "The Main Display Area lies below the toolbars. This area shows the image or MeasurementSet currently loaded. Clicking the mouse inside the display area allows region or position selection according to the settings in the mouse toolbar.The Display Area may have up to three attached panels: the Animators panel, the Cursors panel, and the Regions panel. These may be displayed or hidden from the \\\"View\\\" dropdown menu in the main Viewer Display Panel. If one of these is missing from your viewer, check that it is checked \\\"on\\\" in that menu. The panels can also be turned off by clicking the \\\"X\\\" in the top right corner, in which case you will need to use the View menu to get them back.By default, the three panels appear attached to the main Viewer Display Panel on the right side of the image. They may be dragged to new positions. Each of the three panels can be attached to the left, top, right, or bottom of the main Viewer Display Panel or they can be entirely undocked and left as free-floating panels.\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: Depending on your window manager, windows without focus, including detached panels and tools like the Spectral Profile Browser may sometimes display odd behavior. As a general rule, giving the window focus by clicking on it will correct the issue. If you seem to \"lose\" a detached panel (like the Animators Panel), then click in the main window to get it back.\n",
        "</div>\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: With all three panels turned on (and especially with several images loaded), the Main Display Panel can sometimes shrink to very small sizes as the panels grow. Try detaching the panels to get the main display panel back to a useful size.\n",
        "</div>\n",
        "\n",
        "A restart of the viewer will display all docks in the state of a previous viewer session, given that it was closed normally. In addition, the viewer docking can be changed under \"Preferences\" in the toolbar (for Mac OS: under the \"CASA Viewer\" tab on the toolbar, for Linux: under \"Data\"). An example is given in the *Preference Dialog* figure below. Each item can be changed and the input box will only allow accepted input formats. A complete restart is required to apply the changes.\n",
        "\n",
        "![8feaa9fb0d42d24217df66390ab85c79d44fa0bd](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/8feaa9fb0d42d24217df66390ab85c79d44fa0bd.png?raw=1)\n",
        "\n",
        ">Preference Dialog: The Preference Dialog can be used to manually change the docking and size of the viewer panel.\n",
        "\n",
        "\n",
        "**The Animators Panel**\n",
        "\n",
        "![2cfd77b4f2ced4be1a260718e231ae8110cb6d0d](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/2cfd77b4f2ced4be1a260718e231ae8110cb6d0d.png?raw=1)\n",
        "\n",
        ">Animators Panel: The Animators Panel allows you to scroll through the z-axis of a data cube (using the Channels tape deck) or cycle among open Images. The panel can be undocked from the main display panel.\n",
        "\n",
        "\n",
        "The Animators Panel allows you to scroll through the channels of a data cube and to flip through loaded images. The main features of the panel are the two \"tape decks,\" one labeled \\\"Channels\\\" and one labeled \\\"Images\\\".\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: You will only see the Images tape deck when multiple images are loaded.\n",
        "</div>\n",
        "\n",
        "The \\\"Channels\\\" tape deck scrolls between planes of an individual image. By default, the channel tape deck scrolls among frequency planes when Right Ascension and Declination are the displayed axes (in this case, frequency is the z-axis). From outside to inside, the buttons cause the display to jump all the way to the beginning/end of the z-axis, cause the viewer to step one plane forward or backward along the z-axis, or start a movie. The limits on the z-axis can be set manually using the windows at the end of the scroll bar. The scroll bar can also be dragged or the user can jump the display to a manually entered plane by entering the plane into the text block.When you have multiple images loaded, the Images tape deck cycles through which is image is being displayed. In the movie mode, it allows you continuously click between images. Functionally, the Images tape deck works similarly to the Channels tape deck, with the ability to step, jump, or continuously scroll through images.\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: The check boxes next to the channel and images tabs enable or disable those panels. This doesn't have much effect when the display has only a single panel, but with multiple panels (i.e., several maps at once in the main window) it changes the nature of the display. If the \"Images\" box is checked then interleaved maps from different cubes are displayed. Otherwise a series of maps from a single cube are shown.\n",
        "</div>\n",
        "\n",
        "\n",
        "**The Cursors Panel**\n",
        "\n",
        "![b58deef224d019cae4184041a4e7fd9691bfcaf6](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/b58deef224d019cae4184041a4e7fd9691bfcaf6.png?raw=1)\n",
        "\n",
        ">Cursors Panel: The Cursors Panel gives information about the open data cube at the current location of the cursor. Freeze the Cursors Panel using the SPACE bar.\n",
        "\n",
        "\n",
        "The Cursors Panel (below the Images tape deck in *Initial Viewer Panels* shows the intensity, position (e.g., RA and Dec), Stokes, frequency (or velocity), and pixel location for the point currently under the cursor. A separate box appears for each registered image or MeasurementSet and you can see the tracking information for each. Tracking can be \\'frozen\\' (and unfrozen again) by hitting the space bar when the viewer's focus is on the main display area. (To be sure that the focus is indeed the main display area, first click on the main display area.)\n",
        "\n",
        "\n",
        "**The Region Manager Panel**\n",
        "\n",
        "The Region Manager Panel becomes active when regions are created. It has a large amount of functionality, from display region statistics and histograms to creating position-velocity cuts. Like the Animators and Cursors Panels, the Region Manager Panel can be moved relative to the main Viewer Display Panel or entirely undocked.\n",
        "\n",
        "**Saving and Restoring the Display Panel State**\n",
        "\n",
        "You can save the display panel's current state --- meaning the panel settings and the data on display --- or load a saved panel state from disk. To save the display panel state, select Save Panel State from the Display Panel drop-down menu or click the \\\"Save Display Panel State to File\\\" icon on the main toolbar (an arrow pointing from a picture to a page. It is advisable but not required to retain the file's \\'.rstr\\' (\\\"Restore\\\") extension.You can restore the display panel to the saved state by loading the saved state from the Data Manager Panel, by selecting Restore Panel State from the Display Panel drop down menu, or by clicking the \\\"Restore Display Panel State\\\" icon (just to the right of the \\\"Save Display Panel State\\\" icon).It is possible to restore panel states viewing MeasurementSets, images, or panel states that have multiple layers, such as contour plots over raster images. You can also save LEL displays. You can also the save or restore the panel state with no data loaded, which is a convenient way to restore preferred initial settings such as overall panel size.Data Locations: The viewer is fairly forgiving regarding data location when restoring a saved panel state. It will find files located:\n",
        "\n",
        "-   in the original location recorded in the restore file\n",
        "-   in the current working directory (where you started the viewer)\n",
        "-   in the restore file's directory\n",
        "-   in the original location relative to the restore file\n",
        "\n",
        "This means that you can generally restore a saved panel state if you move that file together with data files. The exception to this rule is that the process is less forgiving if you save the display of an LEL expression. In this case the files must be in the locations specified in the original LEL expression. If a data file is not found, restore will attempt to proceed but results may not be ideal.Manually Editing Saved Display Panel States: The saved \\\"Restore\\\" files are in ascii (xml) format, and manual edits are possible. However, these files are long and complex. Use caution, and back up restore files before editing. If you make a mistake, the viewer may not even recognize the file as a restore file. It is easier and safer to make changes on the display panel and then save the display panel state again.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "-9uBVDxpkuna"
      },
      "source": [
        "**The Data Manager Panel --- Saving and Loading Data**\n",
        "\n",
        "![7d4cd267bbb4a3b269e1f22c908e1dc21a017b70](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/7d4cd267bbb4a3b269e1f22c908e1dc21a017b70.png?raw=1)\n",
        "\n",
        ">Data Manager Panel: The load tab of the Data Manager panel. This appears if you open the viewer without any infile specified, if you use select Open from the Data drop-down menu, or click the Open (Folder) icon. You can access the save image or save region tabs from this view or by selecting Save as\\... from the Data drop down menu. The load tab shows all files in the current directory that can be loaded into the viewer --- images (in task **imview**), MS (in task **msview**), CASA region files, and Display Panel State files.\n",
        "\n",
        "\n",
        "The Data Manager Panel is used to interactively load and save images, MeasurementSets, Display Panel States, and regions. An example of the loading tab in this panel is shown in the *Data Manager Panel* figure. This panel appears automatically if you open the viewer without specifying an input file or it can be accessed through the Data\\\\:Open menu or Open icon of the Viewer Display Panel.\n",
        "\n",
        "\n",
        "**Loading Data**\n",
        "\n",
        "The load tab of the Data Manager Panel allows you to interactively choose images or MeasurementSets to load into the viewer. The load tab automatically shows you the available images, MeasurementSets, and Display Panel States in the current directory that can be opened by the viewer. When you highlight an image in this view, the tab shows a brief summary of the image: pixel shape, extent of the image on the sky and in frequency/velocity, and restoring beam (if available).Selecting a file will bring up information about that file in the panel on the right of the Data Manager Panel provide options for how to display the data. Images can be displayed as:\n",
        "\n",
        "1.  raster image\n",
        "2.  contour map\n",
        "3.  vector map\n",
        "4.  marker map\n",
        "\n",
        "These options area each discussed in [Viewing Images](image_visualization.ipynb#viewing-images-and-cubes).\n",
        "\n",
        "Additionally, the following data types can be loaded via the Data Manager Panel:slice: a subselection of a data cube can be loaded, the start and end pixel in each spatial, polarization, and spectral dimension can be selected.LEL: Instead of only loading an image from disk, you may ask the viewer to evaluate a [Lattice Expression Language](image_analysis.ipynb#Lattice-Expression-Language) (LEL) expression. This can be entered in the box provided after you click the \\\"LEL\\\" box. The images used in the LEL expression should have the same coordinates and extents.MeasurementSets: A MeasurementSet can only be displayed as a raster. For MeasurementSets, the load tab offers options for data selection. This will reduce loading and processing times for visibility flagging.Regridding Images on Load: Optionally, you may regrid the velocity axis of an image you wish to load to match the current coordinates grid in the Display Panel. In this case, the viewer will interpolate (using the selected interpolation scheme) the cube on disk to share the same velocity gridding as the loaded coordinates. This can be used, e.g. to overlay contour maps of different spectral lines or to make synchronized movies of multiple cubes. Note that the regridding depends on the rest frequency in the image, which is used to calculate the velocities used in regridding.\n",
        "\n",
        "\n",
        "**Registered vs. Open Datasets**\n",
        "\n",
        "When you load data as described above, it is first opened, and then registered on all existing Display Panels. An open dataset has been prepared in memory from disk. All open datasets will have a tab in the Data Display Options window, whether currently registered or not. When a data set is registered to a Display Panel its coordinates are aligned to the master coordinate image in the panel and it is ready for drawing. If multiple Display Panels are open then a data set may be registered on one Display Panel and not on another. Only those data sets registered on a particular Display Panel show up in its Cursors Panel.Why Register More Than One Image? It is useful to have more than one image registered on a panel if you are displaying a contour image over a raster image, to 'blink' between images, or to compare images using the Cursors Panel.Unregistering Images: A data set can be registered or unregistered using the Image Manager in the Data drop down menu or the Image Manager icon (third from left). This icon will open the Image Manager window and the checkboxes can be used to register or unregister an image.Closing vs. Unregistering: You can close a data set that is no longer needed using the Close option in the Data drop-down menu, the \\\"Close\\\" icon (fourth from left), or right mouse button \"Close\" selection in the *Image Manager*.If you close a dataset, you must reload it from disk (or recreate it if it's an LEL expression, regridded image, moment or something similar) to see it again. If you unregister a dataset, it will draw immediately if you re-register it, with its options as you have previously set them. In general, close unneeded datasets but unregister those that you intend to use again.\n",
        "\n",
        "\n",
        "**Image Manager**\n",
        "\n",
        "The Image Manager is used to define the master coordinate image, the sequence of images (e.g. for blinking), to register and unregister images, close images, change between raster, contour, vector, and marker displays, and to modify the properties of images. The panel can be invoked from the \"Manage Images\" tool, the third icon from the left (two overlapping squares).An example is shown in *Image Manager* figure. In this case, four images are loaded into the viewer. The sequence of images can be changed by dragging and dropping the images to new positions in the stack. The letter to the left indicates whether the image is a Raster, Contour, Vector, or Marker image. MC marks the coordinate master, in this case the second image. The checkboxes are to change the registration statuses. The Coordinate Master image can be defined by a right mouse click, and selecting the corresponding option. The right mouse menu button also offers options for quick changes between contour and raster images and to close an image. The Options button will open a drop-down box (as shown in *Image Manager* for the first image), in which one can again change between image type, change to a different rest frequency (or \"Reset\" to the value in the image header), or open the \\\"Display Options\\\" panel for that specific image.\n",
        "\n",
        "![8974d9863e86c477d90bafedc2635435d5e45fbb](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/8974d9863e86c477d90bafedc2635435d5e45fbb.png?raw=1)\n",
        "\n",
        ">Image Manager\n",
        "\n",
        "\n",
        "**Saving Data or Regions**\n",
        "\n",
        "![6635be99d7c7c01aecee67542626f14a7a4fab30](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/6635be99d7c7c01aecee67542626f14a7a4fab30.png?raw=1)\n",
        "\n",
        ">Save Data Panel: The Save Data panel that appears when selecting the 'Save as\\...'\n",
        "\n",
        "\n",
        "The viewer can create new images by carrying out velocity regridding, evaluating an LEL expression, or collapsing a data cube. You can save these images to disk using the Data Manager Panel. Select Save As under the Data drop-down menu or click the Save As (disk) icon to bring up the Data Manager Panel set to the save tabs. These tabs are shown in the figure above.From the Save Image tab of the Data Manager Panel, you can export images from the viewer to either a CASA image or FITS file on disk. Select the desired file name and click \\\"Save.\\\" The Data Manager also allows you to save your current regions to a file, either in the CASA or ds9 format. The left side of the Save Data Panel lists all images that can be exported to disk. To save an image to a file, you can either enter the new filename in the box labeled \\'output name:\\' followed by the save-button (alternatively the 'Enter'-key), or choose a file name from the right hand side.\n",
        "\n",
        "\n",
        "***\n",
        "\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "s-rVFBz4kuna"
      },
      "source": [
        "## Viewing Images and Cubes \n",
        "\n",
        "\n",
        "**Viewing Images**\n",
        "\n",
        "There are several options for viewing an image. These are seen at the right of the Load Data - Viewer panel after selecting an image. They are:\n",
        "\n",
        "-   raster image --- a greyscale or color image,\n",
        "-   contour map --- contours of intensity as a line plot,\n",
        "-   vector map --- vectors (as in polarization) as a line plot,\n",
        "-   marker map --- a line plot with symbols to mark positions.\n",
        "\n",
        "The raster image is the default image display, and is what you get if you invoke the viewer with an image file and no other options. In this case, you will need to use the Open menu to bring up the Load Data panel to choose a different display.\n",
        "\n",
        "This page discusses raster images and contour maps in detail; for an example of how to use a vector map, see the 3C286 Polarization CASAguide [here](https://casaguides.nrao.edu/index.php/3C286_Band6Pol_Imaging_for_CASA_4.3).\n",
        "\n",
        "**Initial Viewer Panels**\n",
        "\n",
        "When the viewer is started, two dialogs appear. One is the Data Manager which presents two panels.\n",
        "\n",
        "**Data Manager**\n",
        "\n",
        "The left panel shows the files that the viewer can load while the right panel shows some statistics about the file that is selected.\n",
        "\n",
        "![e4b6e0a334c21c09b02abeac82d22632d050643f](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/e4b6e0a334c21c09b02abeac82d22632d050643f.jpg?raw=1)\n",
        "\n",
        "The other panel is the Viewer Display Panel.\n",
        "\n",
        "**Viewer Display Panel**\n",
        "\n",
        "This panel is the main panel used to interact with the viewer. \n",
        "\n",
        "![1fa6b6a876aad22dcb6fc8c360d20fc4a67784ce](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/1fa6b6a876aad22dcb6fc8c360d20fc4a67784ce.jpg?raw=1)\n",
        "\n",
        "The image is shown on the left and image information is shown on the right. The Cursors panel displays information about the pixel at the current cursor location (as the cursor is moved around the image).\n",
        "\n",
        "**Animators Panel**\n",
        "\n",
        "The Animators panel allows the planes on the image cube to be displayed. This can be done by either single-stepping plane by plane or playing the planes of the image cube like a movie. The buttons are: \n",
        "\n",
        "![iv1](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/2c6505666e66f7864551526a4671489e0113c673.png?raw=1) - move to the first image plane\n",
        "\n",
        "![iv2](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/1664330a16c2db796b734e094af3ea123c7f28e0.png?raw=1) - move back one image plane\n",
        "\n",
        "![iv3](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/031fffc236c0d843392d428addac247288f0e11f.png?raw=1) - play image cube in reverse\n",
        "\n",
        "![iv4](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/b855a1ed3836bbd79eac65b341755ec44597e88d.png?raw=1) - stop playing the movie\n",
        "\n",
        "![iv5](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/9778c0eb8de97fd56c1d9be55c904c1f5cabc235.png?raw=1) - play image cube as a movie\n",
        "\n",
        "![iv6](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/41a79bc85908fd3d50836936c795b9577b4dd0b7.png?raw=1) - move forward one image plane\n",
        "\n",
        "![iv7](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/b0fa85965496a6f8fbfbc38fdec6046466f4bdc8.png?raw=1) - move to the last image plane\n",
        "\n",
        "In addition, to these controls for moving through the image cube, there are two other areas of animation control:\n",
        "\n",
        "![85424f67f54248c57c56336ea81bd66cf6fda3ac](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/85424f67f54248c57c56336ea81bd66cf6fda3ac.jpg?raw=1) - the rate indicates how how fast the movie should be played in terms of frames, and the second entry box (here with a zero) is for going to a particular plane of the image cube (enter a number and hit return) \\[Jump doesn\\'t seem to do anything\\]\n",
        "\n",
        "![9b03ad5ef24dbda549937b824a99bf4094af4343](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/9b03ad5ef24dbda549937b824a99bf4094af4343.jpg?raw=1) - the slider of this control allows for moving through the image cube as the slider is moved. The dialogs at the ends of the slider allows for setting the start and end points for the movie (which can be less than or equal to zero and the number of planes in the cube)\n",
        "  \n",
        "**Button Tools**\n",
        "\n",
        "These tools are designed for use with a three-button mouse. The row of boxes below the icon indicates which mouse button to which the tool is currently bound. For example, the last three icons in this table indicate that these tools are bound to the first, second, and third buttons respectively:\n",
        "\n",
        "![ea7304b3410f36a9dccb3226349b77a36d11a998](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/ea7304b3410f36a9dccb3226349b77a36d11a998.png?raw=1) - zoom: select this tool (by clicking on this icon and pressing one of the three buttons), then click and drag out a rectangle, then double click inside the rectangle to zoom in\n",
        "\n",
        "![ec32ba3d365abd638f28eab5223ff43191f45c76](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/ec32ba3d365abd638f28eab5223ff43191f45c76.png?raw=1) - panning: select this tool, then if the image is zoomed in, click and drag within the image to move the image\n",
        "\n",
        "![ff0fc891b68739126b6757a6f2711f3e298bf37c](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/ff0fc891b68739126b6757a6f2711f3e298bf37c.png?raw=1) - adjust color map: select this tool, then click and drag within the image to adjust the color map\n",
        "\n",
        "![30ae0891708bab0f984a47332160c32eb5a19c74](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/30ae0891708bab0f984a47332160c32eb5a19c74.png?raw=1) - contrast: select this tool, then click and drag within the image\n",
        "\n",
        "![fcdf48b33278a7339b429ba55d5ca04bb3200639](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/fcdf48b33278a7339b429ba55d5ca04bb3200639.png?raw=1) - point region: select this tool, then place a point on the image, the regions panel corresponding to the dot you placed will have statistics an information about the selected point\n",
        "\n",
        "![9f482145a9d4db935ea3ab16d49ee44d1641700c](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/9f482145a9d4db935ea3ab16d49ee44d1641700c.png?raw=1) - rectangular region: select this tool, then click and drag out a rectangle in the image and the regions panel corresponding to this region will have information about the rectangular region; double clicking in the region will display the statistics in to terminal window\n",
        "\n",
        "![41ce877a9905c5c1496a99b09183e2095fcca245](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/41ce877a9905c5c1496a99b09183e2095fcca245.png?raw=1) - eliptical region: select this tool, then click and drag out an ellipse, the regions panel corresponding to this region will have information about the eliptical region; double clicking in the region will display the statistics in the terminal window\n",
        "\n",
        "![954637995892613204657cc0f5b51c865f12a077](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/954637995892613204657cc0f5b51c865f12a077.png?raw=1) - polygon region: select this tool, then click multiple times within the image to mark out a region (one click at a time), double clicking when you have marked all of the points that denote the polygon, the regions panel corresponding to this region will have information about this region; double clicking in the region will display statistics for this region in the terminal window\n",
        "\n",
        "![fdc2fd7995dbfd26ce5939da376bdbe40e2caac4](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/fdc2fd7995dbfd26ce5939da376bdbe40e2caac4.png?raw=1) - polyline region: select this tool, then click multiple times within the image to mark out a multi-segment line, the region panel for this region will display statistics about the region\n",
        "\n",
        "![731bad1ac19871bd8ce249ad527d8dd85589763e](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/731bad1ac19871bd8ce249ad527d8dd85589763e.png?raw=1) - ruler: select this tool, click and drag in the image to get a display of distance along two axes\n",
        "\n",
        "![c19dae88d0d5f8fc261291f1d0c2df6344b4a35e](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/c19dae88d0d5f8fc261291f1d0c2df6344b4a35e.png?raw=1) - pv diagram: select this tool, click and drag within the image to create  a to be used to create a position/velocity diagram (the diagram is created from the region panel corresponding to the P/V line that you\\'ve drawn)\n",
        "\n",
        "These tools create regions that can be used to provide information about a portion of an image.\n",
        "\n",
        "**Regions**\n",
        "\n",
        "Regions are created with the region [Button Tools](#button-tools). For a region to be created, the Region panel (displayed on the left side of the Viewer Display Panel) must be open. If you do not see the Regions panel, it can be included in the Display Panel by selecting the Regions check box in the View menu:\n",
        "\n",
        "![4a9aebf37ad6a0a09105e2438ffd0ba508e4734f](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/4a9aebf37ad6a0a09105e2438ffd0ba508e4734f.jpg?raw=1)\n",
        "\n",
        "Once the Regions dialog is in view Regions can be created and information about the regions can be viewed. For example, here one region (black rectangle) has been created and region statistics is displayed:\n",
        "\n",
        "![f8acac9ee8c014d5338db58636ffffe4c8a181b0](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/f8acac9ee8c014d5338db58636ffffe4c8a181b0.jpg?raw=1)\n",
        "\n",
        "Note that in the statistics window, the brightness units are specified and the beam area is defined as the volume of the elliptical Gaussian $\\frac{Π}{4ln(2)} * FWHM_{major} * FWHM_{minor}$, where ln() is the natural logarithm and $FWHM_{major}$ and $FWHM_{minor}$ are the major and minor FWHM axes of the beam, respectively. The flux density is the mean intensity multiplied by the number of beams included in the selected region.\n",
        "\n",
        "**Region Statistics**\n",
        "\n",
        "If more than one region has been created, the scroll bar can be used to move from the information about one region to the next or the cursor (in the image panel) can be used to move from one region to the next and the region information will be updated as the cursor moves from region to region. Here are three regions, showing histograms for the regions:\n",
        "\n",
        "![cfc4f812ec08c5e86f6ffac0c67aabfc4c03d72a](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/cfc4f812ec08c5e86f6ffac0c67aabfc4c03d72a.jpg?raw=1)\n",
        "\n",
        "\n",
        "**Region Histogram**\n",
        "\n",
        "The region which corresponds to the histogram that is shown has the corner adjustment cubes drawn.\n",
        "\n",
        "Any regions that are created using these tools can be removed by moving the cursor over the region you would like to remove and once that region is highlighted press the escape key. Regions can also be deleted from the region panel that corresponds to the region you would like to remove.\n",
        "\n",
        "\n",
        "**Viewing a Raster Map**\n",
        "\n",
        "A raster map of an image shows pixel intensities in a two-dimensional cross-section of gridded data with colors selected from a colormap according to a scaling that can be specified by the user. Once loaded, the data display can be adjusted by the user through the Data Display Options panel, which appears when you choose the Data\\\\: Adjust Data Display menu or use the wrench icon from the Main Toolbar. The Data Display Options window is shown in the right panel of *Initial Viewer Panels*. It consists of a tab for each image or MS loaded, under which are a cascading series of expandable categories. For an image, these are:\n",
        "\n",
        "-   display axes\n",
        "-   hidden axes\n",
        "-   basic settings\n",
        "-   position tracking\n",
        "-   axis labels\n",
        "-   axis label properties\n",
        "-   beam ellipse\n",
        "-   color wedge\n",
        "\n",
        "The basic settings category is expanded by default. To expand a category to show its options, click on it with the left mouse button.\n",
        "\n",
        "\n",
        "*Data Display Options --- Display and Hidden Axes*\n",
        "\n",
        "In this category the physical axes (i.e. Right Ascension, Declination, Velocity, Stokes) to be displayed can be selected and assigned to the x, y, and z axes of the display. The z axis will be the axis scrolled across by the channel bar in the Animators Panel. If your image has a fourth axis (typically Stokes), then one of the axes will need to be hidden and not used in viewing. Which axis is hidden can be controlled by a slider within the hidden axes drop-down.\n",
        "\n",
        "\n",
        "*Data Display Options --- Basic Settings*\n",
        "\n",
        "This roll-up is open by default showing some commonly-used parameters that alter the way the image is displayed. The most frequently used of these changes how the intensity value of a pixel maps to a color on the screen.\n",
        "\n",
        "\n",
        "![d2baca80c73d185c1ca04583ccba36710108d3d5](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/d2baca80c73d185c1ca04583ccba36710108d3d5.png?raw=1)\n",
        "\n",
        "The options available are:\n",
        "\n",
        "-   basic settings: *aspect ratio*\n",
        "\n",
        "    - This option controls the horizontal-vertical size ratio of data pixels on screen. \\\"Fixed world\\\" (the default) means that the *aspect ratio* of the pixels is set according to the coordinate system of the image (i.e., true to the projected sky). \\\"Fixed lattice\\\" means that data pixels will always be square on the screen. Selecting \\\"flexible\\\" allows the map to stretch independently in each direction to fill as much of the display area as possible.\n",
        "\n",
        "-   basic settings: *pixel treatment*\n",
        "\n",
        "    - This option controls the precise alignment of the edge of the current \\\"zoom window\\\" with the data lattice. \\\"Edge\\\" (the default) means that whole data pixels are always drawn, even on the edges of the display. For most purposes, \\\"edge\\\" is recommended. \\\"center\\\" means that data pixels on the edge of the display are drawn only from their centers inwards.\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: A data pixel's center is considered its \"definitive\" position, and corresponds to a whole number in \"data pixel\" or \"lattice\" coordinates.\n",
        "</div>\n",
        "\n",
        "-   basic settings: *resampling mode*\n",
        "\n",
        "    - This setting controls how the data are resampled to the resolution of the screen. \\\"Nearest\\\" (the default) means that screen pixels are colored according to the intensity of the nearest data point, so that each data pixel is shown in a single color. \\\"Bilinear\\\" applies a bilinear interpolation between data pixels to produce smoother looking images when data pixels are large on the screen. \\\"Bicubic\\\" applies an even higher-order (and somewhat slower) interpolation.\n",
        "\n",
        "-   basic settings: *data range*\n",
        "\n",
        "    - You can use the entry box provided to set the minimum and maximum data values mapped to the available range of colors as a list \\[min, max\\]. For very high dynamic range images, you will probably want to enter a max less than the data maximum in order to see detail in lower brightness-level pixels.\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: By default you edit the scaling of a single image at once and can click between the tabs at the top of the Data Display Options window to manipulate different windows. By checking the Global Color Settings box at the bottom of this window, you will manipulate the scaling for all images at once. This can be very useful, for example, when attempting a detailed comparison between multiple reductions of the same data.\n",
        "</div>\n",
        "\n",
        "-   basic settings: *scaling power cycles*\n",
        "\n",
        "    - This option allows logarithmic scaling of data values to colormap cells, which can be very helpful in the case of very high dynamic range. The color for a data value is determined as follows:\n",
        "\n",
        "        1.  The value is clipped to lie within the data range \\[min, max\\] specified above.\n",
        "        2.  This clipped value is mapped to a new value depending on the selected scaling power cycles in the following way:\n",
        "            -   If the scaling power cycles is set to 0 (the default), the program considers a linear range from \\[min, max\\] and scales this directly onto the set of available colors.\n",
        "            -   For positive scaling values, the data value (after clipping on \\[min, max\\] is scaled linearly to lie between 0 and p (where p is the value chosen) and 10 is raised to this power, yielding a value in the range 1 to 10^p^. That value is scaled linearly to the set of available colors.\n",
        "            -   [For negative scaling values, the data value (after clipping on \\[min, max\\]) is scaled linearly to lie between 1 and 10^\\|p\\|^, where p is the power chosen. The base 10 logarithm is taken of this re-scaled data value, yielding a value in the range 0 to abs(p). That value is scaled linearly to the set of available colors. Thus the data is treated as if it had p decades of range, with an equal number of colors assigned to each decade.]\n",
        "        3.  The color corresponding to a number in final range is determined by the selected colormap and its \\\"fiddling\\\" (shift/slope) and brightness/contrast settings (see Mouse Toolbar, above). Adding a color wedge to your image can help clarify the effect of the various color controls.\n",
        "\n",
        "\n",
        "![71082fec54dd80acd580c40814ca9ad304ba7097](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/71082fec54dd80acd580c40814ca9ad304ba7097.png?raw=1)\n",
        "\n",
        "\n",
        "In practice, you will often manipulate the data range bringing the max down in high dynamic range images, raising the minimum to the near the noise level when using non-zero scaling cycles. It is also common to use negative power cycles when considering high dynamic range images --- this lets you bring out the faint features around the bright peaks.\n",
        "\n",
        "-   basic settings: *colormap*\n",
        "\n",
        "    - You can select from a variety of colormaps here. Hot Metal, Rainbow and Greyscale colormaps are the ones most commonly used.\n",
        "\n",
        "\n",
        "**Graphical Specification of the Intensity Scale**\n",
        "\n",
        "A histogram icon next to the Data Range entry in the Data Display Options window opens the Image Color Mapping window, which allows visualization and graphical manipulation of the mapping of intensity to color. The window at the left shows a histogram of the data with a gray range showing the data range. You can use this window to select the data range graphically (with the mouse), manually (by typing into the Min and Max entry windows), or as a percentile of the data. On the right, you can select the scaling power cycles and see a visualization of the transfer function mapping intensity (x-axis) to color (y-axis).\n",
        "\n",
        "The functionality here follows the other histogram tools, with the Display tab used to change the histogram plotting parameters. It will often be useful to use a logarithmic scaling of the y-axis and filled histograms when manipulating the color table.\n",
        "\n",
        "\n",
        "**Data Display Options --- Other Settings**\n",
        "\n",
        "Many of the other settings on the Data Display Options panel for raster images are self-explanatory such as those which affect beam ellipse drawing (only available if your image provides beam data), or the form of the axis labeling and position tracking information. You can also give your image a color wedge, a key to the current mapping from data values to colors.\n",
        "\n",
        "\n",
        "**Viewer Canvas Manager --- Panels, Margins, and Backgrounds**\n",
        "\n",
        "![bdbf6ab7cf4f4553813d0b9ef67c336d6ca7956d](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/bdbf6ab7cf4f4553813d0b9ef67c336d6ca7956d.png?raw=1)\n",
        "\n",
        "The display area can also be manipulated from the Viewer Canvas Manager window. Use the wrench icon with a \\\"P\\\" (or the \\\"Display Panel\\\" menu) to show this window, which allows you to manipulate the infrastructure of the main display panel. You can set:\n",
        "\n",
        "-   Margins - specify the spacing for the left, right, top, and bottom margins\n",
        "-   Number of panels - specify the number of panels in x and y and the spacing between those panels.\n",
        "-   Background Color - white or black (more choices to come)\n",
        "\n",
        "*Multi-Panel Display* illustrates a multi-panel display along with the Viewer Canvas Manager settings which created it.\n",
        "\n",
        "\n",
        "**Viewing a Contour Map**\n",
        "\n",
        "Viewing a contour image is similar to viewing a raster map. A contour map shows lines of equal data value for the selected plane of gridded data. Contour maps are particularly useful for overlaying on raster images so that two different measurements of the same part of the sky can be shown simultaneously.\n",
        "\n",
        "Several basic settings options control the contour levels used:\n",
        "\n",
        "-   The contours themselves are specified by a list in the box *Relative Contour Levels*. These are defined relative to the two other parameters:\n",
        "-   The *Base Contour Level* sets the zero level for the relative contour list corresponds to in units of intensity in the image.\n",
        "-   The *Unit Contour Level* sets what 1 in the relative contour list corresponds to in units of intensity in the image.\n",
        "\n",
        "Additionally, you have the option to manipulate the thickness and color of the image and to have either positive or negative contours appear dashed.\n",
        "\n",
        "![65b29709d5005d1f999a3482263d05da8effaea4](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/65b29709d5005d1f999a3482263d05da8effaea4.png?raw=1)\n",
        "\n",
        "\n",
        "For example, the following settings:\n",
        "\n",
        "```\n",
        "       Relative Contour Levels = [0.2, 0.4, 0.6, 0.8]\n",
        "       Base Contour Level = 0.0\n",
        "       Unit Contour Level = <image max>\n",
        "```\n",
        "\n",
        "would map the maximum of the image to 1 in the relative contour levels and the base contour level to zero. So the contours will show 20%, 40%, 60%, and 80% of the peak.\n",
        "\n",
        "Another approach is to set the unit contour to 1, so that the contours are given in intensity units (usually Jy/beam). So this setup:\n",
        "\n",
        "```\n",
        "       Relative Contour Levels = [0.010, 0.0.020, 0.040, 0.080, 0.160, 0.320]\n",
        "       Base Contour Level = 0.0\n",
        "       Unit Contour Level = 1.0\n",
        "```\n",
        "\n",
        "would create contours starting at 10 mJy/beam and doubling every contour.\n",
        "\n",
        "Another useful approach is to set contours in units of the rms noise level of the image, which can be worked out from a signal free region. Then a setup like this:\n",
        "\n",
        "```\n",
        "       Relative Contour Levels = [-3,3,5,10,15,20]\n",
        "       Base Contour Level = 0.0\n",
        "       Unit Contour Level = <image rms>\n",
        "```\n",
        "\n",
        "Would indicate significance of the features in the image. The first two contours show emission at ± 3-sigma and so on. You can get the image rms using the [imstat task](../api/casatasks.rst) or using the *Region Statistics* on a region of the image .\n",
        "\n",
        "Not all images are of intensity, for example a moment-1 image ([immoments task](../api/casatasks.rst)) has units of velocity. In this case, absolute contours (like the last two examples) will work fine, but by default the viewer will set fractional contours but refer to the min and max of the image:\n",
        "\n",
        "```\n",
        "       Relative Contour Levels = [0.2, 0.4, 0.6, 0.8]\n",
        "       Base Contour Level = <image min>\n",
        "       Unit Contour Level = <image max>\n",
        "```\n",
        "\n",
        "Here we have contours spaced evenly from min to max, and this is what you get by default if you load a non-intensity image (like the moment-1 image).\n",
        "\n",
        "\n",
        "**Overlay Contours on a Raster Map**\n",
        "\n",
        "Contours of either a second data set or the same data set can be used for comparison or to enhance visualization of the data. The Data Display Options Panel will have multiple tabs (switch between them at the top of the window) that allow you to adjust each overlay individually.\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: Axis labeling is controlled by the first-registered image overlay that has labeling turned on (whether raster or contour), so make label adjustments within that tab.\n",
        "</div>\n",
        "\n",
        "To add a Contour overlay, open the Load Data panel (Use the Data menu or click on the folder icon), select the data set and click on contour map.\n",
        "\n",
        "![f37c9cebb709797c6c3f7326d397cc7d38cb3038](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/f37c9cebb709797c6c3f7326d397cc7d38cb3038.png?raw=1)\n",
        "\n",
        "\n",
        "**Creating a Position/Velocity Diagram**\n",
        "\n",
        "With an image cube loaded, it is possible to create a position/velocity diagram using the P/V Button Tool. The first step in creating a P/V diagram is to select the tool with the mouse button to which you would like to bind the tool:\n",
        "\n",
        "![e33db1e64044bac99a712e5e56c84163c63b8a7c](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/e33db1e64044bac99a712e5e56c84163c63b8a7c.jpg?raw=1)\n",
        "\n",
        "Here we have bound the P/V button tool to the first mouse button. At this point, we can drag out a P/V line, by clicking and dragging on the image:\n",
        "\n",
        "![258d6b45ebcda4acc8293fb0be9714b062e5cb6d](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/258d6b45ebcda4acc8293fb0be9714b062e5cb6d.jpg?raw=1)\n",
        "\n",
        "\n",
        "After creating the P/V line, it will appear with two circles on each end. These circles can be used to adjust the line by clicking within the circle and dragging:\n",
        "\n",
        "![0b9e0d612e604fad380a7cc40a443547806e1d81](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/0b9e0d612e604fad380a7cc40a443547806e1d81.jpg?raw=1)\n",
        "\n",
        "After the P/V line is properly in place, the final P/V diagram can be created from the P/V Regions panel. It is just a matter of generating the P/V diagram with the Generate P/V button:\n",
        "\n",
        "![13f7ffec391f0f9340b6d1feb8b1c7889a12e69e](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/13f7ffec391f0f9340b6d1feb8b1c7889a12e69e.jpg?raw=1)\n",
        "\n",
        "The generation of the P/V diagram may take some time, but then the final diagram is displayed:\n",
        "\n",
        "![a66c61bd7ca3a4de494cacda916c4075803c6fa7](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/a66c61bd7ca3a4de494cacda916c4075803c6fa7.jpg?raw=1)\n",
        "\n",
        "\n",
        "\n",
        "***\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "gWxOO_fekunb"
      },
      "source": [
        ""
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "2-UnZQkpkunb"
      },
      "source": [
        "## Regions in the Viewer \n",
        "\n",
        "**Regions and the Region Manager**\n",
        "\n",
        "\n",
        "![b0a36b1085af0c104e3d638b0a2d23ee2a5b74d9](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/b0a36b1085af0c104e3d638b0a2d23ee2a5b74d9.png?raw=1)\n",
        "\n",
        "CASA regions are following the CASA \\'crtf\\' standard as described in § [D](https://casa.nrao.edu/docs/cookbook/casa_cookbook015.html#chapter%3Aregionformat). CASA regions can be used in all applications, including **tclean** and [Image Analysis Tasks](image_analysis.ipynb).\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE:** The CASA image analysis tasks will determine how a region is projected on a pixel image. The current CASA definition is that when the center of a pixel is inside the region, the full pixel is considered to be included in the region.  If the center of the pixel is outside the region, the full pixel will be excluded. Note that the CASA viewer behavior is not entirely consistent and for rectangles it assumes that *any* fractional pixel coverage will include the entire pixel. For other supported shapes (ellipses and polygons), however, ithe viewer adheres to the 'center of pixel' definition, consistent with the image analysis tools and tasks. \n",
        "\n",
        "For purely single-pixel work regions may not necessarily be the best choice and alternate methods may be preferable to using regions, eg. **ia.topixel**, **ia.toworld**, **ia.pixelvalue**.\n",
        "</div>\n",
        "\n",
        "<div class=\"alert alert-warning\">\n",
        "**ALERT:** Some region file specifications are not recognized by the viewer, the viewer only supports rectangles (box), ellipses, and polygons.\n",
        "</div>\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: A leading 'ann' (short for annotation) to a region definition indicates that it is for visual overlay purposes only.\n",
        "</div>\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: Whereas the region format is supported by all the data processing tasks, some aspects of the viewer implementation are still limited to rectangles, ellipses, and some markers. Full support for all region types is progressing with each CASA release.\n",
        "</div>\n",
        "\n",
        "Once one or more regions are created, the Region Manager Panel becomes active. Like the Position Tracking and Animator Panels, this can be docked or detached from the main viewer display. It contains several tabs that can be used to adjust, analyze, and save or load regions.\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: Moving the mouse into a region will bring it into focus for the Spectral Profile or Histogram tools.\n",
        "</div>\n",
        "\n",
        "\n",
        "**Region Creation, Selection, and Deletion**\n",
        "\n",
        "Within the display area, you can draw regions or select positions using the mouse. Regions can be created with the buttons marked as \\'R\\' in the mouse tool bar, which can be found on the top-left (second row of buttons) in the [Viewer Display Panel](image_visualization.ipynb#viewer-basics). The viewer currently supports creation of rectangles, ellipses, polygons, and the point. As usual, a mouse button can be assigned to each button as indicated by the small black square in each button (marking the left, middle, or right mouse button).\n",
        "\n",
        "Regions can be selected by SHIFT+click, de-selected by pressing SHIFT+click again. The bottom of the Region Manager Panel features a slider to switch between regions in the image. Regions can be removed by hovering over and pressing ESC or by pressing the buttons to the right side of the slider where the first button (trash can icon) deletes all regions and the far right button (red circle with a white X) deletes the region that is currently displayed in the panel.\n",
        "\n",
        "![9978959045808465057ed10e8fa21f4bbfeb7aa5](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/9978959045808465057ed10e8fa21f4bbfeb7aa5.png?raw=1)\n",
        "\n",
        "\n",
        "Once regions are selected, they will feature little, skeletal squares in the corners of their boundary boxes. Selected regions can be moved by dragging with the mouse button and manually resized by grabbing the corners as handles. If more than one region is selected, all selected regions move together.\n",
        "\n",
        "The Rectangle Region drawing tool currently enables the full functionality of the various Region Manager tabs (see below) as well as:\n",
        "\n",
        "-   Region statistics reporting for images via double clicking (also shown in the Statistics tab of the Region Manager),\n",
        "-   Defining a region to be averaged for the spectral profile tool (accessed via the Tools:Spectral Profile drop down menu or \\\"Open the Spectrum Profiler\\\" icon),\n",
        "-   Flagging of MeasurementSets. Note that the Rectangle Region tool's mouse button must also be double-clicked to confirm an MS flagging edit.\n",
        "-   Selecting Clean regions interactively (§ [5.3.5](https://casa.nrao.edu/docs/cookbook/casa_cookbook006.html#section%3Aim.clean.interactive))\n",
        "\n",
        "The Polygon Region and Ellipse Region drawing have the same uses, except that polygon region flagging of a MeasurementSet is not supported.\n",
        "\n",
        "\n",
        "**Region Positioning**\n",
        "\n",
        "\n",
        "![67074e8c42de2d0374c1c00629cdbaa989c3a1d3](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/67074e8c42de2d0374c1c00629cdbaa989c3a1d3.png?raw=1)\n",
        "\n",
        "\n",
        "With at least one region drawn, the Region Manager becomes active. Using the Properties tab, one can manually adjust the position, annotation, and display style of the region. The entries labeled \\\"frames\\\" set which planes of the image cube the region persists through (regions can have a depth associated with them and will only appear in the frames listed in this range). One can manually adjust the width and height and the center of the box in the chosen units. The \\'selected\\' check box is an alternative way to the SHIFT+click to select a region. The \\'annotation\\' checkbox will place the \\\"ann\\\" string in front of the region ASCII output -- annotation regions are not be used for processing in, e.g. data analysis tasks. In the line and text tabs, one can set the style with which the region is displayed, the associated text, and the position and style of that text.\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: Updating the position of a region will update the spectral profile shown if the Spectral Profile tool is open and the histogram if the Histogram tool is open. The views are linked. Dragging a region or adjusting it manually with the Properties tab is a good way to explore an image.\n",
        "</div>\n",
        "\n",
        "\n",
        "**Region Statistics**\n",
        "\n",
        "![31a405c0af27796c3ac3fdc1c87645e1d5649f5b](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/31a405c0af27796c3ac3fdc1c87645e1d5649f5b.png?raw=1)\n",
        "\n",
        "\n",
        "One of the most useful features of defining a region is the ability to extract statistics characterizing the intensity distribution inside the region. You can see these in the Statistics tab of the of the Region Manager Panel. This displays statistics for the current region in the current plane of the current image. When more than a single region is drawn, you can select them one by one and the Region Panel will update the statistics to reflect the currently selected region. All values are updated on the fly when the region is dragged across the image.\n",
        "\n",
        "A similar functionality can be achieved by double clicking inside of a region. This will send statistics information for this region in all registered images to the terminal, looking something like this:\n",
        "\n",
        "```\n",
        "(IRC10216.36GHzcont.image) image\n",
        "          Stokes         Velocity            Frame          Doppler        Frequency\n",
        "               I -2.99447e+11km/s             LSRK            RADIO      3.63499e+10\n",
        "  BrightnessUnit         BeamArea             Npts              Sum             Flux\n",
        "         Jy/beam          36.2521            27547     1.087686e-01     3.000336e-03\n",
        "            Mean              Rms          Std dev          Minimum          Maximum\n",
        "    3.948473e-06     3.723835e-04     3.723693e-04    -1.045624e-03     9.968892e-03\n",
        "```\n",
        "\n",
        "Listed parameters are Stokes, and the displayed channel Velocity with the associated Frame, Doppler and Frequency value. Sum, Mean, Rms, Std Deviation, Minimum, and Maximum value refer to those in the selected region and has the units as specified in BrightnessUnit. Npts is the number of pixels in the region, and BeamArea the beam size in pixels. FluxDensity is in Jy if the image is in Jy/beam. This is an easy way to copy and paste the statistical data to a program outside of CASA for further use.\n",
        "\n",
        "Taking the RMS of the signal-free portion of an image or cube is a good way to estimate the noise. Contrasting this number with the maximum of the image gives an estimate of the dynamic range of the image. The FluxDensity measurement gives a way to use the viewer to do very basic photometry.\n",
        "\n",
        "\n",
        "**Saving and Loading Regions**\n",
        "\n",
        "![f9d2972c79da5e3b12e60dc426b81baace780aae](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/f9d2972c79da5e3b12e60dc426b81baace780aae.png?raw=1)\n",
        "\n",
        "The File tab in the Region Manager allows one to save or load selected regions, either individually or en masse. You can choose between CASA and DS9 region format. The default is a CASA region file (saved with a \\'.crtf\\' suffix, see § [D](https://casa.nrao.edu/docs/cookbook/casa_cookbook015.html#chapter%3Aregionformat)). The DS9 format does not offer the full flexibility and cannot capture Stokes and spectral axes. DS9 regions will only be usable as annotations in the viewer, they cannot be used for data processing in other CASA tasks. When saving regions, one can choose to save only the current region, all regions that were selected with SHIFT+click, or all regions that are visible on the screen.\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: The load functionality for this tab will only become available once at least one region exists. To load a region when no regions exist, use the *Region Manager* window.\n",
        "</div>\n",
        "\n",
        "\n",
        "**The Region Fit**\n",
        "\n",
        "The Viewer can attempt to fit a two-dimensional Gaussian to the emission distribution inside the currently selected region. To attempt the fit, go to the Fit tab of the Region Manager and click the \\'gaussfit\\' button in the bottom left of the panel. You can choose whether or not to fit a sky level (e.g., to account for a finite background, either astronomical, sky, or instrumental). After fitting the distribution, the Fit panel shows the results of the fit, the center, major and minor axis, and position angle of the Gaussian fit in pixels (I) and in world coordinates (W, RA and Dec). The detailed results of the fit will also appear in the terminal window, including a flag showing whether the fit converged.\n",
        "\n",
        "\n",
        "**The Region Histogram**\n",
        "\n",
        "![71a8870c7e27d8e4226ab388d473c1f3cba13373](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/71a8870c7e27d8e4226ab388d473c1f3cba13373.png?raw=1)\n",
        "\n",
        "> Histogram Tab: The histogram tab in the Region Manager. Right click to zoom. Hit SHIFT + Right Click to adjust the details of the histogram display.\n",
        "\n",
        "The viewer will automatically derive a histogram of the pixel values inside the selected region. This can be viewed using the Histogram tab of the of the Region Manager Panel. This is a pared down version of the full Histogram Tool. You can manipulate the details of the histogram plot by:\n",
        "\n",
        "1.  Using the Right Click to zoom - either to the full range, a selected percentile, or a range that you have graphically selected by dragging the mouse.\n",
        "2.  Hitting SHIFT + Right Click to open the histogram options. This lets you toggle between a logarithmic and linear y-axis, choose between a line, outline, or filled histogram, and adjust the number of bins.\n",
        "\n",
        "The histogram will update as you change the plane of the cube or shift between regions.\n",
        "\n",
        "***\n",
        "\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "lsy6bHjzkunc"
      },
      "source": [
        "## Spectral Profiler \n",
        "\n",
        "![f460a73178b5a78ab57f1664858a899137979ef2](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/f460a73178b5a78ab57f1664858a899137979ef2.png?raw=1)\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: Make Sure That You Use the Radio Version! This section describes the 'Radio' version of the profiler. To be sure that you have the radio version of the tool selected (this may not be the default), click on the preferences icon (the 'gear' fourth from the left in the Spectral Profile tool) and make sure that the 'Optical' option is not checked. If you are using the Spectral Profile tool in the viewer for the very first time, you will also be prompted for a selection that will subsequently be kept for all future calls unless the preference is changed.\n",
        "</div>\n",
        "\n",
        "The Spectral Profile Tool consists of the *Spectral Profile Toolbar*, a main display area, and two associated tabs: *Spectral-Line Fitting* and *Line Overlays*.\n",
        "\n",
        "Interaction With the Main Display Panel: For the Spectral Profile tool to work, a region or point must be specified in the main Viewer Display window. Use the mouse tools to specify a point, rectangle, ellipse, or polygon region. Alternatively, load a region file. The Spectral Profile tool will show a spectrum extracted from the region most recently highlight by the mouse in the main Viewer Display Panel. The method of extraction (i.e. mean, median, sum, or flux density) can be specified by the user using a drop down menu below the spectrum in the Spectral Profile window; the method of extraction is mean by default.\n",
        "\n",
        "The Spectral Profile tool can also feed back to the Main Display Panel. By holding CTRL and right clicking in the spectrum, you will cause the Main Display Panel to jump to display the frequency channel corresponding to the spectral (x) coordinate of the region highlighted in the Spectral Profile tool. Holding CTRL and dragging out a spectral range while holding the right mouse button will queue a movie scrolling through images across that spectral range. You can achieve the same effect with the two-ended-arrow icon towards the right of the toolbar in the Spectral Profile window.\n",
        "\n",
        "In both the *Spectral-Line Fitting* and *Line Overlays* tabs, it may be useful to select a range in frequency or velocity. You can do this with the parallel lines-and-arrow icon (see below) or by holding shift, left clicking, and dragging out the range of interest. A shaded gray region should appear indicating your selection.\n",
        "\n",
        "\n",
        "**Spectral Profile Toolbar**\n",
        "\n",
        "![b70f90030cd7ed87f57699da695279ded944c906](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/b70f90030cd7ed87f57699da695279ded944c906.png?raw=1)\n",
        "\n",
        ">Spectral Profile Toolbar: The toolbar for the Spectral Profile tool allows the user to save the spectrum, print or save the tool as an image, edit preferences (general, tool, legend), apply spectral smoothing, pan or zoom around the spectrum, select a range of interest, jump to a channel, or add a label.\n",
        "\n",
        "\n",
        "The *Spectral Profile Toolbar* is the toolbar along the top of the Spectral Profile window. From left to right, the icons allow the user to:\n",
        "\n",
        "-   (disk) export the current profile to a FITS or ASCII file\n",
        "-   (printer) print the main window to a hard copy\n",
        "-   (writing desk) save the panel as an image (PNG, JPG, PDF, etc.)\n",
        "-   (gear) set plot preferences\n",
        "-   (color wheel) set color preferences for the plot\n",
        "-   (signpost) set legend preferences\n",
        "-   (triangle) set the spectral smoothing method and kernel width\n",
        "-   (arrows) pan the spectrum in the indicated direction NOTE: The arrow keys also allow one to pan using the keyboard.\n",
        "-   (magnifying glass) zoom to the default zoom, in, and out NOTE: the +/- keys allow one to zoom with the keyboard\n",
        "-   (parallel lines+arrows) drag out a range of interest in the spectrum, for use with fitting or line overlays.\n",
        "-   (double-ended arrow) jump to a channel in the main viewer (single click) or define a range over which to play a movie in the viewer (with a drag).\n",
        "    \n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: You can also jump to a channel with CTRL+Right Click and queue a movie by holding CTRL and dragging out a range while holding the right mouse button.\n",
        "</div>\n",
        "\n",
        "-   (notepad and pencil) Add or edit a label on the plot. Click this icon to enter a mode where you can drag out a box to create a new annotation box or drag the corners of an existing one to resize it. You can edit the contents, color, and font of an existing annotation by right clicking on it and selecting \\\"Edit Annotation\\\" in the main Spectral Profile window.\n",
        "\n",
        "![3298dfa9eac7bb5c2b721bf9ea8613f647cb6b4c](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/3298dfa9eac7bb5c2b721bf9ea8613f647cb6b4c.png?raw=1)\n",
        "\n",
        "*Spectral Profile Tool Preferences* shows the setting dialogs accessible from the toolbar. This Preferences dialog opened by the \\'gear\\' icon allows the user to:\n",
        "\n",
        "-   Toggle automatic scaling the x- and y-ranges of the plot.\n",
        "-   Toggle the coordinate grid overlay in the background of the plot.\n",
        "-   Toggle whether registered images other than the current one appear as overlays on the plot.\n",
        "-   Toggle whether these profiles are plotted relative to the main profile (in development).\n",
        "-   Toggle the display of tooltips (in development).\n",
        "-   Toggle the plotting of a top axis.\n",
        "-   Toggle between a histogram and simple line style for the plot.\n",
        "-   Toggle between the radio and optical versions of the Spectral Profile tool Note: We discuss only the radio version here; this mainly impacts the Spectral Line Fitting and Collapse/Moments functionality..\n",
        "-   Toggle the overplotting of a line showing the channel currently being displayed in the main Display Panel.\n",
        "\n",
        "The Color Curve Preferences dialog opened by the \\'color wheel\\' icon allows the user to:\n",
        "\n",
        "-   Select the color of the line marking the current channel shown in the main Display Panel.\n",
        "-   Select the color used to overlay molecular lines from Splatalogue.\n",
        "-   Select the color to plot the initial Gaussian estimate used in spectral line fitting.\n",
        "-   Select the color used for the zoom rectangle.\n",
        "-   Set a queue of colors used to plot the various data sets registered in the Display Panel.\n",
        "-   Set a queue of colors to plot the set of Gaussian fits.\n",
        "-   Set a queue of colors to plot the synthesized curve.\n",
        "\n",
        "Two sets of preset colors, \\\"Traditional\\\" or \\\"Alternative\\\", are available or the user can define their own custom color palette.\n",
        "\n",
        "The legend options opened by the \\'signpost\\' icon allow the user to toggle the plotting of a legend defining the curves shown in the main Spectral Profile window. Using a drop-down dialog, the legend can be placed in the top left corner of the plot, to the right of the plot, or below the plot. Toggling the color bar causes the color of the curve to be indicated either via a short bar or using the color of the text itself. Double click the names of the files or curves to edit the text shown for that curve by hand. A legend is only available if more than a single spectrum has been loaded.\n",
        "\n",
        "The spectral smoothing option (triangle icon in the Spectral Profile toolbar) has two methods, \\\"Boxcar\\\" and \\\"Hanning\\\" with the selection of odd numbers for the smoothing kernel width in channels.\n",
        "\n",
        "\n",
        "**Main Spectral Profile Window**\n",
        "\n",
        "![b3606599a0ccbeb166c8d7fc12e6fd80a8c7a3ed](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/b3606599a0ccbeb166c8d7fc12e6fd80a8c7a3ed.png?raw=1)\n",
        "\n",
        "The main window shows the spectrum extracted from the active region of the image in the main Display Panel. The spectra from the same region in any other registered images are also plotted if overlays are enabled. Menus along the bottom of the image allow the user to select how the spectrum is displayed. From left to right:\n",
        "\n",
        "-   The units for the bottom spectral axis.\n",
        "-   The units for the top spectral axis.\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: Dual axes are enabled only if a single image is registered and the top axis option is enabled. In general, dual axes are not well-defined for mixed data sets. The exception is that open data cubes with matched frequency/spectral axes will allow dual axes.\n",
        "</div>\n",
        "\n",
        "-   The units for the left intensity or flux axis\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: The \"Fraction of Peak\" option allows for easy comparison of data with disparate intensity scales.\n",
        "</div>\n",
        "\n",
        "-   The velocity reference frame used if a velocity axis is chosen for the top or bottom axis.\n",
        "-   The method used to extract spectrum from the region --- a mean over all pixels in the region, a median, sum, or a sum converting units to get a flux density over the region (Jy).\n",
        "-   Toggle the calculation and overplotting of error bars calculated from scatter in the data (rmse refers to root mean square error).\n",
        "\n",
        "In addition to these drop-down menus, the main Spectral Profile window allows the user to do the following using keyboard and mouse inputs:\n",
        "\n",
        "-   jump the main Display Panel window to a specified channel (CTRL+Right click): hold CTRL and right click in the spectrum. A marker will appear and the main Viewer Display Panel will jump to display that channel.\n",
        "-   animate the main Display Panel in a movie across a frequency range (CTRL+Right click+drag): hold CTRL, Right click, and drag. The main Viewer Display panel will respond by showing a movie scrolling across the selected spectral channels.\n",
        "-   zoom the Spectral Profile (+/-, mouse drag): Use the +/- keys to zoom in the same way as the toolbar buttons. Alternatively, press and drag the left mouse button. A yellow box is drawn onto the panel. After releasing the mouse button, the plot will zoom to the selected range.\n",
        "-   pan the Spectral Profile (arrows): Use the arrow keys to pan the plot.\n",
        "-   select a spectral range for analysis: hold shift, left click, and drag. A gray area will be swept out in the display. This method can be used to select a range for spectral line fitting or collapsing a data cube (in the Collapse/Moments window).\n",
        "\n",
        "**NOTE**: If the mouse input to the Spectral Profile browser becomes confused hit the ESC key several times and it will reset.\n",
        "\n",
        "\n",
        "**Spectral-Line Fitting**\n",
        "\n",
        "![c29793490bd0d5d69c32f5485bc256ff586fd2ab](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/c29793490bd0d5d69c32f5485bc256ff586fd2ab.png?raw=1)\n",
        "\n",
        ">Spectral Line Fitting Tab: Using the Spectral Line Fitting Tab (found at the bottom left of the Spectral Profile Tool), the user can fit a combination of a polynomial and multiple Gaussian components. The range to be fit can be specified (gray region) manually or with a shift+click+drag. Initial estimates for each component may be entered by hand or specified via an initial estimates GUI. The results are output to a dialog and text file with the fit overplotted (here in blue) on the spectrum (with the possibility to save it to disk).\n",
        "\n",
        "\n",
        "![c648346d0ff0181b8a8984116c5357abdaed3bdf](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/c648346d0ff0181b8a8984116c5357abdaed3bdf.png?raw=1)\n",
        "\n",
        ">Specifying Initial Gaussian Estimates Graphically and Fitting Output: The top panel shows the graphical specification of initial estimates for Gaussian fitting. Slider bars specify the center, FWHM, and peak intensity for the initial estimate. The bottom panel shows the verbose output of the fitting.\n",
        "\n",
        "\n",
        "The Spectral-Line Fitting tab allows the user to interactively fit a combination of Gaussian and polynomial profiles to the data shown in the Spectral Line Profile tool. The tool includes a number of options:\n",
        "\n",
        "-   A drag-down menu labeled \\\"Curve\\\" at the top of the panel allows the user to pick which data set to fit.\n",
        "-   The spectral range to fit can be specified by either holding shift+left click+dragging out a region in the main spectral profile window or by typing it manually into the boxes labeled Min and Max near the top left of the fitting panel.\n",
        "-   Optionally multiple fits can be carried out once, fitting each spectrum in the region in turn. To enable this, check the \\'MultiFit\\' box.\n",
        "-   Optionally a polynomial of the specified order may be fit. To do so, check the \\'Polynomial\\' fit check box and then specify the desired order.\n",
        "-   The results may be saved to a text file. This text file should be specified before the fit is carried out. Click \\'Save\\' and then use the dialog to specify the file name. Note that the fit curve itself becomes a normal spectral profile data set and can be saved to disk using the toolbar (\\'disk\\' icon) after the fit.\n",
        "-   One or more Gaussians can be fit, although results are presently most stable for one Gaussian. Specify the number of Gaussians in the box marked \\\"Gaussian Count\\\" and then enter initial estimates for the peak, center, and FWHM in the table below. Any of these values can be fixed for any of the Gaussians being fit. Initial estimates can also be manually specified by clicking \\\"Estimates\\\". This brings up an additional GUI window, where sliders can be used to specify initial estimates for each Gaussian to be fit.\n",
        "-   For plotting purposes, one may wish to oversample the fit (i.e., plot a smooth Gaussian), you can do so by increasing the Fit Samples/Channel to a high number to finely sample the fit when plotting.\n",
        "\n",
        "**NOTE**: Currently the tool works well for specifying a single Gaussian. Fitting multiple Gaussian components can become unstable.\n",
        "\n",
        "\n",
        "**Line Overlays**\n",
        "\n",
        "![4d513d4c6000fd2ea90d88b9a7b01d057d90114f](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/4d513d4c6000fd2ea90d88b9a7b01d057d90114f.png?raw=1)\n",
        "\n",
        ">Line Overlays Tab: The Line Overlay tab (found at the bottom left of the Spectral Profile Tool) allows users to query the CASA copy of the Splatalogue spectral line database. Enter the redshift of your source (far right of the panel), select an Astronomical Filter from the drop down menu, and use shift+click+drag to select a frequency range (or enter the range manually in the boxes marked Min and Max). The \\\"Search\\\" button will bring up a separate \\\"Search Results\\\" window, which can in turn be used to graph the candidate lines in the main Spectral Profile window (here CO v=0).\n",
        "\n",
        "\n",
        "Each version of CASA includes a local version of the [Splatalogue](http://www.splatalogue.net) spectral line database and this can be used to identify and overplot spectral transitions. This feature, shown in *Line Overlay Tab*, allows the user to search Splatalogue over the range of interest.\n",
        "\n",
        "To overlay spectral lines:\n",
        "\n",
        "1.  Select the Line Overlays tab in the Spectral Profiles tab.\n",
        "2.  If you know it, enter the redshift or velocity of your source in the \\\"Doppler Shift\\\" panel. Otherwise, the lines will be overlaid assuming a redshift of 0.\n",
        "3.  Specify a minimum and maximum frequency range to search, either by typing a range or by holding shift and left click and dragging out a range in the spectrum (you will see a gray box appear). If you don't specify a range, the tool will search over the frequency range of spectrum.\n",
        "4.  Optionally, you may select an astronomical filter from the list (e.g., commonly used extragalactic lines or lines often found in hot cores, see [Splatalogue](http://www.splatalogue.net) for more information). This is usually a good idea because it pares the potentially very large list of candidate lines to a smaller set of reasonable candidates.\n",
        "5.  Click \\'Search\\' and the Spectral Profile will search Splatalogue for a list of Spectral lines that fit the selected Astronomical Filter in the selected frequency range for the selected redshift. A \\\"Molecular Line Search Results\\\" dialog box will pop up showing the list of candidate lines.\n",
        "6.  Highlight one or more of these transitions and click \\'Graph Selected Lines\\'. A set of vertical markers will appear in the main Spectral Profile window at the appropriate (redshifted) frequencies for the line.\n",
        "\n",
        "NOTE: You will want to click \\'Clear Lines\\' between searches, especially if you update the redshift.\n",
        "\n",
        "\n",
        "**The Collapse/Moments Tool**\n",
        "\n",
        "\n",
        "![df2fa469ffe23c7fb70cba20c7821a5dfd3da869](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/df2fa469ffe23c7fb70cba20c7821a5dfd3da869.png?raw=1)\n",
        "\n",
        "\n",
        "The CASA Viewer (**imview**) can collapse a data cube into an image, for instance allowing to look at the emission integrated along the z axis or the mean velocity of emission along the line of sight. You can access this functionality via the Collapse/Moments tool (accessed via the Tools drop down menu in the Main Display planel or via the four inward pointing arrows icon in the Main Toolbar) which is shown in *Collapse/Moments Tool*.\n",
        "\n",
        "The tool uses the same format as the Spectral Profile tool and will show the integrated spectrum of whatever region or point is currently selected in the Main Display Panel. To create a moment map:\n",
        "\n",
        "1.  Select a range over which to integrate either manually using the left part of the window, by adding an interval and typing in the values into the boxes marked Min and Max or by holding SHIFT + Left Click and dragging out the range of interest.\n",
        "2.  Pick the set of algorithms (listed in the box labeled \\\"Moment(s)\\\") that you will use to collapse the image along the z-axis. Clicking an option toggles that moment method, and the collapse will create a new image for each selected moment. For details on the individual collapse method, see the [immoments](../api/casatasks.rst) task for more details on each moment.\n",
        "3.  The moment may optionally include or exclude pixels within a certain range (for example, you might include only values with signal-to-noise of three or greater when calculating the velocity dispersion). You can enter the values to include or exclude manually in the Thresholding window on the right or you can open a histogram tool to specify this range graphically by clicking Specify Graphically (before this can work, you must click \\'Include\\' or \\'Exclude\\').\n",
        "4.  The results of the collapse can be saved to a file, which consists of a string specifying the specific moment tacked onto a root file name that you can specify using Select Root Output File.\n",
        "5.  When you are satisfied with your chosen options, press \\'Collapse\\'.\n",
        "\n",
        "**NOTE**: Even if you don't save the results of the collapse to a file, you can still save the map later using the Save as\\... entry in the Data pull down menu from the Main Viewer Display Panel.\n",
        "\n",
        "\n",
        "**Interactive Position-Velocity Diagram Creation**\n",
        "\n",
        "![54c3e56ee2d8faacb841aa44931c419e06cf357e](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/54c3e56ee2d8faacb841aa44931c419e06cf357e.png?raw=1)\n",
        "\n",
        "\n",
        "The route to create position-velocity cuts in the viewer is illustrated in *Position/Velocity Tool*:\n",
        "\n",
        "1.  Select the \\'P/V cut\\' tool from the Mouse Toolbar and use it to draw a line across a data cube along the axis you want to visualize.\n",
        "2.  Open the Region Manager Panel and go to the pV tab. Highlight the cut you just drew. You should see the end point coordinates listed, along with information on the length and position angle of the cut. You can set the averaging width (in pixels) in a window at the bottom of the tab.\n",
        "3.  When you are satisfied, hit \\'Generate P/V\\'. This will create a new Main Viewer Display Panel showing the position velocity cut. The axes should be Offset and velocity.\n",
        "\n",
        "The new image can be saved to disk with the Data\\\\:Save as\\... option.\n",
        "\n",
        "\n",
        "***\n",
        "\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "2nMaIr4ykunc"
      },
      "source": [
        "## Image Analysis in the Viewer (imview) \n",
        "\n",
        "Analysis Tools that are available in the Viewer (task **imview**).\n",
        "\n",
        "**The Brightness Profile Tool**\n",
        "\n",
        "The viewer allows the user to draw multiple line segments using the \\\"Polyline drawing\\\" button, and this feature can be used to display one-dimensional brightness profiles of images, such as shown in the *Spatial Profile Tool*. After double-clicking the last line segment, the \\'Regions\\' dock will then display a preview of the slice in the Spatial Profile tab and the full \\\"Spatial Profile Tool\\\" can be launched from there by clicking the \\\"Spatial Profile Tool\\\" button. This \\\"Spatial Profile Tool\\\" panel allows one to select the interpolation method to connect the pixels, and a number count for the sampled pixels in between markers. \\'Automatic\\' will show all pixels. The x-axis of the display can be either the distance along the slice or the X and Y coordinate projections (e.g. along RA and DEC). All segments are also listed at the bottom with their start and end coordinates, the distance and the position angles of each slice segment. The color tool can be used to give each segment a separate color.\n",
        "\n",
        "![247c9434dc6e7bfcd4508140a7efbe0653671d1d](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/247c9434dc6e7bfcd4508140a7efbe0653671d1d.png?raw=1)\n",
        "\n",
        "\n",
        "**The Histogram Tool**\n",
        "\n",
        "![4bd76aea63562362de82fe6ddeeede1ce551317d](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/4bd76aea63562362de82fe6ddeeede1ce551317d.png?raw=1)\n",
        "\n",
        "CASA can calculate and visualize a histogram of pixel values inside a region of interest. To examine this histogram, select Histogram from the Tools drop-down menu or the \\'Histogram\\' icon in the Main Toolbar (looks like a comb). This opens the full Histogram Tool; more limited versions are accessible from the Region Manager Panel, the graphical color table manipulation tool, and the Collapse/Moments tool.\n",
        "\n",
        "The resulting Histogram Tool should look something like *Histogram Tool*. The menus along the top (or the corresponding mouse clicks) allow one to:\n",
        "\n",
        "-   Zoom to the full range, a selected percentile, or a graphical range.\n",
        "-   Change the display of the histogram to show a log axis, display as either a line plot, an outline, or a filled histogram. Change the number of bins in the histogram, or clear the plot (to start over).\n",
        "-   Configure what data are fed into the histogram. You can use this menu to tell the histogram to track the channel currently selected in the main Viewer Display Panel (click the \\\"Track Channel\\\" box) or to integrate across some range of channels (defaulting to the whole image). You can also switch the 2-D footprint used between the whole Image, the Selected Region, and All Regions.\n",
        "-   Save (via the disk icon) an image of the histogram to a graphical file on disk.\n",
        "\n",
        "The Histogram Tool also allows you to fit the distribution using either a Gaussian or a Poisson distribution, for example to estimate the noise in the image (a Gaussian will be a good choice to describe the noise in most radio data cubes). You can specify initial estimates or let the program generate initial guesses. The fit is then overplotted on the histogram (colors can be adjusted by clicking the color wheel icon in the toolbar) and details of the fit are printed to the text window below the fit button.\n",
        "\n",
        "\n",
        "**The Two-Dimensional Fitting Tool**\n",
        "\n",
        "![df2fff474cbd464f25d5e9bb87cd7107f61a5b87](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/df2fff474cbd464f25d5e9bb87cd7107f61a5b87.png?raw=1)\n",
        "\n",
        "\n",
        "CASA can fit two-dimensional Gaussians to an intensity distribution, and the Two-Dimensional Fitting Tool in the Viewer exposes this functionality interactively. This tool, accessed by the \\'blue circles\\' icon in the Main Toolbar or the Tools:Fit menu item, has an interface like that shown in *Two-Dimensional Fitting Tool*. The interface exposes several options:\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: The two dimensional fitter only operates on a single channel at a time.\n",
        "</div>\n",
        "\n",
        "1.  You can select whether to fit only the selected region or the whole image plane and specify which channel of the cube you want to operate on.\n",
        "2.  Initial Estimates: The box in the top left corner allows the user to specify initial estimates by feeding in a file. The easiest way to make an appropriate file is to edit an existing one. Even easier, you can use the Find Sources button to automatically generate a temporary file of initial estimates.\n",
        "3.  Pixel Range: You can choose to only include a certain range of pixel intensity values in the fit. For example, you might choose to only fit Gaussians to pixels a few times above the measured noise level. You can use the Specify Graphically button to bring up an interactive histogram of the region (a reduced functionality version of the full Histogram Tool).\n",
        "4.  Output: You can choose to save the output of the fit as a file to the specified directory and to subtract the fit from the image and to subtract the fit from the original, creating a Residual Image that gets stored as a CASA image and automatically loaded into the viewer. This gives a way to tell how well your fit describes the total emission.\n",
        "5.  Visualization: You can toggle whether the fit is displayed on the viewer or not and change the color of the marker.\n",
        "\n",
        "Click Fit to start the fit. If the fit does not converge, try improving your initial estimates and fitting again.\n",
        "\n",
        "\n",
        "***\n",
        "\n",
        "\n",
        "\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "L-JRi8Vxkunc"
      },
      "source": [
        "## Printing from the Viewer \n",
        "\n",
        "You can select Data\\\\:Print from the drop down menu or click the printer icon in the Main Toolbar to bring up the Viewer Print Manager. From this panel, you can \\\"Print\\\" the contents of Display Panel to a hardcopy or \\\"Save\\\" them as an image in a format selected from the drop-down menu at the bottom left of the window.\n",
        "\n",
        "<div class=\"alert alert-info\">\n",
        "**NOTE**: The save feature will overwrite the file in question without prompting.\n",
        "</div>\n",
        "\n",
        "The Viewer Print Manager allows you to adjust the DPI, orientation, and page format (Output Media) for Postscript or PDF files and to scale the image to a desired pixel size for other images.\n",
        "\n",
        "To achieve the best output it is usually advisable to adjust the settings in the Viewer Print Manager (printer icon in the Main Toolbar), Data Display Options (Data\\\\:Adjust Data Display), and Viewer Canvas Manager (wrench+\\\"P\\\" icon in the Main Toolbar). For PDF and Postscript output, turning the DPI up all the way yields the best-looking results. For other images, a white background often makes for better looking images than the default black. It is often necessary to increase the Line Width in the Axis Label Properties (in the Data Display Options panel) to ensure that the labels will be visible when printed. Increasing from the default of 1.4 to a value around 2 often works well.\n",
        "\n",
        "The following figure shows an example of printing to a file while adjusting the Data Display Options and Viewer Canvas Manager to improve the appearance of the plot.\n",
        "\n",
        "![173061d000f561f265692b5ea0e5a2cfa7345bfe](https://github.com/casangi/casadocs/blob/master/docs/notebooks/media/173061d000f561f265692b5ea0e5a2cfa7345bfe.png?raw=1)\n",
        "\n",
        "\n",
        "***\n",
        "\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Bn5yvX1Okund"
      },
      "source": [
        "## Scripting using imview \n",
        "\n",
        "\n",
        "The **imview** task offers scriptable access to many **viewer** options. This enables the production of customized plots without invoking the GUI and allows one to open the **viewer** to a carefully selected state.\n",
        "\n",
        "**imview** has the following inputs:\n",
        "\n",
        "```\n",
        "#imview :: View an image\n",
        "raster      =    {}     #(Optional) Raster filename (string)\n",
        "                        #or complete raster config\n",
        "                        #dictionary. The allowed dictionary\n",
        "                        #keys are file (string), scaling\n",
        "                        #(numeric), range (2 element numeric\n",
        "                        #vector), colormap (string), and\n",
        "                        #colorwedge (bool).\n",
        "contour     =    {}     #(Optional) Contour filename (string)\n",
        "                        #or complete contour config\n",
        "                        #dictionary. The allowed dictionary\n",
        "                        #keys are file (string), levels\n",
        "                        #(numeric vector), unit (float), and\n",
        "                        #base (float).\n",
        "zoom        =    1      #(Optional) zoom can specify\n",
        "                        #intermental zoom (integer), zoom\n",
        "                        #region read from a file (string) or\n",
        "                        #dictionary specifying the zoom\n",
        "                        #region. The dictionary can have two\n",
        "                        #forms. It can be either a simple\n",
        "                        #region specified with blc (2 element\n",
        "                        #vector) and trc (2 element vector)\n",
        "                        #[along with an optional coord key\n",
        "                        #(\"pixel\" or \"world\"; pixel is the\n",
        "                        #default) or a complete region\n",
        "                        #rectangle e.g. loaded with\n",
        "                        #\"rg.fromfiletorecord( )\". The\n",
        "                        #dictionary can also contain a\n",
        "                        #channel (integer) field which\n",
        "                        #indicates which channel should be\n",
        "                        #displayed.\n",
        "axes        =    -1     #(Optional) this can either be a\n",
        "                        #three element vector (string) where\n",
        "                        #each element describes what should\n",
        "                        #be found on each of the x, y, and z\n",
        "                        #axes or a dictionary containing\n",
        "                        #fields \"x\", \"y\" and \"z\" (string).\n",
        "out         =    {}     #(Optional) Output filename or\n",
        "                        #complete output config dictionary.\n",
        "                        #If a string is passed, the file\n",
        "                        #extension is used to determine the\n",
        "                        #output type (jpg, pdf, eps, ps, png,\n",
        "                        #xbm, xpm, or ppm). If a dictionary\n",
        "                        #is passed, it can contain the\n",
        "                        #fields, file (string), scale\n",
        "                        #(float), dpi (int), or orient\n",
        "                        #(landscape or portrait). The scale\n",
        "                        #field is used for the bitmap formats\n",
        "                        #(i.e. not ps or pdf) and the dpi\n",
        "                        #parameter is used for scalable\n",
        "                        #formats (pdf or ps).\n",
        "```\n",
        "\n",
        "The *raster* and *contour* parameters specify which images to load and how these images should be displayed. These parameters take python dictionaries as inputs. The fields in these dictionaries specify how the image will be displayed.\n",
        "\n",
        "An example call to **imview** looks like this:\n",
        "\n",
        "```\n",
        "imview(raster={'file': 'ngc5921.clean.image','range': [-0.01,0.03],'colormap': 'Hot Metal 2','scaling': -1},\n",
        "      contour={'file': 'ngc5921.clean.image'},\n",
        "      axes={'x':'Declination'},\n",
        "      zoom={'channel': 7, 'blc': [75,75], 'trc': [175,175],'coord': 'pixel'},\n",
        "      out='myout.png')\n",
        "```\n",
        "\n",
        "The argument to *raster* is enclosed in the curly braces { }. Within these braces are a number of \\\"key\\\":\\\"value\\\" pairs. Each sets an option in the **viewer**, with the GUI parameter to set defined by the \\\"key\\\" and the value to set it to defined by \\\"value.\\\" In the example above, file='ngc5921.clean.image' sets the file name of the raster image, range= \\[-0.01,0.03\\] sets the range of pixel values used for the scaling.\n",
        "\n",
        "*contour* works similarly to *raster* but can accept multiple dictionaries in order to produce multiple contour overlays on a single image. To specify multiple contour overlays, simply pass multiple dictionaries (comma delimited) in to the *contour* argument:\n",
        "\n",
        "```\n",
        "contour={'file': 'file1.image', 'levels': [1,2,3] }, {'file': 'file2.image', 'levels': [0.006, 0.008, 0.010] }\n",
        "```\n",
        "\n",
        "*zoom* specifies the part of the image to be shown. The example above specifies a channel as well as the top right corner \\\"trc\\\" and the bottom left corner \\\"blc\\\" of the region of interest.\n",
        "\n",
        "*axes* defines what axes are shown. By default, the viewer will show 'x':'Right Ascension', 'y':'Declination' but one may also view position-frequency images.\n",
        "\n",
        "*out* defines the filename of the output, with the extension setting the file type.\n",
        "\n",
        "Currently, the following parameters are supported:\n",
        "\n",
        "```\n",
        "raster  -- (string) image file to open\n",
        "           (dict)   file (string)     => image file to open\n",
        "                    scaling (float)   => scaling power cycles\n",
        "                    range (float*2)   => data range\n",
        "                    colormap (string) => name of colormap\n",
        "                    colorwedge (bool) => show color wedge?\n",
        "contour -- (string) file to load as a contour\n",
        "           (dict)   file (string)     => file to load\n",
        "                    levels (float*N)  => relative levels\n",
        "                    base (numeric)    => zero in relative levels\n",
        "                    unit (numeric)    => one in the relative levels\n",
        "zoom    -- (int)    integral zoom level\n",
        "           (string) region file to load as the zoom region\n",
        "           (dict)   blc (numeric*2)   => bottom left corner\n",
        "                    trc (numeric*2)   => top right corner\n",
        "                    coord (string)    => pixel or world\n",
        "                    channel (int)     => channel to display\n",
        "           (dict)   <region record>   => record loaded\n",
        "                                         e.g., rg.fromfiletorecord( )\n",
        "axes    -- (string*3) dimension to display on the x, y, and z axes\n",
        "           (dict)   x                 => dimension for x-axes\n",
        "                    y                 => dimension for y-axes\n",
        "                    z                 => dimension for z-axes\n",
        "out     -- (string) file with a supported extension\n",
        "                    [jpg, pdf, eps, ps, png, xbm, xpm, ppm]\n",
        "           (dict)   file (string)     => filename\n",
        "                    format (string)   => valid ext (filename ext overrides)\n",
        "                    scale (numeric)   => scale for non-eps, non-ps output\n",
        "                    dpi (numeric)     => dpi for eps or ps output\n",
        "                    orient (string)   => portrait or landscape\n",
        "```\n",
        "\n",
        "Examples are also found in `help imview`.\n",
        "\n",
        "\n",
        "**Scripting using the viewer tool**\n",
        "\n",
        "The **viewer** tool may also be used to generate simple figures that can be directly saved to an output image file format (png, jpg, etc). Below is an example.\n",
        "\n",
        "```\n",
        "def dispimage(imname=''): \n",
        "    qq = viewertool() \n",
        "    qq.load(imname) \n",
        "    qq.datarange(range=[-0.01,1.1]) \n",
        "    qq.colormap(map='Rainbow 3') \n",
        "    qq.colorwedge(show=True) \n",
        "    qq.zoom(blc=[100,150], trc=[600,640]) \n",
        "    qq.output(device='fig_trial.png',format='png') \n",
        "    qq.close()\n",
        "```\n",
        "\n",
        "Note that only basic controls are available via the **viewertool** interface. For additional customization via a script, please see the following section describing \\\"Using Viewer state files within a script\\\". \n",
        "\n",
        "\n",
        "**Using Viewer state files within a script**\n",
        "\n",
        "In order to access the full flexibility of the GUI interface in customizing the **viewer** settings and display options, a hand-crafted **viewer** state can be saved, edited, and subsequently restored/rendered via a script that then allows the saving of the figure to a file on disk.\n",
        "\n",
        "For example:\n",
        "\n",
        "Step 1 : Customize the **viewer** by hand. For example, choose to open an image, customize the display data ranges, choose a colormap, change axis label properties, change the units of the movie axis label, edit the panel background color, adjust margins and and resize the panel window.\n",
        "\n",
        "Step 2 : Click on the \\\"save viewer state\\\" button on the top control panel of the **viewer**. This will save a .rstr file, which is an xml file containing a complete description of the current state of the **viewer**.  \n",
        "\n",
        "Step 3 : Edit the text xml file as required. The simplest operation is to search and replace the name of the CASA image being opened. More complex editing can be done via stand-alone editing scripts perhaps using standard python xml parser/editing packages.\n",
        "\n",
        "Step 4 : Restore the state of the **viewer** from the edited xml .rstr file, using the **viewertool** as follows to subsequently save a .png figure to disk.\n",
        "\n",
        "```\n",
        "CASA <1>: vx = viewertool()\n",
        "CASA <2>: x = vx.panel('mystate.rstr')\n",
        "CASA <3>: vx.output('myfig.png',panel=x)\n",
        "```\n",
        "\n",
        "(There are two interactive ways to restore the **viewer** state as well. The first is by starting up the **viewer** with no image chosen, and then clicking on the \\\"restore viewer state\\\" button and choosing this .rstr file to open. Alternately, the **casaviewer** can itself be opened by supplying this .rstr file as the \\'image\\' to open.)\n"
      ]
    }
  ]
}