pyvisi/py_src/camera.py


########################################################
#
# Copyright (c) 2003-2010 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-2010 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__="https://launchpad.net/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"


from position import GlobalPosition
from constant import Viewport
from esys.escript import getMPISizeWorld
if getMPISizeWorld()==1: import vtk

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