Math(3pm)						User Contributed Perl Documentation						 Math(3pm)

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

perl v5.14.2							    2000-02-19								 Math(3pm)