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

From Reallusion Wiki!
Jump to: navigation, search
m
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
+
Inheritance: [[IC_Python_API:RLPy_RIBase|RIBase]] > [[IC_Python_API:RLPy_RIObject|RIObject]] > '''RICamera'''.
−
a camera such as FOV, transformation, etc. All methods of this class
+
See Also: [[IC_Python_API:RLPy_RCameraDofData|RCameraDofData]], [[IC_Python_API:RLPy_RScene|RScene]]
−
are implemented by the system. <syntaxhighlight lang="Python">
+
 
 +
<syntaxhighlight lang="Python">
 
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 21:
 
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 34:
 
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 40:
 
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==
+
−
===GetFocalLength===
+
 
<syntaxhighlight lang="Python">
 
<syntaxhighlight lang="Python">
−
RLPy.RICamera.GetFocalLength ( self, kTime )
+
# Add a DOF key
 +
new_data = RLPy.RCameraDofData()
 +
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===
+
 
 +
==== Parameters ====
 +
:'''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">
 
<syntaxhighlight lang="Python">
−
RLPy.RICamera.SetFocalLength ( self, kTime, fFocalLength )
+
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">
 +
# 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">
 +
# 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">
 +
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">
 +
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">
 +
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">
 +
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">
 +
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">
 +
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">
 +
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">
 +
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
 +
camera.SetNearClippingPlane(RLPy.RTime(60), 10.0)
 +
print(camera.GetNearClippingPlane())
 +
</syntaxhighlight>

Revision as of 23:59, 5 April 2020

Main article: Modules.
Last modified: 04/5/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.

Inheritance: RIBase > RIObject > RICamera. See Also: RCameraDofData, RScene 

camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")

# Set the camera transform values
control = camera.GetControl("Transform")
transform = RLPy.RTransform.IDENTITY
transform.T().x = -75.0
transform.T().y = -150.0
transform.T().z = 250.0
time = RLPy.RTime(0)
control.SetValue(time, transform)
# update after adding a key
camera.Update()

# Set the camera name
camera.SetName( "new_name" )

# Get camera bounds
ret_max = RLPy.RVector3()
ret_center = RLPy.RVector3()
ret_min = RLPy.RVector3()
ret = camera.GetBounds( ret_max, ret_center, ret_min )
print(ret)

# Get the camera pivot transform values
ret_pos = RLPy.RVector3()
ret_rot = RLPy.RVector3()
camera.GetPivot( ret_pos, ret_rot )
print(ret)

# Check whether or the camera is selected
RLPy.RScene.SelectObject(camera)
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
# Add a DOF key
new_data = RLPy.RCameraDofData()
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)

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
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
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
# Get the camera aperture
width = 0
height = 0
result = camera.GetAperture(width,height)
print(result[0])
print(result[1])
print(result[2])

GetDOFData ( self )

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

Returns

Camera DOF data - RCameraDofData
# 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())

GetFarClippingPlane ( self )

Get the camera's Far Clipping Plane distance.

Returns

The camera's far clipping plane distance - int
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
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
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
fov_type = camera.GetFitRenderRegionType()
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
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
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
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
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
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
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
camera.SetFarClippingPlane(RLPy.RTime(60), 1000.0)
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
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
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
camera = RLPy.RScene.FindObject(RLPy.EObjectType_Camera, "Camera")
camera.SetNearClippingPlane(RLPy.RTime(60), 10.0)
print(camera.GetNearClippingPlane())
Retrieved from "https://wiki.reallusion.com/index.php?title=IC_Python_API:RLPy_RICamera&oldid=4426"