fresnel.camera¶

Overview

`Camera`	Camera base class.
`Orthographic`	Orthographic camera.
`Perspective`	Perspective camera.

Details

Cameras.

class fresnel.camera.Camera(_camera)¶

Bases: object

Camera base class.

A Camera defines the view into the Scene.

Camera space is a coordinate system centered on the camera’s position. Positive x points to the right in the image, positive y points up, and positive z points out of the screen. The visible area in the image plane is centered on look_at with the given height. The visible width is height * aspect where aspect is the aspect ratio determined by the resolution of the image in Tracer (aspect = tracer.w / tracer.h). Camera space shares units with Scene space.

Camera provides common methods and properties for all camera implementations. Camera cannot be used directly, use one of the subclasses.

See also

Orthographic
Perspective

property basis¶

Orthonormal camera basis.

basis is computed from position, look_at, and up. The 3 vectors of the basis define the +x, +y, and +z camera space directions in scene space.

Type:: ((3, 3) numpy.ndarray of numpy.float32)

property height¶

The height of the image plane.

Type:: float

property look_at¶

The point the camera looks at.

position - look_at defines the +z direction in camera space.

Type:: ((3, ) numpy.ndarray of numpy.float32)

property position¶

Camera position.

Type:: ((3, ) numpy.ndarray of numpy.float32)

property up¶

A vector pointing toward the +y direction in camera space.

The component of up perpendicular to look_at - position defines the +y direction in camera space.

Type:: ((3, ) numpy.ndarray of numpy.float32)

class fresnel.camera.Orthographic(position, look_at, up, height)¶

Bases: Camera

Orthographic camera.

Parameters:

position ((3, ) numpy.ndarray of numpy.float32) – Camera position.
look_at ((3, ) numpy.ndarray of numpy.float32) – The point the camera looks at (the center of the focal plane).
up ((3, ) numpy.ndarray of numpy.float32) – A vector pointing toward the +y direction in camera space.
height (float) – The height of the image plane.

An orthographic camera traces parallel rays from the image plane into the scene. Lines that are parallel in the Scene will remain parallel in the rendered image.

position is the center of the image plane in Scene space. look_at is the point in Scene space that will be in the center of the image. Together, these vectors define the image plane which is perpendicular to the line from position to look_at.

up is a vector in Scene space that defines the (+y) direction in the camera space). up does not need to be perpendicular to the line from position to look_at, but it must not be parallel to that line. height sets the height of the image sensor in Scene units. The width is height * aspect where aspect is the aspect ratio determined by the resolution of the image in Tracer (aspect = tracer.w / tracer.h).

Note

Only objects inside the rectangular cuboid defined by corners of the image sensor and the focal plane (extended to infinite height) will appear in the image.

Objects in front of the image plane will appear in the rendered image, objects behind the plane will not.

Tip

Place the camera position outside the geometry of the Scene. Decrease height to zoom in and increase height to zoom out.

classmethod fit(scene, view='auto', margin=0.05)¶

Fit a camera to a Scene.

Create an orthographic camera that fits the entire height of the scene in the image plane.

Parameters:

scene (Scene) – Fit the camera to this scene.
view (str) – Select view
margin (float) – Fraction of extra space to leave on the top and bottom of the scene.

view may be ‘auto’, ‘isometric’, or ‘front’.

The isometric view is an orthographic projection from a particular angle so that the x,y, and z directions are equal lengths. The front view is an orthographic projection where +x points to the right, +y points up and +z points out of the screen in the image plane. ‘auto’ automatically selects ‘isometric’ for 3D scenes and ‘front’ for 2D scenes.

class fresnel.camera.Perspective(position, look_at, up, focal_length=0.5, focus_distance=10, f_stop=inf, height=0.24)¶

Bases: Camera

Perspective camera.

Parameters:

position ((3, ) numpy.ndarray of numpy.float32) – Camera position.
look_at ((3, ) numpy.ndarray of numpy.float32) – The point the camera looks at (the center of the focal plane).
up ((3, ) numpy.ndarray of numpy.float32) – A vector pointing toward the +y direction in camera space.
focal_length (float) – Focal length of the camera lens.
focus_distance (float) – Distance to the focal plane.
f_stop (float) – F-stop ratio for the lens.
height (float) – The height of the image plane.

A perspective camera traces diverging rays from the camera position through the image plane into the scene. Lines that are parallel in the Scene will converge rendered image.

position is the center of projection Scene space. look_at is the point in Scene space that will be in the center of the image. Together, these vectors define the image plane which is perpendicular to the line from position to look_at.

Note

Only objects inside the rectangular pyramid defined by the position and corners of the image sensor (extended to infinite height) will appear in the image.

Perspective models an ideal camera system with a sensor and a thin lens. The sensor lies in the image plane and is the location where the pixels in the rendered image will be captured. height sets the height of the sensor in Scene units. The width is height * aspect where aspect is the aspect ratio determined by the resolution of the image in Tracer (aspect = tracer.w / tracer.h). focal_length sets the distance between position and the image plane.

Note

The camera height should be small relative to the objects in the Scene with those objects in front of the image plane. If the scene units are decimeters, the default height of 0.24 is 24 mm, the height of a 35 mm camera sensor.

Tip

There are two ways to zoom a perspective camera. 1) Move the position of the camera while keeping the focal length fixed. Photographers call this “zooming with your feet” and it maintains a fixed field of view. 2) Increase the focal_length to zoom in or decrease it to zoom out while keeping position fixed. This is the the equivalent of rotating the focal length setting on a zoom lens. Changing focal_length changes the field of view.

Like a digital camera, the Perspective camera must be focused. The focal plane is parallel to the image plane at a distance focus_distance from the camera position. Objects on the focal plane will be in sharp focus. Objects in front of and behind the plane will be out of focus. Out of focus areas in an image are called bokeh and can be used to draw the viewer’s attention to the subject that is in clear focus. The space in front of and behind the focal plane that appears to be in focus is the depth of field. Set f_stop to control the amount of depth of field. Small, non-zero values will lead to very little depth of field and a value of inf will extend the depth of field to infinity.

Note

There are convenience methods to set the camera parameters:

focus_on takes a point and computes the focus_distance to put that point on the focal plane.
depth_of_field computes the f_stop needed to achieve a given depth of field.
vertical_field_of_view computes the focal_length needed to achieve a given field of view angle.

Tip

The default height of 0.24 works well for scene objects that are size ~1 or larger. If the typical objects in your scene are much smaller, adjust height by an appropriate fraction.

property depth_of_field¶

The distance about the focal plane in sharp focus.

The area of sharp focus extends in front and behind the focal plane. The distance between the front and back areas of sharp focus is the depth of field.

The depth of field is a function of focus_distance, focal_length, f_stop, and height.

Setting depth_of_field computes f_stop to obtain the desired depth of field as a function of focus_distance, focal_length, and height.

Note

depth_of_field does not remain fixed after setting it.

Type:: float

property f_stop¶

F-stop ratio for the lens.

Set the aperture of the opening into the lens in f-stops. This sets the range of the scene that is in sharp focus. Smaller values of f_stop result in more background blur.

Tip

Use depth_of_field to set the range of sharp focus in Scene distance units.

Type:: float

property focal_length¶

Focal length of the camera lens.

The focal length relative to the image height sets the field of view. Given a fixed height, a larger focal_length gives a narrower field of view.

Tip

With the default height of 0.24, typical focal lengths range from .18 (wide angle) to 0.5 (normal) to 6.0 (telephoto).