pyvisi/py_src/scene.py

"""
@var __author__: name of author
@var __copyright__: copyrights
@var __license__: licence agreement
@var __url__: url entry point on documentation
@var __version__: version
@var __date__: date of the version
"""

__author__="John Ngui, john.ngui@uq.edu.au"
__copyright__="""  Copyright (c) 2006 by ACcESS MNRF
                    http://www.access.edu.au
                Primary Business: Queensland, Australia"""
__license__="""Licensed under the Open Software License version 3.0
             http://www.opensource.org/licenses/osl-3.0.php"""
__url__="http://www.iservo.edu.au/esys"
__version__="$Revision$"
__date__="$Date$"


import vtk
from constant import Renderer, Color, Viewport, ImageFormat

class Scene:
    """
    Class that defines a scene. A scene is a window in which objects are to 
    be rendered on. Only one scene needs to be created. However, a scene may 
    be divided into four smaller windows called viewports (if needed). 
    Each viewport can render a different object.  
    """

    def __init__(self, renderer = Renderer.ONLINE, num_viewport = 1, 
            x_size = 1152, y_size = 864):
        """
        Initialise the scene.

        @type renderer: L{Renderer <constant.Renderer>} constant
        @param renderer: Type of renderer 
        @type num_viewport: Number
        @param num_viewport: Number of viewport(s) in the scene. Either 1 or 4 
        @type x_size: Number
        @param x_size: Size of the render window along the x-axis
        @type y_size: Number
        @param y_size: Size of the render window along the y-axis
        """

        self.__renderer = renderer
        self.__num_viewport = num_viewport
        self.__x_size = x_size
        self.__y_size = y_size
        # Stores the visualization modules (i.e. Map, Velocity, Ellipsoid, etc)
        # which needs to be rendered.
        self.__visualization_modules = []

        self.__OFFLINE = "offline"
        self.__VRML = "vrml"
        self.__IV = "iv"
    
        self.__vtk_render_window = vtk.vtkRenderWindow()
        self.__setupScene()
        
    def __setupScene(self):
        """
        Setup the scene.
        """

        self.__createViewport()         
        self.__addRenderer()
        self.setBackground(Color.WHITE) # Default background color is white.


        # Default title bar.
        self.setTitleBar("Earth Systems Science Computational Centre (ESSCC)")
        self.__setSize(self.__x_size, self.__y_size)

        # True for Online rendering.
        if(self.__renderer.startswith(Renderer.ONLINE)): 
            self.__setupOnlineRendering()
            # True for all Online renderers except Renderer.ONLINE.
            if(self.__renderer != Renderer.ONLINE):
                self.__setupWindowToImage()
        # True for Offline rendering.
        elif(self.__renderer.startswith(self.__OFFLINE)): 
            self.__setupOfflineRendering()
            self.__setupWindowToImage()
        # True for Display rendering.
        elif(self.__renderer.startswith(Renderer.DISPLAY)): 
            # True for all Display renderers except Renderer.DISPLAY.
            if(self.__renderer != Renderer.DISPLAY):
                self.__setupWindowToImage()

    def __createViewport(self):
        """
        Create the viewport(s) in the scene.
        """

        # Create the renderer(s) for the viewport(s).
        self.__vtk_renderer = [] 
        for viewport in range(0, self.__num_viewport):
            self.__vtk_renderer.append(vtk.vtkRenderer())
            
        if(self.__num_viewport == 4): 
            # Renderer for the entire scene (background).   
            self.__vtk_renderer_background = vtk.vtkRenderer()

            # Specify the positioning of the four viewports (between 0 and 1).
            self.__vtk_renderer[Viewport.SOUTH_WEST].SetViewport(
                    0.0, 0.0, 0.5, 0.5) 
            self.__vtk_renderer[Viewport.NORTH_WEST].SetViewport(
                    0.0, 0.5013, 0.5, 1)
            self.__vtk_renderer[Viewport.NORTH_EAST].SetViewport(
                    0.501, 0.5013, 1, 1)
            self.__vtk_renderer[Viewport.SOUTH_EAST].SetViewport(
                    0.501, 0.0, 1.0, 0.5)
            
    def setBackground(self, color):
        """
        Set the background color of the scene.

        @type color: L{Color <constant.Color>} constant
        @param color: Scene background color
        """
        
        # Color the entire scene (background) black initially. 
        # This is carried out mainly to have the borders between 
        # the viewports visibly black.
        if(self.__num_viewport == 4): 
            self.__vtk_renderer_background.SetBackground(Color.BLACK)

        for viewport in range(0, self.__num_viewport):
            self.__vtk_renderer[viewport].SetBackground(color)

    def __addRenderer(self):
        """
        Add the renderer(s) to the render window.
        """

        # Add the renderer for the black scene (background).
        if(self.__num_viewport == 4): 
            self.__vtk_render_window.AddRenderer(
                    self.__vtk_renderer_background)

        for viewport in range(0, self.__num_viewport):
            self.__vtk_render_window.AddRenderer(self.__vtk_renderer[viewport])

    def setTitleBar(self, text):
        """
        Set the text on the title bar of the render window.

        @type text: String
        @param text: Text on the title bar
        """

        self.__vtk_render_window.SetWindowName(text)

    def __setSize(self, x_size, y_size):
        """
        Set the size of the render window.

        @type x_size: Number
        @param x_size: Size of the render window along the x-axis
        @type y_size: Number
        @param y_size: Size of the render window along the y-axis
        """

        self.__vtk_render_window.SetSize(x_size, y_size)    

    def __setupOnlineRendering(self):
        """
        Setup the window interactor for online rendering.
        """

        # Associate the window interactor with the render window.
        self.__vtk_render_window_interactor = vtk.vtkRenderWindowInteractor()
        self.__vtk_render_window_interactor.SetRenderWindow(
                self.__vtk_render_window)
        self.__vtk_render_window_interactor.Initialize()

    def __setupOfflineRendering(self):
        """
        Enables the offline rendering (no window comes up).
        """

        # Enables the offscreen rendering.
        self.__vtk_render_window.OffScreenRenderingOn()

    def __setupWindowToImage(self):
        """ 
        Setup the window to image filter to convert the output from the render 
        window into an image.
        """

        self.__vtk_window_to_image = vtk.vtkWindowToImageFilter()
        self.__vtk_window_to_image.SetInput(self.__vtk_render_window)
        self.__vtk_image_writer = self.__getImageWriter()
        
    def __getImageWriter(self):
        """
        Return the appropriate image writer or exporter based on the 
        specified renderer.

        @rtype: vtkImageWriter or vtkExporter
        @return: Image writer or exporter
        """

        if(self.__renderer.endswith(ImageFormat.JPG)):
            return vtk.vtkJPEGWriter() 
        elif(self.__renderer.endswith(ImageFormat.BMP)):
            return vtk.vtkBMPWriter() 
        elif(self.__renderer.endswith(ImageFormat.PNM)):
            return vtk.vtkPNMWriter()
        elif(self.__renderer.endswith(ImageFormat.PNG)):
            return vtk.vtkPNGWriter()
        elif(self.__renderer.endswith(ImageFormat.TIF)):
            return vtk.vtkTIFFWriter()
        elif(self.__renderer.endswith(ImageFormat.PS)):
            return vtk.vtkPostScriptWriter()
        elif(self.__renderer.endswith(self.__VRML)):
            return vtk.vtkVRMLExporter() # Generates VRML files (.wrl).
        elif(self.__renderer.endswith(self.__IV)):
            return vtk.vtkIVExporter() # Generate OpenInventor files (.iv).
    
    def __saveImage(self, image_name):
        """
        Save the rendered object as an image.

        @type image_name: String
        @param image_name: Name of the saved image.
        """

        # NOTE: Render and Modified must be called everytime before writing 
        # an image. Otherwise, only the first image will always be saved.
        # This is due to the architecture of VTK.
        self.__vtk_render_window.Render()
        self.__vtk_window_to_image.Modified()
        
        # Retrieve the rendered object from the window and convert it into an 
        # image.
        # True for all writers besides VRML.
        if(not(self.__renderer.endswith(self.__VRML)) and \
                not(self.__renderer.endswith(self.__IV))): 
            self.__vtk_image_writer.SetInput(
                    self.__vtk_window_to_image.GetOutput())
        # True only for VRML and IV.
        elif(self.__renderer.endswith(self.__VRML) or \
                self.__renderer.endswith(self.__IV)):
            self.__vtk_image_writer.SetInput(
                    self.__vtk_render_window)
        self.__vtk_image_writer.SetFileName(image_name)
        self.__vtk_image_writer.Write()     

    def __animate(self):
        """ 
        Animate the rendered object on-the-fly.
        """

        # With Render() ONLY, the rendered object is animated onto the 
        # scene on-the-fly and no interaction can occur.
        self.__vtk_render_window.Render()

    def render(self, image_name = None):
        """
        Render the object using either the online, offline or display mode.

        @type image_name: String
        @param image_name: Name of the saved image.
        """ 

        for i in range(0, len(self.__visualization_modules)):
            self.__visualization_modules[i]._render(self)   
            self.__vtk_render_window.Render()

        self.__vtk_render_window.Render()

        if(self.__renderer.startswith(Renderer.ONLINE)):
            # NOTE: Once Start() is executed, the driver will not further 
            # execute any subsequent codes thereafter unless the 'q' or 
            # 'e' keys are pressed.
            self.__vtk_render_window_interactor.Start()

            # True for all online renderers except Renderer.ONLINE.
            if(self.__renderer != Renderer.ONLINE):
                self.__saveImage(image_name)                    
        # True for all display renderers except Renderer.DISPLAY.
        elif(self.__renderer.startswith(self.__OFFLINE) or 
                self.__renderer != Renderer.DISPLAY):
            self.__saveImage(image_name)                    
    
    def _addActor3D(self, viewport, actor):
        """
        Add the actor3D to the appropriate viewport.

        @type viewport: L{Viewport <constant.Viewport>} constant 
        @param viewport: Viewport in which the actor3D is to be added to 
        @type actor: vtkActor
        @param actor: Actor3D which is to be added to the viewport 
        """

        self.__vtk_renderer[viewport].AddActor(actor)   

    def _addActor2D(self, viewport, actor):
        """
        Add the actor2D to the appropriate viewport.

        @type viewport: L{Viewport <constant.Viewport>} constant 
        @param viewport: Viewport in which the actor2D is to be added to 
        @type actor: vtkActor2D
        @param actor: Actor2D which is to be added to the viewport 
        """

        self.__vtk_renderer[viewport].AddActor2D(actor) 

    def _setActiveCamera(self, viewport, camera):
        """
        Set the camera to the appropriate viewport. 

        @type viewport: L{Viewport <constant.Viewport>} constant 
        @param viewport: Viewport in which the camera is to be added to 
        @type camera: vtkCamera
        @param camera: Camera which is to be assigned to the viewport
        """

        self.__vtk_renderer[viewport].SetActiveCamera(camera)

    def _addLight(self, viewport, light):
        """
        Add the light to the appropriate viewport.

        @type viewport: L{Viewport <constant.Viewport>} constant 
        @param viewport: Viewport in which the camera is to be added to 
        @type light: vtkLight
        @param light: Light which is to be assigned to the viewport
        """

        self.__vtk_renderer[viewport].AddLight(light)

    def _getRenderer(self):
        """
        Return the renderer(s)

        @rtype: List 
        @return: A list of renderer(s)
        """
    
        return self.__vtk_renderer

    def _addVisualizationModules(self, module):
        """
        Store visualization modules (i.e. Map, Velocity, Ellipsoid, etc) 
        which needs to be rendered.
        
        @type module: Visualization object
        @param module: Visualization object to be rendered
        """

        self.__visualization_modules.append(module)

1	"""
2	@var __author__: name of author
3	@var __copyright__: copyrights
4	@var __license__: licence agreement
5	@var __url__: url entry point on documentation
6	@var __version__: version
7	@var __date__: date of the version
8	"""
9
10	__author__="John Ngui, john.ngui@uq.edu.au"
11	__copyright__=""" Copyright (c) 2006 by ACcESS MNRF
12	http://www.access.edu.au
13	Primary Business: Queensland, Australia"""
14	__license__="""Licensed under the Open Software License version 3.0
15	http://www.opensource.org/licenses/osl-3.0.php"""
16	__url__="http://www.iservo.edu.au/esys"
17	__version__="$Revision$"
18	__date__="$Date$"
19
20
21	import vtk
22	from constant import Renderer, Color, Viewport, ImageFormat
23
24	class Scene:
25	"""
26	Class that defines a scene. A scene is a window in which objects are to
27	be rendered on. Only one scene needs to be created. However, a scene may
28	be divided into four smaller windows called viewports (if needed).
29	Each viewport can render a different object.
30	"""
31
32	def __init__(self, renderer = Renderer.ONLINE, num_viewport = 1,
33	x_size = 1152, y_size = 864):
34	"""
35	Initialise the scene.
36
37	@type renderer: L{Renderer <constant.Renderer>} constant
38	@param renderer: Type of renderer
39	@type num_viewport: Number
40	@param num_viewport: Number of viewport(s) in the scene. Either 1 or 4
41	@type x_size: Number
42	@param x_size: Size of the render window along the x-axis
43	@type y_size: Number
44	@param y_size: Size of the render window along the y-axis
45	"""
46
47	self.__renderer = renderer
48	self.__num_viewport = num_viewport
49	self.__x_size = x_size
50	self.__y_size = y_size
51	# Stores the visualization modules (i.e. Map, Velocity, Ellipsoid, etc)
52	# which needs to be rendered.
53	self.__visualization_modules = []
54
55	self.__OFFLINE = "offline"
56	self.__VRML = "vrml"
57	self.__IV = "iv"
58
59	self.__vtk_render_window = vtk.vtkRenderWindow()
60	self.__setupScene()
61
62	def __setupScene(self):
63	"""
64	Setup the scene.
65	"""
66
67	self.__createViewport()
68	self.__addRenderer()
69	self.setBackground(Color.WHITE) # Default background color is white.
70
71
72	# Default title bar.
73	self.setTitleBar("Earth Systems Science Computational Centre (ESSCC)")
74	self.__setSize(self.__x_size, self.__y_size)
75
76	# True for Online rendering.
77	if(self.__renderer.startswith(Renderer.ONLINE)):
78	self.__setupOnlineRendering()
79	# True for all Online renderers except Renderer.ONLINE.
80	if(self.__renderer != Renderer.ONLINE):
81	self.__setupWindowToImage()
82	# True for Offline rendering.
83	elif(self.__renderer.startswith(self.__OFFLINE)):
84	self.__setupOfflineRendering()
85	self.__setupWindowToImage()
86	# True for Display rendering.
87	elif(self.__renderer.startswith(Renderer.DISPLAY)):
88	# True for all Display renderers except Renderer.DISPLAY.
89	if(self.__renderer != Renderer.DISPLAY):
90	self.__setupWindowToImage()
91
92	def __createViewport(self):
93	"""
94	Create the viewport(s) in the scene.
95	"""
96
97	# Create the renderer(s) for the viewport(s).
98	self.__vtk_renderer = []
99	for viewport in range(0, self.__num_viewport):
100	self.__vtk_renderer.append(vtk.vtkRenderer())
101
102	if(self.__num_viewport == 4):
103	# Renderer for the entire scene (background).
104	self.__vtk_renderer_background = vtk.vtkRenderer()
105
106	# Specify the positioning of the four viewports (between 0 and 1).
107	self.__vtk_renderer[Viewport.SOUTH_WEST].SetViewport(
108	0.0, 0.0, 0.5, 0.5)
109	self.__vtk_renderer[Viewport.NORTH_WEST].SetViewport(
110	0.0, 0.5013, 0.5, 1)
111	self.__vtk_renderer[Viewport.NORTH_EAST].SetViewport(
112	0.501, 0.5013, 1, 1)
113	self.__vtk_renderer[Viewport.SOUTH_EAST].SetViewport(
114	0.501, 0.0, 1.0, 0.5)
115
116	def setBackground(self, color):
117	"""
118	Set the background color of the scene.
119
120	@type color: L{Color <constant.Color>} constant
121	@param color: Scene background color
122	"""
123
124	# Color the entire scene (background) black initially.
125	# This is carried out mainly to have the borders between
126	# the viewports visibly black.
127	if(self.__num_viewport == 4):
128	self.__vtk_renderer_background.SetBackground(Color.BLACK)
129
130	for viewport in range(0, self.__num_viewport):
131	self.__vtk_renderer[viewport].SetBackground(color)
132
133	def __addRenderer(self):
134	"""
135	Add the renderer(s) to the render window.
136	"""
137
138	# Add the renderer for the black scene (background).
139	if(self.__num_viewport == 4):
140	self.__vtk_render_window.AddRenderer(
141	self.__vtk_renderer_background)
142
143	for viewport in range(0, self.__num_viewport):
144	self.__vtk_render_window.AddRenderer(self.__vtk_renderer[viewport])
145
146	def setTitleBar(self, text):
147	"""
148	Set the text on the title bar of the render window.
149
150	@type text: String
151	@param text: Text on the title bar
152	"""
153
154	self.__vtk_render_window.SetWindowName(text)
155
156	def __setSize(self, x_size, y_size):
157	"""
158	Set the size of the render window.
159
160	@type x_size: Number
161	@param x_size: Size of the render window along the x-axis
162	@type y_size: Number
163	@param y_size: Size of the render window along the y-axis
164	"""
165
166	self.__vtk_render_window.SetSize(x_size, y_size)
167
168	def __setupOnlineRendering(self):
169	"""
170	Setup the window interactor for online rendering.
171	"""
172
173	# Associate the window interactor with the render window.
174	self.__vtk_render_window_interactor = vtk.vtkRenderWindowInteractor()
175	self.__vtk_render_window_interactor.SetRenderWindow(
176	self.__vtk_render_window)
177	self.__vtk_render_window_interactor.Initialize()
178
179	def __setupOfflineRendering(self):
180	"""
181	Enables the offline rendering (no window comes up).
182	"""
183
184	# Enables the offscreen rendering.
185	self.__vtk_render_window.OffScreenRenderingOn()
186
187	def __setupWindowToImage(self):
188	"""
189	Setup the window to image filter to convert the output from the render
190	window into an image.
191	"""
192
193	self.__vtk_window_to_image = vtk.vtkWindowToImageFilter()
194	self.__vtk_window_to_image.SetInput(self.__vtk_render_window)
195	self.__vtk_image_writer = self.__getImageWriter()
196
197	def __getImageWriter(self):
198	"""
199	Return the appropriate image writer or exporter based on the
200	specified renderer.
201
202	@rtype: vtkImageWriter or vtkExporter
203	@return: Image writer or exporter
204	"""
205
206	if(self.__renderer.endswith(ImageFormat.JPG)):
207	return vtk.vtkJPEGWriter()
208	elif(self.__renderer.endswith(ImageFormat.BMP)):
209	return vtk.vtkBMPWriter()
210	elif(self.__renderer.endswith(ImageFormat.PNM)):
211	return vtk.vtkPNMWriter()
212	elif(self.__renderer.endswith(ImageFormat.PNG)):
213	return vtk.vtkPNGWriter()
214	elif(self.__renderer.endswith(ImageFormat.TIF)):
215	return vtk.vtkTIFFWriter()
216	elif(self.__renderer.endswith(ImageFormat.PS)):
217	return vtk.vtkPostScriptWriter()
218	elif(self.__renderer.endswith(self.__VRML)):
219	return vtk.vtkVRMLExporter() # Generates VRML files (.wrl).
220	elif(self.__renderer.endswith(self.__IV)):
221	return vtk.vtkIVExporter() # Generate OpenInventor files (.iv).
222
223	def __saveImage(self, image_name):
224	"""
225	Save the rendered object as an image.
226
227	@type image_name: String
228	@param image_name: Name of the saved image.
229	"""
230
231	# NOTE: Render and Modified must be called everytime before writing
232	# an image. Otherwise, only the first image will always be saved.
233	# This is due to the architecture of VTK.
234	self.__vtk_render_window.Render()
235	self.__vtk_window_to_image.Modified()
236
237	# Retrieve the rendered object from the window and convert it into an
238	# image.
239	# True for all writers besides VRML.
240	if(not(self.__renderer.endswith(self.__VRML)) and \
241	not(self.__renderer.endswith(self.__IV))):
242	self.__vtk_image_writer.SetInput(
243	self.__vtk_window_to_image.GetOutput())
244	# True only for VRML and IV.
245	elif(self.__renderer.endswith(self.__VRML) or \
246	self.__renderer.endswith(self.__IV)):
247	self.__vtk_image_writer.SetInput(
248	self.__vtk_render_window)
249	self.__vtk_image_writer.SetFileName(image_name)
250	self.__vtk_image_writer.Write()
251
252	def __animate(self):
253	"""
254	Animate the rendered object on-the-fly.
255	"""
256
257	# With Render() ONLY, the rendered object is animated onto the
258	# scene on-the-fly and no interaction can occur.
259	self.__vtk_render_window.Render()
260
261	def render(self, image_name = None):
262	"""
263	Render the object using either the online, offline or display mode.
264
265	@type image_name: String
266	@param image_name: Name of the saved image.
267	"""
268
269	for i in range(0, len(self.__visualization_modules)):
270	self.__visualization_modules[i]._render(self)
271	self.__vtk_render_window.Render()
272
273	self.__vtk_render_window.Render()
274
275	if(self.__renderer.startswith(Renderer.ONLINE)):
276	# NOTE: Once Start() is executed, the driver will not further
277	# execute any subsequent codes thereafter unless the 'q' or
278	# 'e' keys are pressed.
279	self.__vtk_render_window_interactor.Start()
280
281	# True for all online renderers except Renderer.ONLINE.
282	if(self.__renderer != Renderer.ONLINE):
283	self.__saveImage(image_name)
284	# True for all display renderers except Renderer.DISPLAY.
285	elif(self.__renderer.startswith(self.__OFFLINE) or
286	self.__renderer != Renderer.DISPLAY):
287	self.__saveImage(image_name)
288
289	def _addActor3D(self, viewport, actor):
290	"""
291	Add the actor3D to the appropriate viewport.
292
293	@type viewport: L{Viewport <constant.Viewport>} constant
294	@param viewport: Viewport in which the actor3D is to be added to
295	@type actor: vtkActor
296	@param actor: Actor3D which is to be added to the viewport
297	"""
298
299	self.__vtk_renderer[viewport].AddActor(actor)
300
301	def _addActor2D(self, viewport, actor):
302	"""
303	Add the actor2D to the appropriate viewport.
304
305	@type viewport: L{Viewport <constant.Viewport>} constant
306	@param viewport: Viewport in which the actor2D is to be added to
307	@type actor: vtkActor2D
308	@param actor: Actor2D which is to be added to the viewport
309	"""
310
311	self.__vtk_renderer[viewport].AddActor2D(actor)
312
313	def _setActiveCamera(self, viewport, camera):
314	"""
315	Set the camera to the appropriate viewport.
316
317	@type viewport: L{Viewport <constant.Viewport>} constant
318	@param viewport: Viewport in which the camera is to be added to
319	@type camera: vtkCamera
320	@param camera: Camera which is to be assigned to the viewport
321	"""
322
323	self.__vtk_renderer[viewport].SetActiveCamera(camera)
324
325	def _addLight(self, viewport, light):
326	"""
327	Add the light to the appropriate viewport.
328
329	@type viewport: L{Viewport <constant.Viewport>} constant
330	@param viewport: Viewport in which the camera is to be added to
331	@type light: vtkLight
332	@param light: Light which is to be assigned to the viewport
333	"""
334
335	self.__vtk_renderer[viewport].AddLight(light)
336
337	def _getRenderer(self):
338	"""
339	Return the renderer(s)
340
341	@rtype: List
342	@return: A list of renderer(s)
343	"""
344
345	return self.__vtk_renderer
346
347	def _addVisualizationModules(self, module):
348	"""
349	Store visualization modules (i.e. Map, Velocity, Ellipsoid, etc)
350	which needs to be rendered.
351
352	@type module: Visualization object
353	@param module: Visualization object to be rendered
354	"""
355
356	self.__visualization_modules.append(module)
357