<!-- This file copyright Persistence of Vision Raytracer Pty. Ltd. 2003-2004 -->
<html>
<head>
<!-- NOTE: In order to users to help find information about POV-Ray using -->
<!-- web search engines, we ask you to *not* let them index documentation -->
<!-- mirrors because effectively, when searching, users will get hundreds -->
<!-- of results containing the same information! For this reason, the two -->
<!-- meta tags below disable archiving and indexing of this page by all -->
<!-- search engines that support these meta tags. -->
<meta content="noarchive" name="robots">
<meta content="noindex" name="robots">
<meta content="no-cache" http-equiv="Pragma">
<meta content="0" http-equiv="expires">
<title>3.7.18 transforms.inc</title>
<link href="povray35.css" rel="stylesheet" type="text/css">
</head>
<body>
<table class="NavBar" width="100%">
<tr>
<td align="left" nowrap="" valign="middle" width="32">
<a href="s_148.html"><img alt="previous" border="0" src="prev.png"></a>
</td>
<td align="left" valign="middle" width="30%">
<a href="s_148.html">3.7.17 textures.inc</a>
</td>
<td align="center" valign="middle">
<strong class="NavBar">POV-Ray 3.6 for UNIX documentation</strong><br> <strong>3.7.18
transforms.inc</strong>
</td>
<td align="right" valign="middle" width="30%">
<a href="s_150.html">3.7.19 woodmaps.inc, woods.inc</a>
</td>
<td align="right" nowrap="" valign="middle" width="32">
<a href="s_150.html"><img alt="next" border="0" src="next.png"></a>
</td>
</tr>
</table>
<h3><a name="s03_07_18">3.7.18 </a>transforms.inc</h3>
<p>
Several useful transformation macros. All these macros produce transformations, you can use them anywhere you can
use scale, rotate, etc. The descriptions will assume you are working with an object, but the macros will work fine for
textures, etc.<a name="s03_07_18_i1"><a name="Shear_Trans"></a>
</p>
<p>
<code>Shear_Trans(A, B, C)</code>. This macro reorients and deforms an object so its original XYZ axes point along
A, B, and C, resulting in a shearing effect when the vectors are not perpendicular. You can also use vectors of
different lengths to affect scaling, or use perpendicular vectors to reorient the object.<br> Parameters:
</p>
<ul>
<li>
<code>A, B, C</code> = Vectors representing the new XYZ axes for the transformation.
</li>
</ul>
<a name="s03_07_18_i2"><a name="Matrix_Trans"></a>
<p>
<code>Matrix_Trans(A, B, C, D)</code>. This macro provides a way to specify a matrix transform with 4 vectors. The
effects are very similar to that of the Shear_Trans() macro, but the fourth parameter controls translation.<br>
Parameters:
</p>
<ul>
<li>
<code>A, B, C, D</code> = Vectors for each row of the resulting matrix.
</li>
</ul>
<a name="s03_07_18_i3"><a name="Axial_Scale_Trans"></a>
<p>
<code>Axial_Scale_Trans(Axis, Amt)</code>. A kind of directional scale, this macro will "stretch" an
object along a specified axis.<br> Parameters:
</p>
<ul>
<li>
<code>Axis</code> = A vector indicating the direction to stretch along.
</li>
<li>
Amt = The amount to stretch.
</li>
</ul>
<a name="s03_07_18_i4"><a name="Axis_Rotate_Trans"></a>
<p>
<code>Axis_Rotate_Trans(Axis, Angle)</code>. This is equivalent to the transformation done by the vaxis_rotate()
function, it rotates around an arbitrary axis.<br> Parameters:
</p>
<ul>
<li>
<code>Axis</code> = A vector representing the axis to rotate around.
</li>
<li>
<code>Angle</code> = The amount to rotate by.
</li>
</ul>
<a name="s03_07_18_i5"><a name="Rotate_Around_Trans"></a>
<p>
<code>Rotate_Around_Trans(Rotation, Point)</code>. Ordinary rotation operates around the origin, this macro rotates
around a specific point.<br> Parameters:
</p>
<ul>
<li>
<code>Rotation</code> = The rotation vector, the same as the parameter to the rotate keyword.
</li>
<li>
<code>Point</code> = The point to rotate around.
</li>
</ul>
<a name="s03_07_18_i6"><a name="Reorient_Trans"></a>
<p>
<code>Reorient_Trans(Axis1, Axis2)</code>. This aligns <code>Axis1</code> to <code>Axis2</code> by rotating the
object around a vector perpendicular to both axis1 and axis2. <br>Parameters:
</p>
<ul>
<li>
<code>Axis1</code> = Vector to be rotated.
</li>
<li>
<code>Axis2</code> = Vectors to be rotated towards.
</li>
</ul>
<a name="s03_07_18_i7"><a name="Point_At_Trans"></a>
<p>
<code>Point_At_Trans(YAxis)</code>. This macro is similar to Reorient_Trans(), but it points the y axis along Axis.<br>
Parameters:
</p>
<ul>
<li>
<code>YAxis</code> = The direction to point the y axis in.
</li>
</ul>
<a name="s03_07_18_i8"><a name="Center_Trans"></a>
<p>
<code>Center_Trans(Object, Axis)</code>. Calculates a transformation which will center an object along a specified
axis. You indicate the axes you want to center along by adding "x", "y", and "z"
together in the Axis parameter.
</p>
<p class="Note">
<strong>Note:</strong> this macro actually computes the transform to center the bounding box of the
object, which may not be entirely accurate. There is no way to define the "center" of an arbitrary object.
</p>
<p>
Parameters:
</p>
<ul>
<li>
<code>Object</code> = The object the center transform is being computed for.
</li>
<li>
<code>Axis</code> = The axes to center the object on.
</li>
</ul>
<p>
Usage:
</p>
<pre>
object {MyObj Center_Trans(MyObj, x)} //center along x axis
</pre>
<p>
You can also center along multiple axes:
</p>
<pre>
object {MyObj Center_Trans(MyObj, x+y)} //center along x and y axis
</pre>
<a name="s03_07_18_i9"><a name="Align_Trans"></a>
<p>
<code>Align_Trans(Object, Axis, Pt)</code>. Calculates a transformation which will align the sides of the bounding
box of an object to a point. Negative values on Axis will align to the sides facing the negative ends of the
coordinate system, positive values will align to the opposite sides, 0 means not to do any alignment on that axis.<br>
Parameters:
</p>
<ul>
<li>
<code>Object</code> = The object being aligned.
</li>
<li>
<code>Axis</code> = A combination of +x, +y, +z, -x, -y, and -z, or a vector where each component is -1, 0, or +1
specifying the faces of the bounding box to align to the point.
</li>
<li>
<code>Point</code> = The point to which to align the bounding box of the object.
</li>
</ul>
<p>
Usage:
</p>
<pre>
object {
MyObj
Align_Trans(MyObj, x, Pt) //Align right side of object to be
//coplanar with Pt
Align_Trans(MyObj,-y, Pt) //Align bottom of object to be
// coplanar with Pt
}
</pre>
<a name="s03_07_18_i10"><a name="vtransform"></a>
<p>
<code>vtransform(Vect, Trans)</code> and <code>vinv_transform(Vect, Trans)</code>.<br> The <code>vtransform()</code>
macro takes a transformation (rotate, scale, translate, etc...) and a point, and returns the result of applying the
transformation to the point. The <code>vinv_transform()</code> macro is similar, but applies the inverse of the
transform, in effect "undoing" the transformation. You can combine transformations by enclosing them in a
transform block.<br> Parameters:
</p>
<ul>
<li>
<code>Vect</code> = The vector to which to apply the transformation.
</li>
<li>
<code>Trans</code> = The transformation to apply to Vect.
</li>
</ul>
<a name="s03_07_18_i11"><a name="spline_trans"></a>
<p>
<code>Spline_Trans(Spline, Time, SkyVector, ForeSight, Banking)</code>. This macro aligns an object to a spline for
a given time value. The Z axis of the object will point in the forward direction of the spline and the Y axis of the
object will point upwards.<br> Parameters:
</p>
<ul>
<li>
<code>Spline</code> = The spline that the object is aligned to.
</li>
<li>
<code>Time</code> = The time value to feed to the spline, for example clock.
</li>
<li>
<code>Sky</code> = The vector that is upwards in your scene, usually y.
</li>
<li>
<code>Foresight</code> = A positive value that controls how much in advance the object will turn and bank. Values
close to 0 will give precise results, while higher values give smoother results. It will not affect parsing speed, so
just find the value that looks best.
</li>
<li>
<code>Banking</code> = How much the object tilts when turning. The amount of tilting is equally much controlled
by the ForeSight value.
</li>
</ul>
<p>
Usage:
</p>
<pre>
object {MyObj Spline_Trans(MySpline, clock, y, 0.1, 0.5)}
</pre>
<br>
<table class="NavBar" width="100%">
<tr>
<td align="left" nowrap="" valign="middle" width="32">
<a href="s_148.html"><img alt="previous" border="0" src="prev.png"></a>
</td>
<td align="left" valign="middle" width="30%">
<a href="s_148.html">3.7.17 textures.inc</a>
</td>
<td align="center" valign="middle">
<strong>3.7.18 transforms.inc</strong>
</td>
<td align="right" valign="middle" width="30%">
<a href="s_150.html">3.7.19 woodmaps.inc, woods.inc</a>
</td>
<td align="right" nowrap="" valign="middle" width="32">
<a href="s_150.html"><img alt="next" border="0" src="next.png"></a>
</td>
</tr>
</table>
</body> </html>
