Ginga Documentation Release 3.2.0
Total Page:16
File Type:pdf, Size:1020Kb
ginga Documentation Release 3.2.0 Ginga Maintainers Jun 07, 2021 CONTENTS I About Ginga1 II Copyright and License5 III Requirements and Supported Platforms9 IV Getting the Source 13 V Building and Installation 17 1 Installation 21 VI Documentation 27 2 What’s New 29 3 Quick Reference 41 4 User’s Manual 49 5 Developer’s Manual 153 6 Optimizing Performance 203 7 FAQs 205 8 Reference/API 209 i VII Bug Reports 285 VIII Developer Info 289 IX Etymology 293 X Pronunciation 297 Python Module Index 301 Index 303 ii Part I About Ginga 1 ginga Documentation, Release 3.2.0 Ginga is a toolkit designed for building viewers for scientific image data in Python, visualizing 2D pixel datain NumPy arrays. It can view astronomical data such as contained in files based on the FITS (Flexible Image Transport System) file format. It is written and is maintained by software engineers at the National Astronomical Observatory ofJapan, the Space Telescope Science Institute, and other contributing entities. The Ginga toolkit centers around an image display class which supports zooming and panning, color and intensity mapping, a choice of several automatic cut levels algorithms and canvases for plotting scalable geometric forms. In addition to this widget, a general purpose “reference” FITS viewer is provided, based on a plugin framework. A fairly complete set of “standard” plugins are provided for features that we expect from a modern FITS viewer: panning and zooming windows, star catalog access, cuts, star pick/FWHM, thumbnails, etc. 3 ginga Documentation, Release 3.2.0 4 Part II Copyright and License 5 ginga Documentation, Release 3.2.0 Copyright (c) 2011-2021 Ginga Maintainers. All rights reserved. Ginga is distributed under an open-source BSD licence. Please see the file LICENSE.txt in the top-level directory for details. 7 ginga Documentation, Release 3.2.0 8 Part III Requirements and Supported Platforms 9 ginga Documentation, Release 3.2.0 Because Ginga is written in pure Python, it can run on any platform that has the required Python modules and has a supported widget set. The basic Ginga display class supports the Qt (4 and 5), PySide, Gtk (3), Tk widget sets natively as well as any Matplotlib Figure, and HTML5 canvases in a web browser. The full reference viewer supports Qt and Gtk variants. Ginga can also be used in Jupyter notebooks. 11 ginga Documentation, Release 3.2.0 12 Part IV Getting the Source 13 ginga Documentation, Release 3.2.0 Clone from Github: git clone https://github.com/ejeschke/ginga.git To get a ZIP file or tarball instead, see the links on About Ginga. 15 ginga Documentation, Release 3.2.0 16 Part V Building and Installation 17 ginga Documentation, Release 3.2.0 Download and install from pip: pip install ginga Or conda: conda install ginga-c conda-forge The reference viewer can then be run using the command ginga. For detailed instructions, see: 19 ginga Documentation, Release 3.2.0 20 CHAPTER ONE INSTALLATION 1.1 Dependencies Ginga is written entirely in Python, and only uses supporting Python packages. There is nothing to compile (unless you need to compile one of the supporting packages). In recent Linux, Mac, and Windows versions, all of the packages are available in binary (installable) form. It should not be necessary to compile anything, but as always, your mileage may vary. 1.1.1 REQUIRED • python (v. 3.7 or higher) • setuptools-scm • numpy (v. 1.14 or higher) • astropy Strongly recommended, because some features will not be available without it: • scipy • pillow • opencv-python (also distributed as opencv or python-opencv, depending on where you get it from) • piexif • beautifulsoup4 • docutils (to display help for plugins) For opening FITS files you will need one of the following packages: • astropy • fitsio For WCS resolution you will need one of the following packages: • astropy • kapteyn • astLib • starlink 21 ginga Documentation, Release 3.2.0 1.1.2 BACKENDS (one or more) Ginga can draw its output to a number of different back ends. Depending on which GUI toolkit you prefer (andwhat you want to do), you will need at least one of the following: • QtPy (PyQt4 or PyQt5) • PySide (Qt4/Qt5 alternative) • pygobject (gi) AND pycairo (GTK 3) • tkinter • matplotlib • tornado • aggdraw • Pillow (PIL fork) 1.1.3 RECOMMENDED Certain plugins in the reference viewer (or features of those plugins) will not work without the following packages: • matplotlib (required by: Pick, Cuts, Histogram, LineProfile) • scipy (required by: Pick, some built-in auto cuts algorithms used when you load an image) • astroquery (required by Catalogs) To save a movie: • mencoder (command line tool required by: Cuts) Helpful, but not necessary (may optimize or speed up certain operations): • opencv-python (speeds up rotation, mosaicing and some transformations) • pyopencl (speeds up rotation, mosaicing and some transformations) • pyopengl + pycairo (for using OpenGL features; very useful for 4K or larger monitors) • numexpr (speeds up rotation a little) • filemagic (aids in identifying files when opening them) • Pillow (useful for various RGB file manipulations) 1.2 Notes on Supported Widget Sets In the discussion below, we differentiate between the Ginga viewing widget, such as used inthe examples/\*/ example\*.py programs and the full reference viewer, which includes many plugins (ginga). Note: For the full reference viewer, Mac and Windows users should probably install the Qt version, unless you are the tinkering sort. Linux can use either Qt or GTK fine. 22 Chapter 1. Installation ginga Documentation, Release 3.2.0 1.2.1 Qt/PySide Ginga can use either PyQt or PySide, version 4 or 5. It will auto-detect which one is installed, using the qtpy compat- ibility package. There is support for both the basic widget and the full reference viewer. Note: If you have both installed and you want to use a specific one then set the environment variable QT_API to either “pyqt” or “pyside”. This is the same procedure as for Matplotlib. 1.2.2 GTK Ginga can use GTK 3 (with gi). (If you have an older version of pycairo package, you may need to install a newer version from pycairo). 1.2.3 Tk Ginga’s Tk support is limited to the viewing widget itself. For overplotting (graphics) support, you will also need one of: • Pillow • opencv-python • aggdraw 1.2.4 Matplotlib Ginga can render directly into a Matplotlib figure. Support is limited to the viewing widget itself. Any of the backends that Matplotlib supports is usable. Performance is not as good as to one of the “native” backends listed above, but oh, the overplot options! 1.2.5 HTML5 web browser Ginga can render into an HTML5 canvas via a web server. Support is limited to the viewing widget itself. See the notes in examples/pg/example2_pg.py. Tested browsers include Chromium (Chrome), Firefox, and Safari. 1.3 Basic Installation You can download and install via pip by choosing the command that best suits your needs (full selection is defined in setup configuration file): pip install ginga # The most basic installation pip install ginga[recommended,qt5] # Qt5 pip install ginga[recommended,gtk3] # GTK 3 Or via conda: 1.3. Basic Installation 23 ginga Documentation, Release 3.2.0 conda install ginga-c conda-forge The reference viewer can then be run using the command ginga. 1.4 Installation from Source 1. Clone from Github: git clone https://github.com/ejeschke/ginga.git Or see links on this page to get a ZIP file or tarball. 2. Unpack, go into the top level directory, and run: pip install-e. 1.5 Platform Specific Instructions 1.5.1 Linux (Debian/Ubuntu) If you are on a relatively recent version of Debian or Ubuntu, something like the following will work: apt install python3-ginga If you are using another distribution of Linux, we recommend to install via Anaconda or Miniconda as described below. 1.5.2 Mac/Windows/Linux (others) Anaconda For Mac/Windows or other Linux users, we recommend installing the Anaconda distribution (or Miniconda). This distribution already includes all of the necessary packages to run Ginga. After installing Anaconda, open the Anaconda Prompt and follow instructions under Basic Installation via conda. 1.6 Running tests 1. Install the following packages: $ pip install -e .[test] 2. Run the tests using pytest: $ pytest 24 Chapter 1. Installation ginga Documentation, Release 3.2.0 1.7 Building documentation 1. Install the following packages: $ pip install -e .[docs] 2. Build the documentation using make: $ cd doc $ make html 1.7. Building documentation 25 ginga Documentation, Release 3.2.0 26 Chapter 1. Installation Part VI Documentation 27 CHAPTER TWO WHAT’S NEW 2.1 Ver 3.2.0 (2021-06-07) • Minimum supported Python version is now 3.7 • Fixed some numpy deprecation warnings with numpy 1.19.0 • Canvas shapes can now be copied • Added an option to make a copy of existing shape in Drawing plugin • Added an option to make a copy of existing cut in Cuts plugin • Added new iqcalc_astropy module to handle FWHM fitting and source finding using astropy and photutils • Added new calc_fwhm_lib configuration item to let Pick switch between iqcalc and iqcalc_astropy • Fixed a bug where certain plots were not cleared in Pick plugin • Removed support for matplotlib versions < 2.1 • Added bicubic and bilinear interpolation methods to OpenGL backend • Fixed a bug where the FWHM labels in the plot didn’t match report values in the Pick plugin • Fixed a bug in gtk/cairo backend where paths were not drawn correctly • Included a couple of additional bundled fonts to improve legibility of small text • Fixed a bug