Object Library Editor

Introduction

Forester does not render scenes itself - instead it creates a scripted scene file for POV-Ray, which perform the actual ray-tracing calculations. All of the Objects that Forester places on the landscape have to be pre-written in POV-Ray - Forester simply manipulates the objects location, rotation and scale to position it in the right place.

Forester does not really know what the objects are that it is positioning (it cannot read POV-Ray files or any other 3D file format). It relies on the user to provide basic information about the object - its name, default size, etc. These parameters are set using the Object Library Editor.

NOTE: To generate new Objects for use in Forester, some knowledge of the POV-Ray scene language is essential. Beginners should start by reading the Help files that come with POV-Ray, which also contains a good tutorial.

The rest of this page assumes that the reader has a basic working knowledge of the POV-Ray scene language.

 

Creating Objects

How Does Forester Position the Objects?

Forester generates a POV-Ray scene file (*.pov) which contains information about the terrain, camera, lighting and all objects in the scene. Each object has its own POV-Ray 'include' file (*.inc) which contains POV-Ray definitions for all the components that make up that particular object.

Forester begins the POV-Ray scene file with a standard 'header', which gives the camera, lighting and fog/haze definitions. Then follows a 'Heightfield' object, which uses a Targa image file (automatically created by Forester) to generate the terrain. If there are clouds or a water level present, then these are also included.

After the header follows a list of all the relevant object 'include' files - these essentially tell POV-Ray to read the individual objects definitions from their respective files (which are located in the Forester\Libraries folder). At this point a POV-Ray string variable is set for each object, containing the folder that that objects .INC file is stored in. This allows a certain amount of folder independency - the object .INC file can then use this variable to reference any further files that are required (eg: graphics images or texture files).

Finally, there is the actual object list itself, which gives the location, rotation and scale of each individual object to be included in the final scene.

Each object is made up from one or more separate components, which must each be '#declared' in the objects *.INC file. Components can be set to appear in the scene depending on the distance of the object from the viewer. Forester calculates the 'pixel size' of the object on the final image, and selects any components that have been set to appear at this size. In this way, simpler versions of objects can be selected if they will only be very small in the final image, allowing a far higher overall number of objects to be positioned in the scene.

Each component is placed in the scene using the following POV-Ray code:

object { Component_Name
  scale { def_Scale }
  rotate { def_Rotation }
  translate { def_Translation }
  material { Material_Name }
  scale { scene_Scale }
  rotate { scene_Rotation }
  translate { scene_Translation }
  }

- Component_Name is the name of the relevant component in the Objects .INC file.

- def_Scale, def_Rotation and def_Translation are set in the Object Library Editor. These are default transformations that are applied to each component. They allow any adjustments to be made to the object to change its coordinate system into the correct orientation/scale as Forester. Note: Forester (and Terragen) use a Z-up coordinate system (Right Handed). However, the POV-Ray scripts that Forester produces use a Y-up coordinate system (Left Handed). Therefore all Object definitions in the *.INC files should use the Y-up system. Alternatively, the def_Rotation for a Right Handed object can be set to -90x (ie -90 degrees around the x-axis) and def_Scale to -y to convert it to a Left Handed system.

- Material_Name is not always present. Objects can be defined with or without material definitions. If they include material definitions, then for each component with a material, there must also be a duplicate one with a 'red only' material for creating the object masks (more on this later). If the objects do not include materials, then Forester will add them with this command (which also eliminates the need for duplicate red objects).

- scene_Scale, scene_Rotation and scene_Translation are the three final transformations that Forester uses to locate the object on the landscape.

'Red' Objects

When rendering images to merge with Terragen, the Objects Mask and Shadows Mask require all objects in POV-Ray must be rendered in a pure red colour. The POV-Ray texture required to achieve this is defined by the following script:

  texture { 
    pigment { color rgb <1.0, 0.0, 0.0> } 
    finish { diffuse 1.0 ambient 0.0 brilliance 0.0 } 
    } 

Scale

Forester does not use a fixed scale for its images - it is the camera position, atmospheric effects and terrain texture that give the feeling of size. However, since Forester is designed to work with objects whose size we are already familiar with, eg trees, aircraft, etc,  a base scale is useful to ensure that all objects are created in proportion to one another. I have therefore chosen a scale of 10m:1unit. All objects that you create should be sized such that when placed on the landscape without any further scaling, one Forester unit should roughly equal 10 metres in reality.

Controlling POV-Ray Objects from Forester

When rendering each scene, frame or motion blur still, Forester inserts a number of variables into the POV-Ray scene, which object definitions can use to control various attributes, eg variables to time animations, or to select specific colour schemes (for different seasons), etc. The variables are as follows:

Forester_RedObjects

Is either true or false. Used by the object definition to choose whether to use the bright red colour for creating the masks for compositing with terragen, or to use normal materials and textures.

Forester_Animation

Is either true or false, depending whether the current scene is part of an animation.

Forester_Frame

Holds the current animation frame number. Can be used for controlling animated objects - although this is not recommended (better to use Forester_Time instead)

Forester_Time

Holds the current animation time, which can be used for controlling time-dependant animated objects. This value is independent of the animations FPS (frames per second), and holds the precise time for the current frame or motion blur still.

Forester_Season

Integer flag to define the current season. Spring = 0, Summer = 1, Autumn = 2, Winter = 3. For example, a simple POV-Ray 'if then else...' statement can be used to define a different colour pigment or image map file for winter or summer (ie: snow or no snow).

Forester_CamAngle

This holds the current horizontal viewing angle of the camera

Forester_CamFocus

This holds the current camera focusing distance (used by  Focal Blur)

Forester_CamAperture

This holds the current camera aperture (used by Focal Blur). NOTE: This value is not the same as that in the Forester Camera Window - Forester performs a calculation based on lens Focal Length and Aperture to arrive at this figure)

Forester_CamPitch

This holds the current camera Pitch value

Forester_CamHeading

This holds the current camera Heading value

Forester_CamRoll

This holds the current camera Roll value (Bank)

Forester_CamLocation

This VECTOR holds the current camera location

Forester_AllRedMaterial

This defines a POV-Ray Material with the correct bright red colour required for the composition masks.

Forester_AllRedTexture

This defines a POV-Ray Texture with the correct bright red colour required for the composition masks.

Examples

The best way to demonstrate the Object Library Editor is by tutorial. There follows two examples - the first uses the preset materials supplied with Forester (which are currently very limited). The second is a more complex example that takes advantage of some of the animation variables mentioned above.

Simple Example

We will create a simple object that will have two 'levels of detail'. There are four steps to this process:

  1. Create a blank folder in the Libraries\ObjectType directory
  2. Create the POV-Ray .INI file that holds the definitions for the object components
  3. Create a new object in Forester and add its components
  4. Define the objects default size and bounding box

Create the directory

In Windows Explorer create a new directory in the Libraries\Misc folder called TestObject1. All files pertaining to this object will be stored in this folder. TestObject1 will be the name of the object in Forester.

NOTE: The sub-folder of the Libraries directory defines which object category the object falls under (eg: Aircraft, Trees, Misc, etc)

Create the POV-Ray .INI file

Using POV-Ray or Notepad, type the following two object definitions and save the file in the above folder as TestObject1.INC (ie: Libraries\Misc\TestObject1\TestObject.INC)

#declare testobject1_ball = sphere {<0,0,0>,0.5}
#declare testobject1_cube = box { < -0.5, -0.5 ,-0.5 >, <0.5, 0.5, 0.5 > }

Create the Forester Object and Components

Open the Object Library Editor in Forester. Click the Miscellaneous group heading in the Object Tree and click Add Object. Enter the name as TestObject1. The new object definition will be created and added to the Miscellaneous group. Expand this object in the Tree (click the + sign next to TestObject1) and select its first component (called Blank).

Rename this component 'Cube'. Set the minimum pixel size to 0 and the maximum pixel size to 30. This tells Forester that this component should be included in the object (and the scene) if the total object size in the scene falls between zero and 30 pixels (measured across the diagonal of the objects bounding box).

Ensure that the 'Where are the Materials Specified?' option is set to 'Within a separate .INC file'.

From the Object .INC File drop-down list, select the TestObject1.inc file (Note that the list contains all the .INC files in the folder created above). Click the Read button - Forester searches through the selected file looking for all POV-Ray #declare statements with which to 'populate' the Object Name listbox. Select testobject1_cube from this listbox.

From the Material .INC file list, select the default_materials_metals.inc and click the 'Read' button. Select one of the metal materials from the Materials list, eg: mat_steel.

OK, that's the first component created. Now for the second. Click the Add Component button and select this new component from the Object Tree. Change its name to 'Ball' and set its minimum pixel size to 30 and maximum to 0 (Forester regards a maximum pixel size of zero as actually meaning infinity). Set the 'Where are the Materials Specified?' to 'Within a separate .INC file'. As before select the TestObject1.inc file from the Object .INC File list and click Read. Set the Object Name to testobject1_ball.

From the Material .INC file list, select the default_materials_metals.inc and click the 'Read' button. Select one of the metal materials from the Materials list, eg: mat_gold.

That's the component definition completed.

Define Default Size and Bounding Box

Select the TestObject1 item in the Object Tree - the Whole Object parameter pane is re-displayed.

Set the translation to 0, 0, 0.5 - this ensures that the objects will 'sit' on the terrain (and not appear half inside it). Leave the scale at 1,1,1 - the objects default size is also 1x1x1, which translates to be roughly 10 metres in size on the terrain, assuming that the terrain scale is 10 metres per unit.

Set the Bounding Box Size to 1, 1, 1 and the bounding box origin to 0, 0, 0.5.

NOTE: The bounding box should just enclose the object. The bounding box origin can be used along with the bounding box size to position the box over the object. NOTE: The DirectX preview window uses these parameters when displaying the objects on the terrain. If the objects always seem to appear slightly offset in the POV-Ray render than in the DirectX preview, it is more than likely to be due to incorrect bounding box origin parameters.

Click the Preview button to view the finished object. It can now be used in all Forester scenes. You'll notice that when it is a long way away in a scene it will be a cube and when it is closer up it will be a sphere. This demonstrates the 'level of detail' effect that Forester uses. Obviously when creating your own objects, use shapes that look similar, but have more detail at the higher pixel sizes.

 

Complex Example

This second example is slightly more complicated. The object .INC file contains its own materials, one of which uses a graphics file as a texture pigment. The model is a childs spinning top toy, which takes advantage of the animation variables to control its spin. Although this is not a particularly useful object to have in a landscape generating program, it does help to demonstrate the principles for creating and animating objects. There are 5 steps to the process:

  1. Create a blank folder in the Libraries\ObjectType directory
  2. Create the POV-Ray .INI file that holds the definitions for the object components and their Materials
  3. Create a picture in a graphics package to use as a texture pigment
  4. Create a new object in Forester and add its components
  5. Define the objects default size, bounding box and object Folder Variable

Create the directory

In Windows Explorer create a new directory in the Libraries\Misc folder called SpinningTop1. All files pertaining to this object will be stored in this folder. SpinningTop1 will also be the name of the object in Forester.

Create the POV-Ray .INI file

Using POV-Ray or Notepad, type the following POV-Ray code (or copy and paste it from here) and save the file in the above folder as SpinningTop1.INC (ie: Libraries\Misc\SpinningTop1\SpinningTop1.INC). Note that the code has comments (//) explaining the various sections.

// Test Forester_RedObjects variable
// If true then use the preset Forester_AllRedTexure
// otherwise define the proper texture

#if (Forester_RedObjects=true)  
  #declare spinningtop1.texture = Forester_AllRedTexture
#else  
  #declare spinningtop1_texture = 
    texture {
      pigment {
        image_map {            

          // Use the concat() command to locate the folder where
          // the objects is stored, and to use that path to 
          // load the PNG image file.

          png concat( SpinningTop1_Folder ,"pigment.png")
          map_type 2
          interpolate 2
          }
        scale <1,12,1>
        }
      normal { dents 0.3 }
      finish {
        ambient 0.4
        diffuse 1.5
        brilliance 0.5
        specular 1
        roughness 0.1
        reflection 0.3
        }
      }     
#end
                                
// Define the shape for the spinning top.
// This example uses the surface of revolution object
// but this could be any object type, eg Mesh, Cylinder, etc)

#declare spinningtop1_top =
  sor { 11, 
    < 0, -1>
    < 0, 0 >
    < 2, 4 >
    < 3, 5 >
    < 5, 7 >
    < 4, 8 >
    < 2, 9 >
    < 1, 10>
    < 2, 11>
    < 0, 12>
    < 0, 12>
    sturm
    }       
      
// Define the object identifer that will be called from Forester
// along with its texture and the rotations to animate the top

#declare spinningtop1_main =
  object {
    spinningtop1_top
    texture { spinningtop1_texture }
    
    // Spin the object around the y axis
    // (Remember that POV-Ray uses the z-up left hand coordinate
    // system - Forester uses the z-up right hand system)
    // This formula makes the top spin 10 times every second
    // 360 degrees = one full rotation
    // *10 =  ten full rotations
    // *Forester_Time = per second
    
    rotate y*360*10*Forester_Time
    
    // Tilt the object 20 degrees around the x axis
    // and then spin it a bit more slowly
    // (once every four seconds)
    
    rotate <20,0.25*360*Forester_Time,0>
    }

Create a Picture to use as a Texture

Using a graphics package (eg: Paint Shop Pro, PhotoShop, etc) create or convert a picture and save it as SpinningTop1Image.PNG in the above folder. NOTE: The POV-Ray code assumes that the image will be in PNG format - you can also use GIF, TGA or BMP formats, but the POV-Ray png command will need to be replaced with the commands gif, tga, or sys respectively.

Create the Forester Object and Components

Open the Object Library Editor in Forester. Click the Miscellaneous group heading in the Object Tree and click Add Object. Enter the name as SpinningTop1. The new object definition will be created and added to the Miscellaneous group. Expand this object in the Tree (click the + sign next to TestObject1) and select the first component (called Blank).

Rename this component 'Top'. Leave the minimum and maximum pixel size at 0 (for simplicity this object will only have one level of detail).

Ensure that the 'Where are the Materials Specified?' option is set to 'Within the POV Object .INC file'.

From the Object .INC File drop-down list, select the SpinningTop1.inc file and click the Read button. Select spinningtop1_main from the Object Name listbox. Also select spinningtop1_main from the Red Version list. Because the SpinningTop1.INC file automatically select the correct texture as determined from the Forester_RedObjects variable, Forester can use the same object when generating the Object Mask files.

That's the component definition completed.

Define Default Size, Bounding Box and Object Folder Variable

Select the SpinningTop1item in the Object Tree - the Whole Object parameter pane is re-displayed.

Set the Bounding Box Size to 10, 10, 12 and the bounding box origin to 0, 0, 6. (This is a very large object - it could be scaled down using the Scale parameters, but as it is only a demonstration we needn't bother).

Set the POV-Ray Folder Identifier to SpinningTop1_Folder. Whenever Forester generates a scene that uses this particular object it will define a variable (called an Identifier in POV-Ray) with this name containing the folder path of this object. This can then be used by the objects .INI file to reference any further files that it needs (in this case it needs a graphics file for the pigment of the spinning top). Note that this variable contains the final back-slash (\) of the folder name. The POV-Ray concat() command can then be used to assemble the file and folder path, eg: png concat( SpinningTop1_Folder ,"pigment.png").

Finished Spinning Top

This image is part of a simple
animation using the object.
Notice that the spinning effect
is easily visible when using
Motion Blur.

Importing Other File Formats

Perhaps one of the most interesting uses of Forester is in placing your own objects onto the Terragen landscape. Using file converters, it is possible to use many different 3D formats (eg 3DS, DXF, OBJ, etc). NOTE: Forester does NOT have any form of built-in 3D file format converter - this is beyond the current scope of the program, but is something which I am considering for the future. However, there are various freeware or shareware file converters available, 3DWin and CrossRoads to name two.

There are a number of points to bear in mind when converting other file formats: