Crate lina 

Linear algebra library with a focus on computer graphics, heavily using strong typing and const generics (while still allowing access via .x, .y, .z and .w).

lina leans heavily into strong typing by distinguishing points and vectors, Cartesian and homogeneous coordinates, and even elements from different semantic spaces. See these docs for more information.

Quick start / overview

• Locations and displacements
  • Point represents a location.
  • Vector represents a displacement.
  • HcPoint represents a point in homogeneous coordinates.
  • Dir represents a direction via unit vector.
  • Use SphericalPos and SphericalDir for spherical coordinates.
• Transformations
  • Matrix represents a linear transformation.
  • HcMatrix represents a potentially non-linear transformation in homogeneous coordinates.
  • Use transform to get common transformation matrices.
  • Use * or and_then to combine two matrices.
  • Use * or transform to transform a vector or point with a matrix.
• Operators are overloaded as you would expect.
• Many types have a Space parameter to use strong typing.
  • Use in_space or with_spaces methods to cast/reinterpret the space parameter.
  • Recommendation: make type aliases for specific types used in your app, e.g. type HelioPoint = Point<f64, 3, HelioSpace>.
• Most types have a to_bytes method to pass them to graphic APIs.
• Other features:
  • Strongly typed angles: Degrees and Radians
  • Useful functions: atan2, clamp, lerp, slerp, cross, dot, …
  • ApproxEq for approximate float equality

This example shows some basic usage:

use lina::{point3, vec3, transform, Degrees, Vector};

// Basic vector/point usage
let player_pos = point3(4.0, 5.0, 1.8);
let fox_pos = point3(10.0, 3.0, 0.5);
let view_direction = vec3(1.3, 0.2, 0.0).normalized();
let speed = 1.5;
let new_player_pos = player_pos + view_direction * speed;

println!("{:.2}m still to go!", player_pos.distance_from(fox_pos));

// Create and compose transformation matrices
let view_matrix = transform::look_into(new_player_pos, view_direction, Vector::unit_z());
let proj_matrix = transform::perspective(
    Degrees(90.0),
    16.0 / 9.0,
    0.1..=f32::INFINITY,
    1.0..=0.0,
);
let view_proj = view_matrix.and_then(proj_matrix); // or `proj_matrix * view_matrix`

// Transform points with matrices
let fox_on_screen = view_proj.transform(fox_pos);  // or `view_proj * fox_pos`

Const generics limitations

To express the signature of some functions, feature(generic_const_exprs) is required. Think of Vector::extend which returns a Vector<T, N + 1>. The + 1 is the problem here as this is currently not yet allowed on stable Rust. Most of these functions are related to HcPoint or HcMatrix.

Not only is that feature not stabilized yet, it is also very unfinished and broken. So unfortunately, lina cannot use it. Instead, these functions are implemented for a small number of fixed dimensions via macro. But worry not! For one, these are just a few functions without which lina can still be used without a problem. Further, for the 3D graphics use case, all relevant functions exist, as one is almost never converned with anything with more than 4 dimensions. So the only relevant disadvantage of this is that the docs look less nice, as there are repetitions of the same function.

One further consequence of this is the choice that the const parameters of HcPoint and HcMatrix don’t reflect the number of values/rows/columns, but the the dimension of the space in which the point lives/which the transformation transforms. E.g. HcPoint<3> represents a 3D point, by storing 4 numbers.

Modules

docs

Auxiliary documentation.

matrix

Helper utilities for matrices.

named_scalar

Helper types and traits to access specific coordinates of vectors of points by name (x, y, z and w).

transform

Transformation matrices for common transformations.

Macros

assert_approx_eq

Like assert_eq, but using ApproxEq to compare for approximate equality.

Structs

Degrees

An angle in degrees. A full rotation is 360°.

Dir

A direction in N-dimensional space, represented by a unit vector.

HcMatrix

A homogeneous transformation matrix with C + 1 columns and R + 1 rows representing a transformation from Src to Dst.

HcPoint

A location in N-dimensional space represented by homogeneous coordinates (with N + 1 values).

Matrix

A linear transformatin matrix with C columns and R rows. Represents a linear transformation on cartesian coordinates from Src to Dst.

Point

A location in N-dimensional space with scalar type T.

Radians

An angle in radians. A full rotation is 2π rad.

SphericalDir

A direction (unit vector) described in spherical coordinates (theta θ and phi φ).

SphericalPos

A 3D point described in spherical coordinates (theta θ, phi φ, radius r).

Vector

A displacement in N-dimensional space with scalar type T.

Enums

ModelSpace

A space that is model/object-local usually with a single object at the center.

ProjSpace

A post-projection space with angles and distances distorted.

ViewSpace

A camera-centric space with the camera at the origin looking down an axis (usually z).

WorldSpace

A space containing the whole scene/world with an arbitrary origin.

Traits

ApproxEq

Types that can be checked for approximate equality. Useful for floats.

Float

A floating point scalar.

Scalar

A scalar type in the context of this library.

Space

A semantic geometric space, e.g. model space, world space, view space.

Functions

angle_between

Returns the angle between the two given vectors. Returns garbage if either vector has length 0.

atan2

The atan2 function.

clamp

Clamps val into the given range min..=max.

cross

Returns the cross product a ⨯ b, a vector perpendicular to both input vectors.

dot

Returns the dot product a · b, a scalar value.

lerp

Linearly interpolates between a and b with the given factor. factor = 0 is 100% a, factor = 1 is 100% b.

point2

Shorthand for Point2::new(...), but with fixed S = Generic.

point3

Shorthand for Point3::new(...), but with fixed S = Generic.

project_onto

Projects v onto target, returning target · (v · target).

slerp

Spherical linear interpolation between a and b with the given factor. factor = 0 is 100% a, factor = 1 is 100% b.

vec2

Shorthand for Vec2::new(...), but with fixed S = Generic.

vec3

Shorthand for Vec3::new(...), but with fixed S = Generic.

Type Aliases

Dir2

A 2-dimensional direction.

Dir3

A 3-dimensional direction.

Dir2f

A 2-dimensional direction with scalar type f32.

Dir3f

A 3-dimensional direction with scalar type f32.

HcMat2

A homogeneous transformation matrix storing 3×3 elements.

HcMat3

A homogeneous transformation matrix storing 4×4 elements.

HcMat2f

A homogeneous transformation matrix storing 3×3 f32 elements.

HcMat3f

A homogeneous transformation matrix storing 4×4 f32 elements.

HcPoint2

A location in 2-dimensional space represented by homogeneous coordinates (with 3 values).

HcPoint3

A location in 3-dimensional space represented by homogeneous coordinates (with 4 values).

HcPoint2f

A location in 2-dimensional space represented by homogeneous coordinates (with 3 f32 values).

HcPoint3f

A location in 3-dimensional space represented by homogeneous coordinates (with 4 f32 values).

Mat2

A 2×2 linear transformation matrix.

Mat3

A 3×3 linear transformation matrix.

Mat2f

A 2×2 linear transformation matrix with f32 elements.

Mat3f

A 3×3 linear transformation matrix with f32 elements.

Point2

A location in 2-dimensional space.

Point3

A location in 3-dimensional space.

Point2f

A location in 2-dimensional space with scalar type f32.

Point3f

A location in 3-dimensional space with scalar type f32.

Vec2

A displacement in 2-dimensional space.

Vec3

A displacement in 3-dimensional space.

Vec2f

A displacement in 2-dimensional space with scalar type f32.

Vec3f

A displacement in 3-dimensional space with scalar type f32.