| Programmer's Guide |
|
|
|
| The commands are notated here in interactive syntax. Of course, they can also be used in any program file. | Die Kommandos sind hier in interaktiver Syntax notiert. Natürlich können sie auch in jeder Programm-Datei verwendet werden.
|
| Contents | Inhalt |
| Basics | Grundlegendes |
| Creation of Diagrams and Layers | Erzeugung von Diagrammen und Layern |
| Labeling | Beschriftung |
| Rendering | Rendern |
| Clearing | Leerung |
| Limits | Grenzen |
| Tkinter Interface | Tkinter-Schnittstelle |
| Setup | Setup |
| Updating | Aktualisierung |
| Programs with Mainloop | Programme mit Mainloop |
| Handling | Handhabung |
| Save Dialog | Speicherdialog |
| Optional Diagram Functionality | Optionale Diagram-Funktionalität |
| Initialisation | Initialisierung |
| Limit retrieval | Grenzwertabfrage |
| Optional Layer2D Functionality | Optionale Layer2D-Funktionalität |
| Initialisation | Intialisierung |
| Properties | Eigenschaften |
| Optional Layer3D Functionality | Optionale Layer3D-Funktionalität |
| Initialisation | Initialisierung |
| Properties | Eigenschaften
|
| Basics | Grundlegendes |
| Creation of Diagrams and Layers | Erzeugung von Diagrammen und Layern |
| To create a diagram
diagram, write:
| Um eine Diagramm
diagram zu erzeugen, schreibe man:
>>> diagram = diagram_cl.Diagram() |
| That's it basically. There are a number of optional arguments, see Sect. "Optional Arguments" below.
| Das war's im Grunde. Es gibt eine Anzahl optionaler Argumente, siehe dazu Abschn. "Optionale Argumente" unten.
|
| To create a layer for plotting
y vs.
x, use:
| Zur Erzeugung eines Layers zum Plotten von
y vs.
x benutze man:
>>> layer2d = diagram_cl.Layer2D(x = x, y = y)
>>> diagram.add_layer(layer2d) |
| Here, there are numerous optional arguments and differing behaviour. See again below. Using the command given, the graph will be drawn as plusses connected by straight lines, and for many layers the color will be varied automatically through blue, green, red, cyan, yellow, black, ...
| Hier gibt es eine Vielzahl optionaler Argumente und abweichende Verhaltensweisen. Siehe wieder unten. Unter Benutzung des angegebenen Kommandos wird der Layer als Plusse, verbunden durch gerade Linien, gezeichnet werden, und für mehrere Layer wird die Farbe automatisch durch blau, grün, rot, cyan, gelb, schwarz, ... variiert werden.
|
| When plotting twodimensional arrays, use:
| Beim Plotten zweidimensionaler Arrays benutze man:
>>> layer3d = diagram_cl.Layer3D(X = X, Y = Y, C = C)
>>> diagram.add_layer(layer3d) |
| This plots in the gray colormap. Optionally
cmap = 'jet' for the blue-to-red colormap (or, explicitly,
cmap = 'bw' for the black-to-white colormap) can be given.
X and
Y specify the corners of the grid, whose cell values are given by
C.
X and
Y can comprise a mesh grid, but may also be given as simple lists, specifying then the coordinates of the edge lines. For the mesh method and in general for
C, the first coordinate of arrays is along the
y direction. Again, there exist some more optional arguments to the constuctor.
| Dies plottet in der grauen Farbtabelle. Optional kann
cmap = 'jet' für die Blau-nach-Rot Farbtabelle (oder explizit
cmap = 'bw' für die Schwarz-nach-Weiß Farbtabelle) angegeben werden.
X und
Y spezifizieren die Ecken des Gitters, dessen Zellwerte durch
C gegeben werden.
X und
Y können ein Mesh-Gitter bilden, können aber auch als einfache Listen angebenen werden, welche dann die Koordinaten der Kantenlinien angeben. Für die Mesh-Methode und im generellen für
C ist die erste Koordinate von Arrays entlang der
y-Richtung. Wiederum gibt es für den Konstuktor einige optionale Argumente mehr.
|
| Labeling | Beschriftung |
| The title, the
x label and the
y label can be set, here as an example:
| Der Titel, die
x-Beschriftung und die
y-Beschriftung können gesetzt werden, hier als ein Beispiel:
>>> diagram.set_title('This is\na Diagram')
>>> diagram.set_xlabel('abscissa')
>>> diagram.set_ylabel('ordinate') |
| In strings,
'\n' can be used to indicate line breaks. Exercise caution with special charakters like "ö" and similar.
| In Strings kann
'\n' benutzt werden, um Zeilenumbrüche anzuzeigen. Seien Sie vorsichtig mit Sonderzeichen wie "ö" und Ähnlichem.
|
| Rendering | Rendern |
| To render to diagram to an EPS file (Encapsulated PostScript), use the following command:
| Um das Diagramm zu einer EPS-Datei (Encapsulated PostScript) zu rendern, benutze man folgendes Kommando:
>>> diagram.render_to_eps((9, 9), 'diagram.eps') |
| Here,
(9, 9) is the size of the diagram in printout in inches. The given choice is suitable for paperfilling printout on A4 paper. Note that the diagram itself occupies only a fraction of its rendering area, thus the lenghes may be bigger than the actual paper dimensions. The second argument is the output file. When it's existing, it is overwritten without promt.
| Hier ist
(9, 9) die Größe des Diagramms im Ausdruck in Inch. Das angegebene Kommando ist für seitenfüllenden Ausdruck auf A4-Papier genügend. Man beachte daß das Diagramm selbst nur einen Bruchteil seiner Render-Fläche beansprucht, sodaß die Längen größer als die Papierausmaße sein können. Das zweite Argument ist die Ausgabedatei. Existiert sie, wird sie ohne Nachfrage überschrieben.
|
| It is also possible to render to PIL image:
| Es ist auch möglich ein PIL-Bild zu rendern:
>>> image = diagram.render_to_image((300, 300)) |
| The shape
(300, 300) is the pixel extent
(x, y) of the resulting image. Internally, to convert to a length quantity, the default dpi value is used.
| Die Form
(300, 300) ist das Pixelausmaß
(x, y) der resultierenden Bildes. Intern wird zur Konversion in eine Längengröße der Default-dpi-Wert verwendet.
|
| Clearing | Leerung |
| To clear the diagram from all layers, use:
| Um das Diagramm von allen Layern zu befreien, benutze man:
>>> diagram.clear() |
| This erases all layers, but maintains labeling.
| Dies löscht alle Layer, erhält aber die Beschriftung.
|
| Limits | Grenzen |
| Initially, and after clearing, the diagram is in autoscale mode. This means, the viewport limits are always maintained to lie at sensible values and simultaneously contain all data. This behaviour can be overridden:
| Zu Anfang, und nach Leerung, ist das Diagramm im Autoskalierungs-Modus. Das heißt, der Sichtbereich wird stets auf Werte gesetzt, die vernünftig sind und gleichzeitig alle Daten enthalten. Dieses Verhalten kann übergangen werden:
>>> diagram.set_xlim((low, high))
>>> diagram.set_ylim((low, high)) |
| The autoscaling is turned off completely by either command. This should be beared in mind when only one axis shall be constrained, and the other is intended to be still scaled automatically. In this case, call
diagram.render() before setting the lim, then the other direction will be scaled properly. This is for shure a workaround and no solution, though. The problem is on the Todo list for future versions.
| Die Autoskalierung wird durch jeden der beiden Kommandos vollständig ausgeschaltet. Dies sollte man im Gedächtnis behalten, wenn ausschließlich eine Achse eingeschränkt werden soll, und die andere als auto-skaliert beabsichtigt ist. In diesem Falle rufe man
diagram.render() vor Setzung des Limits, dann wird die andere Richtung geeignet skaliert werden. Dies ist mit Sicherheit ein Workaround und keine Lösung. Das Problem ist auf der Todo-Liste für zukünftige Versionen.
|
| The autoscaling can be also turned on or off explicitly in any state:
| Die Autoskalierung kann auch in jedem Zustand an- oder ausgeschaltet werden:
>>> diagram.set_autoscale_on(False)
>>> diagram.set_autoscale_on(True)
|
| Tkinter Interface | Tkinter-Schnittstelle |
| Diagram_cl comes with a class to be used to display
diagram_cl.Diagrams using Tkinter. Setup is done simply be instantiation, and there are a few methods to be used later.
| Diagram_cl wird mit einer Klasse ausgeliefert, die dazu benutzt werden kann,
diagram_cl.Diagramme mit Tkinter anzuzeigen. Das Setup beschränkt sich auf eine einfache Instantiierung, und es gibt ein paar Methoden zur späteren Benutzung.
|
| Setup | Setup |
| Here a sample session with all necessary calls is given, said that a
diagram_cl.Diagram is stored in
diagram. Secondy, you need a master widget, e.g. a
Tkinter.Tk,
Tkinter.Toplevel,
Tkinter.Frame, ..., here assumed to be stored in
master.
| Hier wird eine Beispielsession mit allen notwendigen Aufrufen gegeben, angenommen daß ein
diagram_cl.Diagram in
diagram gespeichert ist. Zweitens benötigen Sie ein Master-Widget, z.B. ein
Tkinter.Tk,
Tkinter.Toplevel,
Tkinter.Frame, ..., hier angenommen in
master gespeichert zu sein.
>>> import diagram_cl.kernels.tk
>>> kernel = diagram_cl.kernels.tk.Diagram(master, diagram) |
| Additionaly, you can supply
shape as
(x, y) extent in pixels:
| Zusätzlich können Sie die
shape als
(x, y)-Ausmaß in Pixeln angeben:
>>> kernel = diagram_cl.kernels.tk.Diagram(master, diagram, shape = (500, 500)) |
| The default extent is
(200, 200).
| Das Default-Ausmaß ist
(200, 200).
|
| Internally, the diagram viewport consists entirely of a
Tkinter.Canvas, which is packed by the following code:
| Intern besteht das Diagramm-Sichtfenster allein aus einem
Tkinter.Canvas, welches mit dem folgenden Code gepackt wird:
self.canvas.pack(expand = True, fill = Tkinter.BOTH) |
| Updating | Aktualisierung |
| When the content has changed, there is no mechanism to update the viewport automatically. You must call then:
| Wenn der Inhalt sich geändert hat, gibt es keinen Mechanismus um das Sichtfenster automatisch zu aktualisieren. Sie müssen dann aufrufen:
>>> kernel.update() |
| Also, the viewport is updated on every redraw event.
| Das Sichtfenster wird auch bei jedem Neuzeichnungs-Ereignis aktualisiert.
|
| Programs with Mainloop | Programme mit Mainloop |
| When your program contains a call to some
.mainloop(), it is important to place somewhere the following call:
| Wenn Sie in Ihrem Programm eine
.mainloop() aufrufen, ist es wichtig, den folgenden Aufruf irgendwo zu tätigen:
>>> diagram_cl.has_mainloop = True |
| Your program may hang up otherwise.
| Ihr Programm kann sich sonst aufhängen.
|
| Handling | Handhabung |
| At the beginning, the diagram is most probably in autozoom mode. To restore autozoom, doubleclick onto the diagram. To pan data, drag with pressed right button. To zoom, drag with pressed left button, the point where you started pan stays thereby invariant. To save the diagram as it is at the moment, doubleclick with right button.
| Zu Anfang ist das Diagramm aller Wahrscheinlichkeit nach im Autozoom-Modus. Um den Autozoom wiederherzustellen, klicken Sie doppelt auf das Diagramm. Um die Daten zu verschieben, ziehen Sie mit gedrückter rechter Maustaste. Um zu vergrößern, ziehen Sie mit gedrückter linker Maustaste, der Punkt, an dem Sie angefangen haben zu ziehen, bleibt dabei an Ort und Stelle. Um das Diagramm wie es im Moment ist zu speichern, doppelklicken Sie mit der rechten Maustaste.
|
| Save Dialog | Speicherdialog |
| The save dialog can also be requested by program using the following call:
| Der Speicher-Dialog kann auch von Programm mit dem folgenden Aufruf angefordert werden:
>>> kernel.open_save_dialog() |
| Supply
title as some string to set the window title of the dialog:
| Setzen Sie
title auf einen String um den Fenstertitel des Dialogs festzulegen:
>>> kernel.open_save_dialog(title = 'My Save Dialog')
|
| Optional Diagram Functionality | Optionale Diagram-Funktionalität |
| Initialisation | Initialisierung |
| The full syntax of
Diagram.__init__() with all optional arguments is:
| Die ganze Syntax von
Diagram.__init__() mit allen optionalen Argumenten ist:
>>> diagram = diagram_cl.Diagram(left = 0.2, bottom = 0.2, right = 0.8, top = 0.8) |
| The diagram's viewport is drawn on an abstract rectangle without length units. Length dimensions only come into play on rendering. Before, unity indicates the top or right edge, and zero the bottom or left edge. With the optional arguments, the position of the viewport for data rendering (the black rectangle in printout) can be positioned on this drawing area. When rendering, always the dimensions of the underlying drawing area and not of the data viewport are set.
| Der Sichtbereich des Diagramms wird auf ein abstraktes Rechteck ohne Längeneinheiten gezeichnet. Längendimensionen kommen erst beim Rendern ins Spiel. Davor bedeutet die Einheit die obere oder rechte Kante, und Null die untere oder linke Kante. Mit den optionalen Argumenten kann die Position des Sichtfensters zum Datenrendern (das schwarze Rechteck im Ausdruck) auf dieser Zeichenfläche positioniert werden. Beim Rendern wird immer die Dimension des darunterliegenden Zeichenbereichs angegeben, und nicht die des Datensichtfensters.
|
| Limit retrieval | Grenzwertabfrage |
| The actual limits can be retrieved by:
| Die momentanen Limiten können abgefragt werden durch:
>>> x_low, x_high = diagram.get_xlim()
>>> y_log, y_high = diagram.get_ylim() |
| The numbers have data units.
Low and
high correspond in fact not to the lower and higher number of both, but to
bottom and
top, or
left and
right respectively. Thus, the direction of an axis can be reversed by specifying a bigger value for
x_low than for
x_high in
set_xlim().
| Die Zahlen haben Datenmaßeinheiten.
Low und
high stehen in Wirklichkeit nicht mit der kleineren und größeren Zahl von beiden in Verbindung, sondern mit
unten und
oben bzw. links und rechts. Daher kann die Richtung einer Achse umgekehrt werden, indem in set_xlim() für x_low ein größerer Wert angegeben wird als für x_high.
|
| Optional Layer2D Functionality | Optionale Layer2D-Funktionalität |
| Initialisation | Intialisierung |
| The following functionality exists:
- Graph format: Use fmt to give the format. By default, fmt = '+-' is used.
- - solid line.
- -- dashed line.
- -. dash-dot line.
- : dotted line.
- . dot symbols.
- , pixel symbols.
- o circle symbols.
- ^, v, <, > triangle up/down/left/right symbols.
- s square symbols.
- + plus symbols.
- x cross symbols.
- D diamond symbols.
- d thin diamond symbols.
- 1, 2, 3, 4 tripod down/up/left/right symbols.
- h hexagon symbols.
- H rotated hexagon symbols.
- p pentagon symbols.
- | vertical line symbols.
- _ horizontal line symbols.
- steps use gnuplot style 'steps' (whatever this means ...; kwarg only (implications unknown))
- Graph color: Specify color, e.g. color = 'blue'. The default is, to use no default, which results in a cycle through the color names below, performed by matplotlib automatically.
- b, blue
- g, green
- r, red
- c, cyan
- m, magenta
- y, yellow
- k, black
- w, white
- '#RRGGBB'
- (red, green, blue) (note: numbers)
- (red, green, blue, alpha) (note: numbers)
- 'greyscale' (note: string representing a number)
- Error specification:
- Use xerrors and/or yerrors.
- Give as x and/or as y objects, which possess a .value and an .error attribute. They may, e.g., be enumber2.ENumbers, but they are not restricted to this class. When using this method, x_en or y_en must be given as True correspondingly to indicate this use of x and y. When using enumber2, this option can be very powerful, at most together with numpy.
- Specify envelope as true, when you want to draw dedicated graphs for the yerror margin points. This works only if the color argument and y errors are given, otherwise the graph will be rendered as if envelope were False (as it is by default). The envelope graphs will by default be drawn with the fmt, but you can specify another format especially for the envelope with fmt_envelope.
| Die folgende Funktionalität ist vorhanden:
- Graph-Format: Benutzen Sie fmt um das Format anzugeben. Als Default wird fmt = '+-' verwendet.
- - durchgezogene Linie.
- -- gestrichelte Linie.
- -. Strich-Punkt-Linie.
- : gepunktete Linie.
- . Punktsymbole.
- , Pixelsymbole.
- o Kreissymbole.
- ^, v, <, > Dreiecksymbole oben/unten/links/rechts.
- s Quadratsymbole.
- + Plussymbole.
- x Kreuzsymbole.
- D Rautensymbole.
- d dünne Rautensymbole.
- 1, 2, 3, 4 Dripodsymbole unten/open/links/rechts.
- h Sechsecksymbole.
- H rotierte Sechsecksymbole.
- p Fünfecksymbole (pentagon).
- | Vertikalliniensymbole.
- _ Horizontalliniensymbole.
- steps Benutzt Gnuplotstil 'steps' (was auch immer das heißen mag ...; nur kwarg (Implikationen unbekannt))
- Graphfarbe: Spezifizieren Sie color, z.B. color = 'blue'. Der Default ist, keinen Default zu benutzen, was in einem Zyklus durch die Farbnamen unten resultiert, welcher von matplotlib durchgeführt wird.
- b, blue, blau
- g, green, grün
- r, red, rot
- c, cyan, cyan
- m, magenta, magenta
- y, yellow, gelb
- k, black, schwarz
- w, white, weiß
- '#RRGGBB'
- (red, green, blue) (Bemerkung: Zahlen)
- (red, green, blue, alpha) (Bemerkung: Zahlen)
- 'greyscale' (Bemerkung: Ein eine Zahl repräsentierender String)
- Fehlerspzifikation:
- Benutzen Sie xerrors und yerrors.
- Geben Sie als x und/oder als y Objekte an, welche ein .value und ein .error Attribut besitzen. Die Objekte können z.B. enumber2.ENumbers sein, sind aber nicht auf diese Klasse beschränkt. Bei Benutzung dieser Methode müssen x_en und y_en entsprechend als True angegeben werden, um diese Benutzung von x und y anzuzeigen. Wird enumber2 benutzt, so kann diese Methode sehr mächtig sein, am meisten zusammen mit numpy.
- Spezifizieren Sie envelope als wahr, wenn Sie dedizierte Graphen für die yerror-Grenzpunkte möchten. Dies funktioniert nur, wenn color und y-Fehler gegeben sind, andernfalls wird der Graph gerendert werden, als sei envelope False (wie es per Default der Fall ist). Die Einhüllenden-Graphen werden per Default mit dem fmt gezeichent, aber Sie können ein anderes Format speziell für die Einhüllenden-Graphen mit fmt_envelope angeben.
|
| Properties | Eigenschaften |
| To alter the
x and
y data after initialisation, use:
| Um die
x- und
y-Daten nach Initialisierung zu ändern, nutze man:
>>> layer.set_x(x, xerrors [= None], x_en [= False])
>>> layer.set_y(y, yerrors [= None], y_en [= False]) |
| Also the format, color and envelope style can be changed later on:
| Auch das Format, die Farbe und der Einhüllenden-Stil können später geändert werden:
>>> layer.set_fmt(fmt, fmt_envelope [= fmt])
>>> layer.set_color(color)
>>> layer.set_envelope(envelope)
|
| Optional Layer3D Functionality | Optionale Layer3D-Funktionalität |
| Initialisation | Initialisierung |
| Following functionality is supplied:
- Alpha: Supply some numeric value in the range 0.0 to 1.0 for alpha. Default value is 1.0 (opaque).
- Shading: Give 'flat' or 'faceted' for shading, for default flat behaviour you can also supply None. With the faceted option selected, black lines are drawn around each rectangle.
- Colormap: Specify cm as either 'bw' (gray, "black and white") or 'jet' (a colormap ranging from blue via yellow to red). Default is black-and-white.
- Displayed Value Range: Supply values for vmin and vmax. The default is None for each, which means, use maximal/minimal value of C.
| Folgende Funktionalität wird bereitgestellt:
- Alpha: Geben Sie einen numerischen Wert im Bereich 0.0 bis 1.0 für alpha an. Default-Wert ist 1.0 (deckend).
- Schattierung: Geben Sie 'flat' oder 'faceted' für shading an, für das default ebene (flat) Verhalten können Sie auch None angeben. Mit der Schraffierungs-Option (faceted) aktiviert werden schwaze Linien um jedes Rechteck gezeichnet.
- Farbtabelle: Spezifizieren Sie cm entweder als 'bw' (grau, "schwarz-weiß -- black and white") oder als 'jet' (eine von Blau über Gelb nach Rot reichende Farbtabelle). Default ist schwarz-weiß.
- Angezeiger Wertebereich: Geben Sie Werte für vmin und vmax. Der Default ist None für jedes der beiden, was bedeutet, den maximalen/minimalen Wert von C zu verwenden.
|
| Properties | Eigenschaften |
| To alter the data displayed after initialisation time, use:
| Um die angezeigten Daten nach dem Initialisierungszeitpunkt zu ändern, benutze man:
>>> layer.set_XYC(X, Y, C)
>>> layer.set_vlim(vmin, vmax) Maintained since: 9/09
$Last changed: 10/09$