pyvisi/py_src/camera.py


########################################################
#
# Copyright (c) 2003-2008 by University of Queensland
# Earth Systems Science Computational Center (ESSCC)
# http://www.uq.edu.au/esscc
#
# Primary Business: Queensland, Australia
# Licensed under the Open Software License version 3.0
# http://www.opensource.org/licenses/osl-3.0.php
#
########################################################

__copyright__="""Copyright (c) 2003-2008 by University of Queensland
Earth Systems Science Computational Center (ESSCC)
http://www.uq.edu.au/esscc
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.uq.edu.au/esscc/escript-finley"

"""
@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"


import vtk
from position import GlobalPosition
from constant import Viewport

class Camera:
    """
    Class that defines a camera. A camera controls the display angle of
    the rendered object and one is usually created for a
    L{Scene <scene.Scene>}. However, if a L{Scene <scene.Scene>} has four
    viewports, then a separate camera may be created for each viewport.
    """

    # The SOUTH_WEST default viewport is used when there is only one viewport.
    # This saves the user from specifying the viewport when there is only one.
    def __init__(self, scene, viewport = Viewport.SOUTH_WEST):
        """
        Initialise the camera.

        @type scene: L{Scene <scene.Scene>} object
        @param scene: Scene in which objects are to be rendered on
        @type viewport: L{Viewport <constant.Viewport>} constant
        @param viewport: Viewport in which objects are to be rendered on
        """

        self.__viewport = viewport
        self.__vtk_camera = vtk.vtkCamera()

        # Keeps track whether camera has been modified.
        self.__modified = True 
        # Keeps track whether the modification to the camera was due to the 
        # instantiation. If it is, then __setupCamera() method is called.
        self.__initialization = True
        scene._addVisualizationModules(self)

    def __setupCamera(self, scene):
        """
        Setup the camera.

        @type scene: L{Scene <scene.Scene>} object
        @param scene: Scene in which objects are to be rendered on
        """

        # Assign the camera to the appropriate renderer
        scene._setActiveCamera(self.__viewport, self.__vtk_camera)
        self.__resetCamera(scene)   

    def setFocalPoint(self, position):
        """
        Set the focal point of the camera.

        @type position: L{GlobalPosition <position.GlobalPosition>} object
        @param position: Camera focal point
        """

        self.__vtk_camera.SetFocalPoint(position._getGlobalPosition())      
        self.__modified = True 

    def setPosition(self, position):
        """
        Set the position of the camera.

        @type position: L{GlobalPosition <position.GlobalPosition>} object
        @param position: Camera position
        """

        self.__vtk_camera.SetPosition(position._getGlobalPosition())
        self.__modified = True 

    def setClippingRange(self, near_clipping, far_clipping):
        """
        Set the near and far clipping plane of the camera.

        @type near_clipping: Number
        @param near_clipping: Distance to the near clipping plane
        @type far_clipping: Number
        @param far_clipping: Distance to the far clipping plane
        """
    
        self.__vtk_camera.SetClippingRange(near_clipping, far_clipping)

    def setViewUp(self, position):
        """
        Set the view up direction of the camera.

        @type position: L{GlobalPosition <position.GlobalPosition>} object
        @param position: Camera view up direction
        """

        self.__vtk_camera.SetViewUp(position._getGlobalPosition())

    def azimuth(self, angle):
        """
        Rotate the camera to the left and right.

        @type angle: Number
        @param angle: Degree to rotate the camera
        """

        self.__vtk_camera.Azimuth(angle)
        self.__modified = True 

    def elevation(self, angle):
        """
        Rotate the camera to the top and bottom.
        
        @type angle: Number
        @param angle: Degree to rotate the camera (only between -90 and 90)
        """

        self.__vtk_camera.Elevation(angle)
        # Recompute the view up vector. If not used the elevation angle is  
        # unable to exceed 87/-87 degrees. A warning resetting the
        # view up will also be thrown and the rendered object may be incorrect.
        # With the view up recomputed, the elevation angle can reach between
        # 90/-90 degrees. Exceeding that, the rendered object may be incorrect.
        self.__vtk_camera.OrthogonalizeViewUp()
        self.__modified = True 

    def roll(self, angle):
        """
        Roll the camera to the left and right.

        @type angle: Number
        @param angle: Degree to roll the camera
        """

        self.__vtk_camera.Roll(-angle)
        self.__modified = True 

    def backView(self):
        """
        Rotate the camera to view the back of the rendered object.
        """

        self.azimuth(180)

    def topView(self):
        """
        Rotate the camera to view the top of the rendered object.
        """
        
        self.elevation(90)

    def bottomView(self):
        """
        Rotate the camera to view the bottom of the rendered object.
        """

        self.elevation(-90)

    def leftView(self):
        """
        Rotate the camera to view the left side of the rendered object.
        """

        self.azimuth(-90)

    def rightView(self):
        """
        Rotate the camera to view the right side of the rendered object.
        """

        self.azimuth(90)

    def isometricView(self):
        """
        Rotate the camera to view the isometric angle of the rendered object.
        """

        self.roll(-45)
        self.elevation(-45)
        
    def dolly(self, distance):
        """
        Move the camera towards (greater than 1) the rendered object. However,
        the camera is unable to be moved away from the rendered object.

        @type distance: Number
        @param distance: Amount to move towards the rendered object
        """

        self.__vtk_camera.Dolly(distance)
        self.__modified = True 

    def parallelProjectionOn(self):
        """
        Enable camera parallel projection.
        """

        self.__vtk_camera.ParallelProjectionOn()
        self.__modified = True 

    def parallelProjectionOff(self):
        """
        Disable camera parallel projection.
        """

        self.__vtk_camera.ParallelProjectionOff()
        self.__modified = True

    def __resetCameraClippingRange(self, scene):
        """
        Reset the camera clipping range based on the bounds of the visible 
        actors. This ensures the rendered object is not cut-off.
        Needs to be called whenever the camera's settings are modified.

        @type scene: L{Scene <scene.Scene>} object
        @param scene: Scene in which objects are to be rendered on
        """

        scene._getRenderer()[self.__viewport].ResetCameraClippingRange() 

    def __resetCamera(self, scene):
        """
        Repositions the camera to view the center point of the actors.

        @type scene: L{Scene <scene.Scene>} object
        @param scene: Scene in which objects are to be rendered on
        """

        scene._getRenderer()[self.__viewport].ResetCamera() 

    def _isModified(self):
        """
        Return whether the Camera has been modified.

        @rtype: Boolean
        @return: True or False
        """

        if (self.__modified == True):
            return True
        else:
            return False

    def _render(self, scene):
        """
        Render the camera.

        @type scene: L{Scene <scene.Scene>} object
        @param scene: Scene in which objects are to be rendered on
        """

        if(self._isModified() == True):
            # Will only be true once only when the camera is instantiated.
            if(self.__initialization == True): 
                self.__setupCamera(scene)
                self.__initialization == False

            self.__resetCameraClippingRange(scene)
            self.__modified = False
            

1
2	########################################################
3	#
4	# Copyright (c) 2003-2008 by University of Queensland
5	# Earth Systems Science Computational Center (ESSCC)
6	# http://www.uq.edu.au/esscc
7	#
8	# Primary Business: Queensland, Australia
9	# Licensed under the Open Software License version 3.0
10	# http://www.opensource.org/licenses/osl-3.0.php
11	#
12	########################################################
13
14	__copyright__="""Copyright (c) 2003-2008 by University of Queensland
15	Earth Systems Science Computational Center (ESSCC)
16	http://www.uq.edu.au/esscc
17	Primary Business: Queensland, Australia"""
18	__license__="""Licensed under the Open Software License version 3.0
19	http://www.opensource.org/licenses/osl-3.0.php"""
20	__url__="http://www.uq.edu.au/esscc/escript-finley"
21
22	"""
23	@var __author__: name of author
24	@var __copyright__: copyrights
25	@var __license__: licence agreement
26	@var __url__: url entry point on documentation
27	@var __version__: version
28	@var __date__: date of the version
29	"""
30
31	__author__="John Ngui, john.ngui@uq.edu.au"
32
33
34	import vtk
35	from position import GlobalPosition
36	from constant import Viewport
37
38	class Camera:
39	"""
40	Class that defines a camera. A camera controls the display angle of
41	the rendered object and one is usually created for a
42	L{Scene <scene.Scene>}. However, if a L{Scene <scene.Scene>} has four
43	viewports, then a separate camera may be created for each viewport.
44	"""
45
46	# The SOUTH_WEST default viewport is used when there is only one viewport.
47	# This saves the user from specifying the viewport when there is only one.
48	def __init__(self, scene, viewport = Viewport.SOUTH_WEST):
49	"""
50	Initialise the camera.
51
52	@type scene: L{Scene <scene.Scene>} object
53	@param scene: Scene in which objects are to be rendered on
54	@type viewport: L{Viewport <constant.Viewport>} constant
55	@param viewport: Viewport in which objects are to be rendered on
56	"""
57
58	self.__viewport = viewport
59	self.__vtk_camera = vtk.vtkCamera()
60
61	# Keeps track whether camera has been modified.
62	self.__modified = True
63	# Keeps track whether the modification to the camera was due to the
64	# instantiation. If it is, then __setupCamera() method is called.
65	self.__initialization = True
66	scene._addVisualizationModules(self)
67
68	def __setupCamera(self, scene):
69	"""
70	Setup the camera.
71
72	@type scene: L{Scene <scene.Scene>} object
73	@param scene: Scene in which objects are to be rendered on
74	"""
75
76	# Assign the camera to the appropriate renderer
77	scene._setActiveCamera(self.__viewport, self.__vtk_camera)
78	self.__resetCamera(scene)
79
80	def setFocalPoint(self, position):
81	"""
82	Set the focal point of the camera.
83
84	@type position: L{GlobalPosition <position.GlobalPosition>} object
85	@param position: Camera focal point
86	"""
87
88	self.__vtk_camera.SetFocalPoint(position._getGlobalPosition())
89	self.__modified = True
90
91	def setPosition(self, position):
92	"""
93	Set the position of the camera.
94
95	@type position: L{GlobalPosition <position.GlobalPosition>} object
96	@param position: Camera position
97	"""
98
99	self.__vtk_camera.SetPosition(position._getGlobalPosition())
100	self.__modified = True
101
102	def setClippingRange(self, near_clipping, far_clipping):
103	"""
104	Set the near and far clipping plane of the camera.
105
106	@type near_clipping: Number
107	@param near_clipping: Distance to the near clipping plane
108	@type far_clipping: Number
109	@param far_clipping: Distance to the far clipping plane
110	"""
111
112	self.__vtk_camera.SetClippingRange(near_clipping, far_clipping)
113
114	def setViewUp(self, position):
115	"""
116	Set the view up direction of the camera.
117
118	@type position: L{GlobalPosition <position.GlobalPosition>} object
119	@param position: Camera view up direction
120	"""
121
122	self.__vtk_camera.SetViewUp(position._getGlobalPosition())
123
124	def azimuth(self, angle):
125	"""
126	Rotate the camera to the left and right.
127
128	@type angle: Number
129	@param angle: Degree to rotate the camera
130	"""
131
132	self.__vtk_camera.Azimuth(angle)
133	self.__modified = True
134
135	def elevation(self, angle):
136	"""
137	Rotate the camera to the top and bottom.
138
139	@type angle: Number
140	@param angle: Degree to rotate the camera (only between -90 and 90)
141	"""
142
143	self.__vtk_camera.Elevation(angle)
144	# Recompute the view up vector. If not used the elevation angle is
145	# unable to exceed 87/-87 degrees. A warning resetting the
146	# view up will also be thrown and the rendered object may be incorrect.
147	# With the view up recomputed, the elevation angle can reach between
148	# 90/-90 degrees. Exceeding that, the rendered object may be incorrect.
149	self.__vtk_camera.OrthogonalizeViewUp()
150	self.__modified = True
151
152	def roll(self, angle):
153	"""
154	Roll the camera to the left and right.
155
156	@type angle: Number
157	@param angle: Degree to roll the camera
158	"""
159
160	self.__vtk_camera.Roll(-angle)
161	self.__modified = True
162
163	def backView(self):
164	"""
165	Rotate the camera to view the back of the rendered object.
166	"""
167
168	self.azimuth(180)
169
170	def topView(self):
171	"""
172	Rotate the camera to view the top of the rendered object.
173	"""
174
175	self.elevation(90)
176
177	def bottomView(self):
178	"""
179	Rotate the camera to view the bottom of the rendered object.
180	"""
181
182	self.elevation(-90)
183
184	def leftView(self):
185	"""
186	Rotate the camera to view the left side of the rendered object.
187	"""
188
189	self.azimuth(-90)
190
191	def rightView(self):
192	"""
193	Rotate the camera to view the right side of the rendered object.
194	"""
195
196	self.azimuth(90)
197
198	def isometricView(self):
199	"""
200	Rotate the camera to view the isometric angle of the rendered object.
201	"""
202
203	self.roll(-45)
204	self.elevation(-45)
205
206	def dolly(self, distance):
207	"""
208	Move the camera towards (greater than 1) the rendered object. However,
209	the camera is unable to be moved away from the rendered object.
210
211	@type distance: Number
212	@param distance: Amount to move towards the rendered object
213	"""
214
215	self.__vtk_camera.Dolly(distance)
216	self.__modified = True
217
218	def parallelProjectionOn(self):
219	"""
220	Enable camera parallel projection.
221	"""
222
223	self.__vtk_camera.ParallelProjectionOn()
224	self.__modified = True
225
226	def parallelProjectionOff(self):
227	"""
228	Disable camera parallel projection.
229	"""
230
231	self.__vtk_camera.ParallelProjectionOff()
232	self.__modified = True
233
234	def __resetCameraClippingRange(self, scene):
235	"""
236	Reset the camera clipping range based on the bounds of the visible
237	actors. This ensures the rendered object is not cut-off.
238	Needs to be called whenever the camera's settings are modified.
239
240	@type scene: L{Scene <scene.Scene>} object
241	@param scene: Scene in which objects are to be rendered on
242	"""
243
244	scene._getRenderer()[self.__viewport].ResetCameraClippingRange()
245
246	def __resetCamera(self, scene):
247	"""
248	Repositions the camera to view the center point of the actors.
249
250	@type scene: L{Scene <scene.Scene>} object
251	@param scene: Scene in which objects are to be rendered on
252	"""
253
254	scene._getRenderer()[self.__viewport].ResetCamera()
255
256	def _isModified(self):
257	"""
258	Return whether the Camera has been modified.
259
260	@rtype: Boolean
261	@return: True or False
262	"""
263
264	if (self.__modified == True):
265	return True
266	else:
267	return False
268
269	def _render(self, scene):
270	"""
271	Render the camera.
272
273	@type scene: L{Scene <scene.Scene>} object
274	@param scene: Scene in which objects are to be rendered on
275	"""
276
277	if(self._isModified() == True):
278	# Will only be true once only when the camera is instantiated.
279	if(self.__initialization == True):
280	self.__setupCamera(scene)
281	self.__initialization == False
282
283	self.__resetCameraClippingRange(scene)
284	self.__modified = False
285
286