home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / raytrace / rayshade / docs / olddocs / RayDoc next >
Encoding:
Text File  |  1992-07-23  |  61.5 KB  |  1,421 lines

  1. Options 
  2.  
  3. This appendix describes the commandline arguments accepted by rayshade.
  4. These options override defaults as well as any values  or flags given in the
  5. input file, and are thus useful for generating test and other unusual,
  6. ``non-standard'' renderings.
  7.  
  8. The general form of a rayshade command line is:
  9.  
  10.  rayshade [Options] [filename]
  11.  
  12. If given, the input file is read from  [filename].  By default, the input
  13. file is read from the standard input. Recall that, by default, the image
  14. file is written to the standard output; you will need to redirect the
  15. standard output if you have  not chosen to write the image to a file
  16. directly.  The name of the input file may be given anywhere on the command
  17. line.
  18.  
  19. Command-line options fall into two broad categories: those that set
  20. numerical or other values and thus must be followed by  further
  21. arguments,and those that simply turn features on and off.  Rayshade's
  22. convention is to denote the value-setting arguments  using capital letters,
  23. and feature-toggling arguments using lower-case letters.
  24.  
  25. - A  frame
  26.  Begin rendering (action) on the given frame.
  27. The default starting frame is number zero.
  28.  
  29. - a
  30.  Toggle writing of alpha channel.
  31. This option is only available when the Utah Raster Toolkit is being used.
  32.  
  33. - C  R G B
  34.  Set the adaptive ray tree pruning color.  If all channel contributions
  35. falls below the given cutoff values, no further rays are  spawned. Overrides
  36. the value specified via the cutoff keyword.
  37.  
  38. - c
  39.  Continue an interrupted rendering.
  40. When given, this option indicates that the image file being written to
  41. contains a partially-completed image.  Rayshade will read  the image to
  42. determine the scanline from which to continue the rendering. This option is
  43. only available with the Utah Raster Toolkit. The  -O option must also be
  44. used.
  45.  
  46. - D  depth
  47.  Set maximum ray tree depth.
  48. Overrides the value specified in the input file via the maxdepth keyword.
  49.  
  50. - E  separation
  51.  Set eye separation for rendering of stereo pairs.
  52. Overrides the value specified via the eyesep keyword.
  53.  
  54. - e
  55.  Write exponential RLE file.
  56. This option is only available for use with the Utah Raster Toolkit. See the
  57. Utah Raster Toolkit's unexp manual page for details on  exponential RLE
  58. files.
  59.  
  60. - F  freq
  61.  Set frequency of status report.
  62. Overrides the value given using the report keyword.
  63.  
  64. - G  gamma
  65.  Use given gamma correction exponent writing writing color information to
  66. the image file. The default value for gamma is 1.0.
  67.  
  68. - g
  69.  Use a Gaussian pixel filter.
  70. Overrides the filter selected through the use of the filter keyword.
  71.  
  72. - h
  73.  Print a short use message.
  74.  
  75. - j
  76.  Use jittered sampling to perform antialiasing.
  77. This option overrides the adaptive keyword, if present, in the input file.
  78.  
  79. - l
  80.  Render the left stereo pair image.
  81.  
  82. - m
  83.  Write a sampling map to the alpha channel.
  84. Rather than containing coverage information, the alpha channel values will
  85. be restricted to zero, indicating no supersampling,  and full intensity,
  86. indicating supersampling.  This option is only available if the Utah Raster
  87. Toolkit is being used.
  88.  
  89. - N  frames
  90.  Set the total number of frames to be rendered.
  91. This option overrides any value specified through the use of the frames
  92. keyword.  By default, a single frame is rendered.
  93.  
  94. - n
  95.  Do not render shadows.
  96.  
  97. - O  outfile
  98.  Write the image to the named file.
  99. This option overrides the name given with the outfile keyword, if any, in
  100. the input file.
  101.  
  102. - o
  103.  Toggle the effect of object opacity on shadows.
  104. This option is equivalent to specifying shadowtransp in the input file.  By
  105. default, rayshade traces shadow rays through non- opaque objects.
  106.  
  107. - P  depth
  108.  Use adaptive supersampling with the givenmaximum depth.
  109. This option overrides the jittered keyword and the value associated the
  110. adaptive keyword given in the input file, if any.
  111.  
  112. - P
  113.  Specify the options that should be passed to the C preprocessor.
  114. The C preprocessor, if available, is applied to all of the inputpassed to
  115. rayshade.
  116.  
  117. - p
  118.  Perform preview-quality rendering.
  119. This option is equivalent to -n -S 1 -D 0.
  120.  
  121. - q
  122.  Do not print warning messages.
  123.  
  124. - R  xsize ysize
  125.  Produce an image xsize pixels wide by ysize pixels high.
  126. This option overrides any screen size set by use of the screen keyword.
  127.  
  128. - r
  129.  Render the right stereo pair image.
  130.  
  131. - S samples
  132.  Use samples^2 jittered samples.
  133. This option overrides any value set through the use of the samples keyword
  134. in the input file.
  135.  
  136. - s
  137.  Disable caching of  shadowing information.
  138. It should not be necessary to ever use this option.
  139.  
  140. - T   r g b
  141.  Set the contrast threshold in the three color channels for use in adaptive
  142. supersampling. This option overrides any value given through the use of the
  143. contrast keyword.
  144.  
  145.  
  146. - V   filename
  147.  Write verbose output to the named file.
  148. This option overrides any file named through the use of the  report keyword.
  149.  
  150. - v
  151.  Write verbose output.
  152. When given, this option causes information about the options selected and
  153. the objects defined to be included in the report file.
  154.  
  155. - W  minx miny maxx maxy
  156.  Render the specified subwindow.  The parameters should fall between zero
  157. and one. This option is provided to facilitate changing and/or examining a
  158. small portion of an image without having to re-render the entire  image.
  159.  
  160.  
  161. A View
  162.  
  163. When designing a rayshade input file, there are two main issues that must be
  164. considered.  The first and more complex is the  selection of the objects to
  165. be rendered and the appearances they should be assigned.  The second and
  166. usually easier issue is the  choice of viewing parameters.  This chapter
  167. deals with the latter problem; the majority of the following chapters
  168. discuss aspects of objects and their appearances.
  169.  
  170. Rayshade uses a camera model to describe the geometric relationship between
  171. the objects to be rendered and the image that is  produced.  This
  172. relationship describes a perspective projection from world space onto the
  173. image plane.
  174.  
  175. The geometry of the perspective projection may be thought of as an infinite
  176. pyramid, known as the viewing frustum. The apex of  the frustum is defined
  177. by the camera's position, and the main axis of the frustum by a ``look''
  178. vector. The four sides of the pyramid are differentiated by their
  179. relationship to a reference ``up'' vector from the camera's position.
  180.  
  181. The image ultimately produced by rayshade may then be thought of as the
  182. projection of the objects closest to the eye onto a  rectangular screen
  183. formed by the intersection of the pyramid with a plane orthogonal to the
  184. pyramid's axis.  The overall shape of  the frustum (the lengths of the top
  185. and bottom sides compared to left and right) is described by the horizontal
  186. and vertical fields  of view.
  187.  
  188.  
  189. Position 
  190.  
  191. The three basic camera properties are its position, the direction in which
  192. it is pointing, and its orientation.  The keywords for  specifying these
  193. values are described below. The default values are designed to provide a
  194. reasonable view of a sphere or radius 2 located at origin.  If these default
  195. values are  used, the origin is projected onto the center of the image
  196. plane, with the world x axis  running left-to-right, the z axis bottom-to-
  197. top, and the y axis going ``into'' the screen.
  198.  
  199. eyep  evec (pos)
  200.  Place the virtual camera at the given position.
  201. The default camera position is (0, -8, 0).
  202.  
  203. lookp  evec{pos }
  204.  Point the virtual camera toward the given position. The default look point
  205. is the origin (0, 0, 0).  The look point and camera position must not be
  206. coincident.
  207.  
  208. up  evec{direction }
  209.  The ``up'' vector from the camera point is set to the given direction. This
  210. up vector need not be orthogonal to the view vector, nor need it be
  211. normalized.  The default up direction is (0, 0, 1).
  212.  
  213. Another popular standard viewing geometry, with the x axis running
  214. left-to-right, the y axis bottom-to-top, and the z axis pointing  out of the
  215. screen, may be obtained by setting the up vector to (0, 1, 0) and by placing
  216. the camera on the positive z axis.
  217.  
  218.  
  219. View
  220.  
  221. Another important choice to be made is that of the field of view of the
  222. camera.  The size of this field describes the angles  between the left and
  223. right sides and top and bottom sidesof the frustum.
  224.  
  225. fov  hfov, vfov
  226.  Specify the horizontal and vertical field of view, in degrees. The default
  227. horizontal field of view is 45 degrees. If {em vfov} is omitted, as is the
  228. general practice, the vertical field of view is  computed using the
  229. horizontal field of view, the output image resolution, and the assumption
  230. that a pixel samples a square area.   Thus, the values passed via the screen
  231. keyword define the shape of the final image. If you are displaying on a
  232. non-square pixeled  device, you must set the vertical field of view to
  233. compensate for the ``squashing'' that will result.
  234.  
  235.  
  236. Field
  237.  
  238. Under many circumstances, it is desirable to render objects in the image
  239. suchthat they are in sharp focus on the image plane.   This is achieved by
  240. using the default ``pinhole' camera.  In this mode, the camera's aperture is
  241. a single point, and all light rays are  focused on the image plane.
  242.  
  243. Alternatively, one may widen the aperture in order to simulate depth of
  244. field. In this case, rays are cast from various places on the  aperture disk
  245. towards a point whose distance from the camera is equal to the focus
  246. distance.  Objects that lay in the focal plane  will be in sharp focus.  The
  247. farther an object is from the image plane, the more out-of-focus it will
  248. appear to be. A wider aperture  will lead to a greater blurring of objects
  249. that do not lay in the focal plane. When using a non-zero aperture radius,
  250. it is best to use  jittered sampling in order to reduce aliasing.
  251.  
  252. aperture  radius
  253.  Use an aperture with the given radius. The default radius is zero,
  254. resulting in a pinhole camera model.
  255.  
  256. focaldist  distance
  257.  Set the focal plane to be distance units from the camera. By default, the
  258. focal distance is equal to the distance from the camera to the look point.
  259.  
  260.  
  261. Rendering 
  262.  
  263. Producing a stereo pair is a relatively simple process; rather than simply
  264. rendering a single image, one creates two related images  which may then be
  265. viewed on a stereo monitor, in a stereo slide viewer, or by using colored
  266. glasses and an appropriate display  filter.
  267.  
  268. Rayshade facilitates the rendeing of stereo pairs by allowing you to specify
  269. the distance between the camera positions used in  creating the two images.
  270. The camera position given in the rayshade input file defines the midpoint
  271. between the two camera   positions used to generate the images. Generally,
  272. the remainder of the viewing parameters are kept constant.
  273.  
  274. eyesep  separation
  275.  Specifies the camera separation to be used in rendering stereo pairs. There
  276. is no default value. The separation may also be specified on the command
  277. line through the -E option. The view to be  rendered (left or right) must be
  278. specified on the command line by using the -l or -r options.
  279.  
  280. There are several things to keep in mind when generating stereo pairs.
  281. Firstly, those objects that lie in from of the focal plane  will appear to
  282. protrude from the screen when viewed in stereo, while objects farther than
  283. the focal plane will recede into the  screen.  As it is usually easier to
  284. look at stereo images that recede into the screen, you willusually want to
  285. place the look point  closer to the camera than the objectof  primary
  286. interest.
  287.  
  288. The degree of stereo effect is a function of the camera separation and the
  289. distance from the camera to the look point. Too large a  separation will
  290. result in a hyperstereo effect that will be hard to resolve, while too
  291. little a value will result in no stereo effect at  all.  A separation equal
  292. to one tenth the distance from the camera to the look point is often a good
  293. choice.
  294.  
  295.  
  296. Surfaces
  297.  
  298. Surfaces are used to control the interaction between light sources
  299. andobjects.  A surface specification consists of information  about how the
  300. light interacts with both the exterior and interior of an object . For
  301. non-closed objects, such as polygons, the ``interior'' of an object is the
  302. ``other side'' of the object's surface relative to the  origin of a ray.
  303.  
  304. Rayshade usually ensures that a primitive's surface normal is pointing
  305. towards the origin of the incident ray when performing  shading
  306. calculations.  Exceptions to this rule are transparent primitives, for which
  307. rayshade uses the direction of the surface  normal to determine if the
  308. incident ray is entering or exiting the object. All non-transparent
  309. primitives will, in effect, be double- sided.
  310.  
  311.  
  312. description 
  313.  
  314. A surface definition consists of a number of component keywords, each of
  315. which is usually followed by either a single number or  a red-green-blue
  316. color triple.   Each of the values in the color triple are normalized, with
  317. zero indicating zero intensity, and one  indicating full intensity. If any
  318. surface component is left unspecified, its value defaults to zero, with the
  319. exception of the index of refraction, which is  assigned the default index
  320. of refraction (normally 1.0).
  321.  
  322. Surface descriptions are used in rayshade to compute the color of a raythat
  323. strikes the surface at a point evec{p }. The normal to  the surface at
  324. evec{p },  evec{n }, is also computed.
  325.  
  326. ambient  evec{color }
  327.  Use the given color to approximate those surface-surface  interactions
  328. (e.g., diffuse interreflection) not modeled by the  raytracing process. A
  329. surface's ambient color is always applied to a ray.  The color applied is
  330. computed by multiplying the ambient color by the  intensity of the ambient
  331. light source.
  332.  
  333. If  evec{p } is in shadow with respect to a given light source, that light
  334. source makes no contribution to the shading of evec{p }.
  335.  
  336. diffuse  evec{color)
  337.  Specifies the diffuse color The diffuse contribution from each non-shadowed
  338. light source at evec{p } is equal to the diffuse color of the surface scaled
  339. by the  cosine of the angle between evec{n } and the vector from evec{p } to
  340. the light source.
  341.  
  342. specular  evec{color }
  343.  Specifies the base color of specular reflections.
  344.  
  345. specpow  exponent
  346.  Specifies the specular highlight exponent. The intensity of specular
  347. highlights from light sources are scaled by the specular color of the
  348. surface.
  349.  
  350. reflect  reflectivity
  351.  Specifies the specular reflectivity of the surface.  If non-zero, reflected
  352. rays will be spawned. The intensity of specularly reflected rays will be
  353. proportional to the specular color of the surface scaled by the
  354. reflectivity.
  355.  
  356. transp  transparency
  357.  Specifies the specular transmissivity of the surface.  If non-zero,
  358. transmitted (refracted) rays will be spawned.
  359.  
  360. body  evec{color }
  361.  Specifies the body color of the object.  The body color affects the color
  362. of rays that are transmitted through the object.
  363.  
  364. extinct  coefficient
  365.  Specifies the extinction coefficient of the interior of the object.
  366.  
  367. The extinction coefficient is raised to a power equal to the distance the
  368. transmitted ray travels through the object. The overall  intensity of
  369. specularly transmitted rays will be proportional  to this factor multiplied
  370. by the surface's body color multiplied by the  transparency of the object.
  371.  
  372. index  N
  373.  Specifies the index of refraction.  The default value is equal to the index
  374. of refraction of the atmosphere surrounding the eye.
  375.  
  376. translucency  translu  evec{color }  stexp
  377.  Specifies the translucency, diffusely transmitted color, and Phong exponent
  378. for transmitted specular highlights. If a light source illuminates a
  379. translucent surface from the side opposite that from which a ray approaches,
  380. illumination  computations are performed,   using the given color as the
  381. surface's diffuse color, and the given exponent as the Phong highlight
  382. exponent.  The resulting color is then scaled by the surface's translucency.
  383.  
  384.  
  385.  
  386. Atmospheric effects
  387.  
  388. Any number of atmospheric effects may also be associated with a surface.
  389. These effects will be applied to those rays that are  transmitted through
  390. the surface.  Applying atmospheric effects to opaque objects is a waste of
  391. input file.
  392.  
  393. fog  evec{color }  evec{thinness }
  394.  Add exponential fog with the specified  thinness and color. Fog is
  395. simulated by blending the color of the fog with the color of each ray.  The
  396. amount of fog color blended into a ray color is  an exponentialfunction of
  397. the distance from the ray origin to the point of intersection    divided by
  398. the specified thinness for each  color channel. If the distance is equal to
  399. thinness, a ray's new color will be half ofthe fog color plus half its
  400. original color.
  401.  
  402. mist  evec{color }  evec{thinness }  zero scale
  403.  Add global low-altitude mist of the specified color.  The color of a ray is
  404. modulated by a fog with density that varies linearly  with the difference in
  405. z coordinate (altitude) between the ray origin and the point of
  406. intersection.  The thinness values specify the  transmissivity of the fog
  407. for each color channel. The base altitude of the mist is given by {em zero},
  408. and the apparent heightof the mist can be modulated using {em scale}, which
  409. scales the difference in altitude used to compute the fog.
  410.  
  411.  
  412.  
  413. default Medium
  414.  
  415. The default medium is the medium which surrounds and encompasses all of the
  416. objects in the scene; it is the ``air'' through which  eye rays usually
  417. travel before hitting an object.  The properties of the default medium may
  418. be modified through the use of the   atmosphere  keyword.
  419.  
  420. atmosphere  N  atmospheric effects
  421. If given, N specifies the index of refraction of the default medium.  The
  422. default is 1.0.  Any atmospheric effects listed are applied  to rays that
  423. are exterior to every object in the scene (e.g., rays emanating from the
  424. camera).
  425.  
  426. \begin{verbatim }
  427.     /*
  428.      * Red sphere on a grey plane, with fog.
  429.      */
  430.     eyep 0. -10. 2.
  431.     atmosphere fog  .8 .8 .8 14. 14. 14.
  432.     plane 0 0 0  0 0 1
  433.     sphere diffuse 0.8 0 0   1.5  0 0 1.5
  434. \end{verbatim }
  435.  
  436.  
  437. Specification 
  438.  
  439. Rayshade provides a number of ways to define surfaces and to bind these
  440. surfaces to objects.  The most straight-forward method  of surface
  441. specification is to simply list the surface properties to be used.
  442. Alternatively, one may associate a name with a given surface. This name may
  443. subsequently be used to refer to that surface.
  444.  
  445. surface  name { Surface Definition}
  446.  Associate the given collection of surface attributes with the given name.
  447.  
  448. The binding of a collection of surface properties to a given object is
  449. accomplished in a bottom-up manner; the surface that  ``closest'' in the
  450. modeling tree to the primitive being rendered is the one that is used to
  451. give the primitive its appearance.
  452.  
  453. An object that has no surface bound to it is assigned a default surface that
  454. give an object the appearance of white plastic.
  455.  
  456. The first and most direct way to bind a surface to a primitive is by
  457. specifying the surface to be bound to the primitive when it is
  458. instantiated. This is accomplished by inserting a list of surface attributes
  459. or a surface name after the primitive's type keyword and  before the actual
  460. primitive data.
  461.  
  462. \begin{verbatim }
  463.     /*
  464.      * A red 'mud' colored sphere reseting on a
  465.      * white sphere. To the right is a sphere with
  466.      * default surface attributes.
  467.      */
  468.    surface mud ambient .03 0. 0.  diffuse .7 .3 0.
  469.     sphere  ambient .05 .05 .05 diffuse .7 .7 .7   1. 0 0 0
  470.     sphere mud  1. 0 0 2
  471.     sphere 1. 1.5 0 0
  472. \end{verbatim }
  473.  
  474. Here, we define a red surface named ``mud''.  We then instantiate a sphere,
  475. which has a diffuse white surface bound to it.  The  next line instantiates
  476. a sphere with the defined ``mud'' surface bound to it.  The last line
  477. instantiates a sphere with no surface  bound to it; it is assigned the
  478. default surface by rayshade.
  479.  
  480. The applysurf keyword may be used to set the default surface characteristics
  481. for the aggregate object currently being defined.
  482.  
  483. applysurf {surface Specification}
  484.  The specified surface is applied to all following instantiated objects that
  485. do not have surfaces associated with them. The scope of this keyword is
  486. limited to the aggregate currently being defined.
  487.  
  488. \begin{verbatim }
  489.     /*
  490.      * Mirrored ball and cylinder sitting on 'default' plane.
  491.      */
  492.     surface mirror .01 .01 .01  diffuse .05 .05 .05
  493.             specular .8 .8 .8 speccoef 20  reflect 0.95
  494.  
  495.     plane 0 0 0  0 0 1
  496.     applysurf mirror
  497.     sphere 1 0 0 0
  498.     cylinder 1  3 0 0  3 0 3
  499. \end{verbatim }
  500.  
  501. For convenience, the name cursurf may be used to refer to the current
  502. default surface.
  503.  
  504. The utility of bottom-up binding of surfaces lies in the fact that one may
  505. be as adamant or as noncommittal about surface binding  as one sees fit when
  506. defining objects.  For example, one could define a king chess piece
  507. consisting of triangles that have no  surface bound to them, save for the
  508. cross on top, which has a gold-colored surface associated with it.  One may
  509. then instantiate  the king twice, once applying a black surface, and once
  510. applying a white surface.  The result:  a black king and a white king, each
  511. adorned with a golden cross.
  512.  
  513. \begin{verbatim }
  514.     surface white ...
  515.     surface black ...
  516.     surface gold  ...
  517.     ...
  518.     define cross
  519.             box x y z  x y z
  520.             ...
  521.     defend
  522.     define king
  523.             triangle x y z  x y z  x y z
  524.             ...
  525.             object gold cross
  526.     defend
  527.  
  528.     object white king translate 1. 0 0
  529.     object black king
  530. \end{verbatim }
  531.  
  532.  
  533.  
  534.  
  535.  
  536. Objects
  537.  
  538. Objects in rayshade are composed of relatively simple  primitive objects.
  539. These primitives may be used by themselves, or they  may be combined to form
  540. more complex objects known as aggregates. A special family of aggregate
  541. objects,  Constructive Solid Geometry or CSG objects, are the result of a
  542. boolean operations  applied to primitive, aggregate, or CSG objects.
  543.  
  544. This chapter describes objects from a strictly geometric point of view.
  545. Later chapters on surfaces, textures, and shading describe  how object
  546. appearances are defined.
  547.  
  548. An instance is an object that has optionally been transformed and textured.
  549. They are the entities that are actually rendered by  rayshade; when you
  550. specify that, for example, a textured sphere is to be rendered, you are said
  551. to be instantiating the textured  sphere. An instance is specified as a
  552. primitive, aggregate, or CSG object that is followed by optional
  553. transformation and texturing  information. Transformations and textures are
  554. described in Chapters 7 and 8 respectively.
  555.  
  556.  
  557. World Object
  558.  
  559. Writing a rayshade input file is principally a matter of defining a special
  560. aggregate object, the World object, which is a list of the  objects in the
  561. scene.  When writing a rayshade input file, all objects that are
  562. instantiated outside of object-definition blocks are  added to the World
  563. object; you need not (not should you) define the World object explicitly in
  564. the input file.
  565.  
  566.  
  567. Primitives 
  568.  
  569. Primitive objects are the building box with which other objects are created.
  570. Each primitive type has associated with it specialized methods for creation,
  571. intersection with a ray, bounding box calculation, surface normal
  572. calculation, ray enter/exit classification,  and for the computation 2D
  573. texture coordinates termed  u-v coordinates. This latter method is often
  574. referred to as the inverse mapping method.
  575.  
  576. While most of these methods should be of little concern to you, the inverse
  577. mapping methods will affect the way in which certain  textures are applied
  578. to primitives. Inverse mapping is a matter of computing normalized u and v
  579. coordinates for a given point on  the surface of the primitive.  For planar
  580. objects, the u and v coordinates of a point are computed by linear
  581. interpolation based  upon the u and v coordinates assigned to vertices or
  582. other known points on the primitive.  For non-planar objects, uv computation
  583. can be considerably more involved.
  584.  
  585. This section briefly describes each primitive and the syntax that should be
  586. used to create an instance of the primitive. It also  describes the inverse
  587. mapping method, if any, for each type.
  588.  
  589. blob  thresh  st  r  evec{p }  [st  r  evec{p }  ldots]
  590. Defines a blob with consisting of a threshold equal to  thresh and a group
  591. of one or ore metaballs.  Each  metaball is defined by its position
  592. evec{p }, radius  r, and strength  st. For now, see the source code for more
  593. explicit documentation. There is no inverse mapping method for blobs.
  594.  
  595. box  evec{corner1 }  evec{corner2 }
  596. Creates an axis-aligned bo which has  evec{corner1 } and  evec{corner2 } as
  597. opposite corners. Transformations may be applied to the box if a
  598. non-axis-aligned instance is required.  There is no inverse mapping method
  599. for  boxes.
  600.  
  601. sphere  radius  evec{center }
  602. Creates a sphere with the given radius and centered at the given position.
  603. Note that ellipsoids may be created by applying the proper scaling to a
  604. sphere.  Inverse mapping on the sphere is accomplished  by computing the
  605. longitude and latitude of the point on the sphere, with the u value
  606. corresponding to longitude and v to latitude. On an untransformed sphere,
  607. the z axis defines the poles, and the x axis intersects the sphere at u = 0,
  608. v = 0.5.  There are  degeneracies at the poles: the south pole contains all
  609. points of latitude 0., the north all points of latitude 1.
  610.  
  611. torus  rmajor  rminor  evec{center }  evec{up }
  612. Creates a torus centered at evec{center } by rotating a circle with the
  613. given minor radius around the center at a  distance equal to the major
  614. radius.  In tori inverse mapping, the u value is computed using the angle of
  615. rotation about the up vector, and the v value is computing the  angle of
  616. rotation around the tube, with v=0 occuring on the innermost point of the
  617. tube.
  618.  
  619. triangle  evec{p1 }  evec{p2 }  evec{p3 }
  620. Creates a triangle with the given vertices.
  621.  
  622. triangle  evec{p1 }  evec{n1 }  evec{p2 }  evec{n2 }  evec{p3 }  evec{n3 }
  623. Creates a Phong-shaded triangle with the given vertices and vertex normals.
  624. For both Phong- and flat-shaded triangles, the u axis is the vector from
  625. evec{p1 } to evec{p2 }, and the v axis the vector from  evec{p1 } to
  626. evec{p3 }.  There is a degeneracy at evec{p3 }, which contains all points
  627. with v = 1.0.  This default mapping may be  modified using the triangleuv
  628. primitive described below.
  629.  
  630. triangleuv  evec{p1 } evec{n1 } evec{uv1} evec{p2 } evec{n2 } evec{uv2 } evec{p3 } evec{n3 } evec{uv3 }
  631. Creates a Phong-shaded triangle with the given vertices, vertex normals.
  632. When performing texturing, the uv  given for each vertex are used instead of
  633. the default values. When computing uv coordinates within the interior of the
  634. triangle, linear interpolation of the coordinates associated with each
  635. triangle vertex is used.
  636.  
  637. poly  evec{p1 } evec{p2 } evec{p3 } [evec{p4 } ldots ]
  638. Creates a polygon with the given vertices. The vertices should be given in
  639. counter-clockwise order as one is  looking at the ``top'' side of the
  640. polygon.  The number of vertices in a polygon is limited only by available
  641. memory. Inverse mapping for arbitrary polygons is problematical. Rayshade
  642. punts and equate u with the x coordinate of the point of  intersection, and
  643. v with the y coordinate.
  644.  
  645. hf   file
  646. Creates a height field defined by the altitude data stored in the named
  647. file.  The height field is based upon  perturbations of the unit square in
  648. the z=0 plane, and is rendered as a surface tessellated by right isosceles
  649. triangles. See Appendix B for a discussion of the format of a height field
  650. file. Height field inverse mapping is straight-forward:  u is the x
  651. coordinate of the point of intersection, v the y coordinate.
  652.  
  653. plane  evec{point } evec{normal }
  654. Creates a plane that passes through the given point and has the specified
  655. normal. Inverse mapping on the plane is identical to polygonal inverse
  656. mapping.
  657.  
  658. cylinder  radius evec{bottom } evec{top }
  659. Creates a cylinder that extends from  evec{bottom } to  evec{top } and has
  660. the indicated radius.  Cylinders are  rendered without endcaps. The
  661. cylinder's axis defines the v axis.  The u axis wraps around the cylinder,
  662. with u=0 dependent upon the orientation of the  cylinder.
  663.  
  664. cone  rad_{bottom }  evec{bottom }  rad_{top }  evec{top }
  665. Creats a (truncated) cone that extends from evec{bottom } to evec{top }.
  666. The cone will have a radius of  rad_{bottom } at evec{bottom } and a radius
  667. of rad_{top } at  evec{top }. Cones are rendered without endcaps. Cone
  668. inverse mapping is analogous to cylinder mapping.
  669.  
  670. disc radius  evec{pos }  evec{normal }
  671. Creates a disc centered at the given position and with the indicated surface
  672. normal. Discs are useful for placing endcaps on cylinders and cones. Inverse
  673. mapping for the disc is based on the computation of the  normalized polar
  674. coordinates of the point of intersection.  The normalized radius of the
  675. point of intersection is assigned to u,  while the normalized angle from a
  676. reference vector is assigned to v.
  677.  
  678.  
  679. Objects 
  680.  
  681. An aggregate is a collection of primitives, aggregate, and CSG objects.  An
  682. aggregate, once defined, may be instantiated at will,  which means that
  683. copies that are optionally transformed and textured may be made. If a scene
  684. calls for the presence of many geometrically identical objects, only one
  685. such object need be defined; the one defined  object may then be
  686. instantiated many times.
  687.  
  688. An aggregate is one of several possible types.  These aggregate types are
  689. differentiated by the type of ray/aggregate intersection  algorithm (often
  690. termed an acceleration technique or efficiency scheme that is used.
  691.  
  692. Aggregates are defined by giving a keyword that defines the type of the
  693. aggregate, followed by a series of object instantiations  and surface
  694. definitions, and terminated using the end keyword. If a defined object
  695. contains no instantiations, a warning message is printed.
  696.  
  697. The most basic type of aggregate, the list, performs intersection testing in
  698. the simplest possible way:  Each object in the list is  tested for
  699. intersection with the ray in turn, and the closest intersection is returned.
  700.  
  701. list  ldots  end
  702. Create a List object containing those objects instantiated between the
  703. list/end pair.
  704.  
  705. The grid aggregate divides the region of space it occupies into a number of
  706. discrete box-shaped voxels.  Each of these voxels  contains a list of the
  707. objects that intersect the voxel.  This discretization makes it possible to
  708. restrict the objects tested for  intersection to those that are likely to
  709. hit the ray, and to test the objects in nearly ``closest-first'' order.
  710.  
  711. grid  xvox  yvox  zvox  ldots  end
  712. Create a Grid objects composed of  xvox by  yvox by zvox voxels containing
  713. those objects instantiated between  the grid/end pair.
  714.  
  715. It is usually only worthwhile to ``engrid'' rather large, complex
  716. collections of objects.  Grids also use a great deal more memory  than List
  717. objects.
  718.  
  719.  
  720. Solid Geometry
  721.  
  722. Constructive Solid Geometry is the process of building solid objects from
  723. other solids. The three CSG operators are Union,  Intersection, and
  724. Difference.  Each operator acts upon two objects and produces a single
  725. object result. By combining multiple  levels of CSG operators, complex
  726. objects can be produced from simple primitives.
  727.  
  728. The union of two objects results in an object that encloses the space
  729. occupied by the two given objects. Intersection results in an  object that
  730. encloses the space where the two given objects overlap.  Difference is an
  731. order dependent operator; it results in the  first given object minus the
  732. space where the second intersected the first.
  733.  
  734. In Rayshade:
  735.  
  736. CSG in rayshade will generally operate properly when applied to conjunction
  737. with on boxes, spheres, tori, and blobs. These  primitives are by nature
  738. consistent, as they all enclose a portion of space (no hole from the
  739. "inside" to the "outside"), have surface  normals which point outward (they
  740. are not "inside-out"), and do not have any extraneous surfaces.
  741.  
  742. CSG objects may also be constructed from aggregate objects. These aggregates
  743. contain whatever is listed inside, and may  therefore be inconsistent. For
  744. example, an object which contains a single triangle will not produce correct
  745. results in CSG models,  because the triangle does not enclose space.
  746. However, a collection of four triangles which form a pyramid does enclose
  747. space,  and if the triangle normals are oriented correctly, the CSG
  748. operators should work correctly on the pyramid.
  749.  
  750. CSG objects are specified by surrounding the objects upon which to operate,
  751. as well as any associated surface-binding  commands, by the operator verb on
  752. one side and the end keyword on the other:
  753.  
  754. union  object  Object  Object  ldots  end
  755. Specify a new object defined as the union of the given objects.
  756.  
  757. difference  object  Object  Object  ldots  end
  758. Specify a new object defined as the difference of the given objects.
  759.  
  760. intersect  object  Object  Object  ldots  end
  761. Specify a new object defined as the intersection of the given objects.
  762.  
  763. Note that the current implementation does not support more that two objects
  764. in a CSG list (but it is planned for a future version).
  765.  
  766. * The following aren simple CSG objects using the four consistent
  767. * primitives:
  768. * union box ... difference ...
  769.  
  770. csg Problems:
  771.  
  772. A consistent CSG model is one which is made up of solid objects with no
  773. dangling surfaces.  In rayshade, it is quite easy to  construct inconsistent
  774. models, which will usually appear incorrect in the final images. In
  775. rayshade, CSG is implemented by maintaining the tree structure of the CSG
  776. operations.  This tree is traversed, and the  operators therein applied, on
  777. a per-ray basis. It is therefore difficult to verify the consistency of the
  778. model ``on the fly.'' One class of CSG problems occur when surfaces of
  779. objects being operated upon coincide.  For example, when subtracting a box
  780. from another box to make a square cup, the result will be wrong if the tops
  781. of the two boxes coincide.  To correct this, the inner  box should be made
  782. slightly taller than the outer box. A related problem that must be avoided
  783. occurs when two coincident  surfaces are assigned different surface
  784. properties.
  785.  
  786. It may seem that the union operator is unnecessary, since listing two
  787. objects together in an aggregate results in an image that  appears to be the
  788. same. While the result of such a short-cut may appear the same on the
  789. exterior, the interior of the resulting  object will contain extraneous
  790. surfaces. The following examples show this quite clearly.
  791.  
  792. \begin{verbatim }
  793.     difference
  794.       box -2 0 -3  2 3 3
  795.       union  /* change to list; note bad internal surfaces */
  796.         sphere 2 1 0 0
  797.         sphere 2 -1 0 0
  798.       end
  799.     end rotate 1 0 0 -40  rotate 0 0 1 50
  800. \end{verbatim }
  801.  
  802. The visual evidence of an inconsistent CSG object varies depending upon the
  803. operator being used. When subtracting a consistent  object from and
  804. inconsistent one, the resulting object will appear to be the union of the
  805. two objects, but the shading will be  incorrect. It will appear to be
  806. inside-out in places, while correct in other places.  The inside-out
  807. sections indicate the areas where  the problems occur. Such problems are
  808. often caused by polygons with incorrectly specified normals, or by surfaces
  809. that exactly coincide (which  appear as partial ``swissh-cheese'' objects).
  810.  
  811. The following example illustrates an attempt to subtract a sphere from a
  812. pyramid defined using an incorrectly facing triangle.   Note that the
  813. resulting image obviously points to which triangle is reversed.
  814.  
  815. \begin{verbatim }
  816.     name pyramid list
  817.         triangle 1 0 0  0 1 0  0 0 1
  818.         triangle 1 0 0  0 0 0  0 1 0
  819.         triangle 0 1 0  0 0 0  0 0 1
  820.         triangle 0 0 1  1 0 0  0 0 0  /* wrong order */
  821.     end
  822.  
  823.     difference
  824.         object pyramid scale 3 3 3 rotate 0 0 1 45
  825.             rotate 1 0 0 -30 translate 0 -3.5 0
  826.         sphere 2.4 0 0 0
  827.     end
  828. \end{verbatim }
  829.  
  830. By default, cylinders and cones do not have end caps, and thus are not
  831. consistent primitives.  One must usually add endcaps by  listing the
  832. cylinder or cone with (correctly-oriented) endcap discs in an aggregate.
  833.  
  834.  
  835. Objects 
  836.  
  837. A name may be associated with any primitive, aggregate, or CSG object
  838. through the use of the name keyword:
  839.  
  840. name  objname Instance
  841. Associate objname with the given object.  The specified object is not
  842. actually instantiated; it is only stored  under the given name.
  843.  
  844. An object thus named may then be instantiated (with possible additional
  845. transforming and texturing) via the object keyword:
  846.  
  847. object  objname Transformations Textures
  848. Instantiate a copy of the object associated with objname. If given, the
  849. transformations and textures are  composed with any already associated with
  850. the object being instantiated. Texturing 
  851.  
  852. Textures are used to modify the appearance of an object through the use of
  853. procedural functions. A texture may modify any  surface characteristic,such
  854. as diffuse color, reflectivity, or transparency, or it may  modify the
  855. surface normal (``bump mapping'')  in order to give the appearance of a
  856. rough surface.
  857.  
  858. Any number of textures may be associated with an object.  If more than one
  859. texture is specified, they are applied in the order  given.  This allowsone
  860. to compose texturing functions and create, for example a tiled marble ground
  861. plane using the checker and  marble textures.
  862.  
  863. Textures are associated with objects by following the object specification
  864. bya number of lines of the form:
  865.  
  866. texture  name  Texturing Arguments  Transformations
  867.  
  868. Transformations may be applied to the texture in order to, for example,
  869. shrink or grow feature size, change the orientation of  features, and change
  870. the position of features.
  871.  
  872. Several of the texturing functions take the name of a colormap as an
  873. argument. A colormap is 256-line ASCII file, with each line  containing
  874. three space-separated values ranging from 0 to 255. Each line gives the red,
  875. green, and blue values for a single entry  in the colormap.
  876.  
  877.  
  878. Functions 
  879.  
  880. blotch  BlendFactor  surface
  881. Produces a mildly interesting blotchy-looking surface. BlendFactor is used
  882. to control the interpolation between the default  surface characteristics
  883. and the characteristics of the given surface.  A value of 0 results in a
  884. roughly 50-50 mix of the two  surfaces.  Higher values result in a great
  885. portion of the default surface characteristics.
  886.  
  887. bump  scale
  888. Apply a random bump map.  The point of intersection is passed to DNoise().
  889. The returned normalized vector is weighted by   scale and the result is
  890. added to the normal vector at the point of intersection
  891.  
  892. checker surface 
  893. Applies a 3D checkerboard texture.  Every point that falls within an
  894. ``even'' unit cube will be assigned the characteristics of the  named
  895. surface applied to it, while points that fall within ``odd'' cubes will have
  896. its usual surface characteristics.  Be wary of  strange effects due to
  897. roundoff error that occur when a planar checkered surface lies in a plane of
  898. constant integral value (e.g.,  z=0) in texture space. In such cases, simply
  899. translate the texture to ensure that the planar surface is not coincident
  900. with an integral plane in texture space (e.g., translate 0 0 0.1).
  901.  
  902. cloud  scale H  lambda octaves cthresh lthresh tscale
  903. This texture is a variant on Geoff Gardner's ellipsoid-texturing algorithm.
  904. It should be applied to unit spheres centered at the  origin. Thesespheres
  905. may, of course, be transformed at will to form the appropriately-shaped
  906. cloud or tree.
  907.  
  908. A sample of normalized  fBm (see the fbm texture) is generated at the point
  909. of intersection.  This sample is used to modulate the  surface transparency.
  910. The final transparency if a function of the sample value,  the proximity of
  911. the point of intersection to the  edge of the sphere (as seen from the ray
  912. origin), and three parameters to control the overall  ``density.'' The
  913. proximity of the point to the sphere edge is determined by  evaluating a
  914. limb function, which varies from 0 on the  limb to 1 at the center of the
  915. sphere.
  916.  
  917. transp = 1. - \frac{- cthresh - (lthresh - cthresh)(1 - limb)}{tscale }
  918.  
  919. fbm  offset scale H lambda octaves thresh colormap
  920. Generate a sample of discretized fractional Brownian motion (fBm) and uses
  921. it to scale the diffuse and ambient component of an  object's surface.
  922.  
  923. -Scale is used to scale the value returne the fBm function.  
  924. -Offset allows one to control  minimum value of the fBm function.
  925. -H is the {m Holder exponent} used in the fBm function (a value of 0.5 works
  926. well). $\lambda$ is used to control  lacunarity,   and specifies  the
  927. frequency difference between successive samples of the fBm basis function (a
  928. value of 2.0 will suffice).    -Octaves specifies the numberof octaves
  929. (samples) to take of the fBm basis function (in this case, Noise()). Between
  930. five and  seven octaves usually works well. {em Thresh} is used to specify a
  931. lower bound onthe output of the fBm function. Any value  lower than thresh
  932. is set to zero. If a colormap is named, a 256-entry colormap is read from
  933. the named file, and the sample of fBm is scaled by 255 and is used as  an
  934. index into thecolormap. The resulting colormap entry is used to scale the
  935. ambient and diffuse components of the object's  surface.
  936.  
  937. fbmbump  offset  scale  H  lambda  octaves
  938. Similar to the  fbm texture. Rather than modifying the color of a surface,
  939. this texture acts as a bump map.
  940.  
  941. gloss  glossiness
  942. Gives reflective surfaces a glossy appearance. This texture erturbs the
  943. object's surace normal such that the normal ``samples'' a  cone of unit
  944. height with radius 1. - glossiness.  A value of 1 results in perfect
  945. mirror-like reflections, while a value of 0 results in  extremely fuzzy
  946. reflections.  For best results, jittered sampling should be used to render
  947. scenes that make use of this texture.
  948.  
  949. marble  colormap 
  950. Gives a surface a marble-like appearance. The texture is implemented as
  951. roughly parallel alternating veins of marble, each of  which is separated by
  952. 1/7 of a unit and runs perpendicular to the Z axis. If a colormap is named,
  953. the surface's ambient and diffuse  colors will be scaled using the RGB
  954. values in the colormap. If no colormap is given, the diffuse and ambient
  955. components are  simply scaled by the value of the marble function. One may
  956. transform the texture to control the density and orientation of the  marble
  957. veins.
  958.  
  959. sky  scale  H  lambda  octaves  cthresh  ltresh
  960. Similar to the  fbm texture. Rather than modifying the color of a surface,
  961. this texture modulates its transparency. cthresh is the  value of the fBm
  962. function above which the surface is totally opaque. Below lthresh, the
  963. surface is totally transparent.
  964.  
  965. stripe  surface  size  bump Mapping
  966. Apply a ``raised'' stripe pattern to the surface. The surface properties
  967. used to color the stripe are those of the given surface. The  width of the
  968. stripe, as compared to the unit interval, is given by  size. The magnitude
  969. of bump controls the extent to which the  bump appears to be displaced from
  970. the rest of the surface. If negative, the stripe will appear to sink into
  971. the surface; if negative, it  will appear to stand out of the surface.
  972.  
  973. Mapping functions are described below.
  974.  
  975. wood 
  976. Gives a surface a wood-like appearance. The feature size of this texture is
  977. approximately 0.01 of a unit, making it often necessary  to scale the
  978. texture in order to achieve the desired appearance.
  979.  
  980.  
  981. Texturing 
  982.  
  983. Rayshade also supports an  image texture.  This texture allows you to use
  984. images to modify the characteristics of a surface. You  can use
  985. three-channel images to modify the any or all of the ambient, diffuse, and
  986. specular colors of a surface.
  987.  
  988. If you are using the Utah Raster Toolkit, you can also use single-channel
  989. images to modify surface reflectance, transparency, and  the specular
  990. exponent. You can also use a single-channel image to apply a bump map to a
  991. surface.
  992.  
  993. In all but the bump-mapping case, a component is modified by multiplying the
  994. given value by the value computed by the  texturing function. When using the
  995. Utah Raster Toolkit, surface characteristics are modified in proportion to
  996. the value of the   alpha channel in the image. If there is no {em
  997. alpha}channel, or you are not using the Utah Raster Toolkit,  alpha is
  998. assumed to  be everywhere equal to 1.
  999.  
  1000. component  component 
  1001. The named component will be modified.
  1002.  
  1003. Possible surface components are:
  1004.  
  1005. ambient   (modify ambient color),
  1006. diffuse     (modify diffuse color),
  1007. specular  (modify specular color),
  1008. specpow  (modify specular exponent),
  1009. reflect     (modify reflectivity),
  1010. transp     (modify transparency),
  1011. bump      (modify surface normal).
  1012.  
  1013. The specpow,  reflect,  transp, and  bump components require the use of a
  1014. single-channel image. range  high low Specify the range of values to which
  1015. the values in the image should be mapped.  An value of 1 will be mapped
  1016. high, 0 to  low.   Intermediate values will be linearly interpolated.
  1017.  
  1018. smooth 
  1019. When given, pixel averaging will be performed in order to smooth the sampled
  1020. image.  If not specified, no averaging will occur.
  1021.  
  1022. textsurf  surface Specification
  1023. For use when modifying surface colors, this keyword specifies that the given
  1024. surface should be used as the base to be modified  when the alpha value in
  1025. the image is non-zero.  When alpha is zero, the object's unmodified default
  1026. surface characteristics are  retained.
  1027.  
  1028. The usual behavior is for the object's default surface properties to be used.
  1029.  
  1030. tile  un vn
  1031. Specify how the image should be tiled (repeated) along the u and v axes. If
  1032. positive, the value of un gives the number of times the  image should be
  1033. repeated along the u axis, starting from the origin of the texture, and
  1034. positive vn gives the number of times it  should be repeated along the v
  1035. axis. If either valueis zero, the image is repeated infinitely along the
  1036. appropriate axis.
  1037.  
  1038. Tiling is usually only a concern when linear mapping is being used, though
  1039. it may also be used if image textures are being scaled.  By default em un
  1040. and em vn are both zero.
  1041.  
  1042.  A mapping function may also be associated with an image texture.
  1043.  
  1044.  
  1045. Functions 
  1046.  
  1047. Mapping functions are used to apply two-dimensional textures to surfaces.
  1048. Each mapping functions defines a different method of  transforminga three
  1049. dimensional point of intersection to a two dimensional u-v pair termed
  1050. texturing coordinates. Typically, the arguments to a mapping method define a
  1051. center of a projection and two non-parallel axes that define a local
  1052. coordinate system.
  1053.  
  1054. The default mapping method is termed u-v mapping or inverse mapping.
  1055. Normally, there is a different inverse mapping method  for each primitive
  1056. type (see chapter 5).
  1057.  
  1058. When inverse mapping is used, the point of intersection is passed to the uv
  1059. method for the primitive that was hit.
  1060.  
  1061. map  uv
  1062. Use the uv (inverse mapping) method associated with the object that was
  1063. intersected in order to map from 3D to determine  texturing coordinates.
  1064.  
  1065. The inverse mapping method for each primitive is described in Chapter 5.
  1066.  
  1067. map  linear  evec{origin }  evec{vaxis }  evec{uaxis }
  1068. Use a linear mapping method. The 2D texture is transformed so that its u
  1069. axis is given by evec{uaxis } and its v axis by vaxis. The  texture is
  1070. projected along the vector defined by the cross product of the u and v axes,
  1071. with the (0,0) in texture space mapped to  evec{origin }.
  1072.  
  1073. map  cylindrical  evec{origin }  evec{vaxis }  evec{uaxis }
  1074. Use a cylindrical mapping method.  The point of intersectionis projected
  1075. onto an imaginary cylinder, and the location of the  projected point is used
  1076. to determine the texture coordinates. If given, evec{origin } and evec{vaxis
  1077. } define the cylinder's axis,  and evec{uaxis } defines where u=0 is
  1078. located. See the description of the inverse mapping method for the cylinder
  1079. in Chapter 5.  By default, the point of intersection is projected  onto a
  1080. cylinder that runs through the origin along the z axis, with evec{uaxis }
  1081. equal to the x axis.
  1082.  
  1083. map  spherical  evec{origin }  evec{vaxis }  evec{uaxis }
  1084. Use a spherical mapping method.  The intersection point is projected onto an
  1085. imaginary sphere, and the location of the projected  point is used to
  1086. determine the texturing coordinates in a manner identical to that used in
  1087. the inverse mapping method for the  sphere primitive. If given, the center
  1088. of the projection is evec{origin }, evec{vaxis } defines the sphere axis,
  1089. and the point where the non-parallel  evec{uaxis } intersects the sphere
  1090. defines where u=0 is located. By default, a spherical mapping projects
  1091. points towards the origin, with evec{vaxis } defined to be the z axis and
  1092. evec{uaxis }  defined to be the x axis.
  1093.  
  1094.  
  1095. Sources 
  1096.  
  1097. The lighting in a scene is determined by the number, type, and nature of the
  1098. light sources defined in the input file.  Available light  sources range
  1099. from simple directional sources to more realistic but computationally costly
  1100. quadrilateral area light sources.   Typically, you will want to use point or
  1101. directional light sources while developing images.  When final renderings
  1102. are made,  these simple light sources may be replaced by the more complex
  1103. ones.
  1104.  
  1105. No matter what kind of light source you use, you will need to specify its
  1106. intensity. In this chapter, an Intensity is either a red- green-blue triple
  1107. indicating the color of the light source, or a single value that is
  1108. interpreted as the intensity of a ``white'' light. In the current version of
  1109. rayshade, the intensity of a light does not decrease as one moves farther
  1110. from it.
  1111.  
  1112. If you do not define a light source, rayshade will create a directional
  1113. light source of intensity 1.0 defined by the vector (1., -1.,  1.). This
  1114. default light source is designed to work well when default viewing
  1115. parameters and surface values are being used.
  1116.  
  1117. You may define any number of light sources, but keep in mind that it will
  1118. require more time to render images that include many  light sources.  It
  1119. should also be noted that the light sources themselves will not appear in
  1120. the image, even if they are placed in  frame.
  1121.  
  1122.  
  1123. Source Types
  1124.  
  1125. The amount of ambient light present in a scene is controlled by a pseudo
  1126. light source of type ambient.
  1127.  
  1128. light  Intensity  ambient
  1129. Define the amount of ambient light present in the entire scene.
  1130.  
  1131. There is only one ambient light source; its default intensity is {1 , 1, 1}.
  1132. If more than one ambient light source is defined, only  the last instance is
  1133. used.  A surface's ambient color is multiplied by the intensity of the
  1134. ambient source to give the total ambient  light reflected from the surface.
  1135.  
  1136. Directional sources are described by a direction alone, and are useful for
  1137. modeling light sources that are effectively infinitely far  away from the
  1138. objects they illuminate.   
  1139.  
  1140. light  Intensity  directional  evec{direction }
  1141. Define a light source with the given intensity that is defined to be in the
  1142. given direction from every point it illuminates.  The  direction need not be
  1143. normalized.
  1144.  
  1145. Point sources are defined as a single point in space.  They produce shadows
  1146. with sharp edges and are a good replacement for  extended and other
  1147. computationally expensive light source.
  1148.  
  1149. light  Intensity  point  evec{pos }
  1150. Place a point light source with the given intensity at the given position.
  1151.  
  1152. Spotlights are useful for creating dramatic localized lighting effects. They
  1153. are defined by their position, the direction in which  they are pointing,
  1154. and the width of the beam of light they produce.
  1155.  
  1156. light  Intensity  spot evec{pos }  evec{to }  alpha  theta_{in }  theta_{out }
  1157. Place a spotlight at evec{pos }, oriented as to be pointing at evec{to }.
  1158. The intensity of the light falls off as (cosine theta)^{alpha  }, where
  1159. theta is the angle between the spotlight's main axis and the vector from the
  1160. spotlight to the point being illuminated.   theta_{in } and  theta_{out }
  1161. may be used to control the radius of the cone of light produced by the
  1162. spotlight. theta_{in } is the the angle at which the light source begins to
  1163. be attenuated.  At theta_{out }, the spotlight intensity is zero. This
  1164. affords control over how ``fuzzy'' the edges of the spotlight are.  If
  1165. neither angle is given, they both are effectively set to 180  degrees.
  1166.  
  1167. Extended sources are meant to model spherical light sources.  Unlike point
  1168. sources, extended sources actually possess a radius,  and as such are
  1169. capable or producing shadows with fuzzy edges (penumbrae).  If you do not
  1170. specifically desire penumbrae in  your image, use a point source instead.
  1171.  
  1172. light  Intensity  extended  radius  evec{pos } 
  1173. Create an extended light source at the given position and with the given
  1174. radius. The shadows cast by extended sources are modeled by taking samples
  1175. of the source at different locations on its surface.  When  the source is
  1176. partially hidden from a given point in space, that point is in partial
  1177. shadow with respect to the extended source, and  the sampling process is
  1178. usually able to determine this fact.
  1179.  
  1180. Quadrilateral light sources are computationally more expensive than extended
  1181. light sources, but are more flexible and produce  more realistic results.
  1182. This is due to the fact that an area source is approximated by a number of
  1183. point sources whose positions are jittered to reduce  aliasing. Because each
  1184. of these point sources has shading calculations performed individually, area
  1185. sources may be placed  relatively close to the objects it illuminates, and a
  1186. reasonable image will result.
  1187.  
  1188. light  Intensity  area  evec{p1 }  evec{p2 }  usamp  evec{p3 }  vsamp
  1189. Create a quadrilateral area light source. The u axis is defined by the
  1190. vector from  evec{p1 } to evec{p2 }.  Along this axis a total  of usamp
  1191. samples will be taken. The v axis of the light source is defined by the
  1192. vector from evec{p1 } to evec{p3 }.  Along this  axis a total of vsamp
  1193. samples will be taken.
  1194.  
  1195. The values of usamp and vsamp are usually chosen to be proportional to the
  1196. lengths of the u and v axes.  Choosing a relatively  high number of samples
  1197. will result in a good approximation to a ``real'' quadrilateral source.
  1198. However, because complete  lighting calculations are performed for each
  1199. sample, the computational cost is directly proportional to the product of
  1200. usamp and  vsamp.
  1201.  
  1202.  
  1203. Shadows 
  1204.  
  1205. In order to determine the color of a point on the surface of any object, it
  1206. is necessary to determine if that point is in shadow with  respect to each
  1207. defined light source.  If the point is totally in shadow with respect to a
  1208. light source, then the light source makes no  contribution to the point's
  1209. final color.
  1210.  
  1211. This shadowing determination is made by tracing rays from the point of
  1212. intersection to each light source.  These ``shadow feeler''  rays can add
  1213. substantially to the overall rendering time.  This is especially true if
  1214. extended or area light sources are used.  If at  any point you wish to
  1215. disable shadow determination on a global scale, there is a command-line
  1216. option -n that allows you to do so.   It is also possible to disable the
  1217. casting of shadows onto given objects through the use of the noshadow
  1218. keyword in surface  descriptions.  In addition, the noshadow keyword may be
  1219. given following the definition of a light source, causing the light source
  1220. to cast no shadows onto any surface.
  1221.  
  1222. Determining if a point is in shadow with respect to a light source is
  1223. relatively simple if all the objects in a scene are opaque.  In  this case,
  1224. one simply traces a ray from the point to the light source. If the ray hits
  1225. an object before it reaches the light source, then the point is in shadow.
  1226.  
  1227. Shadow determination becomes more complicated if there are one or more
  1228. objects with non-zero transparency between the point  and the light source.
  1229. Transparent objects may not completely block the light from a source, but
  1230. merely attenuate it. In such cases,  it is necessary to compute the amount
  1231. of attenuation at each intersection and to continue the shadow ray until it
  1232. either reaches the  light source or until the light is completely
  1233. attenuated.
  1234.  
  1235. By default, rayshade computes shadow attenuation by assuming that the index
  1236. of refraction of the transparent object is the same  as that of the medium
  1237. through which the ray is traveling. To disable partial shadowing due to
  1238. transparent objects, the   shadowtransp keyword should be given somewhere in
  1239. the input file.
  1240.  
  1241. shadowtransp 
  1242. The intensity of light striking a point is  not affected by intervening
  1243. transparent objects.
  1244.  
  1245. If you enclose an object behind a transparent surface, and you wish the
  1246. inner object to be illuminated, you must not use the   shadowtransp keyword
  1247. or the  -o option.
  1248.  
  1249.  
  1250. Transformations 
  1251.  
  1252. Rayshade supports the application of linear transformations to objects and
  1253. textures. If more than one transformation is specified,  the total resulting
  1254. transformation is computed and applied.
  1255.  
  1256. translate  evec{delta }
  1257. Translate (move) by delta.
  1258.  
  1259. rotate  evec{axis }  theta
  1260. Rotate counter-clockwise about the given axis by theta degrees.
  1261.  
  1262. scale  evec{v }
  1263. Scale by v.
  1264. All three scaling components must be non-zero, else degenerate matrices will
  1265. result.
  1266.  
  1267. transform  evec{row1 }  evec{row2 }  evec{row3 }  [ evec{delta ]
  1268. Apply the given 3-by-3 transformation matrix.  If given,  delta specifies a
  1269. translation vector.
  1270.  
  1271. Transformations should be specified in the order in which they are to be
  1272. applied immediately following the item to be  transformed.  For example:
  1273.  
  1274. \begin{verbatim }
  1275.         /*
  1276.          * Ellipsoid, rotated cube
  1277.          */
  1278.         sphere 1. 0 0 0   scale 2. 1. 1. translate 0 0 -2.5
  1279.         box 0 0 0 .5 .5 .5
  1280.            rotate 0 0 1 45 rotate 1 0 0 45 translate 0 0 2.5
  1281. \end{verbatim }
  1282.  
  1283. Transformations may also be applied to textures:
  1284.  
  1285. \begin{verbatim }
  1286.    plane 0 0 -4  0 0 1
  1287.      texture checker red scale 2 2 2 rotate 0 0 1 45
  1288. \end{verbatim }
  1289.  
  1290. Note that transformation parameters may be specified using of animated
  1291. expressions, causing the transformations themselves to  be animated. See
  1292. Appendix B for further details.
  1293.  
  1294.  
  1295. Field Files
  1296.  
  1297. This appendix describes the format of the files that store data for the
  1298. height field primitive. The format is an historical relic; a  better format
  1299. is needed.
  1300.  
  1301. Height field data is stored in binary form. The first record in the file is
  1302. a 32-bit integer giving the square root of number of data  points in the
  1303. file. We'll call this number the size of the height field.
  1304.  
  1305. The size is followed by altitude ('z') values stored as 32-bit floating
  1306. pointvalues. The 0th value in the file specifies the 'z'  coordinate of the
  1307. lower-left corner of the height field (0, 0). The next specifies the Z
  1308. coordinate for '(1/(size-1), 0)'. The last  specifiesthe coordinate for
  1309. '(1., 1.)'. In other words, the 'i^{th }' value in the heightfield file
  1310. specifies the 'z' coordinate for the  point whose 'x' coordinate is '(i \%
  1311. size) / (size -1)', and whose 'y' coordinate is '(i / size) / (size -1)'.
  1312. Non-square height fields may be rendered by specifying altitude values less
  1313. than or equal to the magic value '-1000'. Triangles  that have any vertex
  1314. lessthan or equal in altitude to this value are not rendered.
  1315.  
  1316. While this file format is compact, it sacrifices portability for ease of
  1317. use. While creating and handling height field files is simple,  transporting
  1318. a height field from one machine to another is problematical due to the fact
  1319. that differences in byte order and floating- point format between machines
  1320. is not taken into account.
  1321.  
  1322. These problems could be circumvented by writing the height field file in a
  1323. fixed-point format, taking care to write the bytes that  encode a given
  1324. value in a consistent way from machine to machine. An even better idea would
  1325. be to write a set of tools for  manipulating arbitrary 2D arrays of
  1326. floating-point values in a compact, portable way, allowing for comments and
  1327. the like in the  file\ldots
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336. Animation 
  1337.  
  1338. Rayshade provides basic animation animation support by allowing time-varying
  1339. transformations to be associated with primitives  and aggregate objects.
  1340. Commands are provided for controlling the amount of time between each frame,
  1341. the speed of the camera  shutter, and the total number of frames to be
  1342. rendered.
  1343.  
  1344. By default, rayshade renders a single frame, with the shutter open for an
  1345. instant (0 units of time, in fact).  The shutter speed in no  way changes
  1346. the light-gathering properties of the camera, i.e. frames rendered using a
  1347. longer exposure will not appear brighter  than those with a shorter
  1348. exposure.  The only change will be in the potential amount of movement that
  1349. the frame ``sees'' during  the time that the shutter is open.
  1350.  
  1351. Each ray cast by \rayshade samples a particular moment in time. The time
  1352. value assigned to a ray ranges from the starting time of  the current frame
  1353. to the starting time plus the amount of time the shutter is open.  When a
  1354. ray encounters an object or texture that  possesses an animated
  1355. transformation, the transformed entity is moved into whatever position is
  1356. appropriate for the ray's current  time value before intersection, shading,
  1357. or texturing computations are performed.
  1358.  
  1359. The starting time of the current frame is computed using the length of each
  1360. frame the current frame number, and the starting time  of the first frame.
  1361.  
  1362. shutter  t
  1363. Specifies that the shutter is open for t units of time for each exposure. A
  1364. larger value of  t will lead to more motion blur in the final image.   Note
  1365. that t may be greater than the actual length of a frame.   By default, t is
  1366. zero, which prevents all motion blur.
  1367.  
  1368. framelength   frameinc
  1369. Specifies the time increment between frames.
  1370. The default time between frames is 1 unit.
  1371.  
  1372. starttime  time
  1373. Specifies the starting time of the first frame.
  1374. By default,  time is zero.
  1375.  
  1376. Variables may be defined thorugh the use of the define keyword:
  1377.  
  1378. define  name  value
  1379. Associate  name with the given  value.  Value may be a constant or a
  1380. parenthesized expression. The variable name may thereafter be used in
  1381. expressions in the input file.
  1382.  
  1383. An animated transformation is one for which animated expressions have been
  1384. used to define one or more of its parameters (e.g.  the angle through which
  1385. a rotation occurs).  An animated expression is one that makes use of a
  1386. time-varying (``animated'')  variable or function.
  1387.  
  1388. There are two supported animated variables. The first, time, is equal to the
  1389. current time. When a ray encounters an animated  transformation defined
  1390. using an expression containing  time, the ray substitutes its time value
  1391. into the expression before  evaluation. Using the  time variable in an
  1392. animated expression is the most basic way to create blur-causing motion.
  1393.  
  1394. The second animated variable,  frame, is equal to the current frame number.
  1395. Unlike the  time variable,  frame takes on a single  value for the duration
  1396. of each frame.  Thus, transforms animated through the use of the  frame
  1397. variable will not exhibit motion  blurring.
  1398.  
  1399. Also supported is the linear function.  This function uses time implicitly
  1400. to interplate between two values.
  1401.  
  1402. linear  Stime, Sval, Etime, Eval
  1403. Linearly interpolate between Sval at time Stime and Eval at time Etime. If
  1404. the current time is less than Stime, the function returns  Sval.  If the
  1405. current time is greater than Etime,  Eval is returned.
  1406.  
  1407. The following example shows the use of the time variable to animate a sphere
  1408. by translating it downwards over five frames. Note  thet the shutter keyword
  1409. is used to set the shutter duration in order to induce motion blurring.
  1410.  
  1411. \begin{verbatim }
  1412.     frames 5
  1413.     shutter 1
  1414.     sphere 1 0 0 2 translate 0 0 (-time)
  1415. \end{verbatim }
  1416.  
  1417.  
  1418.  
  1419.  
  1420.