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	"""
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 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	def __init__(self, scene, viewport = Viewport.SOUTH_WEST):
36	"""
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	self.__vtk_camera = vtk.vtkCamera()
47
48	# 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	scene._addVisualizationModules(self)
54
55	def __setupCamera(self, scene):
56	"""
57	Setup the camera.
58
59	@type scene: L{Scene <scene.Scene>} object
60	@param scene: Scene in which objects are to be rendered on
61	"""
62
63	# Assign the camera to the appropriate renderer
64	scene._setActiveCamera(self.__viewport, self.__vtk_camera)
65	self.__resetCamera(scene)
66
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	self.__modified = True
77
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	self.__modified = True
88
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	self.__modified = True
121
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	self.__modified = True
138
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	self.__modified = True
149
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	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
198	@type distance: Number
199	@param distance: Amount to move towards the rendered object
200	"""
201
202	self.__vtk_camera.Dolly(distance)
203	self.__modified = True
204
205	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	def __resetCameraClippingRange(self, scene):
222	"""
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
227	@type scene: L{Scene <scene.Scene>} object
228	@param scene: Scene in which objects are to be rendered on
229	"""
230
231	scene._getRenderer()[self.__viewport].ResetCameraClippingRange()
232
233	def __resetCamera(self, scene):
234	"""
235	Repositions the camera to view the center point of the actors.
236
237	@type scene: L{Scene <scene.Scene>} object
238	@param scene: Scene in which objects are to be rendered on
239	"""
240
241	scene._getRenderer()[self.__viewport].ResetCamera()
242
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	def _render(self, scene):
257	"""
258	Render the camera.
259
260	@type scene: L{Scene <scene.Scene>} object
261	@param scene: Scene in which objects are to be rendered on
262	"""
263
264	if(self._isModified() == True):
265	# Will only be true once only when the camera is instantiated.
266	if(self.__initialization == True):
267	self.__setupCamera(scene)
268	self.__initialization == False
269
270	self.__resetCameraClippingRange(scene)
271	self.__modified = False
272
273