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