The Visualisation Sub project
Introducion and Overview
We have made many afforts to draw paper tapes on computer screens. This subproject is surely one of the biggest and most complex programs in the complete paper tape project. It hasn't be simply written down in some days but has gone throught various development generations, from simply two C files up to the current bunch of a dozen C++ files. This is the structure we are targetting:
- LOCHSTREIFEN: A small pure C library that uses the cairo graphics library (famous from GTK, Mozilla Firefox and other) for drawing paper tapes on any Cairo surface. This is very low level.
- cli frontend: A simple command line interface written in pure C to the LOCHSTREIFEN library. The frontend should be non interactive, so it's controlled via command line arguments.
- web-frontend: Rendering paper tapes via the Web by using PHP and the cli frontend. Due to it's complexity this is an own sub project.
- gtkpapertape: A Gtkmm widget (written in C++) that wraps all features of LOCHSTREIFEN with a very powerful and flexible GUI. This is split up in many Cpp/header files, so it's almost an own library
- gtk-frontend: A simple (almost dummy) C++ frontend that simply uses the gtkpapertape widget.
LOCHSTREIFEN cairo drawing routines
The files lochstreifen.c and lochstreifen.h implement the
drawing of paper tapes by using the cairo graphics library.
These routines only need cairo, so they can be compiled
by using `pkg-config --cflags --libs cairo`. They do not
need neither GTK nor Glib (this is a special feature! :-) )
The routines only implement the drawing routines - the cairo object (cairo_t) must be given from the implementing programs. In this way you have full freedom to choose a cairo surface -- among others PNG, SVG, PDF, ...). See lochstreifen.h for the structure of the object `LOCHSTREIFEN'. See lochstreifen.c for help with the usage of the functions.
There are two generations of this file: The one before I learned that there's a standard for paper tapes and the one after I learned that there's such a standard, called ECMA 10. When I read about this ECMA standard, I've rewritten the routines completely, cleaning the programming interface and making it more flexible and robust. The new code is stable right now.
Features of this library:
- Pure C: Very flexible in usage with other programming languages
- Standard compilant (ECMA 10): The rendered paper tape will have proper geometrical dimensions
- Lightweight object system, e.g:
LOCHSTREIFEN *papertape = lochstreifen_new(); printf( "%d", lochstreifen_get_width(papertape) ); lochstreifen_set_d(papertape, 42); int dir = lochstreifen_get_orientation(papertape); lochstreifen_draw(papertape, cairo_context); // ...
- Everything is configurable -- e.g. any colors/surfaces,
rotation/translation matrix, margins, paddings, etc.:
- Papertape can easily be rotated and flipped horizontically or vertically. Even affine matrices can be defined -- you can use the full power of cairo.
- All colors can be set directly, all objects can be said to be skipped in the painting process.
- The paper tape data can be served (input) in a simple byte array or read from a file. The LOCHSTREIFEN structure will not own or manage the data, so you're completely free where to store your data.
- Highlighting of bytes: Ranges (regions) of bytes
(data rows) can be highlighted in various manner: There are
three highlight modes:
- Region highlight: Rows are highlighted from a user defined start row to an end row
- Row highlight: Only one user defined row is highlighted
- Bit highlight: One bit (defined via row/track) is highlighted
- There are powerful functions to transform coordinates to bytes and vice versa for GUI support
- The painting process can actually skip bytes and therefore only paint areas, which is also good for GUI support
- There's even callback support that can be called at each row iteration for individual settings
- Thanks to cairo and C all painting operations are handled very fast and the output is always high quality
Command line and web frontend
The file cli.c uses the LOCHSTREIFEN structure directly. It only depends on the two lochstreifen.c/h files. For argument parsing, it uses the argp.h, from the GNU C library. Unfortunately argp.h doesn't seem to be present in other c librarys, that's still an issue. Apart from that the CLI program is complete platform independent and only has to be linked against libcairo: gcc cli.c lochstreifen.c `pkg-config --cflags --libs cairo`.
Features of the command line frontend:
- Powerful parameter set to control the result in every detail – thus you can use LOCHSTREIFEN from any other application
- Verbose help on every argument: ./cli --help
- Unix phiosophy: Simple usage, can read in (any) data from stdin, can put out result (SVG/PNG binary) on stdout
We actually have developed a web frontend in PHP which uses
the command line interface to generate the results. It
recieves the user input by an huge HTML form. Using a lot
of AJAX magic, it even caches already created images and
creates reports which contain the input data and all
settings and which are finally available for the client.
To avoid denial of service attacks (DoS), the PHP frontend
will deny creating paper tapes if the input file exceeds
some MB because the resulting file will be very big
(most web browsers reject rendering such big files which are,
for example, 400.000px in width).
This progam is an own sub project, see ../web-frontend/ for the sources and it's documentation.
The library GtkPaperTape is a typical and unexpected result of the growth of the complete program. Whereas the GTK visualisatoin frontend initlally consisted of only one C file (corresponding to cli.c), gtk.c, it rapidly got very big and confusing so I decided to write divide the sourcecode into a Gtk+ widget, called GtkPaperTape and the program around it, still called gtk.c. Well, I developed this widget, and it got even much bigger than the former gtk.c program (about 1200 lines pure C and Glib code). There occured quite some problems (the sourcecode was badly maintainable and confusing, and there wer some drawing bugs that I could not solve), but the program was working quite fine.
Well, there was the issue about the Windows version and the
implementation of punching/reading features. This made the
things much more complex, as it requires more features from
both LOCHSTREIFEN and GtkPaperTape. I therefore
decided to learn C++ and Gtkmm to produce a new program from
the scratch with a cleaner interface and a better documentation.
As was only to be expected, the sourcecode is now much more
bulky, we have now more than a dozen Cpp/header files with
more than 2400 lines of code (still growing). The third generation
of the GtkPaperTape is still supposed to be called
GtkPaperTape, but uses the gtkmm namespace Gtk,
so it's actually Gtk::PaperTape.
There's a meta header file, gtkpapertape.h. Include this file when you want to use the GtkPaperTape widget.
This is an overview of the features of the current generation of GtkPaperTape:
- Gtkmm widget, clean object oriented interface
- Very big files can be displayed very perfomant, because only the neccessary regions of the paper tapes have to be redrawn (very big = many MB or even GB, only limited by the size of your RAM ;-) )
- The widget implements a complete Hex editor with all features like copying, moving, deleting, inserting bytes and toggling bits
- The widget was programed in a model/view/controller fashion. There's an optional statusbar, as well as a complete menu, scrolling, help, mouse interaction, etc.
- The widget even can generate files and fonts/labels by interacting with the schriften subproject.
- Powerful export of picture of the displayed papertape with the current settings to a SVG or PNG file.
- Zoom, Rotating or directly editing the display matrix is possible
- All colors can be changed interactively, all components can be switched off and on as you want
There is still a bug while scrolling over really big paper tapes, but I've managed to get solved who's the guilty library: It's a Gtk+ bug, commited on the GNOME bugzilla by me.
Compared to the widget, there's a quite trivial and simple frontend programm called gtk.cc that replaces the old gtk.c.