package OCADml

  1. Overview
  2. Docs

2-dimensional vector type, including basic mathematical/geometrical operations and transformations, allowing for points in 2d space, and higher level types composed of them (e.g. Path2.t and Poly2.t) to be manipulated.

type t = v2
val v : float -> float -> t

v x y

Construct a vector from x and y coordinates.

val of_tup : (float * float) -> t

of_tup (x, y)

Construct a vector from a tuple of xy coordinates.

val to_tup : t -> float * float

to_tup t

Convert the vector t to a tuple of xy coordinates.

val zero : t

Zero vector

type line = {
  1. a : t;
  2. b : t;
}

A line segment between two points.

Comparison

val equal : t -> t -> bool

equal a b

Float equality between the vectors a and b.

val compare : t -> t -> int

compare a b

Compare the vectors a and b.

val approx : ?eps:float -> t -> t -> bool

approx ?eps a b

Returns true if the distance between vectors a and b is less than or equal to the epsilon eps.

Basic Arithmetic

val horizontal_op : (float -> float -> float) -> t -> t -> t

horizontal_op f a b

Hadamard (element-wise) operation between vectors a and b using the function f.

val add : t -> t -> t

add a b

Hadamard (element-wise) addition of vectors a and b.

val sub : t -> t -> t

sub a b

Hadamard (element-wise) subtraction of vector b from a.

val mul : t -> t -> t

mul a b

Hadamard (element-wise) product of vectors a and b.

val div : t -> t -> t

div a b

Hadamard (element-wise) division of vector a by b.

val neg : t -> t

neg t

Negation of all elements of t.

val sadd : t -> float -> t

add_scalar t s

Element-wise addition of s to t.

val ssub : t -> float -> t

sub_scalar t s

Element-wise subtraction of s from t.

val smul : t -> float -> t

mul_scalar t s

Element-wise multiplication of t by s.

val sdiv : t -> float -> t

div_scalar t s

Element-wise division of t by s.

val abs : t -> t

abs t

Calculate the absolute value of the vector t.

Vector Math

val norm : t -> float

norm t

Calculate the vector norm (a.k.a. magnitude) of t.

val distance : t -> t -> float

distance a b

Calculate the magnitude of the difference (Hadamard subtraction) between a and b.

val normalize : t -> t

normalize t

Normalize t to a vector for which the magnitude is equal to 1. e.g. norm (normalize t) = 1.

val dot : t -> t -> float

dot a b

Vector dot product of a and b.

val cross : t -> t -> v3

cross a b

Vector cross product of a and b. In the case of 2d vectors, the cross product is performed with an assumed z = 0.

val mid : t -> t -> t

mid a b

Compute the midpoint between the vectors a and b.

val mean : t list -> t

mean l

Calculate the mean / average of all vectors in l.

val mean' : t array -> t

mean' a

Calculate the mean / average of all vectors in the array a.

val angle : t -> t -> float

angle a b

Calculate the angle between the vectors a and b.

val angle_points : t -> t -> t -> float

angle_points a b c

Calculate the angle between the points a, b, and c.

val ccw_theta : t -> float

ccw_theta t

Calculate the angle in radians counter-clockwise t is from the positive x-axis along the xy plane.

val vector_axis : t -> t -> v3

vector_axis a b

Compute the vector perpendicular to the vectors a and b.

val clockwise_sign : ?eps:float -> t -> t -> t -> float

clockwise_sign ?eps a b c

Returns the rotational ordering (around the z-axis, from the perspective of the origin, looking "up" the z-axis) of the points a, b, and c as a signed float, 1. for clockwise, and -1. for counter-clockwise. If the points are collinear (not forming a valid triangle, within the tolerance of eps), 0. is returned.

val collinear : t -> t -> t -> bool

collinear p1 p2 p3

Returns true if p2 lies on the line between p1 and p3.

val lerp : t -> t -> float -> t

lerp a b u

Linearly interpolate between vectors a and b.

val lerpn : ?endpoint:bool -> t -> t -> int -> t list

lerpn a b n

Linearly interpolate n vectors between vectors a and b. If endpoint is true, the last vector will be equal to b, otherwise, it will be about a + (b - a) * (1 - 1 / n).

val distance_to_vector : t -> t -> float

distance_to_vector p v

Distance from point p to the line passing through the origin with unit direction v.

val distance_to_line : ?bounds:(bool * bool) -> line:line -> t -> float

distance_to_line ?bounds ~line t

Distance between the vector t, and any point on line. bounds indicates whether each end {a; b} of line is bounded, or a ray (default = (false, false), indicating an infinite line in both directions.).

val point_on_line : ?eps:float -> ?bounds:(bool * bool) -> line:line -> t -> bool

point_on_line ?eps ?bounds ~line t

Return true if the point t falls within eps distance of the line. bounds indicates whether each end {a; b} of line is bounded, or a ray (default = (false, false), indicating an infinite line in both directions.)

val line_closest_point : ?bounds:(bool * bool) -> line:line -> t -> t

line_closest_point ?bounds ~line t

Find the closest point to t lying on the provided line. bounds indicates whether each end {a; b} of line is bounded, or a ray (default = (false, false), indicating an infinite line in both directions.)

val lower_bounds : t -> t -> t

lower_bounds a b

Compute the lower bounds (minima of each dimension) of the vectors a and b.

val upper_bounds : t -> t -> t

upper_bounds a b

Compute the upper bounds (maxima of each dimension) of the vectors a and b.

Utilities

val map : (float -> float) -> t -> t
val x : t -> float
val y : t -> float
val z : t -> float
val to_v2 : t -> v2
val to_string : t -> string
val deg_of_rad : t -> t

deg_of_rad t

Element-wise conversion of t from radians to degrees.

val rad_of_deg : t -> t

rad_to_deg t

Element-wise conversion of t from degrees to radians.

Infix operations

val (+@) : t -> t -> t

a +@ b

Hadamard (element-wise) addition of a and b.

val (-@) : t -> t -> t

a -@ b

Hadamard (element-wise) subtraction of b from a.

val (*@) : t -> t -> t

a *@ b

Hadamard (element-wise) product of a and b.

val (/@) : t -> t -> t

a /@ b

Hadamard (element-wise) division of a by b.

val (+$) : t -> float -> t

t +$ s

Scalar addition of the vector t and scalar s.

val (-$) : t -> float -> t

t -$ s

Scalar subtraction of the scalar s from the vector t.

val (*$) : t -> float -> t

t *$ s

Scalar multiplication of the vector t by the scalar s.

val (/$) : t -> float -> t

t /$ s

Scalar division of the vector t by the scalar s.

val ortho : t -> t

ortho t

Compute the orthoganal vector of t.

val left_of_line : ?eps:float -> line:line -> t -> float

left_of_line ?eps ~line t

Return -1. if t is left of line, 1. if it is to the right, and 0. if it falls on (within eps) the line. Float is returned as this is simply a clockwise check.

val line_intersection : ?eps:float -> ?bounds1:(bool * bool) -> ?bounds2:(bool * bool) -> line -> line -> t option

line_intersection ?eps ?bounds1 ?bounds2 a b

Find the intersection (if it exists) between the lines a and b. bounds1 and bounds2 indicate whether the ends of a and b respectively are bounded or are infinite rays.

val line_normal : t -> t -> t

line_normal p1 p2

Calculates the normal (perpendicular vector) of the line between p1 and p2.

Transformations

Spatial transformations. Quaternion operations are provided when this module is included in OCADml.

val rotate : ?about:t -> float -> t -> t

rotate ?about r t

Rotation of t by r (in radians) around the origin (or the point about if provided).

val zrot : ?about:t -> float -> t -> t

zrot ?about r t

Rotation of t by r (in radians) around the origin (or the point about if provided). Alias to rotate.

val translate : t -> t -> t

translate p t

Translate t along the vector p. Equivalent to add.

val xtrans : float -> t -> t

xtrans x t

Translate t by the distance x along the x-axis.

val ytrans : float -> t -> t

ytrans y t

Translate t by the distance y along the y-axis.

val scale : t -> t -> t

scale s t

Scale t by factors s. Equivalent to mul.

val xscale : float -> t -> t

xscale x t

Scale t by the factor x in the x-dimension.

val yscale : float -> t -> t

yscale y t

Scale t by the factor y on the y-dimension.

val mirror : t -> t -> t

mirror ax t

Mirrors t across an axis through the origin, defined by the vector ax.

2d - 3d conversion

val of_v3 : v3 -> t

of_v3 v

Drop the z coordinate from v to create a 2d vector.

val to_v3 : ?z:float -> t -> v3

to_v3 ?z v

Create a 3d vector from the 2d vector v by adding a z coordinate (default = 0.)

val lift : Plane.t -> V2.t -> V3.t

lift p t

Lift the 2d vector/point t onto the plane p. On partial application of p, a Affine3.t is computed to perform the lift transform. Alias to Plane.lift.

Additional 2d transformations

val affine : Affine2.t -> V2.t -> V2.t

affine m t

Apply 2d affine transformation matrix m to the vector t.

2d to 3d transformations

val affine3 : Affine3.t -> v2 -> V3.t

affine3 m t

Apply 3d affine transformation matrix m to the vector t, taking it into the 3rd dimension.

val quaternion : ?about:V3.t -> Quaternion.t -> v2 -> V3.t

quaternion ?about q t

Rotate t with the quaternion q around the origin (or the point about if provided), taking it into the 3rd dimension.

val axis_rotate : ?about:V3.t -> V3.t -> float -> v2 -> V3.t

axis_rotate ?about ax a t

Rotates the vector t around the axis ax through the origin (or the point about if provided) by the angle a, taking it into the third dimension.