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