.POV File Format – Cameras

Syntax

camera {
  [camera identifier]
  [perspective | orthographic | fisheye | ultra_wide_angle | omnimax | panoramic |
   cylinder 1..4 | spherical | mesh_camera { … } | user_defined { … }]
  [location <v>] [direction <v>] [right <v>] [up <v>] [sky <v>]
  [angle horizontal [, vertical]] [look_at <v>]
  [aperture a] [blur_samples [min,] max] [focal_point <v>]
  [confidence c] [variance v] [bokeh { pigment { … } }]
  [normal { … }]
  [translate | rotate | scale | transform | matrix …]
}

The projection type, if written, must come first. All other items may be written in any order (see below for how the parser applies them). A projection type word that comes after other items is the error “Expected … camera modifier”. When no type is written the camera is a perspective camera.

For mesh_camera and user_defined the parser turns on an “experimental feature” flag and the program prints a warning at the end of parsing.

Defaults and the default camera

The default camera is the same as camera { perspective location <0,0,0> direction <0,0,1> right <w/h,0,0> up y sky y }. Without a #version directive the scene has language version 3.62, so right is <1.33, 0, 0> for the default camera.

The manual gives a variance default of 1/128 and a focal point default of <0,0,0>; the source of the camera class (source/core/scene/camera.cpp) has 1/10000 and <0,0,1>, which is what this page lists. The focal point only matters through its distance from the location: if no focal_point is written, the focal distance is the length of the direction vector (1 if that is 0).

Location, direction, right, up, angle and look_at

• Order of application. From language version 3.5 the parser applies the items in a fixed order, whatever the order in the text: right, direction, angle, up, sky, location, look_at, focal_point, then the transformations. So look_at may stand anywhere, and angle always sees the final right. Before 3.5 the items took effect one by one in the order written and look_at had to be last.
• angle. For perspective and orthographic the length of direction is changed to |right| / (2 × tan(angle / 2)) (the direction vector is normalised first). The angle must be smaller than 180: “Viewing angle has to be smaller than 180 degrees.” A negative angle is the error “Negative viewing angle.” The other types store the angle and use it as in the table below. An angle of 0 does not change the direction.
• look_at. The direction becomes look_at − location, normalised and then given the old length. The new right is sky × direction (normalised, with the old length of right; its sign keeps the old handedness) and up is direction × right (with the old length of up). If the direction is parallel to sky there is a warning and the previous right is used. If location and look_at are equal: “Camera location and look_at point must be different.”
• Perpendicular vectors. direction, up and right should be perpendicular. If not, the parser warns “Camera vectors are not perpendicular. Making look_at the last statement may help.” and the image is distorted.
• Aspect ratio. The ratio of the lengths of right and up is the aspect ratio of the picture. Set it from the image size: right x*image_width/image_height (the default from language version 3.8). For a fisheye camera an elliptical picture instead of a circle means the aspect ratio does not match the image.
• Handedness. POV-Ray is left-handed by default (x to the right, y up, z into the picture). right -x*image_width/image_height with the camera at positive z makes it right-handed.
• Transformations. translate, rotate, scale, transform and matrix move the finished camera. They are applied in the order written, after everything else.

Projection types

mesh_camera

mesh_camera {
  rays_per_pixel distribution [max_distance]
  mesh { … } | mesh2 { … }  [mesh …]
  [smooth]
}
[location <v>] [direction <v>]

The first two numbers are not separated by a comma (a comma is a parse error). Each pixel is assigned to a face of a mesh; the ray starts at the centre of the face and goes along its normal (distribution 3 uses a point of the face found from its UV coordinates). location and direction have a special meaning: the z of location moves the ray origin along the normal of the face, and a negative z of direction (less than −EPSILON) reverses all rays.

Ordinary antialiasing and jitter do not make sense for distributions 0, 1 and 2, because the pixel position is turned into an integer for the face index; the program gives no warning.

user_defined

user_defined {
  [location  { function { … }, function { … }, function { … } } | location <v>]
  [direction { function { … }, function { … }, function { … } } | direction <v>]
}

The three functions take the screen position x, y (also called u, v) as parameters. The coordinates run from −0.5 (left and bottom) to 0.5 (right and top). Each triple of functions gives the ray origin (location) and the ray direction (direction). Where a triple is not written, the plain vector is used (the default location is the origin and the default direction is <0, 0, 1>), and the ordinary items (look_at, transformations) work. angle is an error in this camera type. The type can copy the others and is meant for light probes, angular, cube-map, side-by-side stereo, omni-directional stereo and map projections.

Focal blur

Depth of field is simulated by shooting several rays from jittered points of the aperture and averaging. It is turned on when aperture is greater than 0 and blur_samples is set; the default is no blur.

Ray perturbation

normal { bumps 0.5 } in the camera perturbs all camera rays with a normal pattern; the image looks as if seen through bumpy glass (see Normals and finishes).

Camera identifiers

A camera can be declared with #declare Name = camera { … } (or #local) and used as camera { Name }. From language version 3.5 the only items that may follow the identifier are transformations (translate, rotate, scale, transform, matrix); keywords that change the behaviour of the camera (angle, location …) are not allowed, because the parser has to resolve their order first. The transformations of the identifier are kept, and the new ones are added after them. Camera identifiers can be used to switch between views with one line.

stdcam.inc and screen.inc

stdcam.inc is a ready-made scene start, not a set of macros. Including it creates a camera (location <-2, 1.75, -5>, right x*1.3333, angle 70, look_at <-0.75, -0.5, 0>), a light source at <20, 20, -25> and a plane y, 0 with the pigment Plum (from colors.inc, so include that first).

screen.inc puts objects and textures in front of the camera, for logos and signatures. It works with the perspective camera and creates the camera itself when it is included. These identifiers and macros exist:

Objects placed by screen.inc are still part of the scene: they are lit, and affected by perspective. See Include files.

Examples

#declare Cam_Perspective = camera {
  perspective
  location <3, 5, -10>
  sky <1, 1, 0>
  angle 50
  look_at <0, 2, 1>
}

#declare Cam_Orthographic = camera {
  orthographic
  location <0, 5, -5>
  look_at 0
  angle 30
}

#declare Cam_Ortho_Window = camera {
  orthographic
  location <0, 0, -5>
  right 4*x
  up 3*y
  look_at 0
}

camera {
  Cam_Perspective
  translate <1, 0, 0>
}

#declare Cam_Fisheye    = camera { fisheye location <0, 0, -3> look_at 0 angle 180 }
#declare Cam_Ultra      = camera { ultra_wide_angle location <0, 0, -3> look_at 0 angle 240 right 20*x up 10*y }
#declare Cam_Omnimax    = camera { omnimax location <0, 0, -3> look_at 0 }
#declare Cam_Panoramic  = camera { panoramic location <0, 0, -3> look_at 0 }
#declare Cam_Spherical  = camera { spherical location <0, 0, -3> angle 360, 180 }
#declare Cam_Cylinder1  = camera { cylinder 1 location <0, 0, -3> look_at 0 angle 120 }
#declare Cam_Cylinder4  = camera { cylinder 4 location <0, 0, -3> angle 90 }

camera {
  location <0, 2, -6>
  look_at 0
  aperture 0.3
  blur_samples 4, 20
  focal_point <0, 0, 0>
  confidence 0.95
  variance 1/10000
  bokeh { pigment { radial color_map { [0 rgb 1] [1 rgb 0] } } }
  normal { bumps 0.02 scale 0.1 }
}

#declare Grid = mesh {
  triangle { <-1, -1, 0>, <1, -1, 0>, <1, 1, 0> }
  triangle { <-1, -1, 0>, <1, 1, 0>, <-1, 1, 0> }
}

camera {
  mesh_camera {
    1 0
    mesh { Grid translate <0, 0, -4> }
  }
  location <0, 0, 0>
  direction <0, 0, 1>
}

#declare Cam_Ortho_UD = camera {
  user_defined
  location {
    function { x * 4 }
    function { y * 4 }
    function { -5 }
  }
  direction {
    function { 0 }
    function { 0 }
    function { 1 }
  }
}

#declare Cam_Pinhole_UD = camera {
  user_defined
  direction {
    function { x }
    function { y }
    function { 1 }
  }
  location <0, 0, -3>
  rotate y*5
}

camera { Cam_Ortho_UD }

#include "screen.inc"

Set_Camera(<0, 2, -6>, <0, 0, 0>, 50)

Screen_Plane(texture { pigment { rgbf <1, 1, 0, 0.5> } }, 0.1, <0.05, 0.05>, <0.25, 0.15>)

Not described

Known, not yet covered

• Reference: the exact ray equations of the fisheye, ultra wide angle, omnimax, panoramic and cylinder cameras (source/core/render/trace.cpp and the camera ray code) are described by the manual’s words only. The old (before 3.5) order-dependent syntax is mentioned but not listed keyword by keyword.
• Reference: the manual lists the vista buffer as available for perspective and orthographic cameras only; that is not covered here.