Module Scad_ml.V3

3-dimensional vector type, including basic mathematical/geometrical operations and transformations mirroring those found in Scad, 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 in similar fashion to 3d OpenSCAD shapes (Scad.d3).

type t = v3 = {
x : float;
y : float;
z : float;
}

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.

type bbox = {
min : t;
max : t;
}

Bounding box.

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.

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) 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.

val bbox : t -> t -> bbox

bbox a b

Compute the bounding box that contains the vectors a and b.

val bbox_intersect : bbox -> bbox -> bbox option

bbox_intersect a b

Compute the intersect of the bounding boxes a and b.

val bbox_area : bbox -> float

bbox_area bb

Compute the area of the bounding box bb.

val bbox_centroid : bbox -> t

bbox_centroid bb

Compute the centroid of the bounding box bb.

Utilities

val map : ( float -> float ) -> t -> t
val get_x : t -> float
val get_y : t -> float
val get_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 bbox_volume : bbox -> float

bbox_volume bb

Compute the volume of the bounding box bb.

Transformations

Equivalent to those found in Scad. Quaternion operations are provided when this module is included in Scad_ml.

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 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.