source: projects/visualisator/README.htm @ 23

Last change on this file since 23 was 23, checked in by sven, 11 years ago

Documentation:

  • documentation/index.php: New small wrapper system that puts any HTM file in this reposity in a small homepage
  • README.txt => README.htm conversion in most of the subprojects

-- Sven @ workstation

File size: 9.9 KB
Line 
1<html>
2<body>
3<h2>The Visualisation Sub project</h2>
4
5<h3>Introducion and Overview</h3>
6<p>
7   We have made many afforts to draw paper tapes on computer screens.
8   This subproject is surely one of the biggest and most complex
9   programs in the complete paper tape project. It hasn't be
10   simply written down in some days but has gone throught various
11   development generations, from simply two C files up to the current
12   bunch of a dozen C++ files.
13
14   This is the structure we are targetting:
15</p>
16
17<ul>
18   <li><b>LOCHSTREIFEN</b>: A small pure C library that uses the
19      <a href="http://www.cairographics.org">cairo graphics library</a>
20      (famous from GTK, Mozilla Firefox and other) for
21      drawing paper tapes on any Cairo surface. This is very
22      low level.
23   <li><b>cli frontend</b>: A simple command line interface written in
24      pure C
25      to the LOCHSTREIFEN library. The frontend should be non interactive,
26      so it's controlled via command line arguments.</li>
27   <li><b>web-frontend</b>: Rendering paper tapes via the Web by using
28      PHP and the cli frontend. Due to it's complexity this is an
29      own sub project.</li>
30   <li><b>gtkpapertape</b>: A <a href="http://www.gtkmm.org">Gtkmm</a>
31      widget (written in C++) that wraps all features of LOCHSTREIFEN
32      with a very powerful and flexible GUI. This is split up in many
33      Cpp/header files, so it's almost an own library</li>
34   <li><b>gtk-frontend</b>: A simple (almost dummy) C++ frontend
35      that simply uses the gtkpapertape widget.</li>
36</ul>
37
38<h3>LOCHSTREIFEN cairo drawing routines</h3>
39<p>The files <i>lochstreifen.c</i> and <i>lochstreifen.h</i> implement the
40   drawing of paper tapes by using the cairo graphics library.
41   These routines only need cairo, so they can be compiled
42   by using <tt>`pkg-config --cflags --libs cairo`</tt>. They do not
43   need neither GTK nor Glib (this is a special feature! :-) )
44<br/>The routines only implement the drawing routines - the
45   cairo object (<tt>cairo_t</tt>) must be given from the implementing
46   programs. In this way you have full freedom to choose a
47   cairo surface -- among others PNG, SVG, PDF, ...).
48   See <i>lochstreifen.h</i> for the structure of the object
49   `LOCHSTREIFEN'. See <i>lochstreifen.c</i> for help with the usage
50   of the functions.
51</p>
52
53<p>There are two generations of this file: The one before I
54learned that there's a standard for paper tapes and the one after
55I learned that there's such a standard, called <a
56href="http://www.srcf.ucam.org/~jsm28/ECMA-10/">ECMA 10</a>. When
57I read about this ECMA standard, I've rewritten the routines completely,
58cleaning the programming interface and making it more flexible and
59robust. The new code is stable right now.</p>
60
61<p>Features of this library:</p>
62<ul>
63   <li><b>Pure C</b>: Very flexible in usage with other programming
64       languages</li>
65   <li><b>Standard compilant (ECMA 10)</b>: The rendered paper tape
66       will have proper geometrical dimensions</li>
67   <li><b>Lightweight object system</b>, e.g:
68      <pre>
69       LOCHSTREIFEN *papertape = lochstreifen_new();
70       printf( "%d", lochstreifen_get_width(papertape) );
71       lochstreifen_set_d(papertape, 42);
72       int dir = lochstreifen_get_orientation(papertape);
73       lochstreifen_draw(papertape, cairo_context);
74       // ...
75       </pre>
76   <li>Everything is <b>configurable</b> -- e.g. any colors/surfaces,
77       rotation/translation matrix, margins, paddings, etc.:
78       <ul>
79         <li>Papertape can easily be rotated and flipped horizontically
80             or vertically. Even affine matrices can be defined --
81             you can use the full power of cairo.</li>
82         <li>All colors can be set directly, all objects can be
83             said to be skipped in the painting process.
84       </ul>
85   <li>The paper tape data can be served (input) in a simple byte
86       array or read from a file. The LOCHSTREIFEN structure will
87       not own or manage the data, so you're completely free where
88       to store your data.</li>
89   <li><b>Highlighting of bytes</b>: Ranges (regions) of bytes
90       (data rows) can be highlighted in various manner: There are
91       three highlight modes:
92       <ol>
93         <li>Region highlight: Rows are highlighted from a user defined
94             start row to an end row</li>
95         <li>Row highlight: Only one user defined row is highlighted</li>
96         <li>Bit highlight: One bit (defined via row/track) is highlighted</li>
97       </ol>
98       All modes can be used concurrently.
99   <li>There are powerful functions to transform coordinates to bytes
100       and vice versa for GUI support</li>
101   <li>The painting process can actually skip bytes and therefore
102       only paint areas, which is also good for GUI support
103   <li>There's even <b>callback</b> support that can be called at
104       each row iteration for individual settings</li>
105   <li>Thanks to cairo and C all painting operations are handled
106       <i>very fast</i> and the output is always high quality</li>
107</ul>
108
109<h3>Command line and web frontend</h3>
110<p>The file <tt>cli.c</tt> uses the <i>LOCHSTREIFEN</i> structure
111   directly. It only depends on the two <tt>lochstreifen.c/h</tt> files.
112   For argument parsing, it uses the <tt>argp.h</tt>, from the
113   <a href="http://www.gnu.org/software/libc/">GNU C library</a>.
114   Unfortunately <tt>argp.h</tt> doesn't seem to be present in other
115   c librarys, that's still an issue. Apart from that the CLI
116   program is complete platform independent and only has to be
117   linked against libcairo: <tt>gcc
118   cli.c lochstreifen.c `pkg-config --cflags --libs cairo`</tt>.
119</p>
120<p>Features of the command line frontend:</p>
121<ul>
122  <li>Powerful parameter set to control the result in every
123      detail &ndash; thus you can use LOCHSTREIFEN from any other
124      application</li>
125  <li>Verbose help on every argument: <tt>./cli --help</tt></li>
126  <li>Unix phiosophy: Simple usage, can read in (any)
127      data from stdin, can put out result (SVG/PNG binary) on
128      stdout</li>
129</ul>
130<p>
131   We actually have developed a web frontend in PHP which uses
132   the command line interface to generate the results. It
133   recieves the user input by an huge HTML form. Using a lot
134   of AJAX magic, it even caches already created images and
135   creates reports which contain the input data and all
136   settings and which are finally available for the client.
137   To avoid denial of service attacks (DoS), the PHP frontend
138   will deny creating paper tapes if the input file exceeds
139   some MB because the resulting file will be very big
140   (most web browsers reject rendering such big files which are,
141   for example, 400.000px in width).
142<br/>This progam is an own sub project, see
143   <a href="../web-frontend/">../web-frontend/</a> for the
144   sources and it's documentation.</p>
145
146<h3>GtkPaperTape</h3>
147<p>The library GtkPaperTape is a typical and unexpected result of
148   the growth of the complete program. Whereas the GTK visualisatoin
149   frontend initlally consisted of only one C file (corresponding to
150   <tt>cli.c</tt>), <tt>gtk.c</tt>, it rapidly got very big and
151   confusing so I decided to write divide the sourcecode into a
152   Gtk+ widget, called <i>GtkPaperTape</i> and the program around it,
153   still called <i>gtk.c</i>. Well, I developed this widget, and it
154   got even much bigger than the former <tt>gtk.c</tt> program
155   (about 1200 lines pure C and Glib code). There occured
156   quite some problems (the sourcecode was badly maintainable and
157   confusing, and there wer some drawing bugs that I could not
158   solve), but the program was working quite fine.
159</p>
160<p>Well, there was the issue about the Windows version and the
161   implementation of punching/reading features. This made the
162   things much more complex, as it requires more features from
163   both <i>LOCHSTREIFEN</i> and <i>GtkPaperTape</i>. I therefore
164   decided to learn C++ and Gtkmm to produce a new program from
165   the scratch with a cleaner interface and a better documentation.
166   As was only to be expected, the sourcecode is now much more
167   bulky, we have now more than a dozen Cpp/header files with
168   more than 2400 lines of code (still growing). The third generation
169   of the <i>GtkPaperTape</i> is still supposed to be called
170   <i>GtkPaperTape</i>, but uses the gtkmm namespace <i>Gtk</i>,
171   so it's actually <i>Gtk::PaperTape</i>.
172<br/>There's a meta header file, <tt>gtkpapertape.h</tt>. Include
173   this file when you want to use the GtkPaperTape widget.</p>
174
175<p>This is an overview of the features of the current generation of
176   <i>GtkPaperTape</i>:</p>
177<ul>
178   <li><b>Gtkmm</b> widget, clean object oriented interface</li>
179   <li>Very big files can be displayed very perfomant, because
180       only the neccessary regions of the paper tapes have to
181       be redrawn (very big = many MB or even GB, only limited
182       by the size of your RAM ;-) )</li>
183   <li>The widget implements a complete <b>Hex editor</b> with
184       all features like copying, moving, deleting, inserting
185       bytes and toggling bits</li>
186   <li>The widget was programed in a model/view/controller
187       fashion. There's an optional statusbar, as well as
188       a complete menu, scrolling, help, mouse interaction, etc.</li>
189   <li>The widget even can generate files and fonts/labels by
190       interacting with the <a href="../schriften/">schriften</a>
191       subproject.</li>
192   <li>Powerful <b>export</b> of picture of the displayed
193       papertape with the current settings to a SVG or PNG file.</li>
194   <li>Zoom, Rotating or directly editing the display matrix is
195       possible</li>
196   <li>All colors can be changed interactively, all components
197       can be switched off and on as you want</li>
198</ul>
199<p>There is still a bug while scrolling over really big paper tapes,
200but I've managed to get solved who's the guilty library: It's a
201Gtk+ bug, commited on <a href="http://bugzilla.gnome.org/show_bug.cgi?id=552672">the GNOME
202bugzilla</a> by me.</p>
203<p>Compared to the widget, there's a quite trivial  and simple
204frontend programm called <tt>gtk.cc</tt> that replaces the old
205<tt>gtk.c</tt>.</p>
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