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	gross	606	\chapter{The module \pyvisi}
2	jongui	879	\label{PYVISI CHAP}
3	jongui	1002	\declaremodule{extension}{esys.pyvisi}
4			\modulesynopsis{Python Visualization Interface}
5	jongui	879
6	gross	999	\section{Introduction}
7	jongui	1002	\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	gross	606
11	jongui	1002	The general rule of thumb when using \pyvisi is to perform the following
12			in sequence:
13	gross	606
14	jongui	1002	\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	gross	999
31	jongui	1002	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	gross	999
42			\section{\pyvisi Classes}
43	jongui	1002	This section gives a brief overview of the important classes and their
44			corresponding methods. Please refer to \ReferenceGuide for full details.
45	gross	999	%=====================================================================================
46			\subsection{Scene Classes}
47	jongui	1002	\begin{classdesc}{Scene}{renderer = Renderer.ONLINE, num_viewport = 1,
48			x_size = 1152, y_size = 864}
49	gross	999	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	jongui	961	on a plane.
88	gross	999	\end{classdesc}
89
90			\begin{classdesc}{MapOnScalarClip}{}
91			Displays a scalar field using a domain surface clipped
92	jongui	961	using a scalar value.
93	gross	999	\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	jongui	961	plane.
106	gross	999	\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	jongui	961	plane.
115	gross	999	\end{classdesc}
116
117			\begin{classdesc}{EllipsoidOnPlaneClip}{}
118			Displays a tensor field using spheres clipped
119	jongui	961	on a plane.
120	gross	999	\end{classdesc}
121
122	jongui	961
123	gross	999	\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	jongui	961	a given plane.
130	gross	999	\end{classdesc}
131
132			\begin{classdesc}{ContourOnClip}{}
133			Shows a scalar field by contour surfaces on
134	jongui	961	a given clip.
135	gross	999	\end{classdesc}
136	jongui	961
137	gross	999	\begin{classdesc}{IsoSurface}{}
138			Shows a scalar field for a given value by
139	jongui	879	an isosurface.
140	gross	999	\end{classdesc}
141
142			\begin{classdesc}{IsoSurfaceOnPlane}{}
143			Shows a scalar field for a given value by
144	jongui	879	an isosurfaceon a given plane.
145	gross	999	\end{classdesc}
146
147			\begin{classdesc}{IsoSurfaceOnClip}{}
148			Shows a scalar field for a given vlaue by
149	jongui	879	an isosurface on a given clip.
150	gross	999	\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	jongui	879	the plane normal.
159	gross	999	\end{classdesc}
160	gross	606
161	gross	999	\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	jongui	1002	%===========================================
188	gross	999
189	jongui	1002	\section{Rendering}
190			same word on rendering, off-line, on-line, how to rotate, zoom, close the window, ...
191	gross	999
192	jongui	1002	%==============================================
193			\section{How to Make a Movie}