doc/user/pyvisi.tex

\chapter{The module \pyvisi}
\label{PYVISI CHAP}
\declaremodule{extension}{esys.pyvisi}
\modulesynopsis{Python Visualization Interface}

\section{Introduction}
\pyvisi is a Python module that is used to generate 2D and 3D visualization 
for escript and its PDE solvers: finley and bruce. This module provides 
an easy to use interface to the \VTK library (\VTKUrl).  

The general rule of thumb when using \pyvisi is to perform the following 
in sequence:

\begin{enumerate}
\item Create a scene instance, in which objects are to be rendered on.
\item Create an input instance, which deals with the source of data for 
the visualization.
\item Create a data visualization instance (i.e. Map, Velocity, Ellipsoid, 
etc), which extracts and manipulates the data accordingly.
\item Create a camera instance, which controls the lighting 
source and view angle.
\item Finally, render the object.
\end{enumerate}
\begin{center}
\begin{math}
scene \rightarrow input \rightarrow visualization \rightarrow 
camera \rightarrow render
\end{math}
\end{center}

The sequence in which instances are created is very important due to
to the dependencies among them. For example, an input instance must 
always be created BEFORE a data visualisation instance is created. 
If the sequence is switched, the program will throw an error because a 
source data needs to be specified before the data can be 
manipulated. Similarly, a camera instance must always be created
AFTER an input instance has been created. Otherwise, the program will throw 
an error because the camera instance needs to calculate its 
default position (automatically carried out in the background) based on 
the source data. 

\section{\pyvisi Classes}
This section gives a brief overview of the important classes and their 
corresponding methods. Please refer to \ReferenceGuide for full details.
%=====================================================================================
\subsection{Scene Classes}
\begin{classdesc}{Scene}{renderer = Renderer.ONLINE, num_viewport = 1, 
x_size = 1152, y_size = 864}
Displays a scene in which objects are to be rendered on.
\end{classdesc}

\begin{classdesc}{Camera}{}
 Controls the camera manipulation. 
\end{classdesc}

\begin{classdesc}{Light}{}
 Controls the light manipulation.
\end{classdesc}

%============================================================================================================
\subsection{Input Classes}

\begin{classdesc}{Image}{}
 Displays an image.
\end{classdesc}

\begin{classdesc}{Text}{}
 Shows some 2D text.
\end{classdesc}

\begin{classdesc}{DataCollector}{}
Deals with the source of data for visualization.
\end{classdesc}

%============================================================================================================
\subsection{Data Visualization}
\begin{classdesc}{Map}{}
 Displays a scalar field using a domain surface.
\end{classdesc}

\begin{classdesc}{MapOnPlaneCut}{}
 Displays a scalar field using a domain surface cut on a plane. 
\end{classdesc}

\begin{classdesc}{MapOnPlaneClip}{}
 Displays a scalar field using a domain surface clipped 
        on a plane.
\end{classdesc}

\begin{classdesc}{MapOnScalarClip}{}
 Displays a scalar field using a domain surface clipped 
        using a scalar value.
\end{classdesc}

\begin{classdesc}{Velocity}{}
 Displays a vector field using arrows.
\end{classdesc}

\begin{classdesc}{VelocityOnPlaneCut}{}
 Displays a vector field using arrows cut on a plane.
\end{classdesc}

\begin{classdesc}{VelocityOnPlaneClip}{}
 Displays a vector field using arrows clipped on a 
        plane.
\end{classdesc}

\begin{classdesc}{Ellipsoid}{}
 Displays a tensor field using spheres.
\end{classdesc}

\begin{classdesc}{EllipsoidOnPlaneCut}{}
 Displays a tensor field using spheres cut on a
        plane.
\end{classdesc}

\begin{classdesc}{EllipsoidOnPlaneClip}{}
 Displays a tensor field using spheres clipped 
        on a plane.
\end{classdesc}

        
\begin{classdesc}{Contour}{}
 Shows a scalar field by contour surfaces. 
\end{classdesc}

\begin{classdesc}{ContourOnPlane}{}
 Shows a scalar field by contour surfaces on 
a given plane.
\end{classdesc}

\begin{classdesc}{ContourOnClip}{}
 Shows a scalar field by contour surfaces on 
a given clip.
\end{classdesc}

\begin{classdesc}{IsoSurface}{}
 Shows a scalar field for a given value by 
an isosurface.
\end{classdesc}

\begin{classdesc}{IsoSurfaceOnPlane}{}
 Shows a scalar field for a given value by 
an isosurfaceon a given plane.
\end{classdesc}

\begin{classdesc}{IsoSurfaceOnClip}{}
 Shows a scalar field for a given vlaue by 
an isosurface on a given clip.
\end{classdesc}

\begin{classdesc}{StreamLines}{}
 Shows the path of particles in a vector field.
\end{classdesc}

\begin{classdesc}{Carpet}{}
 Shows a scalar field as plane deformated along 
the plane normal.
\end{classdesc}

\section{Geometry}
\begin{classdesc}{Position}{}
 Defines the x,y and z coordinates rendered object.
\end{classdesc}

\begin{classdesc}{Transform}{}
Defines the orientation of rendered object.
\end{classdesc}

\begin{classdesc}{Plane}{}
Defines the cutting/clipping of rendered objects.
\end{classdesc}


\subsection{Beautification}
\begin{classdesc}{Style}{}
Defines the style of text.
\end{classdesc}

\begin{classdesc}{BlueToRed}{}
 Defines a map spectrum from blue to red.
\end{classdesc}

\begin{classdesc}{RedToBlue}{}
 Defines a map spectrum from red to blue.
\end{classdesc}
%===========================================

\section{Rendering}
same word on rendering, off-line, on-line, how to rotate, zoom, close the window, ...

%==============================================
\section{How to Make a Movie}
1	\chapter{The module \pyvisi}
2	\label{PYVISI CHAP}
3	\declaremodule{extension}{esys.pyvisi}
4	\modulesynopsis{Python Visualization Interface}
5
6	\section{Introduction}
7	\pyvisi is a Python module that is used to generate 2D and 3D visualization
8	for escript and its PDE solvers: finley and bruce. This module provides
9	an easy to use interface to the \VTK library (\VTKUrl).
10
11	The general rule of thumb when using \pyvisi is to perform the following
12	in sequence:
13
14	\begin{enumerate}
15	\item Create a scene instance, in which objects are to be rendered on.
16	\item Create an input instance, which deals with the source of data for
17	the visualization.
18	\item Create a data visualization instance (i.e. Map, Velocity, Ellipsoid,
19	etc), which extracts and manipulates the data accordingly.
20	\item Create a camera instance, which controls the lighting
21	source and view angle.
22	\item Finally, render the object.
23	\end{enumerate}
24	\begin{center}
25	\begin{math}
26	scene \rightarrow input \rightarrow visualization \rightarrow
27	camera \rightarrow render
28	\end{math}
29	\end{center}
30
31	The sequence in which instances are created is very important due to
32	to the dependencies among them. For example, an input instance must
33	always be created BEFORE a data visualisation instance is created.
34	If the sequence is switched, the program will throw an error because a
35	source data needs to be specified before the data can be
36	manipulated. Similarly, a camera instance must always be created
37	AFTER an input instance has been created. Otherwise, the program will throw
38	an error because the camera instance needs to calculate its
39	default position (automatically carried out in the background) based on
40	the source data.
41
42	\section{\pyvisi Classes}
43	This section gives a brief overview of the important classes and their
44	corresponding methods. Please refer to \ReferenceGuide for full details.
45	%=====================================================================================
46	\subsection{Scene Classes}
47	\begin{classdesc}{Scene}{renderer = Renderer.ONLINE, num_viewport = 1,
48	x_size = 1152, y_size = 864}
49	Displays a scene in which objects are to be rendered on.
50	\end{classdesc}
51
52	\begin{classdesc}{Camera}{}
53	Controls the camera manipulation.
54	\end{classdesc}
55
56	\begin{classdesc}{Light}{}
57	Controls the light manipulation.
58	\end{classdesc}
59
60	%============================================================================================================
61	\subsection{Input Classes}
62
63	\begin{classdesc}{Image}{}
64	Displays an image.
65	\end{classdesc}
66
67	\begin{classdesc}{Text}{}
68	Shows some 2D text.
69	\end{classdesc}
70
71	\begin{classdesc}{DataCollector}{}
72	Deals with the source of data for visualization.
73	\end{classdesc}
74
75	%============================================================================================================
76	\subsection{Data Visualization}
77	\begin{classdesc}{Map}{}
78	Displays a scalar field using a domain surface.
79	\end{classdesc}
80
81	\begin{classdesc}{MapOnPlaneCut}{}
82	Displays a scalar field using a domain surface cut on a plane.
83	\end{classdesc}
84
85	\begin{classdesc}{MapOnPlaneClip}{}
86	Displays a scalar field using a domain surface clipped
87	on a plane.
88	\end{classdesc}
89
90	\begin{classdesc}{MapOnScalarClip}{}
91	Displays a scalar field using a domain surface clipped
92	using a scalar value.
93	\end{classdesc}
94
95	\begin{classdesc}{Velocity}{}
96	Displays a vector field using arrows.
97	\end{classdesc}
98
99	\begin{classdesc}{VelocityOnPlaneCut}{}
100	Displays a vector field using arrows cut on a plane.
101	\end{classdesc}
102
103	\begin{classdesc}{VelocityOnPlaneClip}{}
104	Displays a vector field using arrows clipped on a
105	plane.
106	\end{classdesc}
107
108	\begin{classdesc}{Ellipsoid}{}
109	Displays a tensor field using spheres.
110	\end{classdesc}
111
112	\begin{classdesc}{EllipsoidOnPlaneCut}{}
113	Displays a tensor field using spheres cut on a
114	plane.
115	\end{classdesc}
116
117	\begin{classdesc}{EllipsoidOnPlaneClip}{}
118	Displays a tensor field using spheres clipped
119	on a plane.
120	\end{classdesc}
121
122
123	\begin{classdesc}{Contour}{}
124	Shows a scalar field by contour surfaces.
125	\end{classdesc}
126
127	\begin{classdesc}{ContourOnPlane}{}
128	Shows a scalar field by contour surfaces on
129	a given plane.
130	\end{classdesc}
131
132	\begin{classdesc}{ContourOnClip}{}
133	Shows a scalar field by contour surfaces on
134	a given clip.
135	\end{classdesc}
136
137	\begin{classdesc}{IsoSurface}{}
138	Shows a scalar field for a given value by
139	an isosurface.
140	\end{classdesc}
141
142	\begin{classdesc}{IsoSurfaceOnPlane}{}
143	Shows a scalar field for a given value by
144	an isosurfaceon a given plane.
145	\end{classdesc}
146
147	\begin{classdesc}{IsoSurfaceOnClip}{}
148	Shows a scalar field for a given vlaue by
149	an isosurface on a given clip.
150	\end{classdesc}
151
152	\begin{classdesc}{StreamLines}{}
153	Shows the path of particles in a vector field.
154	\end{classdesc}
155
156	\begin{classdesc}{Carpet}{}
157	Shows a scalar field as plane deformated along
158	the plane normal.
159	\end{classdesc}
160
161	\section{Geometry}
162	\begin{classdesc}{Position}{}
163	Defines the x,y and z coordinates rendered object.
164	\end{classdesc}
165
166	\begin{classdesc}{Transform}{}
167	Defines the orientation of rendered object.
168	\end{classdesc}
169
170	\begin{classdesc}{Plane}{}
171	Defines the cutting/clipping of rendered objects.
172	\end{classdesc}
173
174
175	\subsection{Beautification}
176	\begin{classdesc}{Style}{}
177	Defines the style of text.
178	\end{classdesc}
179
180	\begin{classdesc}{BlueToRed}{}
181	Defines a map spectrum from blue to red.
182	\end{classdesc}
183
184	\begin{classdesc}{RedToBlue}{}
185	Defines a map spectrum from red to blue.
186	\end{classdesc}
187	%===========================================
188
189	\section{Rendering}
190	same word on rendering, off-line, on-line, how to rotate, zoom, close the window, ...
191
192	%==============================================
193	\section{How to Make a Movie}