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