Vegetation Placement Include File

Vegetation Object Placement Include File
for the Persistence Of Vision SuperPatch v3.1e

Created by Mark Wagner, 21 June 1999
Updated 10 July 1999
Updated 17 July 1999
Updated 14 September 1999

INSTALLATION

Copy the Object Placement include file (Vegetate.inc) to one of the directories (folders) in your POV-Ray library path. Normally this is the INCLUDE sub-directory of the directory where you installed POV-Ray, so if you installed POV-Ray in C:\POVRAY you should copy the Vegetate.inc file to C:\POVRAY\INCLUDE. On a Windows 95 system, this is probably something like:

C:\Program Files\POV-Ray for Windows\Include

On UNIX and similar systems, where filenames are case-sensitive, you may have to rename the include file so that all letters are lowercase. This will enable you to render the sample files without modification.

QUICK START

The Object Placement include file allows you to randomly place user-defined objects on the surface of another object with random rotation around the sky vector. This is mainly useful for placing vegetation on a heightfield, but can be used for many other things (craters on a planet, bugs on a windshield, etc.) You can specify the objects to use, the maximum and minimum altitudes for placement, and many other options.

Using the Object Placement include file is as simple as declaring the object to place items on and including the file, eg:

#declare VegeObject = sphere{ <0,0,0>, 15 pigment{ rgb <0,1,0> } }
#include "vegetate.inc"

This will create 100 pine trees (the default object) scattered on the upper surface of an invisible sphere. As the include file does not automatically add the object the items are being placed on to the scene, you will need to include a line such as:

object{ VegeObject }

somewhere else in your scene.

There are options which control how the objects will be placed; to use any of these you simply add the following line to your POV-Ray scene file:

#declare [variable-name]=[value]

substituting the desired variable name and value where appropriate. After you have declared all the options you want to use, you add the following line to your POV-Ray scene file:

#include "Vegetate.inc"

The Object Placement include file will then automatically place the objects for you. Although only one option is required to place objects (VegeObject), you will want to use the options listed below to ensure you get the result that you want.

Note that Vegetate.inc should never be included at the start of a scene (like colors.inc or textures.inc). It should only be included after first declaring the desired options.

Basic Options

VegeObject

This is the object that you want to place objects on, and can be a predefined object or a completely new object, including textures and transformations, eg:

#declare VegeObject = object{MyHeightField scale .007}
#declare VegeObject = cylinder{ y*3, y*17, 2.71828 pigment{ rgb<3,.14,15> }}

Note: the Object Placement include file will not place a copy of this object in your scene.
Any POV-Ray object can be used, including CSG objects and triangle meshes.
Declaring this parameter is required.

VegeNumber

This is the number of objects to place on the VegeObject. The default is 100.

#declare VegeNumber = 299792458; //Note: this will take almost forever to generate

VegeMinBox and VegeMaxBox

These are two-dimensional vectors defining the boundaries for placing objects. The default box is <0,0> to <1,1>. The meaning of these vectors depends on the direction of the sky vector as follows:

Sky Vector	Order of Coordinates
y (normal)	<x,z>
x	<y,z>
z	<x,y>

Example:

#declare VegeMinBox = <2,17>;
#declare VegeMaxBox = <3+clock*4,18>; //The box increases as time passes.

VegeList

This is an array of objects that contains the objects to place. When Vegetate places an object, it will choose the object from this list.

#declare VegeList = array[3] //3 different objects to choose from
#declare VegeList[0] = object{DeadFly}
#declare VegeList[1] = object{BirdSplat}
#declare VegeList[2] = cylinder{y*1,y*7,8.31 texture{Sky03}}

The default object is a very simple pine tree one unit high.

Note: the objects in this list should have their bases at the origin in order for random rotation and scaling to work.

VegeRotate

Turn random rotation of objects around the sky vector on or off (default on).

#declare VegeRotate = off;

VegeAlign

Turn alignment of objects to the surface normal on or off (default off).

#declare VegeAlign = on;

VegeWaterLevel

The altitude below which Vegetate will not place objects. Usually used to keep Vegetate from placing submerged trees and similar things. Default: no minimum altitude.

#declare VegeWaterLevel = 4.0026;

VegeTimberLine

The altitude above which Vegetate will not place objects. Usually used to keep Vegetate from placing plants on glaciers and similar things. Default: no minimum altitude.

#declare VegeTimberLine = 1840;

Note: If the value specified for VegeTimberLine is less than the value of VegeWaterLevel, an error will occur because you have eliminated all possible locations to place objects.

VegeMaxSlope

If the slope of the object in degrees at the point that Vegetate tries to place something at is greater than this value, Vegetate will find another place to put the item. Useful for keeping Vegetate from placing things on cliffs. If not specified, slope will not be a limiting factor in object placement.

#declare VegeMaxSlope = 90; //Only exclude vertical walls

VegeMaxScale and VegeMinScale

The maximum and minimum random scaling factors used for scaling objects. Both default to 1 (no scaling). Note: Because of the way that scaling works, the random scaling is currently biased towards making objects larger. I am working on a fix for this.

#declare VegeMaxScale = 3; //Objects will not be made more than 3 times their original size
#declare VegeMinScale = .5; //or less than half their original size

Advanced Options

VegeHeight

This is the height along the sky vector to fire 'trace' rays from. The default value of 1,000,000 will work for most situations, but if the VegeObject is exceptionally large, you may need to increase this.

VegeSeed

This is the random seed to use for placing objects. The main reason to change this from the default of 1 is if you want to get a different arrangement of objects.

VegePosGauss

If this variable is set to true, objects will be positioned with a Gaussian distribution -- that is, they will tend to be placed towards the middle of the specified placement box.

VegeTypesGauss

If this variable is set to true, objects will be selected based on a Gaussian distribution -- that is, objects in the middle of the object list will tend to be selected more often than objects towards the start or end of the list.

SkyVector

This is the direction of 'up'. It is the direction that 'trace' rays are fired from, and the vector that objects are rotated around. It can be different from the 'sky' or 'up' parameters in the current camera definition, but must be parallel to one of the coordinate axes.

#declare SkyVector = -x; //Ok
#declare SkyVector = z; //Useful for scenes created in Moray
#declare SkyVector = <1,.32,7.6>; //Won't work

VegeCollide

Turns collision detection on or off, eg:

#declare VegeCollide = on; //or true, or yes

The default is off.

Note: The time taken for collision detection increases as the square of the number of objects, meaning that doubling the number of objects will more than quadruple the time needed to place the objects. Also, it is possible that when placing a large number of objects in a small area, Vegetate will be unable to place all the objects and will get stuck in an infinite loop, so use collision detection with care. Also, to save time, the collision detection routine does not take random scaling of the objects into account.

VegeRadius

The collision detection routine and exclusion routines assume that all objects in the VegeList array are approximately cylindrical and the same size. The value specified for VegeRadius determines that size. The default is one POV-Ray unit.

#declare VegeRadius = 6.02e23;

VegeExcludeHeight

An optional one-dimensional array of heights that Vegetate should not place objects at. For example, if you have a flat area on a heightfield at height 7 that you don't want objects placed on (you plan on putting a road there, and a tree in the middle of the road would look funny):

#declare VegeExcludeHeight = array[1]
#declare VegeExcludeHeight[0] = 7;

VegeExcludeCircle

An optional list of circular regions that Vegetate should not put objects in. The list is a n by 2 dimensional array of 2D vectors, with the first vector being the location of the region and the second being the radius of the region, eg:

#declare VegeExcludeCircle = array[1][2] //Replace 1 with the number of circles in the array
#declare VegeExcludeCircle[0][0] = <5,5>; //Region is centered at 5,5
#declare VegeExcludeCircle[0][1] = <2,2>; //Radius is 2.

VegeExcludeBox

An optional list of rectangular regions that Vegetate should not place objects in. The list is a n by 2 dimensional array of 2D vectors defining the corners of the regions, eg:

#declare VegeExcludeBox = array[1]
#declare VegeExcludeBox[0][1] = <5,5>;
#declare VegeExcludeBox[0][0] = <7,3>; //The order in which the corners are specified does not matter

Verbose

Defining this variable turns the display of an enormous amount of debugging data on, but slows parsing down a little. Use it if you want to see, for example, that Vegetate really is making progress placing all five zillion individual blades of grass on your model of the Great Plains.

#declare Verbose = 8.314510; //Any value at all will do, even zero

COPYRIGHT AND LEGAL INFORMATION

The Vegetation Object Placement Include File, including Vegetate.inc, all documentation, and associated sample *.POV files are Copyright 1999 by Mark Wagner. Full permission is granted to the user to modify any or all of the files for his/her own use. If modified versions are to be distributed the user should make clear the modifications that have been made by him/herself.

The Vegetation Object Placement Include File may be bundled with or without other software on CD-ROM collections, Bulletin Board systems and other file archives, providing that all associated files, including documentation and samples, are included. I would also request that persons intending to distribute the Vegetation Object Placement Include File in this manner or otherwise would first contact me to ensure that they are in possession of the latest available version.

Further, no restrictions of any sort are placed on the usage of the include file itself (Vegetate.inc), and scene files or images created using the include file remain entirely the property of the user or users who have created them. I claim no liability or responsibility for damages or loss resulting from usage of the include file, or any part of the include file package.

CONTACTING THE AUTHOR

If you wish to contact me with bug reports, bug fixes, criticisms, comments, suggested improvements, questions, etc. you can reach me by email at:

rengaw03@yahoo.com

POV-Ray^TM and Persistence of Vision^TM are registered trademarks of the POV-Ray Team^TM