Camera

A mutable camera you can position and configure, then apply to the current view.

Build a camera with Camera.default() or get one from scene.getCamera(). Use the fluent setters to adjust orientation, field of view, and projection type, then pass camera.build() to model.view.setCamera() to apply it.

Example

let model = await SketchUpApi.getActiveModel();

// Position the camera looking at the model origin
let cam = SketchUpApi.Camera.default()
  .setOrientation(
    [0, -500, 200],
    [0, 0, 0],
    [0, 0, 1]
  )
  .setFieldOfView(35);

await model.view.setCamera(cam.build());

See

Constructor

new Camera(camera): Camera

Parameters

Parameter	Type
`camera`	`CameraData` \| `Camera`

Returns

Camera

Accessors

aspectRatio

Get Signature

get aspectRatio(): number

The ratio of viewport width to height.

Returns

number

center_2d

Get Signature

get center_2d(): Point2d

The 2D center point of the view on the plane orthogonal to the direction vector. Only meaningful for perspective2d and parallel2d camera types. Returns the origin for others.

Returns

Point2d

computePerspectiveEye

Get Signature

get computePerspectiveEye(): Point3d

A reliable eye position for both parallel and perspective cameras. For parallel cameras the position is recalculated from height each time, so it is always consistent. Useful when the camera is returned from SketchUp, as it could have been set by a Ruby extension and be in an invalid state

Returns

Point3d

data

Get Signature

get data(): CameraData

Return a copy of the underlying CameraData

Since

SDK 2.35.0

Returns

CameraData

description

Get Signature

get description(): string | undefined

An optional description for this camera.

Returns

string | undefined

direction

Get Signature

get direction(): Vector3d

The normalized vector from eye to target — the direction the camera is looking.

Returns

Vector3d

eye

Get Signature

get eye(): Point3d

The stored eye position. For parallel cameras, SketchUp does not always keep this up to date — use computePerspectiveEye when you need a reliable position for any camera type.

See

CameraReader.computePerspectiveEye

Returns

Point3d

fieldOfView

Get Signature

get fieldOfView(): number

The horizontal field of view in degrees.

Returns

number

focalLength

Get Signature

get focalLength(): number

The focal length in mm, derived from fieldOfView and imageWidth. When imageWidth is not set, 36 mm is used as a fallback. Only meaningful for perspective cameras. Returns 1000 mm for parallel cameras.

Returns

number

height

Get Signature

get height(): number

For parallel cameras, the distance along the direction vector that determines the zoom level. For perspective cameras, this is computed from the distance between eye and target and the field of view. Returned in inches.

See

CameraReader.direction

Returns

number

scale_2d

Get Signature

get scale_2d(): number

The 2D scale factor. Only meaningful for perspective2d and parallel2d camera types. Returns 1.0 for others.

Returns

number

target

Get Signature

get target(): Point3d

The point in the model the camera is aimed at.

Returns

Point3d

type

Get Signature

get type(): CameraType

The camera projection type — perspective or parallel. Use CameraTypeEnum values to compare.

Returns

CameraType

up

Get Signature

get up(): Vector3d

The direction that appears “up” in the rendered view. Always perpendicular to the vector from eye to target.

Returns

Vector3d

xAxis

Get Signature

get xAxis(): Vector3d

The camera’s right axis — a vector parallel to a line running left-to-right in screen coordinates.

Returns

Vector3d

yAxis

Get Signature

get yAxis(): Vector3d

The camera’s up axis — a vector parallel to a line running bottom-to-top in screen coordinates.

Returns

Vector3d

zAxis

Get Signature

get zAxis(): Vector3d

Same as direction. The normalized vector the camera is looking along.

See

CameraReader.direction

Returns

Vector3d

Methods

build()

build(): Readonly<CameraData>

Builds the camera data object to pass to view.setCamera().

Returns

Readonly<CameraData>

See

View.setCamera

toString()

toString(): string

Returns

string

withDescription()

withDescription(description): Camera

Returns a new camera with the given description

Parameters

Parameter	Type
`description`	`string`

Returns

Camera

Since

SDK 2.35.0

withFieldOfView()

withFieldOfView(fov): Camera

Returns a new camera with the horizontal field of view in degrees. Only applies to perspective cameras. Ignored with a warning for parallel. Clamped to the range 1–120 degrees.

Parameters

Parameter	Type	Description
`fov`	`number`	field of view in degrees

Returns

Camera

Since

SDK 2.35.0

withFocalLength()

withFocalLength(focalLengthMM): Camera

Returns a new camera with the focal length in millimeters, adjusting the field of view accordingly. Only applies to perspective cameras. Clamped to 1–3000 mm.

Parameters

Parameter	Type	Description
`focalLengthMM`	`number`	focal length in millimeters

Returns

Camera

Since

SDK 2.35.0

withHeight()

withHeight(heightInches): Camera

Sets the height in inches for parallel cameras, controlling the zoom level. Only applies to parallel cameras. Ignored with a warning for perspective. Minimum value: 0.001 inches.

Parameters

Parameter	Type	Description
`heightInches`	`number`	height in inches

Returns

Camera

Since

SDK 2.35.0

withImageWidth()

withImageWidth(imageWidth): Camera

Sets the image width in millimeters, used when computing focal length. Only applies to perspective cameras.

Parameters

Parameter	Type	Description
`imageWidth`	`number`	image width in millimeters

Returns

Camera

Since

SDK 2.35.0

withOrbit()

withOrbit(radians): Camera

Returns a new camera with the eye horizontally around the target point, keeping the target fixed and the up vector unchanged.

Parameters

Parameter	Type	Description
`radians`	`number`	rotation angle in radians

Returns

Camera

Since

SDK 2.35.0

withOrientation()

withOrientation(eye, target, up): Camera

Returns a new camera with updated eye position, target, and up direction. Accepts Point3d objects or [x, y, z] arrays for convenience.

Parameters

Parameter	Type	Description
`eye`	`Point3Like`	camera position in 3D space
`target`	`Point3Like`	point the camera is aimed at
`up`	`Vector3Like`	direction that appears “up” in the view

Returns

Camera

Throws

if eye and target are the same point, or the up vector is parallel to the view direction

Since

SDK 2.35.0

withPerspective()

withPerspective(perspective): Camera

Returns a new camera that has either perspective (true) or parallel (false) projection. The camera position and direction are preserved. Only the projection type changes.

Parameters

Parameter	Type	Description
`perspective`	`boolean`	`true` for perspective, `false` for parallel

Returns

Camera

Since

SDK 2.35.0

withTransform()

withTransform(transform): Camera

Returns a new camera with a transformation to the camera’s eye, target, and up vector. Useful for aligning the camera to a component’s axes.

Parameters

Parameter	Type
`transform`	`Transformation`

Returns

Camera

Since

SDK 2.35.0

withVerticalOrbit()

withVerticalOrbit(angle): Camera

Returns a new camera after rotating the eye vertically around the target point — tilts the camera up or down while keeping the target fixed.

Parameters

Parameter	Type	Description
`angle`	`number`	rotation angle in radians

Returns

Camera

Since

SDK 2.35.0

default()

static default(): Camera

Creates a camera with defaults: perspective projection, 30° field of view, looking down the negative Y axis.

Returns

Camera

Show Deprecated

Deprecated

orbit()

orbit(radians): this

Rotates the eye horizontally around the target point, keeping the target fixed and the up vector unchanged.

Parameters

Parameter	Type	Description
`radians`	`number`	rotation angle in radians

Returns

this

orbitVertical()

orbitVertical(angle): this

Rotates the eye vertically around the target point — tilts the camera up or down while keeping the target fixed.

Parameters

Parameter	Type	Description
`angle`	`number`	rotation angle in radians

Returns

this

setDescription()

setDescription(description): this

Sets an optional description for this camera.

Parameters

Parameter	Type
`description`	`string`

Returns

this

setFieldOfView()

setFieldOfView(fov): this

Sets the horizontal field of view in degrees. Only applies to perspective cameras. Ignored with a warning for parallel. Clamped to the range 1–120 degrees.

Parameters

Parameter	Type	Description
`fov`	`number`	field of view in degrees

Returns

this

setFocalLength()

setFocalLength(focalLengthMM): this

Sets the focal length in millimeters, adjusting the field of view accordingly. Only applies to perspective cameras. Clamped to 1–3000 mm.

Parameters

Parameter	Type	Description
`focalLengthMM`	`number`	focal length in millimeters

Returns

this

setHeight()

setHeight(heightInches): this

Sets the height in inches for parallel cameras, controlling the zoom level. Only applies to parallel cameras. Ignored with a warning for perspective. Minimum value: 0.001 inches.

Parameters

Parameter	Type	Description
`heightInches`	`number`	height in inches

Returns

this

setImageWidth()

setImageWidth(imageWidth): this

Sets the image width in millimeters, used when computing focal length. Only applies to perspective cameras.

Parameters

Parameter	Type	Description
`imageWidth`	`number`	image width in millimeters

Returns

this

setOrientation()

setOrientation(eye, target, up): this

Sets the camera’s eye position, target, and up direction. Accepts Point3d objects or [x, y, z] arrays for convenience.

Parameters

Parameter	Type	Description
`eye`	`Point3Like`	camera position in 3D space
`target`	`Point3Like`	point the camera is aimed at
`up`	`Vector3Like`	direction that appears “up” in the view

Returns

this

Throws

if eye and target are the same point, or the up vector is parallel to the view direction

setPerspective()

setPerspective(perspective): this

Switches between perspective (true) and parallel (false) projection. The camera position and direction are preserved. Only the projection type changes.

Parameters

Parameter	Type	Description
`perspective`	`boolean`	`true` for perspective, `false` for parallel

Returns

this

transform()

transform(transform): this

Applies a transformation to the camera’s eye, target, and up vector. Useful for aligning the camera to a component’s axes.

Parameters

Parameter	Type
`transform`	`Transformation`

Returns

this