;;
;; Copyright 2002, 2009 Genworks International
;;
;; This source file is part of the General-purpose Declarative
;; Language project (GDL).
;;
;; This source file contains free software: you can redistribute it
;; and/or modify it under the terms of the GNU Affero General Public
;; License as published by the Free Software Foundation, either
;; version 3 of the License, or (at your option) any later version.
;;
;; This source file is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
;; Affero General Public License for more details.
;;
;; You should have received a copy of the GNU Affero General Public
;; License along with this source file. If not, see
;; .
;;
Utility Functions, Macros, and Types Defined in GDL
====================================================
NOTE: These are also included in the reference documentation available from a running GDL session at
http://localhost:/yadd
(defun 3d-distance (point-1 point-2)
"Return a number which is the three-dimensional distance from point-1 to point-2")
(defun 3d-vector-to-array (vector)
"Returns a Lisp array of numbers from a 3d-vector.")
;;
;; NOTE: matrix:add-matrix is also available, from the CMU repository.
;; it works similarly to this function.
;;
(defun add-matrices (&rest matrices)
"Adds together matrices of similar rank.")
(defun add-vectors (&rest vectors)
"Return a new vector, the result of addition")
(defun alignment (axis1 vector1 &optional axis2 vector2 axis3 vector3)
"Returns a transformation matrix corresponding to the given axes and vectors. Axis3
and vector3 should be given only if you want the transformation matrix to have a
left-handed coordinate system -- otherwise vector3 will default to the cross
of vector1 and vector2 (in the appropriate order).")
(defun alist2plist (alist)
"Returns a plist converted from an assoc-list")
(defun always (arg)
"Always returns T.")
(defun angle-between-vectors (vector-1 vector-2 &optional reference-vector &key (epsilon *zero-epsilon*) -ve)
"Returns smallest positive angle between vector-1 and vector-2, if reference-vector
is nil. If non-nil, reference-vector indicates the direction of positive rotation.
If -ve is non-nil, true negative angles will be returned. Epsilon is used to check
for angles close to zero or 2pi.")
(defun angle-between-vectors-d (vector-1 vector-2 &optional reference-vector -ve)
"return the angle (in degrees) between the two vectors, in degrees. If
no reference-vector given, return smallest possible angle. If direction
vector is given, return according to right-hand rule. If \"-ve\" is given,
return negative number for angle if it really is negative according to
right-hand rule.")
(defun array-to-3d-vector (array)
"Returns a 3d-vector from a 3-by-1 Lisp array of numbers.")
(defun coincident-point? (point-1 point-2 &key (tolerance *zero-epsilon*))
"Returns t if the distance between point-1 and point-2 is less
than epsilon. The default epsilon is *zero-epsilon*.")
;;
;;NOTE: create-obliqueness currently computes absolute obliqueness -
;; computation relative to self's parent is not yet implemented.")
;;
(defun create-obliqueness (v1 name-v1 v2 name-v2 self)
"Compute absolute transformation matrix. v1 and v2 are vectors,
name-v1 and name-v2 are direction keywords such as :front, :right,
etc. v1 and v2 should be normal to each other.")
(defun cross-vectors (vector-1 vector-2)
"Compute the cross-product of vector-1 and vector-2, a new vector.")
(defun degree (degrees &optional (minutes 0) (seconds 0))
"Converts degrees to radians")
(defun dot-vectors (vector-1 vector-2)
"Compute the dot-product of vector-1 and vector-2, a number.")
(defun ensure-list (possible-list)
"Returns a list from possible-list")
(defun flatten (list)
"Returns a flat list with all nesting (and all NIL values) removed.")
(defun get-x (point)
"Returns X component of point or vector")
(defun get-y (point)
"Returns Y component of point or vector")
(defun get-z (point)
"Returns Z component of point or vector")
(defun half (num)
"Divides number by two.")
(defun index-filter (function list)
"Returns items from list for whose indices function is true.")
(defun inter-circle-circle (center-1 radius-1 center-2 radius-2 positive-angle? &key (tolerance *zero-epsilon*))
"Returns one of two points of intersection between two circles, or NIL if there is no intersection.")
(defun inter-circle-sphere (circle-center circle-radius circle-plane-normal
sphere-center sphere-radius positive-angle? &key (tolerance *zero-epsilon*))
"Returns one of two points of intersection between circle and sphere, or NIL if there is no intersection.")
(defun inter-line-plane (p-line u-line p-plane u-plane)
"Return single point of intersection between line and plane or NIL if
no intersections. p-line is a point on the line, u-line is direction
vector of the line, p-plane is a point on the plane, and u-plane is
normal vector to the plane.")
(defun inter-line-sphere (p-line u-line center radius side-vector)
"Takes point on the line (p-line), direction vector of line (u-line),
center of sphere (center), radius of sphere (radius), and a
side-selection vector (side-vector) to decide between two possible
intersections, and return either a point or NIL.")
(defun lastcar (list)
"Returns last element of list.")
(defun length-vector (vector)
"Returns the vector's magnitude.")
(defun list-of-numbers (num1 num2 &optional (increment 1))
"Returns a list of numbers starting from num2 going to num2 incremented by increment.")
(defun make-keyword (string)
"Converts string or symbol into a keyword symbol.")
(defmacro make-vector (x y z)
"Return a 3D vector of double-floats.")
(defmacro make-point (x y z)
"Return a 3D vector of double-floats (points are identical with vectors).")
(defun make-transform (list-of-lists)
"Converts a list of lists into a tranformation matrix.")
(defun mapsend (object-list message)
"Sends message, which should evaluate to a keyword, to each object in object-list,
and returns a new list with each resultant value.")
(defun maptree (node function &optional (accept? #'always)
(prune? #'never)
(get-children :children))
"Returns the list resulting from applying function to each object
in a defpart tree starting from node, accepting only those which pass
the accept? function, stopping tree recursion at those which pass the
prune? function, and using the get-children message to compute the
children of a given object.")
(defun matrix*vector (matrix vector)
"Multiplies matrix by vector with compatible rank.")
;;
;; From Paul Graham ANSI Common Lisp
;;
(defun most (function list)
"return member of list which returns max when function applied.
As second value return actual max value (return-value of function)")
;;
;; NOTE: matrix:multiply-matrix is also available, from the CMU repository.
;; it works similarly to this function.
;;
(defun multiply-matrices (matrix-1 matrix-2)
"Multiplies one matrix by another of compatible rank.")
(defun near-to? (number near-to &optional (tolerance *zero-epsilon*))
"Predicate to test if number is within tolerance of
near-to. The default tolerance is *zero-epsilon*.")
(defun near-zero? (number &optional (tolerance *zero-epsilon*))
"Returns T if number is within tolerance of zero.")
(defun never (arg)
"Always returns NIL.")
(defun number-format (number &optional decimal-places)
"Returns string representing number rounded to specified number of decimal places.")
(defun number-round (number &optional decimal-places)
"Returns double-float of number rounded to specified number of decimal places.")
(defun orthogonal-component (vector reference-vector)
"Returns the vector closest to reference-vector which is normal to vector.")
(deftype part-name-symbol ()
"(typep