pyvisi/py_src/camera.py

"""
@author: John NGUI
"""

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) and away (less than 1) from 
        the rendered object. 

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

        self.__vtk_camera.Dolly(distance)
        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.__isModified = False
            

1	ksteube	1147	"""
2			@author: John NGUI
3			"""
4
5			import vtk
6			from position import GlobalPosition
7			from constant import Viewport
8
9			class Camera:
10			"""
11			Class that defines a camera. A camera controls the display angle of
12			the rendered object and one is usually created for a
13			L{Scene <scene.Scene>}. However, if a L{Scene <scene.Scene>} has four
14			viewports, then a separate camera may be created for each viewport.
15			"""
16
17			# The SOUTH_WEST default viewport is used when there is only one viewport.
18			# This saves the user from specifying the viewport when there is only one.
19	jongui	1148	def __init__(self, scene, viewport = Viewport.SOUTH_WEST):
20	ksteube	1147	"""
21			Initialise the camera.
22
23			@type scene: L{Scene <scene.Scene>} object
24			@param scene: Scene in which objects are to be rendered on
25			@type viewport: L{Viewport <constant.Viewport>} constant
26			@param viewport: Viewport in which objects are to be rendered on
27			"""
28
29			self.__viewport = viewport
30	jongui	1148	self.__vtk_camera = vtk.vtkCamera()
31	ksteube	1147
32	jongui	1148	# Keeps track whether camera has been modified.
33			self.__modified = True
34			# Keeps track whether the modification to the camera was due to the
35			# instantiation. If it is, then __setupCamera() method is called.
36			self.__initialization = True
37	jongui	1158	scene._addVisualizationModules(self)
38	jongui	1148
39	jongui	1158	def __setupCamera(self, scene):
40	ksteube	1147	"""
41			Setup the camera.
42	jongui	1158
43			@type scene: L{Scene <scene.Scene>} object
44			@param scene: Scene in which objects are to be rendered on
45	ksteube	1147	"""
46
47			# Assign the camera to the appropriate renderer
48	jongui	1158	scene._setActiveCamera(self.__viewport, self.__vtk_camera)
49			self.__resetCamera(scene)
50	ksteube	1147
51			def setFocalPoint(self, position):
52			"""
53			Set the focal point of the camera.
54
55			@type position: L{GlobalPosition <position.GlobalPosition>} object
56			@param position: Camera focal point
57			"""
58
59			self.__vtk_camera.SetFocalPoint(position._getGlobalPosition())
60	jongui	1148	self.__modified = True
61	ksteube	1147
62			def setPosition(self, position):
63			"""
64			Set the position of the camera.
65
66			@type position: L{GlobalPosition <position.GlobalPosition>} object
67			@param position: Camera position
68			"""
69
70			self.__vtk_camera.SetPosition(position._getGlobalPosition())
71	jongui	1148	self.__modified = True
72	ksteube	1147
73			def setClippingRange(self, near_clipping, far_clipping):
74			"""
75			Set the near and far clipping plane of the camera.
76
77			@type near_clipping: Number
78			@param near_clipping: Distance to the near clipping plane
79			@type far_clipping: Number
80			@param far_clipping: Distance to the far clipping plane
81			"""
82
83			self.__vtk_camera.SetClippingRange(near_clipping, far_clipping)
84
85			def setViewUp(self, position):
86			"""
87			Set the view up direction of the camera.
88
89			@type position: L{GlobalPosition <position.GlobalPosition>} object
90			@param position: Camera view up direction
91			"""
92
93			self.__vtk_camera.SetViewUp(position._getGlobalPosition())
94
95			def azimuth(self, angle):
96			"""
97			Rotate the camera to the left and right.
98
99			@type angle: Number
100			@param angle: Degree to rotate the camera
101			"""
102
103			self.__vtk_camera.Azimuth(angle)
104	jongui	1148	self.__modified = True
105	ksteube	1147
106			def elevation(self, angle):
107			"""
108			Rotate the camera to the top and bottom.
109
110			@type angle: Number
111			@param angle: Degree to rotate the camera (only between -90 and 90)
112			"""
113
114			self.__vtk_camera.Elevation(angle)
115			# Recompute the view up vector. If not used the elevation angle is
116			# unable to exceed 87/-87 degrees. A warning resetting the
117			# view up will also be thrown and the rendered object may be incorrect.
118			# With the view up recomputed, the elevation angle can reach between
119			# 90/-90 degrees. Exceeding that, the rendered object may be incorrect.
120			self.__vtk_camera.OrthogonalizeViewUp()
121	jongui	1148	self.__modified = True
122	ksteube	1147
123			def roll(self, angle):
124			"""
125			Roll the camera to the left and right.
126
127			@type angle: Number
128			@param angle: Degree to roll the camera
129			"""
130
131			self.__vtk_camera.Roll(-angle)
132	jongui	1148	self.__modified = True
133	ksteube	1147
134			def backView(self):
135			"""
136			Rotate the camera to view the back of the rendered object.
137			"""
138
139			self.azimuth(180)
140
141			def topView(self):
142			"""
143			Rotate the camera to view the top of the rendered object.
144			"""
145
146			self.elevation(90)
147
148			def bottomView(self):
149			"""
150			Rotate the camera to view the bottom of the rendered object.
151			"""
152
153			self.elevation(-90)
154
155			def leftView(self):
156			"""
157			Rotate the camera to view the left side of the rendered object.
158			"""
159
160			self.azimuth(-90)
161
162			def rightView(self):
163			"""
164			Rotate the camera to view the right side of the rendered object.
165			"""
166
167			self.azimuth(90)
168
169			def isometricView(self):
170			"""
171			Rotate the camera to view the isometric angle of the rendered object.
172			"""
173
174			self.roll(-45)
175			self.elevation(-45)
176
177			def dolly(self, distance):
178			"""
179			Move the camera towards (greater than 1) and away (less than 1) from
180			the rendered object.
181
182			@type distance: Number
183			@param distance: Amount to move towards or away the rendered object
184			"""
185
186			self.__vtk_camera.Dolly(distance)
187	jongui	1148	self.__modified = True
188	ksteube	1147
189	jongui	1158	def __resetCameraClippingRange(self, scene):
190	ksteube	1147	"""
191			Reset the camera clipping range based on the bounds of the visible
192			actors. This ensures the rendered object is not cut-off.
193			Needs to be called whenever the camera's settings are modified.
194	jongui	1158
195			@type scene: L{Scene <scene.Scene>} object
196			@param scene: Scene in which objects are to be rendered on
197	ksteube	1147	"""
198
199	jongui	1158	scene._getRenderer()[self.__viewport].ResetCameraClippingRange()
200	ksteube	1147
201	jongui	1158	def __resetCamera(self, scene):
202	ksteube	1147	"""
203			Repositions the camera to view the center point of the actors.
204	jongui	1158
205			@type scene: L{Scene <scene.Scene>} object
206			@param scene: Scene in which objects are to be rendered on
207	ksteube	1147	"""
208
209	jongui	1158	scene._getRenderer()[self.__viewport].ResetCamera()
210	jongui	1148
211			def _isModified(self):
212			"""
213			Return whether the Camera has been modified.
214
215			@rtype: Boolean
216			@return: True or False
217			"""
218
219			if (self.__modified == True):
220			return True
221			else:
222			return False
223
224	jongui	1158	def _render(self, scene):
225	jongui	1148	"""
226			Render the camera.
227	jongui	1158
228			@type scene: L{Scene <scene.Scene>} object
229			@param scene: Scene in which objects are to be rendered on
230	jongui	1148	"""
231
232			if(self._isModified() == True):
233			# Will only be true once only when the camera is instantiated.
234			if(self.__initialization == True):
235	jongui	1158	self.__setupCamera(scene)
236	jongui	1148	self.__initialization == False
237
238	jongui	1158	self.__resetCameraClippingRange(scene)
239	jongui	1148	self.__isModified = False
240
241