The Punched Paper Project / paper-tape/visualisator/README.htm

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:
1. Region highlight: Rows are highlighted from a user defined start row to an end row
2. Row highlight: Only one user defined row is highlighted
3. Bit highlight: One bit (defined via row/track) is highlighted
All modes can be used concurrently.
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.

GtkPaperTape

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.