# Ginga: Image Viewer and Toolkit¶

Ginga is a toolkit designed for building viewers for scientific image data in Python, visualizing 2D pixel data in 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 Subaru Telescope, National Astronomical Observatory of Japan.

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.

## Requirements and Supported Platforms¶

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 (2 and 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.

## Getting the Source¶

Clone from Github:

$git clone https://github.com/ejeschke/ginga.git  To get a zip or tar ball instead, see the links on About Ginga. ## Building and Installation¶ Download and install from pip: $ pip install ginga


Or, if you have downloaded the source, go into the top-level directory and run the following:

$python setup.py install  The reference viewer can then be run using the command ginga. ## Documentation¶ Some training videos are available in the downloads page on Github. Be sure to also check out the Ginga wiki. ## Bug Reports¶ Please file an issue with the issue tracker on Github. Ginga has a logging facility, and it would be most helpful if you can invoke Ginga with the logging options to capture any logged errors: $ ginga --loglevel=20 --log=ginga.log


If the difficulty is with non-display or non-working World Coordinate System (WCS) for a particular image file please be ready to supply the file for our aid in debugging.

## Developer Info¶

In the source code examples/* directories, see example{1,2}_gtk.py (Gtk), example{1,2}_qt.py (Qt), example{1,2}_tk.py (Tk) or example{1,2,3,4,5}_mpl.py (Matplotlib). There is more information for developers in the The Ginga Viewer and Toolkit Manual.

See also the Module Index for a complete list of the available modules.

## Etymology¶

“Ginga” is the romanized spelling of the Japanese word “銀河” (Hiragana: ぎんが), meaning “galaxy” (in general) and, more familiarly, the Milky Way. This viewer was written by software engineers at Subaru Telescope, National Astronomical Observatory of Japan—thus the connection.

## Pronunciation¶

Ginga the viewer may be pronounced “ging-ga” (proper Japanese) or “jing-ga” (perhaps easier for Westerners). The latter pronunciation has meaning in the Brazilian dance/martial art Capoeira: a fundamental rocking or back and forth swinging motion. Pronunciation as “jin-ja” is considered poor form.