OrsCameraPositionHelper

A tutorial plugin that manages the camera position

author:ORS Team
contact:http://theobjects.com
email:info@theobjects.com
organization:Object Research Systems (ORS), Inc.
address:760 St-Paul West, suite 101, Montréal, Québec, Canada, H3C 1M4
copyright:Object Research Systems (ORS), Inc. All rights reserved 2020.
date:Jul 13 2016 15:42
dragonflyVersion:
 3.0
UUID:de2fa5f6760f11e7bc4e448a5b5d70c0

Class Code

class OrsPythonPlugins.OrsCameraPositionHelper.OrsCameraPositionHelper.OrsCameraPositionHelper(varname=None, managed=True)
UIDescriptors = [<ORSServiceClass.OrsPlugin.uidescriptor.UIDescriptor object>]
addView()

This method simply verifies if the current view is set in 3D mode. If it is, it calls our “addCameraToList” method which is responsible for interacting with the “_tableModel”. Also, if our plugin has an associated UI running, it will resize the new row containing the information about our added camera.

Return:Nothing Here we return nothing in order to avoid executing any other command if our current view is not in 3D mode.
addViewPoint()

The “addViewPoint” method is a little bit different than what we are used to.

Here, the reason we create an “Action” object is to allow us to deal with key shortcuts in the application. It is important to understand that this structure enables the use of key shortcuts, but will also work fine if the user does not setup a key. In other words, this method can be called like any other from the command line and will work similarly. The advantage of resorting to this structure is that you can customize each event point of a keystroke. This means that a key stroke can behave a certain way as it is being pressed, while it is pressed and when it is released.

In our case, we only have a “enterAction” specified. When someone presses the key shortcut(specified within the application in the preferences settings) associated to our “addViewPoint” method, it will call the “addView” method once even if the key remains pressed. In order to add another view, the user will need to release the key and press it again.

Return:string We return our Action object.
applyCameraFromIndex(QIndex)

This method allows us to apply a saved camera to our current view.

To do so, we first verify that the list only contains items with a common row index. We add this verification as each row from our “_tableModel” represents a unique camera. Therefore, if we were to select two different rows, we wouldn’t know which associated camera to apply to our view.

Once our unique row has been obtained, we get the camera list from “_tableModel” and select all 4 vectors from said row. Since these vectors were saved as Strings, we must use eval() on them to generate their usable object.

By doing so, we are able to create a camera object from the saved vector Strings and apply it to our view.

Parameters:QIndexList – Expects a list of Qt indexes.
classmethod applyCameraToView(view, camera)

The “applyCameraToView” method simply takes a given camera and uses it to replace the one used by our current view. It is important to refresh the view at the end of the method, otherwise our changes won’t be visible in the application.

Parameters:
Returns:

output (bool) – True if successful, False otherwise
applyCurrentCameraInfo()

This method takes the current camera information from our “_currentCameraTableModel” and applies it to our current view.

It is important to normalize them at this stage to avoid unexpected behaviour from our camera.

Note that only vectors we normalize here are the “direction” and “up” vector. Normalizing the “position” vector would not make any sense when considering the physical position of our camera. It would always be at a distance of 1 from our pivot. The same principle applies for the pivot point of the camera.

applyCurrentCameraInformation(row)
cameraChanged(camera)

This method serves as a middle man. It receives a camera in order to call the “setCameraSettings()” method of our “_currentCameraTableModel”. This method is called every time the camera of the current 3D view is modified.

Parameters:camera – orsCamera Camera containing the information needed for our model: direction, position, up and pivot.
closable = True
deleteCameraChangeCallback()

This method deletes the CameraChangeCallback if it is not None. We want to delete the callback each time we reinstall it.

deleteViewModeChangeCallback()

This method deletes the ViewModeChangeCallback if it is not None. We want to delete the callback each time we reinstall it.

exportCurrentCamera(view)
exportSelectedCamera(QIndexList)
getCurrentCameraTableModel()

This method’s only purpose is to respect the concept of encapsulation. It gives the outside access to our “_currentCameraTableModel”, a private variable, without breaking any rules.

Return:CurrentCameraTableModel Reference to the _currentCameraTableModel private variable.
classmethod getMainFormClass()

This methods returns the class used as the main form.

Returns:output – main form class
getState()

We want to save all the camera positions that we are currently holding.

Return:string
getTableModel()

This method’s only purpose is to respect the concept of encapsulation. It gives the outside access to our “_tableModel”, a private variable, without breaking any rules.

Return:TableModel Reference to the _currentCameraTableModel private variable.
getThumbnailForView(view)
getView()
importCamera()
installCameraChangeCallback()

This is the way we install a callback. Callbacks can be used to react to different events that may occur in the rest of the application.

Callbacks that are available can be found in: “pythonOrsEventeventCallback.py”. The concept of callbacks is to get rid of them when they’re not needed anymore. That being said, in this method, we first try to delete the callback before going any further. After, it is important to get a weak reference on self otherwise we won’t be able to delete the callback as it would still have a strong reference to our plugin.

Then, we can install the callback by setting up its associated variable to “EventCallback.” and the desired callback.

These methods usually take in 2 or 3 parameters. In this case, “addCallbackSetCameraEvent” takes in an an ORSObject, a callback id, that should be unique, and a function. Said function will be called each time the callback triggers. It is primordial that the callback id should be unique. We suggest giving it a general name and adding to it “repr(id(self))” to make sure it is unique.

Parameters:view – View View to which the callback should be associated.
installViewModeChangeCallback()

This is the way we install a callback. Callbacks can be used to react to different events that may occur in the rest of the application.

Callbacks that are available can be found in: “pythonOrsEventeventCallback.py”. The concept of callbacks is to get rid of them when they’re not needed anymore. That being said, in this method, we first try to delete the callback before going any further. After, it is important to get a weak reference on self otherwise we won’t be able to delete the callback as it would still have a strong reference to our plugin.

Then, we can install the callback by setting up its associated variable to “EventCallback.” and the desired callback.

These methods usually take in 2 or 3 parameters. In this case, “addCallbackViewModeChangeEvent” takes in an ORSObject, a callback id, that should be unique, and a function. Said function will be called each time the callback triggers. It is primordial that the callback id should be unique. We suggest giving it a general name and adding to it “repr(id(self))” to make sure it is unique.

Parameters:view – View View to which the callback should be associated.
keepAlive = False
classmethod lookAtBox(view, box, eyeVector)

Takes the given box, sets the direction of the camera and fits it to the desired view.

Parameters:
Returns:

output (bool) – True if successful, False otherwise
multiple = False
orsCurrentViewChange()

When the current view changes, we need to re-install the ViewModeChangeCallback and send it the new view. If our plugin has an instantiated mainform, it will also be informed of the view change.

removeCameraAtIndexes(QIndexList)

This method allows us to remove saved cameras from the camera list of “_tableModel”.

In this case, we do not need to verify that the list only contains items with a common row index. Here it is logical that a user may want to delete multiple cameras at the same time. So, we should not limit him.

The unique role of this method is to act as a middle man between the user and the model or the UI and the model. The responsibility and logic of how to remove the indexes is our model’s concern.

Parameters:QIndexList – Expects a list of Qt indexes.
savable = True
setCameraViewXAxis(lookAtPositive)

This method is predefined to look into a specific direction. In this case, the X axis. Depending on the value of the parameter that gets passed, said orientation will look towards the positives or the negatives.

In order to deal with different types of situations, the method has two ways of knowing how to setup the camera. First, it will try to get the best possible box from selected objects. This approach allows us to be a bit more selective and gives us a degree of liberty when choosing which box our camera should look at. However, if it fails to get a box, the method will use the viewBox instead. This one usually fills our needs, but doesn’t offer as much customization.

Once a box has been found with either method, we will call “_setCamera()” and send it the necessary information.

Parameters:lookAtPositive – boolean Determines if the camera will be oriented towards negatives or positives.
setCameraViewYAxis(lookAtPositive)

This method is predefined to look into a specific direction. In this case, the Y axis. Depending on the value of the parameter that gets passed, said orientation will look towards the positives or the negatives.

In order to deal with different types of situations, the method has two ways of knowing how to setup the camera. First, it will try to get the best possible box from selected objects. This approach allows us to be a bit more selective and gives us a degree of liberty when choosing which box our camera should look at. However, if it fails to get a box, the method will use the viewBox instead. This one usually fills our needs, but doesn’t offer as much customization.

Once a box has been found with either method, we will call “_setCamera()” and send it the necessary information.

Parameters:lookAtPositive – boolean Determines if the camera will be oriented towards negatives or positives.
setCameraViewZAxis(lookAtPositive)

This method is predefined to look into a specific direction. In this case, the Z axis. Depending on the value of the parameter that gets passed, said orientation will look towards the positives or the negatives.

In order to deal with different types of situations, the method has two ways of knowing how to setup the camera. First, it will try to get the best possible box from selected objects. This approach allows us to be a bit more selective and gives us a degree of liberty when choosing which box our camera should look at. However, if it fails to get a box, the method will use the viewBox instead. This one usually fills our needs, but doesn’t offer as much customization.

Once a box has been found with either method, we will call “_setCamera()” and send it the necessary information.

Parameters:lookAtPositive – boolean Determines if the camera will be oriented towards negatives or positives.
setState(state)

Send our saved camera positions to the model.

Parameters:state –
showInToolbar = True
classmethod toolsMenu()

In this method, we are specifying how our plugin will be accessible from within the application. Seeing as the name of the method is “toolsMenu()”, it is only logical that our plugin will be accessible through the ‘Tools’ drop-down menu at the top left of the application. Within the ‘Tools’ drop-down menu, the plugin’s access will be in the ‘Example’ section (the section at the top).

Our plugin will be labeled as ‘Camera Position Bookmarks’ and will have an id, ‘OrsCameraPositionHelper01’, to be recognizable by the application.

When ‘Camera Position Bookmarks’ is clicked, it will launch its GUI through the ‘startupDefault()’ method. :return:

updateSelectedCamera(QIndexList)