dymokomi/luce-3d
Source of release 0.9.5
0.9.5 / src / cameras / camera.lucb
import interop
from luce_std import math
import errors
from luce_geocore.geocore import Vector3
## A camera's view for one aspect: where it is, its axes, and its lens. A
## perspective lens has `focal` (1 / tan of half the vertical field of view)
## and `ortho` 0; an orthographic one has `ortho`, half the view's height in
## world units, and sees along -`backward` from every point of its film.
## Depths are measured along -`backward` from `position`; nothing nearer than
## `near` or farther than `far` is seen.
pub struct Projection:
pub let position: Vector3
pub let right: Vector3
pub let up: Vector3
pub let backward: Vector3
pub let focal: f64
pub let aspect: f64
pub let near: f64
pub let far: f64
pub let ortho: f64
## Whether the view is orthographic.
pub func orthographic() -> bool:
return self.ortho > 0.0
## `point`'s depth along the view: its distance in front of `position`.
pub func depth(point: Vector3) -> f64:
return -point.subtract(self.position).dot(self.backward)
## `point` on a `width` by `height` view: x and y in its pixels (y down)
## and its depth. A point at or behind the near plane lands as if on it:
## only for clipping.
pub func screen(point: Vector3, width: f64, height: f64) -> Vector3:
let relative = point.subtract(self.position)
let depth = -relative.dot(self.backward)
let scale = self.scale(depth)
return Vector3((relative.dot(self.right) * scale / self.aspect + 1.0) * width * 0.5,
(1.0 - relative.dot(self.up) * scale) * height * 0.5, depth)
## How much a world length across the view at `depth` grows on the film
## (in units of half the view's height).
pub func scale(depth: f64) -> f64:
if self.ortho > 0.0: return 1.0 / self.ortho
return self.focal / math.max(depth, self.near)
## Where the view ray through pixel (x, y) of a `width` by `height` view
## starts: the eye in perspective, a point of the film in orthographic.
pub func ray_origin(x: f64, y: f64, width: f64, height: f64) -> Vector3:
if self.ortho <= 0.0: return self.position
let sx = (x / width * 2.0 - 1.0) * self.aspect * self.ortho
let sy = (1.0 - y / height * 2.0) * self.ortho
return self.position.add(self.right.multiply_scalar(sx)).add(self.up.multiply_scalar(sy))
## The view ray's direction through pixel (x, y), not normalized (in
## perspective a unit step along it is a unit of depth).
pub func ray_direction(x: f64, y: f64, width: f64, height: f64) -> Vector3:
if self.ortho > 0.0: return self.backward.multiply_scalar(-1.0)
return self.right.multiply_scalar((x / width * 2.0 - 1.0) * self.aspect / self.focal).add(
self.up.multiply_scalar((1.0 - y / height * 2.0) / self.focal)).subtract(self.backward)
## Where the view ray that meets `point` starts: the eye in
## perspective, the point of the film in front of it in orthographic.
pub func eye_for(point: Vector3) -> Vector3:
if self.ortho <= 0.0: return self.position
return point.add(self.backward.multiply_scalar(self.depth(point)))
## The world length one pixel of a view `height` pixels high covers at
## `depth`.
pub func pixel(depth: f64, height: f64) -> f64:
if self.ortho > 0.0: return 2.0 * self.ortho / math.max(1.0, height)
return 2.0 * math.max(depth, self.near) / (self.focal * math.max(1.0, height))
## `point` in clip space ([x, y, z, w], depth 0..1 between the near and
## far planes), as projection_matrix maps it; `bias` pulls it toward the
## eye by that share of the depth range, in perspective and
## orthographic alike (a line drawn over a surface).
pub func clip(point: Vector3, bias: f64 = 0.0) -> f64[4]:
let relative = point.subtract(self.position)
let depth = -relative.dot(self.backward)
if self.ortho > 0.0:
return [relative.dot(self.right) / (self.ortho * self.aspect), relative.dot(self.up) / self.ortho,
(depth - self.near) / (self.far - self.near) - bias, 1.0]
return [relative.dot(self.right) * self.focal / self.aspect, relative.dot(self.up) * self.focal,
self.far * (depth - self.near) / (self.far - self.near) - bias * depth, depth]
## A camera placed in world space and looking at a target, its up toward an
## up direction: perspective with a vertical field of view, or orthographic
## with a view height (set_orthographic). Separate from scene membership; its
## projection is made from validated lens parameters.
pub struct Camera:
var field_of_view: f64
var ratio: f64
var near_plane: f64
var far_plane: f64
var location: Vector3
var target: Vector3
var upward: Vector3
var half_height: f64
pub func init(fov: f64 = 50.0, aspect: f64 = 1.0, near: f64 = 0.1, far: f64 = 1000.0) -> !:
try lens(fov, aspect, near, far)
self.field_of_view = fov
self.ratio = aspect
self.near_plane = near
self.far_plane = far
self.location = Vector3(0.0, 0.0, 5.0)
self.target = Vector3()
self.upward = Vector3(0.0, 1.0, 0.0)
self.half_height = 0.0
pub func position() -> Vector3:
return self.location
pub func set_position(position: Vector3) -> !:
if not position.is_finite():
error(errors.invalid, "camera position must be finite")
_ = try position.subtract(self.target).normalized()
self.location = position
## Look at `target`, the view's up as near `up` as it can be (world Y
## when `up` runs along the view).
pub func look_at(target: Vector3, up: Vector3 = Vector3(0.0, 1.0, 0.0)) -> !:
if not target.is_finite() or not up.is_finite():
error(errors.invalid, "camera target and up must be finite")
_ = try self.location.subtract(target).normalized()
self.upward = try up.normalized()
self.target = target
pub func aspect() -> f64:
return self.ratio
pub func set_aspect(aspect: f64) -> !:
try lens(self.field_of_view, aspect, self.near_plane, self.far_plane)
self.ratio = aspect
pub func set_projection(fov: f64, near: f64, far: f64) -> !:
try lens(fov, self.ratio, near, far)
self.field_of_view = fov
self.near_plane = near
self.far_plane = far
## The vertical field of view, in degrees (perspective).
pub func fov() -> f64:
return self.field_of_view
## See orthographically, `half_height` world units above and below the
## view's center; 0 sees in perspective again.
pub func set_orthographic(half_height: f64) -> !:
if not (half_height >= 0.0 and half_height < 1.0e12):
error(errors.invalid, "an orthographic camera needs a finite half height, 0 for perspective")
self.half_height = half_height
## Half the orthographic view's height; 0 in perspective.
pub func orthographic() -> f64:
return self.half_height
pub func projection(aspect: f64? = none) -> Projection!:
let ratio = aspect else self.ratio
try lens(self.field_of_view, ratio, self.near_plane, self.far_plane)
let backward = try self.location.subtract(self.target).normalized()
var right = self.upward.cross(backward)
if right.length() < 0.000001:
right = Vector3(0.0, 1.0, 0.0).cross(backward)
if right.length() < 0.000001:
right = Vector3(0.0, 0.0, 1.0).cross(backward)
right = try right.normalized()
return Projection(self.location, right, backward.cross(right), backward,
1.0 / math.tan(self.field_of_view * math.pi / 360.0), ratio, self.near_plane, self.far_plane, self.half_height)
pub func close():
_ = self.location
pub let camera_type: interop.Type[Camera] = interop.Type[Camera]("Camera", Camera.close, closeable = true, main_thread = true)
func lens(fov: f64, aspect: f64, near: f64, far: f64) -> !:
if not (fov > 0.0 and fov < 179.0 and aspect >= 0.000001 and aspect <= 1000000.0 and near > 0.0 and far > near and far <= 1000000000.0):
error(errors.invalid, "a camera needs finite fov (0,179), positive aspect and 0 < near < far <= 1e9")