source: projects/visualisator/README.txt @ 7

Last change on this file since 7 was 7, checked in by sven, 16 years ago

Completed/more accurate documentation.

File size: 5.9 KB
Line 
1
2   The Paper Tape Project -- The Visualisation subproject
3   ======================================================
4
5   We have made many afforts to draw paper tapes on computer screens.
6   This subproject implements a C library which uses the
7   cairo graphics library (famous from GTK, Mozilla Firefox,
8   and other), a GTK widget that builds ontop this lowlevel
9   drawing object and several standalone progams with GTK
10   interface and CLI interface which use the GTK widget/Cairo
11   widget, respectively.
12
13   LOCHSTREIFEN cairo drawing routines
14   -----------------------------------
15   The files lochstreifen.c and lochstreifen.h implement the
16   drawing of paper tapes by using the cairo graphics library.
17   These routines only need cairo, so they can be compiled
18   by using `pkg-config --cflags --libs cairo`. They do not
19   need neither GTK nor Glib.
20   The routines only implement the drawing routines - the
21   cairo object (cairo_t) must be given from the implementing
22   programs. In this way you have full freedom to choose a
23   cairo surface -- among others PNG, SVG, PDF, ...).
24   See lochstreifen.h for the structure of the object
25   `LOCHSTREIFEN'. See lochstreifen.c for help with the usage
26   of the functions.
27
28   Features:
29   * Lightweight object system, e.g:
30       LOCHSTREIFEN *papertape = lochstreifen_new();
31       printf( "%d", lochstreifen_get_width(papertape) );
32       lochstreifen_set_d(papertape, 42);
33       int dir = lochstreifen_get_orientation(papertape);
34       lochstreifen_draw(papertape, cairo_context);
35       // ...
36   * Everything is configurable -- e.g. geometrical settings
37     like the distance of byte rows, bit columns, feed hole,
38     diameter of the holes, margins and paddings from the
39     paper, etc.
40   * Papertape can easily be rotated and flipped horizontically
41     or vertically. Even affine matrices can be defined --
42     you can use the full power of cairo.
43   * All colors can be set directly, all objects can be
44     said to be skipped in the painting process.
45   * The paper tape data can be served in a byte array or
46     read from a file
47   * Bytes or arrays of bytes can be highlighted with special
48     user-defined colors.
49   * There are functions to transform coordinates to bytes
50     and vice versa for GUI support.
51   * The painting process can actually skip bytes and therefore
52     only paint areas, which is also good for GUI support.
53   * Thanks to cairo and C all painting operations are handled
54     very fast and the output is always high quality.
55
56   GtkPaperTape
57   ------------
58   The files gtkpapertape.c and gtkpapertape.h implement a
59   GTK widget which uses the LOCHSTREIFEN object to display
60   paper tapes on computer displays. It can be used in GTK
61   programs directly and serves dozens of features to control
62   the behaviour and look of the paper tape directly. It is
63   even capable of displaying animations, reacting on mouse
64   movements, intelligent scrolling, byte highlighting, etc.
65
66   Features:
67   * Nice GTK/Glib like object oriented interface:
68       GtkPaperTape *papertape = gtk_paper_tape_new(mainwindow);
69       gtk_paper_tape_menu_view(papertape, menu);
70       gtk_paper_tape_menu_colors(papertape, menu);
71       gtk_paper_tape_get_whole_box(papertape);
72       // ...
73   * Scrollable widget: Thus, it is possible to zoom the
74     papertape to fill out the complete monitor or to zoom
75     out so you can e.g. read a labeled paper tape.
76   * Very big files can be displayed very performant because
77     only the neccessary regions of the paper tape are
78     redrawn (very big = many MB or even GB)
79   * The widget even serves an optional statusbar on which
80     status informations are printed (like zoom level)
81   * Mouse movements are catched, thus the statusbar can
82     print up-to-date information about the region on wich
83     the mouse cursor resides.
84   * Several menus are provided by this widget:
85     * Export: Display dialogs to export papertape with the
86       current settings to a SVG or PNG file
87     * View: A menu to zoom the papertape, fit it to the window
88       size or display it in real life size (DPI calculation),
89       rotate or flip it or fix the number of virtual null bytes
90       which are added at the beginning/end of the paper tape
91     * Colors: The colors of all components are displayed and
92       can be changed interactively.
93   * Regions can be highlighted, as an frontend for the
94     LOCHSTREIFEN widget.
95
96   Exemplar GtkPaperTape implementation: gtk.c
97   -------------------------------------------
98   The file gtk.c shows the GtkPaperTape in a window. It even
99   handles some arguments and can read up data from stdin.
100
101   Command Line Interface to the LOCHSTREIFEN
102   ------------------------------------------
103   The file cli.c provides a direct command line interface to
104   the LOCHSTREIFEN object. Thus you can use the LOCHSTREIFEN
105   drawing routines from any other program.
106
107   Features:
108   * powerful parameter set to control the result in every
109     detail (test it: ./cli --help)
110   * Unix philosophy: Simple usage, can read in data from
111     stdin, can put out result (SVG/PNG) on stdout
112
113   Web frontend
114   ------------
115   We actually have developed a web frontend in PHP which uses
116   the command line interface to generate the results. It
117   recieves the user input by an huge HTML form. Using a lot
118   of AJAX magic, it even caches already created images and
119   creates reports which contain the input data and all
120   settings and which are finally available for the client.
121   To avoid denial of service attacks (DoS), the PHP frontend
122   will deny creating paper tapes if the input file exceeds
123   some MB because the resulting file will be very big
124   (most web browsers reject rendering such big files which are,
125   for example, 400.000px in width).
126   See ../web-frontend/ for the sources and another README.txt.
127
128
129
130   See more descriptions and copyright information in the
131   accordant .c and .h files.
132
133   Sven Köppel, 19.07.2008
Note: See TracBrowser for help on using the repository browser.
© 2008 - 2013 technikum29 • Sven Köppel • Some rights reserved
Powered by Trac
Expect where otherwise noted, content on this site is licensed under a Creative Commons 3.0 License