Class: Sketchup::Camera

Inherits:
Object
  • Object
show all

Overview

The Camera class contains methods for creating and manipulating a camera. The camera in SketchUp is the “point of view” from which you look at the model.

Examples:

# Create a camera from scratch with an "eye" position in
# x, y, z coordinates, a "target" position that
# defines what to look at, and an "up" vector.
eye = [1000,1000,1000]
target = [0,0,0]
up = [0,0,1]
my_camera = Sketchup::Camera.new eye, target, up

# Get a handle to the current view and change its camera.
view = Sketchup.active_model.active_view
view.camera = my_camera

Version:

  • SketchUp 6.0

Instance Method Summary # collapse

Constructor Details

#initialize(eye, target, up, perspective = true, fov = 30.0) ⇒ Object

Returns a new camera with eye (where the camera is) and targets (where the camera is looking) of type Point3d, up direction of type Vector3d, optional perspective flag of value true or false, and optional field-of-view value in degrees of type Float.

Examples:

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

Returns camera - a new Camera object if successful

Parameters:

Version:

  • SketchUp 6.0

Instance Method Details

#aspect_ratioObject

The aspect_ratio method is used to retrieve the aspect ratio of the Camera.

Examples:

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

Returns:

  • aspectratio - an aspect ratio, such as 1.85, if successful

Version:

  • SketchUp 6.0

#aspect_ratio=(ratio) ⇒ Object

The aspect_ratio= method is used to set the aspect ratio for a Camera. Changing this value will cause SketchUp to show gray bars over the screen to show the resulting view.

If you set the value to 0.0, then the aspect ratio of the Camera will match the aspect ratio of its View.

Examples:

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

Returns aspectratio - an aspect ratio, such as 1.85, if successful

Parameters:

  • ratio (Float)

Returns:

  • aspectratio - an aspect ratio, such as 1.85, if successful

Version:

  • SketchUp 6.0

#center_2dObject

The center_2d method returns a point with the x and y offset of the camera when it's in 2d mode. When the camera is in two-point perspective and the user pans around, the x and y values will change. These values are in normalized device coordinates, so for instance, the range [-1.0, 1.0] spans the full width or height of the screen.

The z value is unused and it is always zero.

Examples:

Sketchup.active_model.active_view.camera.center_2d

Returns:

  • Point3d

Version:

  • SketchUp 2015

#descriptionObject

The description method is used to retrieve the description for a Camera object.

Examples:

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

Returns:

  • description - a string description for the camera if successful

Version:

  • SketchUp 6.0

#description=(description) ⇒ Object

The description= method is used to set the description for the Camera.

Examples:

camera = Sketchup::Camera.new
description = camera.description = "35 mm Camera"

Returns description - a string description for the camera if successful

Parameters:

Returns:

  • description - a string description for the camera if successful

Version:

  • SketchUp 6.0

#directionObject

The direction method is used to retrieve a Vector3d object in the direction that the Camera is pointing.

Examples:

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.to_s
else
  UI.messagebox "Failure"
end

Returns:

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

Version:

  • SketchUp 6.0

#eyeObject

The eye method is used to retrieve the eye Point3d object for the Camera.

Examples:

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

Returns:

  • eye - a Point3d object if successful

Version:

  • SketchUp 6.0

#focal_length(length) ⇒ Object

The focal_length method is used to get the focal length in millimeters of perspective Camera.

This value is computed based on the field of view (see the fov method) and the image width (see image_width).

Examples:

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

Returns nil

Parameters:

  • length

    The focal length for the camera if successful.

Returns:

  • nil

Version:

  • SketchUp 6.0

#focal_length=(value) ⇒ Object

The focal_length= method allows you to sent the focal length (in millimeters) of a perspective camera. It must be between 1 and 3000, inclusive. This is an alternate way of setting the field of view.

Examples:

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

Returns length - the new focal length for the camera if successful

Parameters:

  • value (Float)

Returns:

  • length - the new focal length for the camera if successful

Version:

  • SketchUp 6.0

#fovObject

The fov method retrieves the field of view of the camera (in degrees).

This is only applicable to perspective cameras.

Examples:

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

Returns:

  • fov - field of view, in degrees, if successful

Version:

  • SketchUp 6.0

#fov=(fov) ⇒ Object

The fov= method sets the field of view, in millimeters, for a Camera. It must be between 1 and 120, inclusive.

This is only valid on a perspective camera.

Examples:

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

Returns fov - the new field of view if successful

Parameters:

  • fov

    A field of view in millimeters.

Returns:

  • fov - the new field of view if successful

Version:

  • SketchUp 6.0

#fov_is_height?Object

The fov_is_height? method indicates whether the field of view is horizontal or vertical.

Examples:

camera = Sketchup.active_model.active_view.camera
if camera.fov_is_height?
  fov_vertical = camera.fov
  # Compute the horizontal FOV.
else
  fov_horizontal = camera.fov
  # Compute the vertical FOV.
end

Returns:

  • bool - true if vertical, false otherwise

  • (Boolean)

Version:

  • SketchUp 2015

#heightObject

The height method retrieves the height of a Camera in inches.

This is only valid if it is not a perspective camera.

Examples:

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

Returns:

  • height - height in current units if successful

Version:

  • SketchUp 6.0

#height=(value) ⇒ Object

The height= method is used to set the height for the Camera in inches.

This is only valid if it is not a perspective camera.

Examples:

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

Returns height - height in current units if successful

Parameters:

  • value (Float)

Returns:

  • height - height in current units if successful

Version:

  • SketchUp 6.0

#image_widthObject

The image_width method retrieves the size of the image on the image plane of the Camera.

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.

Examples:

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

Returns:

  • width - the width of the camera if successful

Version:

  • SketchUp 6.0

#image_width=(value) ⇒ Object

The image_width= method is used to set the size of the image on the “film” for a perspective camera.

The value is given in millimeters. It is used in the conversions between field of view and focal length.

Examples:

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

Returns width - the width of the camera if successful

Parameters:

  • value (Float)

Returns:

  • width - the width of the camera if successful

Version:

  • SketchUp 6.0

#is_2d?Object

The is_2d? method indicates if the camera is in 2d mode. 2 point perspective mode and PhotoMatch mode are 2d cameras.

Examples:

Sketchup.active_model.active_view.camera.is_2d?

Returns:

  • Boolean - true if camera is in 2d mode, false otherwise

  • (Boolean)

Version:

  • SketchUp 2015

#perspective=(perspective) ⇒ Object

The perspective= method is used to set whether or not this is a perspective camera or an orthographic camera.

Examples:

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

Returns status - true if perspective, false if orthographic

Parameters:

  • perspective

    true for perspective, false for orthographic

Returns:

  • status - true if perspective, false if orthographic

Version:

  • SketchUp 6.0

#perspective?Object

The perspective? method is used to determine whether a camera is a perspective or orthographic camera.

Examples:

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

Returns:

  • status - true if perspective, false if orthographic

  • (Boolean)

Version:

  • SketchUp 6.0

#scale_2dObject

The scale_2d method returns a float indicating the scaling factor of 2d cameras.

When the camera is in two-point perspective and the user uses the zoom tools, this value will change. Zooming out will produce a value greater than 1.0.

Examples:

Sketchup.active_model.active_view.camera.scale_2d

Returns:

  • float

Version:

  • SketchUp 2015

#set(eye, target, up) ⇒ Object

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.

Examples:

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.set eye, target, up
if (camera)
  UI.messagebox camera.to_s
else
  UI.messagebox "Failure"
end

Returns camera - the modified camera

Parameters:

  • eye

    See Camera.eye.

  • target

    See Camera.target.

  • up

    See Camera.up.

Returns:

  • camera - the modified camera

Version:

  • SketchUp 6.0

#targetObject

The target method retrieves Point3d that the camera is pointing at.

Examples:

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

Returns:

  • target - a Point3d object if successful

Version:

  • SketchUp 6.0

#upObject

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.

Examples:

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

Returns:

  • up - a Vector3d object if successful

Version:

  • SketchUp 6.0

#xaxisObject

The xaxis method is used to retrieve the x axis of the camera coordinate system defined by the camera's direction and up vector.

This value is computed from the cross product between the camera direction and the up vector.

Examples:

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

Returns:

  • vector - a Vector3d object if successful

Version:

  • SketchUp 6.0

#yaxisObject

The yaxis method retrieves the y axis of the camera coordinate system defined by the camera's direction and up vector.

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.

Examples:

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

Returns:

  • vector - a Vector3d object if successful

Version:

  • SketchUp 6.0

#zaxisObject

The zaxis method retrieves the z axis of the camera coordinate system defined by the camera's direction and up vector.

This value is computed. It is the same as Camera.direction

Examples:

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

Returns:

  • vector - a Vector3d object if successful

Version:

  • SketchUp 6.0