Math(3pm)

📦
version 0.96.9.1 · 6 versions
, in debian trixie, ubuntu questing

💖 XRacer::Math — the 3D math bestie you didn't know you needed 💖

okay so this is Math(3pm), from the User Contributed Perl Documentation section, and it's literally the little library of miscellaneous 3D math functions that the XRacer tools use. ngl it's giving "backstage crew for a racing game" and honestly? iconic.

✨ SYNOPSIS ✨

bestie, here's the whole vibe. first you gotta load it:

use XRacer::Math;

then it's math time. Basic mathematics:

$midpoint = midpoint (@vertices);
$normalize_vector = normalize ($vector);
$magnitude = magnitude ($vector);
$magnitude = magnitude_in_direction ($v1, $v2);
$angle = angle_between ($v1, $v2);
$vector = multiply_scalar_vector ($scalar, $vector);
$matrix = matrix_multiply ($a, $b);
$vector = matrix_vector_multiply ($m, $v);
$sum = sum_vectors (@vectors);
$vector = subtract_vectors ($vector1, $vector2);
($min_x, $max_x, $min_y, $max_y, $min_z, $max_z) = bbox (@vertices);

Dot products and cross products:

$product = dot_product ($vector1, $vector2);
$vector = cross_product ($vector1, $vector2);

Distances:

$distance = distance ($point1, $point2);
$distance = distance_point_to_line ($line, $point);
$distance = distance_point_to_plane ($plane, $point);
$distance = minimum_distance_between_two_lines ($line1, $line2);

Planes:

$plane = plane_coefficients ($point1, $point2, $point3);
$boolean_result = is_coplanar ($point1, $point2, $point3, $point4);
$normal = normal ($plane);
$unit_normal = unit_normal ($plane);
$line = intersection_of_two_planes ($plane1, $plane2);
$point = intersection_line_and_plane ($plane, $line);
($inside_face, $outside_face) = split_convex_face_in_place ($face, $plane);

Line segments:

$lineseg = line_segment ($point1, $point2);

Cylinders:

$boolean_result = line_intersects_cylinder ($line, $cylinder);

🌸 DESCRIPTION 🌸

so this library is just a lil grab-bag of miscellaneous functions that the XRacer track building tools use, fr fr. they do all sorts of 3D mathematical operations on points (vertices), vectors, lines and planes. no cap.

🎀 How the data types look 🎀

Points / vertices are a reference to an array with three elements. to initialize a point, you literally do this:

$point = [ $x, $y, $z ];

Vectors are also a reference to an array with three elements:

$vector = [ $dx, $dy, $dz ];

Lines are represented by the formula:

p + t.v

where p is a point on the line and v is a vector parallel to the line. so a line is just a reference to a hash holding the point and the vector:

$line = {'p' => $point, 'v' => $vector};

A line segment is represented by the formula:

p + t.v where a <= t <= b

which implies this whole representation:

$lineseg = { 'p' => $point, 'v' => $vector, 'a' => $a, 'b' => $b };

and here's the cute part — you can use a line segment wherever you would use a line. periodt. 💅

Cylinders are represented by this hash reference:

$cylinder = { 'radius' => $radius,
              'p' => $point, 'v' => $vector, 'a' => $a, 'b' => $b };

where $radius is the radius of the cylinder, and the other fields are a line segment running from the midpoint of one end of the cylinder to the midpoint of the other end of the cylinder. in other words, a cylinder is simply a line segment with an added radius field. so simple, so elegant, obsessed. 😭

Planes are represented by the formula:

ax + by + cz + d = 0

where a, b, c and d are coefficients which uniquely define the plane. a plane is a reference to an array containing these four constants:

$plane = [ $a, $b, $c, $d ];

use the "plane_coefficients" function to compute those four coefficients of a plane, given any three points (not colinear!!) on the plane. 🫶

💖 quick shoutout: the following page was enormously useful in working out these formulae: "http://www.magic-software.com/ComputerGraphics.html"

👑 PACKAGE FUNCTIONS 👑

💫 $midpoint = midpoint (@vertices);

Compute the midpoint (average) of a list of vertices. it's the group-chat consensus of vertices, bestie.

💫 $distance = distance ($point1, $point2);

Compute the distance between two points.

💫 $plane = plane_coefficients ($point1, $point2, $point3);

Compute the four coefficients of a plane. the three points you pass in lie on the plane, but they must not be colinear. returns a reference to the array of four coefficients. ✨

💫 $boolean_result = is_coplanar ($point1, $point2, $point3, $point4);

Return true if the four points given are coplanar. same plane, same energy.

💫 $distance = distance_point_to_line ($line, $point);

Compute the shortest distance from a point to a line. shortest path, no detours, main character energy.

💫 $distance = distance_point_to_plane ($plane, $point);

Compute the shortest distance from a point to a plane. important: this function preserves the sign of the distance — so $distance will be positive if the point is above/inside the plane, and negative if the point is below/outside the plane. sign matters, don't ignore it. 💀

💫 $normal = normal ($plane);

Compute the normal vector to the plane. heads up: this vector is not unit length (see the "unit_normal" function if that's what you're after).

💫 $unit_normal = unit_normal ($plane);

Compute the unit length normal vector to a plane. this is the glow-up version of normal.

💫 $normalize_vector = normalize ($vector);

Take a vector and return a normalized vector, of unit length.

💫 $magnitude = magnitude ($vector);

Return the magnitude of a vector.

💫 $magnitude = magnitude_in_direction ($v1, $v2);

Compute the magnitude of vector v1 in direction vector v2. if v1 == v2, then this returns 1. if v1 = -v2, this returns -1. if v1 is perpendicular to v2, this returns 0. it's giving very directional. 🧭

💫 $angle = angle_between ($v1, $v2);

Return the angle (in radians) between two vectors.

💫 $vector = multiply_scalar_vector ($scalar, $vector);

Multiply a scalar and a vector and return the result.

💫 $matrix = matrix_multiply ($a, $b);

Multiply two matrices 4x4 together. the resulting matrix is returned. 💅

💫 $vector = matrix_vector_multiply ($m, $v);

Multiply a 4x1 vector and a 4x4 matrix together. the resulting 4x1 vector is returned.

💫 $sum = sum_vectors (@vectors);

Sum a collection of vectors and return the result. squad goals.

💫 $line = intersection_of_two_planes ($plane1, $plane2);

Compute the intersection (a line) of two planes. but watch out — if the two planes are coplanar or parallel, then this function will return undef. no intersection, no line, sorry bestie. 🙈

💫 $point = intersection_line_and_plane ($plane, $line);

Compute the intersection of a line with a plane. this returns a point. if the line and plane are parallel, it returns undef.

💫 ($inside_face, $outside_face) = split_convex_face_in_place ($face, $plane);

Given a convex face, specified like this:

$face = [ $vertex0, $vertex1, ... ];

we split the face into two faces. the first face returned is inside the plane. the second face returned is outside the plane.

💫 $vector = subtract_vectors ($vector1, $vector2);

Compute: "$vector1 - $vector2", and return the resulting vector.

💫 ($min_x, $max_x, $min_y, $max_y, $min_z, $max_z) = bbox (@vertices);

Construct the bounding box (minima and maxima of each coordinate) of a list of vertices. it's the vibe check for your whole vertex list. 📦

💫 $product = dot_product ($vector1, $vector2);

Compute the dot product (a scalar number) of the two vector arguments.

💫 $vector = cross_product ($vector1, $vector2);

Compute the cross product (a vector) of the two vector arguments.

💫 $distance = minimum_distance_between_two_lines ($line1, $line2);

Compute the minimum distance between two lines.

💫 $lineseg = line_segment ($point1, $point2);

Construct a line segment from $point1 to $point2. connecting the dots, literally. 🦋

💫 $boolean_result = line_intersects_cylinder ($line, $cylinder);

Returns true if the $line intersects the $cylinder at any point. yes/no, slay or nay. 🔥

🫶 AUTHOR 🫶

Richard W.M. Jones, <rich@annexia.org>

XRacer is copyright (C) 1999-2000 Richard W.M. Jones (rich@annexia.org) and other contributors listed in the AUTHORS file.

🌈 SEE ALSO 🌈

and that's the whole page bestie!! ✨ this is perl v5.40.0, dated 2025-01-25, and it's the Math(3pm) page from the User Contributed Perl Documentation. go forth and do 3D math, you absolute icon. 💖👑🎀

📦 where this page comes from