# The Scene File

An example of a scene file is shown below.

    RenderWorld_data_file scene 2 2
           output_file Ex00
           output_format -b-.-f-
           number_of_bands 3
           band_id wavelength width
           1       0.701      0.158
           2       0.535      0.085
           3       0.473      0.037
           sun_flag 1
           number_of_times 1
           time theta phi
           0    0     0
           nfile: sun.dat
           number_of_objects 1
           number_of_times 1
           time x   y   z theta phi chi
           0    0   0  -1 0     0   0
         	 name: airabc
           type: air
           input: air_clean_flat.dat
           priority 0
           Number_of_cameras 1
           Number_of_times 2
           time x  y  z      theta phi chi
           0    0  0  10     90    0   0
           1    0  0  1010   90    0   0
           type: camera
           camera_file: camera.dat
           usr_fields: 0
           number_of_entries : 2
           tod_flag 0
           frame time
           1     0.00000
           31    1.00000
           end
           initial_frame 1
           final_frame 1
           increment 1

Starting at the top of the scene file and proceeding one line at a time: The first line of the file identifies this as a RenderWorld scene description file and contains some version information. Each input file has a version pattern at the top similar to this line. The versions in each of the input files does not have to be the same as the other input files, i.e. the impact of version information is localized within each file.

The second line specifies the root of the name for the output image files. The format of the image file names is given in the next line, and described in the section Image File Name Convention. The next few lines state that the simulation will be run in three colors and specifies exactly what part of the color spectrum red, green, and blue correspond to.

> RenderWorld is capable of working with any number of bands, limited only by available RAM. The `number_of_bands` specifies the numbers of color bands or wavelengths the user wishes. Any integer larger than 0 can be used. Immediately following is the description of each of the bands, including the `band_id` (which also appears in other input files), the center `wavelength` for the band, and the spectral `width` of the band, with the units of `wavelength` and `width` being microns. Each band has a `band_id` because some objects in the scene may have no optical properties in some bands. Also, multiple cameras can be placed in the scene with each responding only to a subset of the bands. The `band_id` provides a way for RenderWorld to sort out which bands to use for rendering and modeling. In general the `wavelength` can vary over the visible range of the spectrum and maintain good physical models for each of the environmental components.

Following the color band information is the description of the sun. The `sun_flag 1` designates that the sun is present. The option `sun_flag 0` leaves no sun present. Normally you will want a sun in your simulations because all lighting of the environment is dependent on the sun intensity and color. The line `number_of_times 1` means that the sun position will be specified at only one keyframe. The following two lines specify where the sun is at in the sky as a function of physical time (i.e. time in units of seconds). In this case, only one key time line is provided, so the sun is stationary. Specifically, it is located at `theta` = 0, `phi` = 0 (which is straight overhead). Lastly, the file `sun.dat` contains additional information on the sun which is described in a later section.

Next in the scene file is the list and descriptions of the objects in the scene. First we specify that there is 1 object in this scene (the sun and cameras are not counted for this number; cameras are listed separately below). Following that is the description of the first (and in this case, only) object. With the line `number_of_times 1` key frame information for this object will only be provided for one time. There must be at least one key frame line for each object. There is no maximum, but the entries must be listed in order of increasing time. Frames at intermediate times are calculated by linear interpolation of the position and orientation angles in the list.

The specific key frame information for this object is that it is located at a position of (x=0, y=0, z=-1) with no rotations at time 0 seconds. The fact that z is -1 meter instead of zero is important. The atmosphere ends at the z value specified, so if you had an ocean surface with a 2ft trough, there would be a 2ft gap with no air in it. Normally this is not a problem, but in the case of extremely thick fog it can be noticeable. It is therefore advisable to have a negative z value of a meter or two for the air as a precaution.

Each object in the object list must be given a unique `name`, in this case `airabc`. The name can be arbitrary, and is used to create compositing fields discussed in the section ``Compositing Fields''.

Next is the specification of what type this object is. In this case it is air. It could also have been an ocean surface, a box, or something else. After having specified that it is an air object in general, we next specify that the details of this air object are located in the file`air_clean_flat.dat`. Lastly, we specify the priority of this object to be zero. Priority comes into play when two objects overlap each other in space. The object with the higher priority occupies the space and controls the rendering. Thus, we could give our ocean a priority of 10, so that it displaces the air instead of visa versa, and then maybe give a box that is floating in the water a priority of 10.5.

This is the same form followed for the description of all objects (except for the sun and cameras) in RenderWorld scenes. If we had more objects in our scene we would repeat the block of lines from `number_of_times` to `priority` for each of them and adjust the entry on the `number_of_objects` line accordingly.

Now, having completed our list of objects in the scene, we can proceed to list all of the cameras ("all" being 1 in this case) which will be imaging the objects. The format is nearly identical to the listing of the objects. First we tell how many cameras there are, and then provide key frame information, type, and descriptor file for each. Note that in this case the camera is moving, since it has 2 key frame lines. Specifically, it is moving upward at a rate of 1000 meters per second.

The `use_fields` line controls whether compositing fields will be generated for the camera. The value `0` means no compositing fields, and `1` means at least one field is generated. Additional lines inserted after the `use_fields` line determine which compositing fields are generated. See the section Compositing Fields for more information.

The next group of lines specifies the relation between time (in seconds) and frame number. Typically frame 1 corresponds to time zero, but this doesn't have to be. Frame 1 could occur at time 62 seconds or any other time you choose. This section also indirectly specifies frame rate. By placing frame 31 at 1 second, we have established a frame rate of 30 frames/second. For 24Hz we would place frame 25 at 1 second. Lastly note that you can specify different rates of time for different frame ranges to achieve slow motion or fast forward effects.

Lastly, we specify the first and last frame to render and the increment between them. Here we are only imaging frame 1. To image all of the odd frames from 5 to 15, we would enter 5, 15, and 2 on these three lines. These three values may be overridden using command line arguments when the rendering engine is launched. This is discussed in a later section.

Contents