OCADml 0.3.1 · OCaml Package

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

type t = Gg.v3

3d vector

val v : float -> float -> float -> t

v x y z

Construct a vector from x, y, and z coordinates.

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

of_tup (x, y, z)

Construct a vector from a tuple of xyz coordinates.

val to_tup : t -> float * float * float

to_tup t

Convert the vector t to a tuple of xyz coordinates.

val zero : t

Zero vector

type line = {

a : t;
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.

Transformations

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

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

xrot ?about theta t

Rotate t by theta radians in around the x-axis through the origin (or the point about if provided).

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

yrot ?about theta t

Rotate t by theta radians in around the y-axis through the origin (or the point about if provided).

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

zrot ?about theta t

Rotate t by theta radians in around the z-axis through the origin (or the point about if provided).

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

rotate ?about r t

Euler (zyx) rotation of t by the r (in radians) around the origin (or the point about if provided). Equivalent to xrot x t |> yrot y |> zrot z, where {x; y; z} = r.

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 ztrans : float -> t -> t

ztrans z t

Translate t by the distance z along the z-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 in the y-dimension.

val zscale : float -> t -> t

zscale z t

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

val mirror : t -> t -> t

mirror ax t

Mirrors t on a plane through the origin, defined by the normal vector ax.

val projection : t -> t

projection t

Project t onto the XY plane.

2d - 3d conversion

val of_v2 : ?z:float -> v2 -> t

of_v2 ?z v

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

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

project p t

Project the 3d vector/point t onto the plane p. On partial application of p, a Affine3.t is computed to perform the projection transform. Alias to Plane.project.

Additional 3d transformations

val affine : Affine3.t -> V3.t -> V3.t

affine m t

Apply affine transformation matrix m to the vector t.

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

quaternion ?about q t

Rotate t with the quaternion q around the origin (or the point about if provided).

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

axis_rotate ax a t

Rotates the vector t around the axis ax through the origin (or the point about if provided) by the angle a.

package OCADml