Documentation Center

  • Trial Software
  • Product Updates

UpVector, UpVectorX, UpVectorY, UpVectorZ, KeepUpVector

Up direction of a camera

Value Summary

UpVectorLibrary wrapper for "[UpVectorX, UpVectorY, UpVectorZ]" (3D)List of 2 or 3 expressions, depending on the dimension
UpVectorX, UpVectorY, UpVectorZOptionalMuPAD® expression
KeepUpVectorInheritedFALSE, or TRUE

Graphics Primitives

ObjectsDefault Values
plot::Camera

UpVector: [0.0, 0.0, 1.0]

UpVectorX, UpVectorY: 0.0

UpVectorZ: 1.0

KeepUpVector: TRUE

Description

UpVector = [x, y, z] sets the 3D vector that corresponds to the vertical direction of the 2D picture taken by the camera.

UpVectorX etc. denote the coordinates of the UpVector.

KeepUpVector = TRUE keeps the UpVector constant when the camera is moved. With KeepUpVector = FALSE, the UpVector is kept orthogonal to the optical axis when the camera is moved.

The picture taken by a camera is defined by the attributes Position (the 3D position of the camera) and FocalPoint (the 3D point the camera is pointed at). The vector from the position to the focal point is the optical axis of the camera.

As an additional degree of freedom, the camera may be rotated around the optical axis. This rotation is defined by specifying a 3D vector UpVector. In the final 2D picture taken by the camera, this vector is parallel to the vertical axis, pointing upwards.

With the default value UpVector = [0, 0, 1] the z-axis in 3D points upwards in the 2D picture.

The UpVector of a camera must not be zero and must not be parallel to the optical axis.

The default values are UpVector = [0, 0, 1] and KeepUpVector = TRUE.

The restriction that the UpVector must not be parallel to the optical axis leads to discontinuities when the camera moves in such a way that this restriction is violated. In such a case, KeepUpVector = FALSE should be used. Cf. Example 2.

Examples

Example 1

We view a cross of three arrows by a camera with the usual UpVector pointing into z-direction:

camera := plot::Camera([0.3, -4.0, 0.2], [0, 0, 0], PI/4,
                       UpVector = [0, 0, 1]):
plot(plot::Arrow3d([-1, 0, 0], [1, 0, 0], Color = RGB::Red),
     plot::Arrow3d([0, -1, 0], [0, 1, 0], Color = RGB::Green),
     plot::Arrow3d([0, 0, -1], [0, 0, 1], Color = RGB::Blue),
     camera)

We redefine the UpVector of the camera to point into the direction [1, 0, 1]. Now, this 3D direction becomes the vertical direction of the 2D picture:

camera::UpVector := [1, 0, 1]:
plot(plot::Arrow3d([-1, 0, 0], [1, 0, 0], Color = RGB::Red),
     plot::Arrow3d([0, -1, 0], [0, 1, 0], Color = RGB::Green),
     plot::Arrow3d([0, 0, -1], [0, 0, 1], Color = RGB::Blue),
     camera)

delete camera:

Example 2

We use an animated camera to fly over the north pole of a planet using the default UpVector = [0, 0, 1]. With KeepUpVector = TRUE, we encounter a discontinuity when the camera is positioned exactly over the north poly pointing straight down. The UpVector is parallel to the optical axis at this point:

camera := plot::Camera([4*cos(a), 0, 4*sin(a)], [0, 0, 0], PI/4,
                       a = 0..PI, Frames = 300,
                       UpVector = [0, 0, 1], 
                       KeepUpVector = TRUE):
planet := plot::Surface([cos(u)*sin(v), sin(u)*sin(v), cos(v)],
    u = 0..2*PI, v = 0..PI, 
    FillColorFunction = proc(u, v) 
             begin 
               [cos(u)*cos(v)^2, cos(u)*cos(v)^2, cos(u)]
             end_proc):
font := ["sans-serif", 10, RGB::Grey80]:
text1 := plot::Text3d("North", [0, 0, 1.2], TextFont = font):
text2 := plot::Text3d("South", [0, 0, -1.2], TextFont = font):
plot(camera, planet, text1, text2, Scaling = Constrained);

With KeepUpVector = FALSE, no such discontinuity is encountered. However, when reaching the equator on the dark side of the planet, the UpVector has turned around: the upper side of the picture now is south, the lower side is north:

camera::KeepUpVector := FALSE:
plot(camera, planet, text1, text2, Scaling = Constrained);

delete camera, planet, font, text1, text2:

See Also

MuPAD Functions

Was this topic helpful?