SketchUp Ruby API Reference

Camera class

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

Parent: Object

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

Example Code: camera.rb (film and stage), cameratests.rb

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

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

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

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

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

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

Return Value

direction - a Vector3d object pointing in the direction that the Camera is pointing if successful

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

Return Value

eye - a Point3d object if successful

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

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

Return Value

length - the new focal length for the camera if successful

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

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

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

Return Value

height - height in current units if successful

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

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

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

Return Value

status - true if perspective, false if orthographic

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?

Return Value

status - true if perspective, false if orthographic

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

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

Return Value

target - a Point3d object if successful

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

Return Value

up - a Vector3d object if successful

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

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

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

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