Difference between revisions of "Reference:Object"

From POV-Wiki
Jump to navigation Jump to search
m (1 revision: Initial Load (TF))
 
m (Precision about 40 char limited version number)
 
(11 intermediate revisions by 2 users not shown)
Line 2: Line 2:
 
[[Category:Objects]]
 
[[Category:Objects]]
 
<!--<sectiondesc desc=<"scene objects reference">--->
 
<!--<sectiondesc desc=<"scene objects reference">--->
<p>Objects are the building blocks of your scene. There are a lot of different types of objects supported by POV-Ray. In the following sections, we describe [[#Finite Solid Primitives|Finite Solid Primitives]], [[#Finite Patch Primitives|Finite Patch Primitives]] and [[#Infinite Solid Primitives|Infinite Solid Primitives]]. These primitive shapes may be combined into complex shapes using [[#Constructive Solid Geometry|Constructive Solid Geometry]] (also known as CSG).</p>
+
<p>Objects are the building blocks of your scene. There are a lot of different types of objects supported by POV-Ray. In the following sections, we describe [[Reference:Finite Solid Primitives|Finite Solid Primitives]], [[Reference:Finite Patch Primitives|Finite Patch Primitives]] and [[Reference:Infinite Solid Primitives|Infinite Solid Primitives]]. These primitive shapes may be combined into complex shapes using [[Reference:Constructive Solid Geometry|Constructive Solid Geometry]] (also known as CSG).</p>
 
<p>
 
<p>
The basic syntax of an object is a keyword describing its type, some floats,
+
The basic syntax of an object is a keyword describing its type, some floats, vectors or other parameters which further define its location and/or shape and some optional object modifiers such as texture, interior_texture, pigment, normal, finish, interior, bounding, clipping or transformations. Specifically the syntax
vectors or other parameters which further define its location and/or shape
 
and some optional object modifiers such as texture, interior_texture, pigment, normal, finish,
 
interior, bounding, clipping or transformations. Specifically the syntax
 
 
is:</p>
 
is:</p>
 
<pre>
 
<pre>
Line 16: Line 13:
 
FINITE_SOLID_OBJECT:
 
FINITE_SOLID_OBJECT:
 
   BLOB | BOX | CONE | CYLINDER | HEIGHT_FIELD | ISOSURFACE | JULIA_FRACTAL |
 
   BLOB | BOX | CONE | CYLINDER | HEIGHT_FIELD | ISOSURFACE | JULIA_FRACTAL |
   LATHE | OVUS | PARAMETRIC | PRISM | SPHERE | SPHERE_SWEEP | SUPERELLIPSOID |
+
   LATHE | LEMON | OVUS | PARAMETRIC | PRISM | SPHERE | SPHERE_SWEEP | SUPERELLIPSOID |
 
   SOR | TEXT | TORUS
 
   SOR | TEXT | TORUS
 
FINITE_PATCH_OBJECT:
 
FINITE_PATCH_OBJECT:
Line 27: Line 24:
 
</pre>
 
</pre>
  
<p>Object identifiers may be declared to make scene files more readable and
+
<p>Object identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An identifier is declared as follows.</p>
to parameterize scenes so that changing a single declaration changes many
 
values. An identifier is declared as follows.</p>
 
 
<pre>
 
<pre>
 
OBJECT_DECLARATION:
 
OBJECT_DECLARATION:
Line 36: Line 31:
 
</pre>
 
</pre>
  
<p>Where <em>IDENTIFIER</em> is the name of the identifier up to 40
+
<p>Where <em>IDENTIFIER</em> is the name of the identifier and <em>OBJECT</em> is any valid object. To invoke an object identifier, you wrap it in an <code>object{...}</code> statement. You use the <code>object</code> statement regardless of what type of object it originally was. Although early versions of POV-Ray required this <code> object</code> wrapper all of the time, now it is only used with <em>OBJECT_IDENTIFIERS</em>.</p>
characters long and <em>OBJECT</em> is any valid object. To invoke
+
<p class="Note"><strong>Note:</strong> In versions prior to 3.6.2, identifier names <em>were</em> limited to 40 characters. There has been a {{Change}} removing that restriction.</p>
an object identifier, you wrap it in an <code>object{...}</code> statement.
 
You use the <code>object</code> statement regardless of what type of object
 
it originally was. Although early versions of POV-Ray required this <code>
 
object</code> wrapper all of the time, now it is only used with <em>
 
OBJECT_IDENTIFIERS</em>.</p>
 
 
<p>
 
<p>
Object modifiers are covered in detail later. However here is a brief
+
Object modifiers are covered in detail later. However here is a brief overview.</p>
overview.</p>
 
 
<p>
 
<p>
The texture describes the surface properties of the object. Complete details
+
The texture describes the surface properties of the object. Complete details are in [[Reference:Texture|textures]]. Textures are combinations of pigments, normals, and finishes. In the section [[Reference:Pigment|:pigment|pigment]] you will learn how to specify the color or pattern of colors inherent in the material. In [[Reference:Normal|normal]], we describe a method of simulating various patterns of bumps, dents, ripples
are in [[Reference:Texture|textures]]. Textures are combinations of pigments, normals,
+
or waves by modifying the surface normal vector. The section on [[Reference:Finish|finish]] describes the reflective properties of the surface. The [[Reference:Interior|Interior]] is a feature introduced in POV-Ray v3.1. It contains information about the interior of the object which was formerly contained in the finish and halo parts of a texture. Interior items are no longer part of the texture. Instead, they attach directly to the objects. The halo feature has been discontinued and replaced with a new feature called [[Reference:Media|Media]] which replaces both halo and atmosphere.</p>
and finishes. In the section [[Reference:Pigment|:pigment|pigment]] you will learn how to
 
specify the color or pattern of colors inherent in the material. In [[Reference:Normal|normal]], we describe a method of simulating various patterns of bumps, dents, ripples
 
or waves by modifying the surface normal vector. The section on [[Reference:Finish|finish]] describes the reflective properties of the surface. The [[Reference:Interior|Interior]] is a feature introduced in POV-Ray 3.1. It contains information
 
about the interior of the object which was formerly contained in the finish
 
and halo parts of a texture. Interior items are no longer part of the
 
texture. Instead, they attach directly to the objects. The halo feature has
 
been discontinued and replaced with a new feature called [[Reference:Media|Media]] which replaces both halo and atmosphere.</p>
 
 
<p>
 
<p>
Bounding shapes are finite, invisible shapes which wrap around complex, slow
+
Bounding shapes are finite, invisible shapes which wrap around complex, slow rendering shapes in order to speed up rendering time. Clipping shapes are used to cut away parts of shapes to expose a hollow interior. Transformations tell the ray-tracer how to move, size or rotate the shape and/or the texture in the scene.</p>
rendering shapes in order to speed up rendering time. Clipping shapes are
 
used to cut away parts of shapes to expose a hollow interior. Transformations
 
tell the ray-tracer how to move, size or rotate the shape and/or the texture
 
in the scene.</p>
 
==Finite Solid Primitives==
 
<p>There are seventeen different solid finite primitive shapes: [[Reference:Blob|blob]], [[Reference:Box|box]],
 
[[Reference:Cone|cone]], [[Reference:Cylinder|cylinder]], [[Reference:Height Field|height field]], [[Reference:Isosurface|isosurface]], [[Reference:Julia Fractal|Julia fractal]], [[Reference:Lathe|lathe]], [[Reference:Ovus|ovus]], [[Reference:Parametric|parametric]], [[Reference:Prism|prism]], [[Reference:Sphere|sphere]], [[Reference:Sphere Sweep|sphere_sweep]], [[Reference:Superellipsoid|superellipsoid]], [[Reference:Sor|surface of revolution]], [[Reference:Text|text]] and [[Reference:Torus|torus]]. These have a
 
well-defined <em>inside</em> and can be used in CSG (see [[#Constructive Solid Geometry|Constructive Solid Geometry]]). They are finite and respond to automatic bounding. You may specify an interior for these objects.</p>
 
 
 
==Finite Patch Primitives==
 
<p>There are six totally thin, finite objects which have no well-defined inside. They are [[Reference:Bicubic Patch|bicubic patch]], [[Reference:Disc|disc]], [[Reference:Smooth Triangle|smooth triangle]], [[Reference:Triangle|triangle]], [[Reference:Polygon|polygon]], [[Reference:Mesh|mesh]], and [[Reference:Mesh2|mesh2]]. They may be combined in CSG union, but cannot be used inside a <code>clipped_by</code> statement.</p>
 
<p class="Note"><strong>Note:</strong> Patch objects <em>may</em> give unexpected results when used in differences and intersections.</p>
 
<p>These conditions apply:</p>
 
<ol>
 
<li>Solids may be differenced from bicubic patches with the expected results.</li>
 
<li>Differencing a bicubic patch from a solid <em>may</em> give unexpected results.</li>
 
<ul>
 
<li>Especially if the inverse keyword is used!</li>
 
</ul>
 
<li>Intersecting a solid and a bicubic patch will give the expected results.</li>
 
<ul>
 
<li>The parts of the patch that intersect the solid object will be visible.</li>
 
</ul>
 
<li>Merging a solid and a bicubic patch will remove the parts of the bicubic patch that intersect the solid.</li>
 
</ol>
 
 
 
<p>Because these types are finite POV-Ray can use automatic bounding on them to speed up rendering time. As with all shapes they can be translated, rotated and scaled.</p>
 
 
 
==Infinite Solid Primitives==
 
<p>There are six polynomial primitive shapes that are possibly infinite and
 
do not respond to automatic bounding. They are [[Reference:Plane|plane]], [[Reference:Cubic|cubic]], [[Reference:Poly|poly]], [[Reference:Quartic|quartic]], [[Reference:Polynomial|polynomial]],
 
and [[Reference:Quadric|quadric]]. They do have a well defined inside and may be used in CSG and
 
inside a <code>clipped_by</code> statement. As with all shapes they can be
 
translated, rotated and scaled.</p>
 
 
 
{{#indexentry:CSG}}
 
 
 
==Constructive Solid Geometry==
 
<p>In addition to all of the primitive shapes POV-Ray supports, you can also combine multiple simple shapes into complex shapes using <em> Constructive Solid Geometry</em> (CSG). There are four basic types of CSG operations: [[Reference:Union|union]], [[Reference:Intersection|intersection]], [[Reference:Difference|difference]], and [[Reference:Merge|merge]]. CSG objects can be composed of primitives or other CSG objects to create more, and more complex shapes.</p>
 
 
 
===Inside and Outside===
 
<p>Most shape primitives, like spheres, boxes and blobs divide the world into
 
two regions. One region is inside the object and one is outside. Given any
 
point in space you can say it is either inside or outside any particular
 
primitive object. Well, it could be exactly on the surface but this case is
 
rather hard to determine due to numerical problems.</p>
 
<p>
 
Even planes have an inside and an outside. By definition, the surface normal
 
of the plane points towards the outside of the plane. You should note that
 
triangles cannot be used as solid objects in CSG since they have no well defined inside and outside. Triangle-based shapes (<code>mesh</code> and <code>mesh2</code>) can only be used in CSG when they are closed objects and have an inside vector specified. </p>
 
<p class="Note"><strong>Note:</strong> Although the <code>triangle</code>, the <code>bicubic_patch</code> and some other shapes have no well defined inside and outside, they have a front- and backside which makes it possible to use a texture on the front side and an <code>interior_texture</code> on the back side.</p>
 
<p>
 
CSG uses the concepts of inside and outside to combine shapes together as
 
explained in the following sections.</p>
 
<p>
 
Imagine you have two objects that partially overlap like shown in the figure
 
below. Four different areas of points can be distinguished: points that are
 
neither in object <code>A</code> nor in object <code>B</code>, points that
 
are in object <code>A</code> but not in object <code>B</code>, points that
 
are not in object <code>A</code> but in object <code>B</code> and last not
 
least points that are in object <code>A</code> and object <code>B</code>.
 
</p>
 
 
 
<table class="centered" width="660x" cellpadding="0" cellspacing="10">
 
<tr>
 
  <td>
 
    [[Image:RefImgObjoverl.gif|center|640px<!--center--->]]
 
  </td>
 
</tr>
 
<tr>
 
  <td>
 
    <p class="caption">Two overlapping objects.</p>
 
  </td>
 
</tr>
 
</table>
 
 
 
<p>Keeping this in mind it will be quite easy to understand how the CSG
 
operations work.</p>
 
<p>
 
When using CSG it is often useful to invert an object so that it will be
 
inside-out. The appearance of the object is not changed, just the way that
 
POV-Ray perceives it. When the <code>inverse</code> keyword is used the <em>
 
inside</em> of the shape is flipped to become the <em> outside</em> and vice
 
versa.</p>
 
<p>
 
The inside/outside distinction is not important for a <code>union</code>, but is important for <code>intersection</code>, <code>difference</code>, and <code>merge</code>. Therefore any objects may be combined using <code>union</code> but only solid objects, i.e. objects that have a well-defined interior can be used in the other kinds of CSG. The objects described in
 
[[#Finite Patch Primitives|Finite Patch Primitives]] have no well defined inside/outside. All objects described in the sections [[#Finite Solid Primitives|Finite Solid Primitives]] and [[#Infinite Solid Primitives|Infinite Solid Primitives]].</p>
 
 
 
==Object Modifiers==
 
<p>A variety of modifiers may be attached to objects. The following items may
 
be applied to any object:</p>
 
<pre>
 
OBJECT_MODIFIER:
 
  clipped_by { UNTEXTURED_SOLID_OBJECT... } |
 
  clipped_by { bounded_by }                |
 
  bounded_by { UNTEXTURED_SOLID_OBJECT... } |
 
  bounded_by { clipped_by }                |
 
  no_shadow                  |
 
  no_image [ Bool ]          |
 
  no_radiosity [ Bool ]      |
 
  no_reflection [ Bool ]    |
 
  inverse                    |
 
  sturm [ Bool ]            |
 
  hierarchy [ Bool ]        |
 
  double_illuminate [ Bool ] |
 
  hollow  [ Bool ]          |
 
  interior { INTERIOR_ITEMS... }                        |
 
  material { [MATERIAL_IDENTIFIER][MATERIAL_ITEMS...] } |
 
  texture { TEXTURE_BODY }  |
 
  interior_texture { TEXTURE_BODY } |
 
  pigment { PIGMENT_BODY }  |
 
  normal { NORMAL_BODY }    |
 
  finish { FINISH_ITEMS... } |
 
  photons { PHOTON_ITEMS...}
 
  radiosity { RADIOSITY_ITEMS...}
 
  TRANSFORMATION
 
</pre>
 
 
 
<p>Transformations such as translate, rotate and scale have already been discussed. The modifiers <em>[[Reference:Texture|Textures]]</em> and its parts <em>[[Reference:Pigment|Pigment]]</em>, <em>[[Reference:Normal|Normal]]</em>, and <em>[[Reference:Finish|Finish]]</em> as well as <em>[[Reference:Interior|Interior]]</em>, and <em>[[Reference:Media|Media]]</em> (which is part of interior) are each in major chapters of their own below. In the sub-sections below we cover several other important modifiers: <code>[[Reference:Clipped_By Object Modifier|clipped_by]]</code>, <code>[[Reference:Bounded_By Object Modifier|bounded_by]]</code>, <code>[[Reference:Material|material]]</code>, <code>[[Reference:Inverse Object Modifier|inverse]]</code>, <code>[[Reference:Hollow Object Modifier|hollow]]</code>, <code>[[Reference:No_Shadow Object Modifier|no_shadow]]</code>, <code>[[Reference:No_Image Object Modifier|no_image]]</code>, <code>[[Reference:No_Reflection Object Modifier|no_reflection]]</code>, <code>[[Reference:Double_Illuminate Object Modifier|double_illuminate]]</code>, <code>[[Reference:No_Radiosity Object Modifier|no_radiosity]]</code> and <code>[[Reference:Sturm Object Modifier|sturm]]</code>. Although the examples below use object statements and object identifiers, these modifiers may be used on any type of object such as sphere, box etc.</p>
 

Latest revision as of 20:48, 2 July 2021

Objects are the building blocks of your scene. There are a lot of different types of objects supported by POV-Ray. In the following sections, we describe Finite Solid Primitives, Finite Patch Primitives and Infinite Solid Primitives. These primitive shapes may be combined into complex shapes using Constructive Solid Geometry (also known as CSG).

The basic syntax of an object is a keyword describing its type, some floats, vectors or other parameters which further define its location and/or shape and some optional object modifiers such as texture, interior_texture, pigment, normal, finish, interior, bounding, clipping or transformations. Specifically the syntax is:

OBJECT:
  FINITE_SOLID_OBJECT | FINITE_PATCH_OBJECT | 
  INFINITE_SOLID_OBJECT | CSG_OBJECT | LIGHT_SOURCE |
  object { OBJECT_IDENTIFIER [OBJECT_MODIFIERS...] }
FINITE_SOLID_OBJECT:
  BLOB | BOX | CONE | CYLINDER | HEIGHT_FIELD | ISOSURFACE | JULIA_FRACTAL |
  LATHE | LEMON | OVUS | PARAMETRIC | PRISM | SPHERE | SPHERE_SWEEP | SUPERELLIPSOID |
  SOR | TEXT | TORUS
FINITE_PATCH_OBJECT:
  BICUBIC_PATCH | DISC | MESH | MESH2 | POLYGON | TRIANGLE |
  SMOOTH_TRIANGLE
  INFINITE_SOLID_OBJECT:
  PLANE | POLY | CUBIC | QUARTIC | QUADRIC 
CSG_OBJECT:
  UNION | INTERSECTION | DIFFERENCE | MERGE

Object identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An identifier is declared as follows.

OBJECT_DECLARATION:
  #declare IDENTIFIER = OBJECT |
  #local IDENTIFIER = OBJECT

Where IDENTIFIER is the name of the identifier and OBJECT is any valid object. To invoke an object identifier, you wrap it in an object{...} statement. You use the object statement regardless of what type of object it originally was. Although early versions of POV-Ray required this object wrapper all of the time, now it is only used with OBJECT_IDENTIFIERS.

Note: In versions prior to 3.6.2, identifier names were limited to 40 characters. There has been a Change removing that restriction.

Object modifiers are covered in detail later. However here is a brief overview.

The texture describes the surface properties of the object. Complete details are in textures. Textures are combinations of pigments, normals, and finishes. In the section pigment you will learn how to specify the color or pattern of colors inherent in the material. In normal, we describe a method of simulating various patterns of bumps, dents, ripples or waves by modifying the surface normal vector. The section on finish describes the reflective properties of the surface. The Interior is a feature introduced in POV-Ray v3.1. It contains information about the interior of the object which was formerly contained in the finish and halo parts of a texture. Interior items are no longer part of the texture. Instead, they attach directly to the objects. The halo feature has been discontinued and replaced with a new feature called Media which replaces both halo and atmosphere.

Bounding shapes are finite, invisible shapes which wrap around complex, slow rendering shapes in order to speed up rendering time. Clipping shapes are used to cut away parts of shapes to expose a hollow interior. Transformations tell the ray-tracer how to move, size or rotate the shape and/or the texture in the scene.