Skip to content

dkogan/GL_image_display

Repository files navigation

This is an image-display library that uses OpenGL internally for efficient (re)drawing.

Overview

Image-display widgets are common in GUI toolkits (FLTK has =Fl_RGB_Image= for instance), but they generally use the CPU to draw, which becomes slow when given large images. By contrast, this toolkit uses OpenGL hardware, so after the initial cost to load an image, the drawing, redrawing, panning and zooming are effectively free. This makes it possible to quickly build responsive applications that display images.

Three separate interfaces are available:

Build

Run make. A few dependencies are required to build. See the Build-Depends section in the =debian/control= file.

C library

The core functionality in this library is made available in the C library. This can be used directly to build a GLUT application (sample in =GL_image_display-test-glut.c=), or it can be used to implement higher-level components, such as the =Fl_Gl_Image_Widget= FLTK widget.

Please see =GL_image_display.h= and the GLUT sample for the API.

FLTK widget

An Fl_Gl_Image_Widget is provided in =Fl_Gl_Image_Widget.hh=, with a sample application in =GL_image_display-test-fltk.cc=. This is a “normal” FLTK widget, that wraps the necessary functions from the C API, and that defines the expected UI behaviors to make it immediately usable. The UI supported by the default Fl_Gl_Image_Widget::handle() function:

  • Mouse click/drag pans
  • Mousewheel pans. Vertical and horizontal mousewheels are supported to pan in the two directions
  • Ctrl-vertical-mousewheel zooms
  • u key on the keyboard reverts to the original full-size view (this is the key used by gnuplot.)

To define new/different interactions, subclass Fl_Gl_Image_Widget, and override the handle() method.

The widget automatically handles resizing operations.

The normal usage sequence is very simple:

  • Construct the Fl_Gl_Image_Widget
  • Call the update_image2() method to give it data

Note that the set_panzoom() method is virtual, so a derived class can override it to get a “notification” of any pan/zoom operation. One application of this is to sync the pan/zoom setting between multiple Fl_Gl_Image_Widget objects in a single application.

Python FLTK widget

For FLTK applications written in Python using pyfltk, a Python flavor of the Fl_Gl_Image_Widget is available. The wrapper code is generated with SWIG, so the Python API largely mirrors the C++ API. Some Python-specific notes:

  • Instead of returning False to indicate failure, these functions raise an Exception
  • SWIG directors are used, so the widget can be subclassed in Python, and works as one would expect
  • update_image2() can take an image filename (as in C++) or a numpy array of data. The dimensions, depth and pitch are all read from this array
  • The pixel mapping functions map_pixel_viewport_from_image() and map_pixel_image_from_viewport() ingest a length-2 iterable (or a numpy array) and return a length-2 tuple.
  • set_lines() takes in dict objects each with keys
    • points: a numpy array of shape (Nsegments,2,2). These are the line segments, each represented as (x0,y0) - (x1,y1)
    • color_rgb: a numpy array of shape (3,) which contains the RGB color for this set of line segments. Each channel ranges from 0 to 1.

A sample application is available in =GL_image_display-test-fltk.py=.

Repository

https://www.github.com/dkogan/GL_image_display

Author

Dima Kogan (dima@secretsauce.net)

License and Copyright

Copyright (c) 2021 California Institute of Technology (“Caltech”). U.S. Government sponsorship acknowledged. All rights reserved.

Licensed under the Apache License, Version 2.0 (the “License”); You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

About

Image-display library backed by OpenGL. Provided are a C library and a FLTK widget with C++ and Python interfaces

Resources

Stars

Watchers

Forks

Packages

No packages published