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 鈥減oint 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 ⇒ Sketchup::Camera #initialize(eye, target, up, perspective = true, fov = 30.0) ⇒ Sketchup::Camera

Returns a new camera with eye (where the camera is) and targets (where the camera is looking).

Examples:

eye = Geom::Point3d.new(20, 5, 30)
target = Geom::Point3d.new(20, 60, 25)
up = Z_AXIS
camera = Sketchup::Camera.new(eye, target, up)

Default paramaters

camera = Sketchup::Camera.new

Overloads:

Version:

  • SketchUp 6.0

Instance Method Details

↑ #aspect_ratio ⇒ Object

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_2d ⇒ Object

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

↑ #description ⇒ Object

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

↑ #direction ⇒ Object

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

↑ #eye ⇒ Object

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

↑ #fov ⇒ Object

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? ⇒ Boolean

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:

  • (Boolean) —

    bool - true if vertical, false otherwise

Version:

  • SketchUp 2015

↑ #height ⇒ Object

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_width ⇒ Object

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 鈥渇ilm鈥 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? ⇒ Boolean

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) —

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

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? ⇒ Boolean

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:

  • (Boolean) —

    status - true if perspective, false if orthographic

Version:

  • SketchUp 6.0

↑ #scale_2d ⇒ Object

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) ⇒ Sketchup::Camera

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 = Geom::Point3d.new(20, 5, 30)
target = Geom::Point3d.new(20, 60, 25)
up = Z_AXIS
camera.set(eye, target, up)

Parameters:

Returns:

Version:

  • SketchUp 6.0

↑ #target ⇒ Object

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

↑ #up ⇒ Object

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

↑ #xaxis ⇒ Object

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

↑ #yaxis ⇒ Object

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

↑ #zaxis ⇒ Object

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