Camera

class Camera

Parent: Object | Class Index
Methods:new,aspect_ratio,aspect_ratio=, description, description=, direction, eye, focal_length, focal_length=, fov, fov=, height, height=, image_width, image_width=, perspective=, perspective?, set, target, up, xaxis, yaxis, zaxis |
Sample Code: camera.rb (film and stage), cameratests.rb |

The Camera class contains methods for creating and manipulating a camera.

Class Methods

new
The new method is used to create a new Camera object.
Syntax:
camera = Sketchup.camera.new camera = Sketchup::Camera.new eye, target, up, <perspective>, <fov>
Arguments:
eye - see Camera.eye target - see Camera.target up - see Camera.up perspective - (optional) see Camera.perspective fov - (optional) see Camera.fov
Return Value:
camera - a new Camera object if successful
Comments:
Example:

camera = Sketchup::Camera.new
if (camera)
UI.messagebox camera
else
UI.messagebox "Failure"
end

Instance Methods

aspect_ratio
The aspect_ratio method is used to retrieve the aspect ratio of the Camera.
Syntax:
aspectratio = camera.aspect_ratio
Arguments:
Return Value:
aspectratio - an aspect ratio, such as 1.85, if successful
Comments:
See Film and Stage cameras.txt file for sample camera aspect ratios
Example:

camera = Sketchup::Camera.new
ar = camera.aspect_ratio
if (ar)
UI.messagebox ar
else
UI.messagebox "Failure"
end

aspect_ratio=
The aspect_ratio= method is used to set the aspect ratio for a Camera
Syntax:
ar = camera.aspect_ratio = aspect_ratio
Arguments:
Return Value:
aspectratio - an aspect ratio, such as 1.85, if successful
Comments:
If you set the value to 0.0, then the aspect ratio of the Camera will match the aspect ratio of its View. See Film and Stage cameras.txt file for sample camera aspect ratios
Example:

camera = Sketchup::Camera.new
ar = camera.aspect_ratio=1.85
if (ar)
UI.messagebox ar
else
UI.messagebox "Failure"
end

description
The description method is used to retrieve the description for a Camera object.
Syntax:
description = camera.description
Arguments:
Return Value:
description - a string description for the camera if successful
Comments:
See Film and Stage cameras.txt file for sample camera aspect ratios
Example:

camera = Sketchup::Camera.new
description = camera.description
if (description)
UI.messagebox description
else
UI.messagebox "Failure"
end

description=
The description= method is used to set the description for the Camera.
Syntax:
camera.description = description
Arguments:
Return Value:
description - a string description for the camera if successful
Comments:
See Film and Stage cameras.txt file for sample camera aspect ratios
Example:
camera = Sketchup::Camera.new description = camera.description = "35 mm Camera"

direction
The direction method is used to retrieve a Vector3d object in the direction that the Camera is pointing.
Syntax:
direction = camera.direction
Arguments:
Return Value:
direction - a Vector3d object pointing in the direction that the Camera is pointing if successful
Comments:
Example:

camera = Sketchup::Camera.new
# Returns 0,0,-1 which indicates it is pointed down the Z axis
direction = camera.direction
if (direction)
UI.messagebox direction
else
UI.messagebox "Failure"
end

eye
The eye method is used to retrieve the eye Point3d object for the Camera.
Syntax:
eye = camera.eye
Arguments:
Return Value:
eye - a Point3d object if successful
Comments:
Example:

camera = Sketchup::Camera.new
# Returns 0,0,1 which indicates it is right in line with the Z axis.
eye = camera.eye
if (eye)
UI.messagebox eye
else
UI.messagebox "Failure"
end

focal_length
The focal_length method is used to get the focal length for the Camera.
Syntax:
length = camera.focal_length
Arguments:
length - the focal length for the camera if successful
Return Value:
Comments:
This value is computed based on the field of view (see the fov method) and the image width (see image_width.)
Example:

camera = Sketchup::Camera.new
l = camera.focal_length
if (l)
UI.messagebox l
else
UI.messagebox "Failure"
end

focal_length=
The focal_length= method allows you to sent the focal length (in millimeters) of a perspective camera. This is an alternate way of setting the field of view.
Syntax:
length = camera.focal_length= focallength
Arguments:
Return Value:
length - the new focal length for the camera if successful
Comments:
Example:

camera = Sketchup::Camera.new
l = camera.focal_length=120
if (l)
UI.messagebox l
else
UI.messagebox "Failure"
end

fov
The fov method retrieves the field of view of the camera (in degrees)
Syntax:
fov = camera.fov
Arguments:
Return Value:
fov - field of view, in degrees, if successful
Comments:
This is only applicable to perspective cameras.
Example:

camera = Sketchup::Camera.new
fov = camera.fov
if (fov)
UI.messagebox fov
else
UI.messagebox "Failure"
end

fov=
The fov= method sets the field of view, in millimeters, for a Camera.
Syntax:
fov = camera.fov = fov
Arguments:
fov - a field of view in millimeters
Return Value:
fov - the new field of view if successful
Comments:
This is only valid on a perspective camera.
Example:

camera = Sketchup::Camera.new
fov = camera.fov=56.78
if (fov)
UI.messagebox fov
else
UI.messagebox "Failure"
end

height
The height method retrieves the height of a Camera.
Syntax:
height = camera.height
Arguments:
Return Value:
height - height in current units if successful
Comments:
This is only valid if it is not a perspective camera.
Example:

camera = Sketchup::Camera.new
h = camera.height
if (h)
UI.messagebox h
else
UI.messagebox "Failure"
end

height=
The height= method is used to set the height for the camera.
Syntax:
height = camera.height = height
Arguments:
Return Value:
height - height in current units if successful
Comments:
Example:

camera = Sketchup::Camera.new
h = camera.height=20
if (h)
UI.messagebox h
else
UI.messagebox "Failure"
end

image_width
The image_width method retrieves the size of the image on the image plane of the Camera.
Syntax:
width = camera.image_width
Arguments:
Return Value:
width - the width of the camera if successful
Comments:
By default, this value is not set. If it is set, it is used in the calculation of the focal length from the field of view. Unlike most length values in SketchUp, the image_width and focal_length values are specified in millimeters rather than in inches.
Example:

camera = Sketchup::Camera.new
w = camera.image_width
if (w)
UI.messagebox w
else
UI.messagebox "Failure"
end

image_width=
The image_width= method is used to set the size of the image on the "film" for a perspective camera.
Syntax:
width = camera.image_width = width
Arguments:
Return Value:
width - the width of the camera if successful
Comments:
The value is given in millimeters. It is used in the conversions between field of view and focal length.
Example:

camera = Sketchup::Camera.new
w = camera.image_width=1.0
if (w)
UI.messagebox w
else
UI.messagebox "Failure"
end

perspective=
The perspective= method is used to set whether or not this is a perspective camera or an orthographic camera.
Syntax:
status = camera.perspective = true | false
Arguments:
Return Value:
status - true if perspective, false if orthographic
Comments:
Example:

camera = Sketchup::Camera.new
status = camera.perspective=false
if (status)
UI.messagebox "Perspective"
else
UI.messagebox "Orthographic"
end

perspective?
The perspective? method is used to determine whether a camera is a perspective or orthographic camera.
Syntax:
status = camera.perspective?
Arguments:
Return Value:
status - true if perspective, false if orthographic
Comments:
Example:

camera = Sketchup::Camera.new
status = camera.perspective?
if (status)
UI.messagebox "Perspective"
else
UI.messagebox "Orthographic"
end

set
The set method sets the camera orientation. You have to set the camera eye, target and up parameters at the same time to make sure that you have a valid camera definition.
Syntax:
camera = camera.set eye, target, up
Arguments:
eye - see Camera.eye target - see Camera.target up - see Camera.up
Return Value:
camera - a new Camera object
Comments:
Example:

camera = Sketchup::Camera.new
eye = camera.eye
target = camera.target
up = camera.up
# We just set it to exactly what it was pointing at in the first place
camera = camera.set eye, target, up
if (camera)
UI.messagebox camera
else
UI.messagebox "Failure"
end

target
The target method retrieves Point3d that the camera is pointing at.
Syntax:
target = camera.target
Arguments:
Return Value:
target - a Point3d object if successful
Comments:
Example:

camera = Sketchup::Camera.new
# Target point is 0,0,0
t = camera.target
if (t)
UI.messagebox t
else
UI.messagebox "Failure"
end

up
The up method is used to retrieve the up vector for the camera. This is the direction that the top of the camera is facing.
Syntax:
up = camera.up
Arguments:
Return Value:
up - a Vector3d object if successful
Comments:
Example:

camera = Sketchup::Camera.new
# 0.0, 1.0, 0.0
up = camera.up
if (up)
UI.messagebox up
else
UI.messagebox "Failure"
end

xaxis
The xaxis method is used to retrieve the x axis of the camera coordinate system defined by the camera's direction and up vector.
Syntax:
vector = camera.xaxis
Arguments:
Return Value:
vector - a Vector3d object if successful
Comments:
This value is computed from the cross product between the camera direction and the up vector.
Example:

camera = Sketchup::Camera.new
# 1.0, 0.0, 0.0
v = camera.xaxis
if (v)
UI.messagebox v
else
UI.messagebox "Failure"
end

yaxis
The yaxis method retrieves the y axis of the camera coordinate system defined by the camera's direction and up vector.
Syntax:
vector = camera.yaxis
Arguments:
Return Value:
vector - a Vector3d object if successful
Comments:
This value is computed to be perpendicular the camera x and z axes. It is equivalent to the up direction, but is computed to make sure that it is perpendicular to the direction.
Example:

camera = Sketchup::Camera.new
# 0.0, 1.0, 0.0
v = camera.yaxis
if (v)
UI.messagebox v
else
UI.messagebox "Failure"
end

zaxis
The z axis method retrieves the z axis of the camera coordinate system that is defined by the camera's direction and up vector.
Syntax:
vector = camera.zaxis
Arguments:
Return Value:
vector - a Vector3d object if successful
Comments:
This value is computed. It is the same as the camera direction.
Example:

camera = Sketchup::Camera.new
# 0.0, 0.0, -1.0
v = camera.zaxis
if (v)
UI.messagebox v
else
UI.messagebox "Failure"
end