Difference between revisions of "IC Python API:RLPy RICamera"

From Reallusion Wiki!
Jump to: navigation, search
m
m
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{TOC}}
 
{{TOC}}
 
{{Parent|IC_Python_API:RL_Python_Modules|Modules}}
 
{{Parent|IC_Python_API:RL_Python_Modules|Modules}}
−
==Inheritance==
+
{{last_modified}}
−
This class inherits public member functions from:
+
 
−
*[[IC_Python_API:RLPy_RIObject|RLPy.RIObject]]
+
== Description ==
−
*[[IC_Python_API:RLPy_RIBase|RLPy.RIBase]]
+
 
−
==Detailed Description==
+
This class is used to access camera objects in the scene.  A camera can be divided into 3 main parts: the device body, camera lens, and viewing area. Therefore, the interfaces available are: aperture, focal length, angle of view, depth of field, near / far plane settings, and viewport fitting.
−
This class is the interface to cameras in the scene.
+
 
−
<span style="background:#ffcccc">( Experimental Class )</span> It provides methods to access various parts of
+
See Also: [[IC_Python_API:RLPy_RCameraDofData|RCameraDofData]], [[IC_Python_API:RLPy_RScene|RScene]].
−
a camera such as FOV, transformation, etc. All methods of this class
+
 
−
are implemented by the system. <syntaxhighlight lang="Python">
+
=== Inheritance ===
 +
 
 +
[[IC_Python_API:RLPy_RIBase|RIBase]] > [[IC_Python_API:RLPy_RIObject|RIObject]] > [[IC_Python_API:RLPy_RICamera|RICamera]]
 +
 
 +
=== Examples ===
 +
 
 +
<syntaxhighlight lang="python" line='line'>
 
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
 
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
−
 
+
 
−
# set focal length
+
# Set the camera transform values
−
camera.SetFocalLength(RLPy.RTime(60), 100.0)
+
−
print(camera.GetFocalLength(RLPy.RTime(60))) # 100
+
−
 
+
−
# set transform
+
 
control = camera.GetControl("Transform")
 
control = camera.GetControl("Transform")
 
transform = RLPy.RTransform.IDENTITY
 
transform = RLPy.RTransform.IDENTITY
Line 24: Line 26:
 
time = RLPy.RTime(0)
 
time = RLPy.RTime(0)
 
control.SetValue(time, transform)
 
control.SetValue(time, transform)
 +
# update after adding a key
 +
camera.Update()
  
−
 
+
# Set the camera name
−
prop2 = RLPy.RScene.FindObject(RLPy.EObjectType_Prop, "Box2")
+
−
# set Parent
+
−
result = camera.SetParent(prop2)
+
−
result = camera.SetParent(None) #detach from parent
+
−
 
+
−
# link to & unlink
+
−
result = camera.LinkTo(prop2, RLPy.RTime(0))
+
−
result = camera.UnLink(RLPy.RTime(0))
+
−
 
+
−
# set name
+
 
camera.SetName( "new_name" )
 
camera.SetName( "new_name" )
  
−
#get bound
+
# Get camera bounds
 
ret_max = RLPy.RVector3()
 
ret_max = RLPy.RVector3()
 
ret_center = RLPy.RVector3()
 
ret_center = RLPy.RVector3()
Line 45: Line 39:
 
print(ret)
 
print(ret)
  
−
#get pivot
+
# Get the camera pivot transform values
 
ret_pos = RLPy.RVector3()
 
ret_pos = RLPy.RVector3()
 
ret_rot = RLPy.RVector3()
 
ret_rot = RLPy.RVector3()
Line 51: Line 45:
 
print(ret)
 
print(ret)
  
−
#is selected
+
# Check whether or the camera is selected
 
RLPy.RScene.SelectObject(camera)
 
RLPy.RScene.SelectObject(camera)
 
print(camera.IsSelected()) #True
 
print(camera.IsSelected()) #True
 
</syntaxhighlight>
 
</syntaxhighlight>
−
==Operators==
+
 
−
This class supports the following operators:
+
== Member Functions ==
−
{| class="wikitable"
+
 
−
!Member
+
=== AddDofKey ( self, kKey, kDofData ) ===
−
!Operation
+
 
−
!Syntax
+
Key the camera's Depth of Field (DOF) at a given time. Use [[IC_Python_API:RLPy_RCameraDofData|RCameraDofData]] to adjust the DOF settings.
−
!Description
+
 
−
!Example
+
==== Parameters ====
−
|-
+
:'''kKey''' [IN] Designated time - [[IC_Python_API:RLPy_RKey|RKey]]
−
! scope="row"|__eq__
+
:'''kDofData''' [IN] DOF settings - [[IC_Python_API:RLPy_RCameraDofData|RCameraDofData]]
−
|Equality
+
 
−
|a == b
+
==== Returns ====
−
|If the values of two operands are equal, then the condition becomes true.
+
:Success - RLPy.RStatus.Success
−
|(a == b) is not true.
+
:Failure - RLPy.RStatus.Failure
−
|}
+
 
−
==Member Functions==
+
<syntaxhighlight lang="python" line='line'>
−
===GetFocalLength===
+
# Add a DOF key
−
<syntaxhighlight lang="Python">
+
new_data = RLPy.RCameraDofData()
−
RLPy.RICamera.GetFocalLength ( self, kTime )
+
new_data.SetEnable( True )
 +
new_data.SetFocus(20)
 +
data.SetRange(80)
 +
dof_key = RLPy.RKey()
 +
dof_key.SetTime(RLPy.RTime(66))
 +
dof_key.SetTransitionType(RLPy.ETransitionType_Linear)
 +
dof_key.SetTransitionStrength(50)
 +
camera.AddDofKey(dof_key, new_data)
 
</syntaxhighlight>
 
</syntaxhighlight>
−
Get the focal length of the camera.
 
−
<span style="background:#ffcccc">( Experimental API )</span>
 
−
====Returns====
 
−
<div style="margin-left: 2em;">The focal length of the camera - float
 
−
</div>
 
−
====Parameters====
 
−
<div style="margin-left: 2em;">
 
  
−
'''kTime''' [IN] the time to get - RLPy.RTime
+
=== GetAngleOfView ( self, kTime ) ===
−
</div>
+
 
−
-----
+
Get the camera's Angle of View (AOV) at a given time, in degrees (1° to 165°).
−
===SetFocalLength===
+
 
−
<syntaxhighlight lang="Python">
+
==== Parameters ====
−
RLPy.RICamera.SetFocalLength ( self, kTime, fFocalLength )
+
:'''kTime''' [IN] Time at which to get the AOV value - [[IC_Python_API:RLPy_RTime|RTime]]
 +
 
 +
==== Returns ====
 +
:The camera's angle of view - float
 +
 
 +
<syntaxhighlight lang="python" line='line'>
 +
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
 +
camera.GetAngleOfView(RLPy.RGlobal.GetTime())
 
</syntaxhighlight>
 
</syntaxhighlight>
−
Set the focal length of the camera.
 
−
<span style="background:#ffcccc">( Experimental API )</span>
 
−
====Parameters====
 
−
<div style="margin-left: 2em;">
 
  
−
'''kTime''' [IN] the time to set - RLPy.RTime
+
=== GetAperture ( self, fWidth, fHeight ) ===
  
−
'''fFocalLength''' [IN] The focal length value to be set - float
+
Get the camera's aperture dimensions, i.e. the width and height of the photo-sensitive capture plate.
−
</div>
+
−
====Return Values====
+
−
<div style="margin-left: 2em;">
+
  
−
'''RLPy.RStatus.Success''' Success
+
==== Parameters ====
 +
:'''fWidth''' [IN] Width of the camera aperture - float
 +
:'''fHeight''' [IN] Height of the camera aperture - float
  
−
'''RLPy.RStatus.Failure''' Fail
+
==== Returns ====
−
</div>
+
:Success - RLPy.RStatus.Success
 +
:Failure - RLPy.RStatus.Failure
 +
 
 +
<syntaxhighlight lang="python" line='line'>
 +
# Get the camera aperture
 +
width = 0
 +
height = 0
 +
result = camera.GetAperture(width,height)
 +
print(result[0])
 +
print(result[1])
 +
print(result[2])
 +
</syntaxhighlight>
 +
 
 +
=== GetDOFData ( self ) ===
 +
 
 +
Get the camera's Depth of Field (DOF) data.
 +
 
 +
==== Returns ====
 +
:Camera DOF data - [[IC_Python_API:RLPy_RCameraDofData|RCameraDofData]]
 +
 
 +
<syntaxhighlight lang="python" line='line'>
 +
# Grab camera DOF data
 +
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
 +
data = camera.GetDOFData()
 +
if data is not None:
 +
      print(data.GetEnable())
 +
      print(data.GetFocus())
 +
      print(data.GetRange())
 +
      print(data.GetNearTransitionRegion())
 +
      print(data.GetFarTransitionRegion())
 +
      print(data.GetNearBlurScale())
 +
      print(data.GetFarBlurScale())
 +
      print(data.GetMinBlendDistance())
 +
      print(data.GetCenterColorWeight())
 +
      print(data.GetEdgeDecayPower())
 +
</syntaxhighlight>
 +
 
 +
=== GetFarClippingPlane ( self ) ===
 +
 
 +
Get the camera's Far Clipping Plane distance.
 +
 
 +
==== Returns ====
 +
:The camera's far clipping plane distance - int
 +
 
 +
<syntaxhighlight lang="python" line='line'>
 +
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
 +
far_clipping_plane = camera.GetFarClippingPlane()
 +
</syntaxhighlight>
 +
 
 +
=== GetFitFovType ( self ) ===
 +
 
 +
Get the camera's Fit value for the Field of View.  The possible values are the following:
 +
 
 +
*RLPy.ECameraFitResolution_Horizontal - use the horizontal width value for fitting.
 +
*RLPy.ECameraFitResolution_Vertical - use the vertical height value for fitting.
 +
 
 +
==== Returns ====
 +
:the type of setting ( Horizontal / Vertical ) - RLPy.ECameraFitResolution
 +
:*RLPy.ECameraFitResolution_Horizontal
 +
:*RLPy.ECameraFitResolution_Vertical
 +
:*RLPy.ECameraFitResolution_None
 +
 
 +
<syntaxhighlight lang="python" line='line'>
 +
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
 +
fov_type = camera.GetFitRenderRegionType()
 +
print(fov_type)
 +
</syntaxhighlight>
 +
 
 +
=== GetFitRenderRegionType ( self ) ===
 +
 
 +
Get the camera's Fit Resolution setting. The possible values are the following:
 +
 
 +
*RLPy.ECameraFitResolution_Horizontal - use the horizontal width value for fitting.
 +
*RLPy.ECameraFitResolution_Vertical - use the vertical height value for fitting.
 +
 
 +
==== Returns ====
 +
:The camera's Fit Type ( Horizontal / Vertical ) - RLPy.ECameraFitResolution
 +
:*RLPy.ECameraFitResolution_Horizontal
 +
:*RLPy.ECameraFitResolution_Vertical
 +
:*RLPy.ECameraFitResolution_None
 +
 
 +
<syntaxhighlight lang="python" line='line'>
 +
type = camera.GetFitRenderRegionType()
 +
</syntaxhighlight>
 +
 
 +
=== GetFocalLength ( self, kTime ) ===
 +
 
 +
Get the camera's Focal Length distance at a given time.
 +
 
 +
==== Parameters ====
 +
:'''kTime''' [IN] Time at which to get the Focal Length distance - [[IC_Python_API:RLPy_RTime|RTime]]
 +
 
 +
==== Returns ====
 +
:Camera's focal length distance at a given time, in millimeters (2.5 mm to 3,500 mm) - float
 +
 
 +
<syntaxhighlight lang="python" line='line'>
 +
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
 +
camera.GetFocalLength(RLPy.RTime(60))    # get focal length
 +
</syntaxhighlight>
 +
 
 +
=== GetNearClippingPlane ( self ) ===
 +
 
 +
Get the camera's Near Clipping Plane distance.
 +
 
 +
==== Returns ====
 +
:The Near Clipping Plane distance (always a positive value) - int
 +
 
 +
<syntaxhighlight lang="python" line='line'>
 +
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
 +
camera.GetNearClippingPlane()
 +
</syntaxhighlight>
 +
 
 +
=== SetFarClippingPlane ( self, nFarPlane ) ===
 +
 
 +
Set the Far Clipping Plane distance.  This value must be larger than the Near Clipping Plane distance.
 +
 
 +
==== Parameters ====
 +
:'''nFarPlane''' [IN] Far Clipping Plane distance - int
 +
 
 +
==== Returns ====
 +
:Success - RLPy.RStatus.Success
 +
:Failure - RLPy.RStatus.Failure
 +
 
 +
<syntaxhighlight lang="python" line='line'>
 +
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
 +
camera.SetFarClippingPlane(RLPy.RTime(60), 1000.0)
 +
print(camera.GetFarClippingPlane())
 +
</syntaxhighlight>
 +
 
 +
=== SetFocalLength ( self, kTime, fFocalLength ) ===
 +
 
 +
Set the camera's Focal Length at a given point in time.  The possible values lie between 2.5 and 3,500 mm.  If the value set lies outside of this range, then the original Focal Length value remains unchanged.
 +
 
 +
==== Parameters ====
 +
:'''kTime''' [IN] Time for setting the focal length - [[IC_Python_API:RLPy_RTime|RTime]]
 +
:'''fFocalLength''' [IN] Target distance for the focal length in millimeters - float
 +
 
 +
==== Returns ====
 +
:Success - RLPy.RStatus.Success
 +
:Failure - RLPy.RStatus.Failure
 +
 
 +
<syntaxhighlight lang="python" line='line'>
 +
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
 +
camera.SetFocalLength(RLPy.RTime(60), 100.0)
 +
</syntaxhighlight>
 +
 
 +
=== SetNearClippingPlane ( self, nNearPlane ) ===
 +
 
 +
Set the Near Clipping Plane distance, must be smaller than the Far Clipping Plane distance.
 +
 
 +
==== Parameters ====
 +
:'''nNearPlane''' [IN] The Near Clipping Plane distance - int
 +
 
 +
==== Returns ====
 +
:Success - RLPy.RStatus.Success
 +
:Failure - RLPy.RStatus.Failure
 +
 
 +
<syntaxhighlight lang="python" line='line'>
 +
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
 +
camera.SetNearClippingPlane(RLPy.RTime(60), 10.0)
 +
print(camera.GetNearClippingPlane())
 +
</syntaxhighlight>

Latest revision as of 00:05, 15 April 2020

Main article: Modules.
Last modified: 04/15/2020

Description

This class is used to access camera objects in the scene. A camera can be divided into 3 main parts: the device body, camera lens, and viewing area. Therefore, the interfaces available are: aperture, focal length, angle of view, depth of field, near / far plane settings, and viewport fitting.

See Also: RCameraDofData, RScene.

Inheritance

RIBase > RIObject > RICamera

Examples

 1 camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
 2 
 3 # Set the camera transform values
 4 control = camera.GetControl("Transform")
 5 transform = RLPy.RTransform.IDENTITY
 6 transform.T().x = -75.0
 7 transform.T().y = -150.0
 8 transform.T().z = 250.0
 9 time = RLPy.RTime(0)
10 control.SetValue(time, transform)
11 # update after adding a key
12 camera.Update()
13 
14 # Set the camera name
15 camera.SetName( "new_name" )
16 
17 # Get camera bounds
18 ret_max = RLPy.RVector3()
19 ret_center = RLPy.RVector3()
20 ret_min = RLPy.RVector3()
21 ret = camera.GetBounds( ret_max, ret_center, ret_min )
22 print(ret)
23 
24 # Get the camera pivot transform values
25 ret_pos = RLPy.RVector3()
26 ret_rot = RLPy.RVector3()
27 camera.GetPivot( ret_pos, ret_rot )
28 print(ret)
29 
30 # Check whether or the camera is selected
31 RLPy.RScene.SelectObject(camera)
32 print(camera.IsSelected()) #True

Member Functions

AddDofKey ( self, kKey, kDofData )

Key the camera's Depth of Field (DOF) at a given time. Use RCameraDofData to adjust the DOF settings.

Parameters

kKey [IN] Designated time - RKey
kDofData [IN] DOF settings - RCameraDofData

Returns

Success - RLPy.RStatus.Success
Failure - RLPy.RStatus.Failure
 1 # Add a DOF key
 2 new_data = RLPy.RCameraDofData()
 3 new_data.SetEnable( True )
 4 new_data.SetFocus(20)
 5 data.SetRange(80)
 6 dof_key = RLPy.RKey()
 7 dof_key.SetTime(RLPy.RTime(66))
 8 dof_key.SetTransitionType(RLPy.ETransitionType_Linear)
 9 dof_key.SetTransitionStrength(50)
10 camera.AddDofKey(dof_key, new_data)

GetAngleOfView ( self, kTime )

Get the camera's Angle of View (AOV) at a given time, in degrees (1° to 165°).

Parameters

kTime [IN] Time at which to get the AOV value - RTime

Returns

The camera's angle of view - float
1 camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
2 camera.GetAngleOfView(RLPy.RGlobal.GetTime())

GetAperture ( self, fWidth, fHeight )

Get the camera's aperture dimensions, i.e. the width and height of the photo-sensitive capture plate.

Parameters

fWidth [IN] Width of the camera aperture - float
fHeight [IN] Height of the camera aperture - float

Returns

Success - RLPy.RStatus.Success
Failure - RLPy.RStatus.Failure
1 # Get the camera aperture
2 width = 0
3 height = 0
4 result = camera.GetAperture(width,height)
5 print(result[0])
6 print(result[1])
7 print(result[2])

GetDOFData ( self )

Get the camera's Depth of Field (DOF) data.

Returns

Camera DOF data - RCameraDofData
 1 # Grab camera DOF data
 2 camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
 3 data = camera.GetDOFData()
 4 if data is not None:
 5        print(data.GetEnable())
 6        print(data.GetFocus())
 7        print(data.GetRange())
 8        print(data.GetNearTransitionRegion())
 9        print(data.GetFarTransitionRegion())
10        print(data.GetNearBlurScale())
11        print(data.GetFarBlurScale())
12        print(data.GetMinBlendDistance())
13        print(data.GetCenterColorWeight())
14        print(data.GetEdgeDecayPower())

GetFarClippingPlane ( self )

Get the camera's Far Clipping Plane distance.

Returns

The camera's far clipping plane distance - int
1 camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
2 far_clipping_plane = camera.GetFarClippingPlane()

GetFitFovType ( self )

Get the camera's Fit value for the Field of View. The possible values are the following:

  • RLPy.ECameraFitResolution_Horizontal - use the horizontal width value for fitting.
  • RLPy.ECameraFitResolution_Vertical - use the vertical height value for fitting.

Returns

the type of setting ( Horizontal / Vertical ) - RLPy.ECameraFitResolution
  • RLPy.ECameraFitResolution_Horizontal
  • RLPy.ECameraFitResolution_Vertical
  • RLPy.ECameraFitResolution_None
1 camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
2 fov_type = camera.GetFitRenderRegionType()
3 print(fov_type)

GetFitRenderRegionType ( self )

Get the camera's Fit Resolution setting. The possible values are the following:

  • RLPy.ECameraFitResolution_Horizontal - use the horizontal width value for fitting.
  • RLPy.ECameraFitResolution_Vertical - use the vertical height value for fitting.

Returns

The camera's Fit Type ( Horizontal / Vertical ) - RLPy.ECameraFitResolution
  • RLPy.ECameraFitResolution_Horizontal
  • RLPy.ECameraFitResolution_Vertical
  • RLPy.ECameraFitResolution_None
1 type = camera.GetFitRenderRegionType()

GetFocalLength ( self, kTime )

Get the camera's Focal Length distance at a given time.

Parameters

kTime [IN] Time at which to get the Focal Length distance - RTime

Returns

Camera's focal length distance at a given time, in millimeters (2.5 mm to 3,500 mm) - float
1 camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
2 camera.GetFocalLength(RLPy.RTime(60))    # get focal length

GetNearClippingPlane ( self )

Get the camera's Near Clipping Plane distance.

Returns

The Near Clipping Plane distance (always a positive value) - int
1 camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
2 camera.GetNearClippingPlane()

SetFarClippingPlane ( self, nFarPlane )

Set the Far Clipping Plane distance. This value must be larger than the Near Clipping Plane distance.

Parameters

nFarPlane [IN] Far Clipping Plane distance - int

Returns

Success - RLPy.RStatus.Success
Failure - RLPy.RStatus.Failure
1 camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
2 camera.SetFarClippingPlane(RLPy.RTime(60), 1000.0)
3 print(camera.GetFarClippingPlane())

SetFocalLength ( self, kTime, fFocalLength )

Set the camera's Focal Length at a given point in time. The possible values lie between 2.5 and 3,500 mm. If the value set lies outside of this range, then the original Focal Length value remains unchanged.

Parameters

kTime [IN] Time for setting the focal length - RTime
fFocalLength [IN] Target distance for the focal length in millimeters - float

Returns

Success - RLPy.RStatus.Success
Failure - RLPy.RStatus.Failure
1 camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
2 camera.SetFocalLength(RLPy.RTime(60), 100.0)

SetNearClippingPlane ( self, nNearPlane )

Set the Near Clipping Plane distance, must be smaller than the Far Clipping Plane distance.

Parameters

nNearPlane [IN] The Near Clipping Plane distance - int

Returns

Success - RLPy.RStatus.Success
Failure - RLPy.RStatus.Failure
1 camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
2 camera.SetNearClippingPlane(RLPy.RTime(60), 10.0)
3 print(camera.GetNearClippingPlane())
Retrieved from "https://wiki.reallusion.com/index.php?title=IC_Python_API:RLPy_RICamera&oldid=4540"