Difference between revisions of "Reference:Prism"

From POV-Wiki
Jump to navigation Jump to search
m (1 revision: Reference Migration Initial Load)
m (clean up and user contributed additions)
Line 15: Line 15:
 
{{#indexentry:sturm, prism}}
 
{{#indexentry:sturm, prism}}
 
{{#indexentry:keyword, sturm}}
 
{{#indexentry:keyword, sturm}}
<p>The <code>prism</code> is an object generated by specifying one or more two-dimensional, closed curves in the x-z plane and sweeping them along y axis. These curves are defined by a set of points which are connected by linear, quadratic, cubic or bezier splines. The syntax for the prism is:</p>
+
<p>The <code>prism</code> is an object generated by specifying one or more two-dimensional, closed curves in the x-z plane and sweeping them along y axis. These curves are defined by a set of points which are connected by linear, quadratic, cubic or bezier splines.</p>
 +
<p>The syntax for the prism is:</p>
 
<pre>
 
<pre>
 
PRISM:
 
PRISM:
Line 29: Line 30:
 
   sturm | OBJECT_MODIFIER
 
   sturm | OBJECT_MODIFIER
 
</pre>
 
</pre>
 
 
{{#indexentry:default values, prism}}
 
{{#indexentry:default values, prism}}
 
<p>Prism default values:</p>
 
<p>Prism default values:</p>
 
 
<pre>
 
<pre>
 
SPLINE_TYPE  : linear_spline
 
SPLINE_TYPE  : linear_spline
Line 38: Line 37:
 
sturm        : off
 
sturm        : off
 
</pre>
 
</pre>
 
 
{{#indexentry:linear_sweep, prism}}
 
{{#indexentry:linear_sweep, prism}}
 
{{#indexentry:keyword, linear_sweep}}  
 
{{#indexentry:keyword, linear_sweep}}  
<p>The first items specify the spline type and sweep type. The defaults if
+
<p>The first items specify the spline type and sweep type. The defaults if none is specified is <code>linear_spline</code> and <code> linear_sweep</code>. This is followed by two float values <em><code>Height_1</code></em> and <em> <code>Height_2</code></em> which are the y
none is specified is <code>linear_spline</code> and <code>
+
coordinates of the top and bottom of the prism. This is followed by a float value specifying the number of 2-D points you will use to define the prism.This includes all control points needed for quadratic, cubic and bezier splines. This is followed by the specified number of 2-D vectors which define the shape in the x-z plane.</p>
linear_sweep</code>. This is followed by two float values <em><code>
+
<p>The interpretation of the points depends on the spline type. The prism object allows you to use any number of sub-prisms inside one prism statement, they are of the same spline and sweep type. Wherever an even number of sub-prisms overlaps a hole appears.</p>
Height_1</code></em> and <em> <code>Height_2</code></em> which are the y
+
<p class="Note"><strong>Note:</strong> You need not have multiple sub-prisms and they need not overlap as in the following examples.</p>
coordinates of the top and bottom of the prism. This is followed by a float
+
<p>In the <code>linear_spline</code> the first point specified is the start of the first sub-prism. The following points are connected by straight lines. If you specify a value identical to the first point, this closes the sub-prism and next point starts a new one. When you specify the value of that sub-prism's start, then it is closed. Each of the sub-prisms has to be closed by repeating the first point of a sub-prism at the end of the sub-prism's point sequence.</p>
value specifying the number of 2-D points you will use to define the prism.
+
<p>In the following example, there are two rectangular sub-prisms nested inside each other to create a frame.</p>
(This includes all control points needed for quadratic, cubic and bezier
 
splines). This is followed by the specified number of 2-D vectors which
 
define the shape in the x-z plane.</p>
 
<p>
 
The interpretation of the points depends on the spline type. The prism
 
object allows you to use any number of sub-prisms inside one prism statement
 
(they are of the same spline and sweep type). Wherever an even number of
 
sub-prisms overlaps a hole appears.</p>
 
<p class="Note"><strong>Note:</strong> You need not have multiple sub-prisms and they need not overlap as these examples do.</p>
 
<p>
 
In the <code>linear_spline</code> the first point specified is the start of
 
the first sub-prism. The following points are connected by straight lines. If
 
you specify a value identical to the first point, this closes the sub-prism
 
and next point starts a new one. When you specify the value of that
 
sub-prism's start, then it is closed. Each of the sub-prisms has to be
 
closed by repeating the first point of a sub-prism at the end of the
 
sub-prism's point sequence. In this example, there are two rectangular
 
sub-prisms nested inside each other to create a frame.</p>
 
 
<pre>
 
<pre>
 
prism {
 
prism {
Line 73: Line 53:
 
   }
 
   }
 
</pre>
 
</pre>
 
+
<p>The last sub-prism of a linear spline prism is automatically closed, just like the last sub-polygon in the polygon statement, if the first and last point of the sub-polygon's point sequence are not the same. This makes it very easy to convert between polygons and prisms. Quadratic, cubic and bezier splines are <em>never</em> automatically closed.</p>
<p>The last sub-prism of a linear spline prism is automatically closed - just
+
<p>In the <code> quadratic_spline</code>, each sub-prism needs an additional control point at the beginning of each sub-prisms point sequence to determine the slope at the start of the curve. The first point specified is the control point which is not actually part of the spline. The second point is the start of the spline. The sub-prism ends when this second point is duplicated. The next point is the control point of the next sub-prism. The point after that is the first point of the second sub-prism.</p>
like the last sub-polygon in the polygon statement - if the first and last
+
<p>Here is an example:</p>
point of the sub-polygon's point sequence are not the same. This make it
 
very easy to convert between polygons and prisms. Quadratic, cubic and bezier
 
splines are never automatically closed.</p>
 
<p>
 
In the <code> quadratic_spline</code>, each sub-prism needs an additional
 
control point at the beginning of each sub-prisms' point sequence to
 
determine the slope at the start of the curve. The first point specified is
 
the control point which is not actually part of the spline. The second point
 
is the start of the spline. The sub-prism ends when this second point is
 
duplicated. The next point is the control point of the next sub-prism. The
 
point after that is the first point of the second sub-prism. Here is an
 
example:</p>
 
 
<pre>
 
<pre>
 
prism {
 
prism {
Line 98: Line 66:
 
   }
 
   }
 
</pre>
 
</pre>
 
+
<p>In the <code>cubic_spline</code>, each sub-prism needs two additional control points, one at the beginning of each sub-prisms point sequence to determine the slope at the start of the curve and one at the end. The first point specified is the control point which is not actually part of the spline. The second point is the start of the spline. The sub-prism ends when this second point is duplicated. The next point is the control point of the end of the first sub-prism. Next is the beginning control point of the next sub-prism. The point after that is the first point of the second sub-prism.</p>
<p>In the <code>cubic_spline</code>, each sub-prism needs two additional
+
<p>Here is an example:</p>
control points -- one at the beginning of each sub-prisms' point sequence
 
to determine the slope at the start of the curve and one at the end. The
 
first point specified is the control point which is not actually part of the
 
spline. The second point is the start of the spline. The sub-prism ends when
 
this second point is duplicated. The next point is the control point of the
 
end of the first sub-prism. Next is the beginning control point of the next
 
sub-prism. The point after that is the first point of the second
 
sub-prism.</p>
 
<p>
 
Here is an example:</p>
 
 
<pre>
 
<pre>
 
prism {
 
prism {
Line 122: Line 80:
 
   }
 
   }
 
</pre>
 
</pre>
 
 
{{#indexentry:conic_sweep, prism}}
 
{{#indexentry:conic_sweep, prism}}
 
{{#indexentry:keyword, conic_sweep}}
 
{{#indexentry:keyword, conic_sweep}}
<p>The <code>bezier_spline</code> is an alternate kind of cubic spline.
+
<p>The <code>bezier_spline</code> is an alternate kind of cubic spline. Points 1 and 4 specify the end points of a segment and points 2 and 3 are control points which specify the slope at the endpoints. Points 2 and 3 do not actually lie on the spline. They adjust the slope of the spline. If you draw an imaginary line between point 1 and 2, it represents the slope at point 1. It is a line tangent to the curve at point 1. The greater the distance between 1 and 2, the flatter the curve. With a short tangent the spline can bend more. The same holds true for control point 3 and endpoint 4. If you want the spline to be smooth between segments, point 3 and 4 on one segment and point 1 and 2 on the next segment must form a straight line and point 4 of one segment must be the same as point one on the next segment.</p>
Points 1 and 4 specify the end points of a segment and points 2 and 3 are
+
<p>By default linear sweeping is used to create the prism, that is, the prism's walls are perpendicular to the x-z plane. The size of the curve does not change during the sweep. You can also use <code>conic_sweep</code> that leads to a prism with cone-like walls by scaling the curve down during the sweep.</p>
control points which specify the slope at the endpoints. Points 2 and 3 do
+
<p>Like cylinders the prism is normally closed. You can remove the caps on the prism by using the <code>open</code> keyword. If you do, you should not use it in CSG operations, because the result may not be as expected.</p>
not actually lie on the spline. They adjust the slope of the spline. If you
+
<p>The surface normal determination for prism sides depends upon the order in which the splines points are specified. Prism ends have normals which always face outward. The following code, where the linear spline point order is <em>counter-clockwise</em> in the x-z plane, will render sides with the color Red on the outside and the color Blue on the inside. The prism ends will also be Red on the outside and Blue on the inside.</p>
draw an imaginary line between point 1 and 2, it represents the slope at
+
<pre>
point 1. It is a line tangent to the curve at point 1. The greater the
+
#declare Prism_CounterClockwise = prism {
distance between 1 and 2, the flatter the curve. With a short tangent the
+
    linear_spline
spline can bend more. The same holds true for control point 3 and endpoint 4.
+
    linear_sweep
If you want the spline to be smooth between segments, point 3 and 4 on one
+
    0,1,5,
segment and point 1 and 2 on the next segment must form a straight line and
+
    <0.5,-0.5>,<0.5,0.5>,<0.3,0.5>,<0.3,-0.5>,<0.5,-0.5>
point 4 of one segment must be the same as point one on the next segment.</p>
+
    texture          { pigment { Red } }
<p>
+
    interior_texture { pigment { Blue } }
By default linear sweeping is used to create the prism, i.e. the prism's
+
}
walls are perpendicular to the x-z-plane (the size of the curve does not
+
</pre>
change during the sweep). You can also use <code>conic_sweep</code> that
+
<p>While the following example, where the point order for the linear spine is <em>clockwise</em> in the x-z plane, will render sides inside-out with the color Blue on the outside and the color Red on the inside. Surface normals for the prism ends are unchanged.</p>
leads to a prism with cone-like walls by scaling the curve down during the
+
<pre>
sweep.</p>
+
#declare Prism_Clockwise = prism {
<p>
+
    linear_spline
Like cylinders the prism is normally closed. You can remove the caps on the
+
    linear_sweep
prism by using the <code>open</code> keyword. If you do so you should not
+
    0,1,5,
use it with CSG because the results may get wrong.</p>
+
    <0.5,-0.5>,<0.3,-0.5>,<0.3,0.5>,<0.5,0.5>,<0.5,-0.5>
 
+
    texture          { pigment { Red } }
<p>For an explanation of the spline concept read the description of the
+
    interior_texture { pigment { Blue } }
<!--<linkto "Lathe">Lathe</linkto>--->[[Reference:Lathe|Lathe]] object. Also see the tutorials on
+
}
[[Documentation:Tutorial Section 3#Lathe Object|Lathe]] and [[Documentation:Tutorial Section 3#Prism Object|Prism]] objects.</p>
+
</pre>
 
+
<p>The actual normal determination is more complicated than <em>clockwise</em> vs <em>counter-clockwise</em> orientation for complex splines. If the surface normal is important to the visual result, it is best to check how the prism is being rendered by testing with substantially different inside and outside textures.</p>
 +
<p>There is presently a inconsistency with the bezier spline mode of the prism in that the point order with respect to side surface normals is reversed from all other prism spline types. To match the end normals, for all but the bezier spline, the point list should be in <em>counter-clockwise</em> order in the x-z plane, while for the bezier spline, the point order must be <em>clockwise</em>. The behavior of the bezier spline prism will likely be aligned with the other spline types in a later release.</p>
 
{{#indexentry:sturm, prism}}
 
{{#indexentry:sturm, prism}}
 
{{#indexentry:keyword, sturm}}
 
{{#indexentry:keyword, sturm}}
<p>The <code> sturm</code> keyword specifies the slower but more accurate
+
<p>The <code> sturm</code> keyword specifies the slower but more accurate Sturmian root solver which may be used with the cubic or bezier spline prisms if the shape does not render properly. The linear and quadratic spline prisms do not need the Sturmian root solver.</p>
Sturmian root solver which may be used with the cubic or bezier spline prisms
+
<p>For an explanation of the spline concept read the description for the <!--<linkto "Lathe">Lathe</linkto>--->[[Reference:Lathe|Lathe]] object.</p>
if the shape does not render properly. The linear and quadratic spline prisms
+
<p>See also the tutorials on [[Documentation:Tutorial Section 3#Lathe Object|Lathe]] and [[Documentation:Tutorial Section 3#Prism Object|Prism]] objects.</p>
do not need the Sturmian root solver.</p>
 

Revision as of 23:52, 26 May 2016

The prism is an object generated by specifying one or more two-dimensional, closed curves in the x-z plane and sweeping them along y axis. These curves are defined by a set of points which are connected by linear, quadratic, cubic or bezier splines.

The syntax for the prism is:

PRISM:
  prism {
    [PRISM_ITEMS...] Height_1, Height_2, Number_Of_Points,
    <Point_1>, <Point_2>, ... <Point_n>
    [ open ] [PRISM_MODIFIERS...]
    }
PRISM_ITEM:
  linear_spline | quadratic_spline | cubic_spline |
  bezier_spline | linear_sweep | conic_sweep
PRISM_MODIFIER:
  sturm | OBJECT_MODIFIER

Prism default values:

SPLINE_TYPE   : linear_spline
SWEEP_TYPE    : linear_sweep
sturm         : off

The first items specify the spline type and sweep type. The defaults if none is specified is linear_spline and linear_sweep. This is followed by two float values Height_1 and Height_2 which are the y coordinates of the top and bottom of the prism. This is followed by a float value specifying the number of 2-D points you will use to define the prism.This includes all control points needed for quadratic, cubic and bezier splines. This is followed by the specified number of 2-D vectors which define the shape in the x-z plane.

The interpretation of the points depends on the spline type. The prism object allows you to use any number of sub-prisms inside one prism statement, they are of the same spline and sweep type. Wherever an even number of sub-prisms overlaps a hole appears.

Note: You need not have multiple sub-prisms and they need not overlap as in the following examples.

In the linear_spline the first point specified is the start of the first sub-prism. The following points are connected by straight lines. If you specify a value identical to the first point, this closes the sub-prism and next point starts a new one. When you specify the value of that sub-prism's start, then it is closed. Each of the sub-prisms has to be closed by repeating the first point of a sub-prism at the end of the sub-prism's point sequence.

In the following example, there are two rectangular sub-prisms nested inside each other to create a frame.

prism {
  linear_spline
  0, 1, 10,
  <0,0>, <6,0>, <6,8>, <0,8>, <0,0>,  //outer rim
  <1,1>, <5,1>, <5,7>, <1,7>, <1,1>   //inner rim
  }

The last sub-prism of a linear spline prism is automatically closed, just like the last sub-polygon in the polygon statement, if the first and last point of the sub-polygon's point sequence are not the same. This makes it very easy to convert between polygons and prisms. Quadratic, cubic and bezier splines are never automatically closed.

In the quadratic_spline, each sub-prism needs an additional control point at the beginning of each sub-prisms point sequence to determine the slope at the start of the curve. The first point specified is the control point which is not actually part of the spline. The second point is the start of the spline. The sub-prism ends when this second point is duplicated. The next point is the control point of the next sub-prism. The point after that is the first point of the second sub-prism.

Here is an example:

prism {
  quadratic_spline
  0, 1, 12,
  <1,-1>, <0,0>, <6,0>, //outer rim; <1,-1> is control point and 
  <6,8>, <0,8>, <0,0>,  //<0,0> is first & last point
  <2,0>, <1,1>, <5,1>,  //inner rim; <2,0> is control point and 
  <5,7>, <1,7>, <1,1>   //<1,1> is first & last point
  }

In the cubic_spline, each sub-prism needs two additional control points, one at the beginning of each sub-prisms point sequence to determine the slope at the start of the curve and one at the end. The first point specified is the control point which is not actually part of the spline. The second point is the start of the spline. The sub-prism ends when this second point is duplicated. The next point is the control point of the end of the first sub-prism. Next is the beginning control point of the next sub-prism. The point after that is the first point of the second sub-prism.

Here is an example:

prism {
  cubic_spline
  0, 1, 14,
  <1,-1>, <0,0>, <6,0>, //outer rim; First control is <1,-1> and
  <6,8>, <0,8>, <0,0>,  //<0,0> is first & last point.
  <-1,1>,                           //Last control of first spline is <-1,1>
  <2,0>, <1,1>, <5,1>,  //inner rim; First control is <2,0> and 
  <5,7>, <1,7>, <1,1>,  //<1,1> is first & last point
  <0,2>                             //Last control of first spline is <0,2>
  }

The bezier_spline is an alternate kind of cubic spline. Points 1 and 4 specify the end points of a segment and points 2 and 3 are control points which specify the slope at the endpoints. Points 2 and 3 do not actually lie on the spline. They adjust the slope of the spline. If you draw an imaginary line between point 1 and 2, it represents the slope at point 1. It is a line tangent to the curve at point 1. The greater the distance between 1 and 2, the flatter the curve. With a short tangent the spline can bend more. The same holds true for control point 3 and endpoint 4. If you want the spline to be smooth between segments, point 3 and 4 on one segment and point 1 and 2 on the next segment must form a straight line and point 4 of one segment must be the same as point one on the next segment.

By default linear sweeping is used to create the prism, that is, the prism's walls are perpendicular to the x-z plane. The size of the curve does not change during the sweep. You can also use conic_sweep that leads to a prism with cone-like walls by scaling the curve down during the sweep.

Like cylinders the prism is normally closed. You can remove the caps on the prism by using the open keyword. If you do, you should not use it in CSG operations, because the result may not be as expected.

The surface normal determination for prism sides depends upon the order in which the splines points are specified. Prism ends have normals which always face outward. The following code, where the linear spline point order is counter-clockwise in the x-z plane, will render sides with the color Red on the outside and the color Blue on the inside. The prism ends will also be Red on the outside and Blue on the inside.

#declare Prism_CounterClockwise = prism {
    linear_spline
    linear_sweep
    0,1,5,
    <0.5,-0.5>,<0.5,0.5>,<0.3,0.5>,<0.3,-0.5>,<0.5,-0.5>
    texture          { pigment { Red } }
    interior_texture { pigment { Blue } }
}

While the following example, where the point order for the linear spine is clockwise in the x-z plane, will render sides inside-out with the color Blue on the outside and the color Red on the inside. Surface normals for the prism ends are unchanged.

#declare Prism_Clockwise = prism {
    linear_spline
    linear_sweep
    0,1,5,
    <0.5,-0.5>,<0.3,-0.5>,<0.3,0.5>,<0.5,0.5>,<0.5,-0.5>
    texture          { pigment { Red } }
    interior_texture { pigment { Blue } }
}

The actual normal determination is more complicated than clockwise vs counter-clockwise orientation for complex splines. If the surface normal is important to the visual result, it is best to check how the prism is being rendered by testing with substantially different inside and outside textures.

There is presently a inconsistency with the bezier spline mode of the prism in that the point order with respect to side surface normals is reversed from all other prism spline types. To match the end normals, for all but the bezier spline, the point list should be in counter-clockwise order in the x-z plane, while for the bezier spline, the point order must be clockwise. The behavior of the bezier spline prism will likely be aligned with the other spline types in a later release.

The sturm keyword specifies the slower but more accurate Sturmian root solver which may be used with the cubic or bezier spline prisms if the shape does not render properly. The linear and quadratic spline prisms do not need the Sturmian root solver.

For an explanation of the spline concept read the description for the Lathe object.

See also the tutorials on Lathe and Prism objects.