NAME¶
XRacer::Math - Library of miscellaneous 3D math functions used by XRacer tools.
SYNOPSIS¶
use XRacer::Math;
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¶
This library contains miscellaneous functions which are used by the XRacer track
building tools. The functions perform various 3D mathematical operations on
points (vertices), vectors, lines and planes.
Points or vertices are represented by a reference to an array containing three
elements. That is to say, to initialize a point, do this:
$point = [ $x, $y, $z ];
Vectors are represented by a reference to an array containing 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. Therefore
a line is simply a reference to a hash containing the point and vector:
$line = {'p' => $point, 'v' => $vector};
A line segment is represented by the formula:
p + t.v where a <= t <= b
implying the following representation:
$lineseg = { 'p' => $point, 'v' => $vector, 'a' => $a, 'b' => $b };
Notice that you can use a line segment wherever you would use a line.
Cylinders are represented by the 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 added radius field.
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 the four coefficients
of a plane, given any three points (not colinear) on the plane.
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.
- $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
given as parameters lie on the plane, but 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.
- $distance = distance_point_to_line ($line, $point);
- Compute the shortest distance from a point to a line.
- $distance = distance_point_to_plane ($plane, $point);
- Compute the shortest distance from a point to a plane. 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.
- $normal = normal ($plane);
- Compute the normal vector to the plane. This vector is not
unit length (see the "unit_normal" function for that).
- $unit_normal = unit_normal ($plane);
- Compute the unit length normal vector to a plane.
- $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.
- $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.
- $line = intersection_of_two_planes ($plane1, $plane2);
- Compute the intersection (a line) of two planes. If the two
planes are coplanar or parallel, then this function will return
undef.
- $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 as follows:
$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.
- $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.
- $boolean_result = line_intersects_cylinder ($line,
$cylinder);
- Returns true if the $line intersects the $cylinder at any
point.
AUTHOR¶
Richard W.M. Jones, <rich@annexia.org>
COPYRIGHT¶
XRacer is copyright (C) 1999-2000 Richard W.M. Jones (rich@annexia.org) and
other contributors listed in the AUTHORS file.
SEE ALSO¶
perl(1),
xracer(6).