Using the Basic Ginga Viewer Object in Python Programs

The core design principle of the Ginga project is to make it possible to easily build powerful image viewers in Python with many possible GUI toolkits.

This chapter is for developers who want to use only the Ginga rendering class in a program of their own design (not customizing the reference viewer).

Using the basic rendering class in new programs

Ginga basically follows the Model-View-Controller (MVC) design pattern, that is described in more detail in the chapter on internals (see Ginga Internals). The “view” classes are rooted in the base class ImageView. Ginga supports backends for different widget sets through various subclasses of this class.

Typically, a developer picks a GUI toolkit that has a supported backend (Gtk 3, Qt 5/6, Tk, matplotlib, HTML5 canvas) and writes a GUI program using that widget set with the typical Python toolkit bindings and API. Where they want a image view pane they instantiate the appropriate subclass of ImageView (usually a CanvasView), and using the get_widget() call extract the native widget and insert it into the GUI layout. A reference should also be kept to the view object, as this is typically what you will be calling methods on to control the viewer (see Ginga Image Viewer Operations).

Ginga does not create any additional GUI components beyond the image pane itself, however it does provide a standard set of keyboard and mouse bindings on the host widget that can be enabled, disabled or changed. The user interface bindings are configurable via a pluggable Bindings class which constitutes the “controller” part of the MVC design. There are a plethora of callbacks that can be registered, allowing the user to create their own custom user interface for manipulating the view. Of course, the developer can add many different GUI widgets from the selected toolkit to supplement or replace these built in controls.


A simple, “bare bones” FITS viewer written in Qt.

Listing 1 shows a code listing for a simple graphical FITS viewer built using the subclass CanvasView from the module ImageViewQt (screenshot in Figure A simple, “bare bones” FITS viewer written in Qt.) written in around 100 or so lines of Python. It creates a window containing an image view and two buttons. This example will open FITS files dragged and dropped on the image window or via a dialog popped up when clicking the “Open File” button.

#! /usr/bin/env python
# -- Simple FITS viewer using the Ginga toolkit
#                       and Qt widgets.
import sys

from ginga.misc import log
from ginga.qtw.QtHelp import QtGui, QtCore
from ginga.qtw.ImageViewQt import CanvasView, ScrolledView
from ginga.util.loader import load_data

class FitsViewer(QtGui.QMainWindow):

    def __init__(self, logger):
        super(FitsViewer, self).__init__()
        self.logger = logger

        # create the ginga viewer and configure it
        fi = CanvasView(self.logger, render='widget')
        fi.set_callback('drag-drop', self.drop_file)
        fi.set_bg(0.2, 0.2, 0.2)
        self.fitsimage = fi

        # enable some user interaction
        bd = fi.get_bindings()

        w = fi.get_widget()
        w.resize(512, 512)

        # add scrollbar interface around this viewer
        sw = ScrolledView(fi)

        vbox = QtGui.QVBoxLayout()
        vbox.setContentsMargins(QtCore.QMargins(2, 2, 2, 2))
        vbox.addWidget(sw, stretch=1)

        hbox = QtGui.QHBoxLayout()
        hbox.setContentsMargins(QtCore.QMargins(4, 2, 4, 2))

        wopen = QtGui.QPushButton("Open File")
        wquit = QtGui.QPushButton("Quit")

        for w in (wopen, wquit):
            hbox.addWidget(w, stretch=0)

        hw = QtGui.QWidget()
        vbox.addWidget(hw, stretch=0)

        vw = QtGui.QWidget()

    def load_file(self, filepath):
        image = load_data(filepath, logger=self.logger)

    def open_file(self):
        res = QtGui.QFileDialog.getOpenFileName(self, "Open FITS file",
                                                ".", "FITS files (*.fits)")
        if isinstance(res, tuple):
            fileName = res[0]
            fileName = str(res)
        if len(fileName) != 0:

    def drop_file(self, fitsimage, paths):
        fileName = paths[0]

    def quit(self, *args):"Attempting to shut down the application...")

def main(options, args):

    app = QtGui.QApplication(sys.argv)

    # ginga needs a logger.
    # If you don't want to log anything you can create a null logger by
    # using null=True in this call instead of log_stderr=True
    logger = log.get_logger("example1", log_stderr=True, level=40)

    w = FitsViewer(logger)
    w.resize(524, 540)

    if len(args) > 0:


if __name__ == '__main__':
    main(None, sys.argv[1:])

Looking at the constructor for this particular viewer, you can see where we create a CanvasView object. On this object we enable automatic cut levels (using the ‘zscale’ algorithm), configure it to auto zoom the image to fit the window and set a callback function for files dropped on the window. We extract the user-interface bindings with get_bindings(), and on this object enable standard user interactive controls for all the possible key and mouse operations. We then extract the platform-specific widget (Qt-based, in this case) using get_widget() and pack it into a Qt container along with a couple of buttons to complete the viewer.

Scanning down the code a bit, we can see that whether by dragging and dropping or via the click to open, we ultimately call the load_file() method to get the data into the viewer. load_file() creates an AstroImage object (the “model” part of our MVC design), which is then passed to the viewer via the set_image() method. AstroImage objects have methods for ingesting data via a file path, an HDU or a bare Numpy data array. For a reference on the model, see here:ref:_ch-image-data-wrappers.

Many of these sorts of examples for all supported backends are contained in the examples directory in the source distribution.

For a list of many methods provided by the viewer object see this reference Ginga Image Viewer Operations. You can also click on the module index link at the top of this chapter and then click on the link for ImageViewBase.

Graphics plotting with Ginga


An example of a CanvasView widget with graphical overlay.

A CanvasView actually pairs a view with a canvas object (in particular a DrawingCanvas object). You can get more detail about canvases and the objects they support (see Ginga Canvas Graphics). A variety of graphical shapes are available, and plotted objects scale, transform and rotate seamlessly with the viewer.

Rendering into Matplotlib Figures

Ginga can also render directly into a Matplotlib Figure, which opens up possibilities for overplotting beyond the limited capabilities of the Ginga canvas items. See the examples under “examples/matplotlib” for ideas, particularly “”.

Rendering into HTML5 canvases

Ginga can render onto HTML5 canvases displayed in a web browser. This opens up interesting possibilities for server-based remote viewing tools. See the examples under “examples/pg”, particularly “”.

Writing widget toolkit independent code

You can write code that allows the widget set to be abstracted by Ginga’s widget wrappers. This is the same technique used to allow the reference viewer to switch between supported toolkits using the “-t” command line option. Currently only Qt (4/5), Gtk (3), and HTML5 (to a more limited degree) are supported, and there are some limitations compared to developing using a native toolkit directly. Nevertheless, the ability to target different platforms just by changing a command line option is a very interesting proposition.

See the examples under “examples/gw”, particularly “”.