4.2 LiLit Benutzer-Dokumentation

Wir beschreiben nun LiLit in einem einer UNIX-Manualseite ähnlichem Format. Neben dem allgemeinen Programmaufruf stellen wir vor allem auch das ODL-Format vor.

Name
LiLit -- Darstellen und Integrieren von drei-dimensionalen G-Spline-Flächen und Funktionen

Syntax

lilit [-a sens] [-d display] [-e] [-f size] [-i] [-h] [-m sens] [-o] [-v] [-w width] [- -] [- -angle sens] [- -display display] [- -eps] [- -gl] [- -glps-feedsize size] [- -help] [- -iconic] [- -info-width width] [- -move sens] [- -version] odl_file

Beschreibung
LiLit dient im wesentlichen zum Anzeigen und Integrieren von G-Spline-Flächen und darauf definierten Funktionen.
Das Programm liest die Beschreibung für eine Szene aus einer Eingabedatei odl_file im ODL-Format. Diese Datei enthält eine Beschreibung von Grafikobjekten wie Punkte, Polygone, Flächen und Funktionen auf diesen Flächen. Eine Fläche wird dabei durch ein G-Spline-Kontrollnetz beschrieben, welches aus Polygonobjekten zusammengesetzt ist, die wiederum aus Punktobjekten bestehen. Die Funktionen werden über Kontrollpunkte auf den G-Spline-Kontrollnetzen beschrieben. Zusätzlich lassen sich aber auch spezielle Funktionen, wie die Krümmung der Fläche, definieren. Es gibt noch ein paar spezielle Grafikobjekte zur Darstellung der Funktion über Isolinien, etc. Die Datei enthält zusätzlich Befehle zum Anzeigen und Integrieren der Objekte.
Neben den Grafikobjekten enthält die Eingabedatei auch Informationen über Kameraposition und Lichtquellen. Die Kameraposition und Richtung kann interaktiv verändert werden. Es gibt zur Darstellung zwei Anzeigemodi. Im ersten kann die Kamera frei durch den Raum bewegt werden, im zweiten wird nur der Abstand der Kamera vom Ursprung angegeben und die Position der Objekte kann modifiziert werden.
Normalerweise zeigt LiLit die Objekte in einem X11-Fenster an. Eine Kurzbeschreibung der interaktiven Befehle und die Ergebnisse der Integrationen werden in einem zusätzlichen Informationsfenster angezeigt. Es besteht aber auch die Möglichkeit die Szene über den OpenGL-Feedback-Buffer im encapsulated PostScript-Format in einer Datei zu speichern. Der Name dieser Datei wird durch odl_file festgelegt, wobei ein Suffix .odl durch .eps ersetzt wird bzw. einfach .eps an den Dateinamen angehängt wird.

Optionen

-a sens, - -angle sens
Setzt die Sensitivität der Mausbewegungen zum Verändern der Kamerawinkel auf sens. Der default Wert ist .

-d display, - -display display
Setzt das X11-Display, das für die Anzeige der Fenster verwendet wird. Das default Display wird über die Umgebungsvariable DISPLAY festgelegt.

-e, - -eps
Die Objekte aus der ODL-Datei werden mit Hilfe des Feedback-Buffers von OpenGL in eine encapsulated PostScript-Ausgabedatei geschrieben. Die Größe des Feedback-Buffers muß ausreichen, um alle OpenGL-Primitives für die Szene abzulegen.

-f size, - -glps-feedsize size
Setzt die Größe des OpenGL-Feedback-Buffers zum Erzeugen der encapsulated PostScript-Dateien auf size Bytes. Sollte die Größe nicht ausreichen wird pro Ausgabeversuch die Buffergröße jeweils um diesen Wert erhöht, bis nicht mehr genügend Speicher vorhanden ist, oder ein Ausgabeversuch erfolgreich war. Der default Wert ist .

-h, - -help
Druckt eine Kurzbeschreibung des LiLit Syntax' und beendet das Programm.

-i,- -iconic
Beim Starten werden die LiLit Fenster im Icon-Modus geöffnet.

-m sens, - -move sens
Setzt die Sensitivität der Mausbewegungen zum Verändern der Position der Kamera auf sens. Der default Wert ist .

-o, - -gl
Die Objekte aus der ODL-Datei werden mit Hilfe von OpenGL bzw. MesaGL angezeigt. Dies ist die default Einstellung.

-v, - -version
Zeigt Informationen über die LiLit Version an und beendet das Programm.

-w width, - -info-width width
Setzt die Breite des Informationsfensters auf width. Der default Wert ist .

- -
Alle Argumente nach dieser Option werden nicht mehr als Option behandelt, auch wenn sie mit - beginnen. Damit können auch Dateinamen, deren erstes Zeichen - ist, verwendet werden.

Interaktive Bedienung
Im interaktiven Modus von LiLit läßt sich die Kameraposition durch folgende Befehle verändern. Dabei wird im “Eye-Movement-Mode” die Kameraposition und im “Object-Movement-Mode” die Objektposition verändert. Zusätzlich gibt es Tasten zum Festlegen des Anzeigemodus, zum Erzeugen von encapsulated PostScript-Dateien, etc.


Allgemein

Tasten	Mausbewegung	Beschreibung
p	--	Ausgabe der momentanen Szene als encapsulated PostScript-Datei in Farbe.
P	--	Ausgabe der momentanen Szene als encapsulated PostScript-Datei in Graustufen.
q	--	Programm beenden.
e	--	“Eye-Movement-Mode” aktivieren.
o	--	“Object-Movement-Mode” aktivieren.
i	--	Anzeigeparameter zurück auf die Werte der Eingabedatei setzen.

Eye-Movement-Mode

Tasten	Mausbewegung	Beschreibung
j, k	Linke Taste +	Y-Richtung der Kamera verändern.
	Y Bewegung
h, l	Linke Taste +	X-Richtung der Kamera verändern.
	X Bewegung
s, d	Mittlere Taste +	Kamera nach vorne oder hinten bewegen.
	Y Bewegung
a, f	Mittlere Taste +	Kamera nach links oder rechts um die Blickrichtung
	X Bewegung	rotieren.
--	Rechte Taste +	Objekte um die X- und Y-Achse rotieren.
	X/Y Bewegung

Object-Movement-Mode

Tasten	Mausbewegung	Beschreibung
j, k	Linke Taste +	Objekte um die X-Achse rotieren.
	Y Bewegung
h, l	Linke Taste +	Objekte um die Y-Achse rotieren.
	X Bewegung
s, d	Mittlere Taste +	Entfernung der Kamera vom Ursprung vergrößern
	Y Bewegung	oder verkleinern.
a, f	Mittlere Taste +	Objekte um die Z-Achse rotieren.
	X Bewegung
--	Rechte Taste +	Objekte um die X- und Y-Achse rotieren.
	X/Y Bewegung

ODL-Format
Eine ODL-Datei^4.12besteht aus einer Reihe von Objektbeschreibungen und Befehlen zur Bestimmung der Anzeigeparameter. Dabei spielt die Reihenfolge keine Rolle. Allerdings müssen Objektbezeichner, die von Befehlen oder anderen Objektbeschreibungen benötigt werden, vorher eingeführt worden sein.
Eine Objektbeschreibung sieht allgemein wie folgt aus:



Diese Objekte können dann mit folgenden Befehlen angezeigt und integriert werden:





Mit render wird das Objekt gerendert. integrate_s ist das Oberflächenintegral für Skalarfelder, integrate_v das Oberflächenintegral für Vektorfelder, area berechnet den Flächeninhalt und volume das Volumen geschlossener Flächen. Die Integrale müssen für die Objekte sinnvoll sein. Die Parameter maxiter und prec geben die maximale Anzahl der Iterationen und die Genauigkeit pro Flächenstück an.
Die Kameraposition und der Anzeigemodus (object oder eye) werden durch folgenden Befehl festgelegt. Er legt gleichzeitig die Parameter für beide Anzeigemodi fest, wählt aber einen als default aus.

viewmode eye|object Kamera_Azimuth Kamera_Elevation Kamera_X Kamera_Y Kamera_Z Objekt_Azimuth Objekt_Elevation Objekt_Abstand

Die Projektionsmethode wird durch einen der folgenden Befehle festgelegt:

orthographic Limit_links Limit_rechts Limit_unten Limit_oben Limit_nah Limit_fern

perspective Winkel Aspect Limit_nah Limit_fern

Per default wird der Beobachtungspunkt der Kamera als unendlich angesehen. Mit folgendem Befehl wird ein lokaler Beobachtungspunkt eingeführt:





Objekte können mit den Befehlen







verschoben, rotiert und skaliert werden.
Das X11-Fenster wird definiert durch





Die Hintergrundfarbe und der Wert für die ambient Lichtquelle wird durch





gesetzt. Die Größe eines einzelnen Punktes wird gesetzt durch

point_size Punktgröße

Mit





wird die Genauigkeit zum Bestimmen von Null-Werten, etc. festgelegt.
Objekte werden durch Eigenschaften genauer beschrieben. Dabei gibt es eine Reihe von Eigenschaften, die jedes Objekt unabhängig vom Typ besitzt. Andere können nur bei bestimmten Objekttypen angegeben werden. Die Objektstruktur ist dabei hierarchisch, d.h. eine Funktion enthält einen Verweis auf eine Fläche, eine Fläche enthält eine Liste von Polygonen und diese wiederum enthalten Verweise auf Punkte. Dabei ist auch zu beachten, daß für Kontrollnetze für den gleichen Punkt, das gleiche Punktobjekt benutzt werden muß. Ansonsten wird angenommen, daß es sich um zwei verschiedene Punkte handelt, auch wenn die Position gleich ist.
Unabhängig vom Objekttyp wird ein einzelnes Objekt mit den Standardeigenschaften wie folgt definiert:





location, translate, scale und rotate geben dabei die Position, die Translation, die Skalierung und die Rotation bzgl. der -, - und -Achse an. Die Position hat natürlich bei Objekten mit Kontrollnetz, etc. keine Bedeutung, sondern wird durch die Punkte der Teilobjekte festgelegt. ambient, diffuse, specular, emission und shininess geben die Materialeigenschaften des Objekts an. Es wird hierzu das Lichtmodell von OpenGL verwendet. Der Alpha-Kanal wird zum Erzeugen von teilweise transparenten Materialien verwendet. resolution legt die Auflösung fest, mit der das Objekt gezeichnet wird. Die Auflösung gibt dabei die univariate Anzahl der Unterteilungen der zur Berechnung benötigten Gitter an. Die Reihenfolge der Eigenschaften ist nicht wichtig. Für manche existieren default Werte, so daß sie weggelassen werden können. Weitere Eigenschaftstypen werden durch den Objekttyp festgelegt. Dabei stehen point, polygon, gspline, function, isoline und light zur Verfügung.
point definiert einen Punkt. Dieser hat keine weiteren Eigenschaften. Allerdings läßt sich ein Punktobjekt vereinfacht nur über die Position durch





definieren.
Ein Polygon wird durch





definiert. Die PunktbezeichnerX geben die Eckpunkte des Polygons an. Die Reihenfolge der Punkte und damit die Orientierung wird umgedreht, wenn reverse_orientation angegeben ist.
Eine biquadratische G-Spline-Fläche gspline wird über ein entsprechendes Kontrollnetz definiert:






Die PolygonbezeichnerX geben die Polygone des Kontrollnetzes an. Die Befehle trim_func, trim_ball und trim_ellipsoid definieren implizit ein Trimmobjekt im Raum. Mit trim_curve und trim_polygon werden lineare bzw. quadratische Trimmkurven im Parameterbereich definiert. Der Punktbezeichner gibt dabei an, für welche Bézierfläche, deren mittlerer Kontrollpunkt zu diesem Bezeichner gehört, die Trimmkurve angewendet wird. trimlevel gibt die maximale Rekursionstiefe für die Trimmalgorithmen an. doosabin legt die Anzahl der Doo-Sabin-Subdivisionen auf dem Kontrollnetz fest. Mit doosabin_draw kann man alle oder nur die letzte Stufe der Subdivision darstellen lassen. Wird der optionale Parameter grid angegeben, werden nur die Kontrollnetze und nicht die Fläche selbst angezeigt. Mit doosabin_color kann man die Farbe der Kontrollnetze festlegen. Mit reverse_orientation wird die Orientierung des Kontrollnetzes und damit auch die der Fläche umgedreht.
Eine Funktion auf einer G-Spline-Fläche wird wie folgt definiert:





Der G-Spline-Bezeichner verweist auf die Fläche, auf der die Funktion definiert ist. Über map wird jedem Kontrollpunkt der Fläche ein Funktionskontrollpunkt zugewiesen. Natürlich müssen alle Flächenkontrollpunkte in der Liste vorkommen. Alternativ kann man über curvature eine Krümmungsfunktion definieren. H steht für die Gaußkrümmung, K für die mittlere Krümmung, min für die kleinste Hauptkrümmung, max für die größte Hauptkrümmung und square für die quadrierte Länge des Hauptkrümmungsvektors. fscale gibt einen Skalierungsfaktor für die gesamte Funktion an. coldelta und colscale geben die Verschiebungs- und Skalierungsfaktoren für die Farbdarstellung an. Mit display kann man schließlich festlegen welche Darstellungsarten verwendet werden sollen. color stellt die Funktion farbig auf der Fläche dar, colorf stellt sie als farbige Fläche über der Fläche dar, grid als Gitter über der Fläche, spikes als Stacheln auf der Fläche und vectors stellt drei-dimensionale Vektorfelder durch Vektoren dar.
Isolinien werden wie folgt definiert:





G-Spline-Bezeichner gibt die G-Spline-Fläche an, auf der die Isolinien gezeichnet werden sollen. function gibt die Funktion an, für die die Isolinien gezeichnet werden sollen. Alternativ kann man Reflektionslinien mit reflection verwenden. base und isostep geben einen Wert und den Abstand zwischen den Werten für kontinuierliche Isolinien an. Alternativ kann man einzelne Werte mit levels festlegen. maxlevel legt die maximale Rekursionstiefe des Algorithmus' fest. maxlines gibt die maximale Anzahl der Isolinien an, die bei bilinearer Interpolation pro Gitterquadrat gezeichnet werden. Mit raise kann man die Isolinien um den angegebenen Faktor entlang der Normalen über oder unter die Fläche schieben. Wird color_lines angegeben, werden die Isolinien farbig gezeichnet. Die Farben werden mittels coldelta und colscale in Abhängigkeit von dem Funktionswert festgelegt.
Eine Lichtquelle wird definiert durch





Eine Lichtquelle besitzt keine Bezeichner. Es ist allerdings zu beachten, daß OpenGL nur Lichtquellen zuläßt. Die Parameter entsprechen den OpenGL-Parametern zur Spezifikation von Lichtquellen. Die Spotlight-Parameter werden über spot_direction, spot_exponent und spot_cutoff bestimmt. Die Dämpfung des Lichts wird durch constant_attenuation, linear_attenuation und quadratic_attenuation festgelegt. Ein gerichtetes Licht wird über direction eingeführt.
Kommentare in ODL-Dateien beginnen mit einem # und werden immer durch das Zeilenende beendet.

ODL BNF
Das ODL-Format kann auch in BNF (Backus-Naur-Form) dargestellt werden. Im folgenden werden jedoch die unterschiedlichen Eigenschaften für verschiedene Objekttypen nicht berücksichtigt. Zur Vereinfachung werden sie alle durch prop_value repräsentiert. Das Startsymbol ist <odl>. Ein <ident> ist ein Bezeichner und <real> eine reelle Zahl.

<odl>

::=

| <decl> <odl>

<decl>

::=

<render>

| <integrate>

| <view>

| <light>

| <point>

| <polygon>

| <gspline>

| <function>

| <isoline>

| window <ident> <real> <real> <real> <real>

| orthographic <real> <real> <real> <real> <real>

<real>

| perspective <real> <real> <real> <real>

| local_viewer

| ambient_light <vector4>

| background <vector4>

| translate <vector3>

| rotate <vector3>

| scale <vector3>

| point_size <real>

| epsilon <real>

<render>

::=

render <ident>

<integrate>

::=

integrate_s <ident> <real> <real>

| integrate_v <ident> <real> <real>

| area <ident> <real> <real>

| volume <ident> <real> <real>

<view>

::=

viewmode <mmode> <real> <real> <real> <real>

<real> <real> <real> <real>

<mmode>

::=

object | eye

<light>

::=

light { <prop> }

<point>

::=

point <ident> <vector3>

| point <ident> { <prop> }

<polygon>

::=

polygon <ident> { <prop> }

<gspline>

::=

gspline <ident> { <prop> }

<function>

::=

function <ident> { <prop> }

<isoline>

::=

isoline <ident> { <prop> }

<prop>

::=

| <prop_value> <prop>

<prop_value>

::=

ambient <vector4>

| base <real>

| color_lines

| coldelta <real>

| colscale <real>

| constant_attenuation <real>

| curvature H

| curvature K

| curvature max

| curvature min

| curvature square

| diffuse <vector4>

| direction <vector3>

| display <display_mode>

| doosabin <real>

| doosabin_color <vector4>

| doosabin_draw all

| doosabin_draw last

| doosabin_draw grid all

| doosabin_draw grid last

| emission <vector4>

| function <ident>

| fscale <real>

| levels { <reallist> }

| linear_attenuation <real>

| location <vector3>

| maxlevel <real>

| maxlines <real>

| quadratic_attenuation <real>

| map { <map_desc> }

| raise <real>

| reflection <vector3> <vector3> <vector3> <vector3>

| resolution <real>

| reverse_orientation

| rotate <vector3>

| scale <vector3>

| shininess <real>

| specular <vector4>

| spot_cutoff <real>

| spot_direction <vector3>

| spot_exponent <real>

| step <real>

| translate <vector3>

| trim_ball <real> <real> <real> <real>

| trim_curve { <ident> <trimcurve_desc> }

| trim_ellipsoid <real> <real> <real> <real>

<real> <real>

| trim_func <real> <real> <real> <real> <real>

<real> <real> <real> <real> <real> <real>

<real> <real>

| trim_polygon { <ident> <trimcurve_desc> }

| trimlevel <real>

| <ident>

<display_mode>

::=

color <x_display_mode>

| colorf <x_display_mode>

| grid <x_display_mode>

| spikes <x_display_mode>

| vectors <x_display_mode>

<x_display_mode>

::=

| color <x_display_mode>

| colorf <x_display_mode>

| grid <x_display_mode>

| spikes <x_display_mode>

| vectors <x_display_mode>

<trimcurve_desc>

::=

| <vector2> <trimcurve_desc>

<map_desc>

::=

| <ident> : <reallist> <map_desc>

<reallist>

::=

<real> | <real> , <reallist>

<vector2>

::=

"<" <real> , <real> ">"

<vector3>

::=

"<" <real> , <real> , <real> ">"

<vector4>

::=

"<" <real> , <real> , <real> , <real> ">"

Beispiel
Folgende ODL-Datei definiert ein Möbiusband über Polygone mit Hilfe der Doo-Sabin-Subdivision. Zusätzlich wird eine Funktion auf dem Möbiusband definiert. Die Funktion wird durch color angezeigt und sowohl der Flächeninhalt als auch das Oberflächenintegral der Funktion wird berechnet.

# moebius.odl: Möbiusband.

point p_1_0 <0,2,0>
point p_2_0 <2,0,0>
point p_3_0 <5,2,2>
point p_4_0 <2,4,0>

point p_1_1 <0,2,2>
point p_2_1 <2,0,2>
point p_3_1 <4,2,2>
point p_4_1 <2,4,2>

point p_1_2 <0,2,4>
point p_2_2 <2,0,4>
point p_3_2 <3,2,2>
point p_4_2 <2,4,4>

polygon P1_0 {
  p_1_0 p_2_0 p_2_1 p_1_1
  ambient <0.0,0.0,0.0,1.0>
}
polygon P2_0 {
  p_2_0 p_3_0 p_3_1 p_2_1
  ambient <0.0,0.0,0.0,1.0>
}
polygon P3_0 {
  p_3_0 p_3_1 p_4_1 p_4_2
  ambient <0.0,0.0,0.0,1.0>
}
polygon P4_0 {
  p_4_2 p_4_1 p_1_1 p_1_2
  ambient <0.0,0.0,0.0,1.0>
}

polygon P1_1 {
  p_1_1 p_2_1 p_2_2 p_1_2
  ambient <0.0,0.0,0.0,1.0>
}
polygon P2_1 {
  p_2_2 p_2_1 p_3_1 p_3_2
  ambient <0.0,0.0,0.0,1.0>
}
polygon P3_1 {
  p_3_2 p_3_1 p_4_1 p_4_0
  ambient <0.0,0.0,0.0,1.0>
}
polygon P4_1 {
  p_4_1 p_4_0 p_1_0 p_1_1
  ambient <0.0,0.0,0.0,1.0>
}       

gspline gs {
  P1_0 P2_0 P3_0 P4_0
  P1_1 P2_1 P3_1 P4_1
  shininess 0.5
  diffuse   <0.65,0.0,0.0,1.0>
  ambient   <0.5,0.0,0.0,1.0>
  specular  <1.0,0.6,0.6,1.0>
  location  <0,0,0>
  resolution 8
  reverse_orientation
  doosabin 2
  # doosabin_draw grid last
  # doosabin_color <0.0,0.0,0.0,1.0>
}

function func {
  gs
  map {
    p_1_0:4
    p_2_0:4
    p_3_0:9
    p_4_0:4
    p_1_1:4
    p_2_1:4
    p_3_1:4
    p_4_1:4
    p_1_2:4
    p_2_2:4
    p_3_2:1
    p_4_2:4
  }
  shininess 1.0
  diffuse <1.0,1.0,1.0,1.0>
  ambient <1.0,1.0,1.0,1.0>
  specular <1.0,1.0,1.0,1.0>
  emission <0.0,0.0,0.0,0.0>
  resolution 10
  colscale 0.7
  coldelta -0.6
  display color
  # display grid spikes colorf
  fscale 1
}

light {
  ambient <1.0,1.0,1.0,1.0>
  diffuse <1.0,1.0,1.0,1.0>
  specular <1.0,1.0,1.0,1.0>
  location <2,-1,4>
  constant_attenuation 1.0
  linear_attenuation 0.25
  quadratic_attenuation 0.015
}

window Moebiusband 0 0 500 500

background <1.0, 1.0, 1.0, 1.0>
ambient_light <0.4, 0.4, 0.4, 1.0>

viewmode eye 65.0 10 8 1 5.5 0 0 1
perspective 35.0 1.0 0.01 100.0

# render gs
render func

area gs 50 0.000015625
integrate_s func 50 0.000015625