Construct a Viewpoint3d at the given eye point looking towards the given focal point, with the given global up direction (which will typically be Direction3d.positiveZ or Direction3d.positiveY). For example, to construct a viewpoint at the point (10, 0, 5) looking towards the origin:

viewpoint =
    Viewpoint3d.lookAt
        { eyePoint = Point3d.meters 10 0 5
        , focalPoint = Point3d.origin
        , upDirection = Direction3d.positiveZ
        }


Viewpoint3d.eyePoint viewpoint
--> Point3d.meters 10 0 5


Viewpoint3d.xDirection viewpoint
--> Direction3d.positiveY


Viewpoint3d.yDirection viewpoint
--> Direction3d.xz (Angle.degrees 116.57)


Viewpoint3d.viewDirection viewpoint
--> Direction3d.xz (Angle.degrees -153.43)

That is likely all you need to know but if you are interested in the details and corner cases, read on!

The view direction of the returned viewpoint will point from the eye point to the focal point. The Y direction will be chosen to be as close to the global up direction as possible (the viewpoint will not have any 'roll') and the X direction will point to the right.

If the direction from the eye point to the focal point is parallel to the global up direction (that is, the viewpoint represents looking straight up or straight down) then the X and Y directions will be chosen arbitrarily.

If the given eye point and focal point are coincident (so that there is no well- defined view direction), then the returned frame will have its Y direction set to the global up direction and its X and view directions will be chosen arbitrarily.

Construct a Viewpoint3d looking at the given focal point, the given distance away. The direction from the focal point to the eye point is defined by the given azimuth and elevation angles, which are with respect to the given ground plane (the position of the ground plane does not matter, only its orientation). For example,

Viewpoint3d.orbit
    { focalPoint = Point3d.meters 0 0 1
    , groundPlane = SketchPlane3d.xy
    , azimuth = Angle.degrees 0
    , elevation = Angle.degrees 45
    , distance = Length.meters 10
    }

is equivalent to

Viewpoint3d.lookAt
    { focalPoint = Point3d.meters 0 0 1
    , eyePoint = Point3d.meters 7.071 0 8.071
    , upDirection = Direction3d.z
    }

As the name suggests, Viewpoint3d.orbit is useful for making orbiting cameras; you can orbit around the focal point by changing just the azimuth, and rotate up and down by changing just the elevation.

Get the actual eye point of a viewpoint.

Get the viewing direction of a viewpoint.

The view plane of a viewpoint is a SketchPlane3d perpendicular to the view direction, with origin point equal to the eye point. For an observer looking straight down the view direction, the X direction of the view plane points to the right and the Y direction points up; this means that the view plane's normal direction is the opposite of the view direction. (Note that the Y direction will not be equal to the global up direction unless the view direction is horizontal).

Get the X (right) direction of a viewpoint's view plane.

Get the Y (local up) direction of a viewpoint's view plane.

Get the view matrix of a viewpoint. Multiplying by this matrix transforms from world coordinates to eye coordinates.

Construct a WebGL model-view matrix given a viewpoint and a Frame3d that defines the position and orientation of an object;

Viewpoint3d.modelViewMatrix modelFrame viewpoint

is equivalent to

Matrix4.mul
    (Viewpoint3d.viewMatrix viewpoint)
    (Frame3d.toMat4 modelFrame)

Multiplying by this matrix transforms from object coordinates to eye coordinates.