# Compositing Fields

A variety of information about the 3D environment is computed during rendering. Much of this infomation can be used to perfom compositing operations with other imagery. Pixel maps of information of use for compositing are denoted compositing fields, and may include transmissivity/reflectivity perperties, fractions of pixel filled, distance (z-depth), and other things that depend on the camera and the object.

This list of quantities available as compositing fields for the various objects is as follows:

- Air: `radiance, distance, fraction_filled, path_rad, no_air, transmission, absorption`
- Ocean: `radiance, distance, fraction_filled, sky, glitter, whitecap, reflectance, normal, object_reflected, object_refracted, reflect-objectname, alpha-objectname`
- Sprays/Blobs/Clouds: `radiance, distance, fraction_filled, transmission, absorption`
- Scene: `scene_no_radiance, scene_distance, scene_xyz`

All of the objects (except the scene) have the basic three of `radiance`, `distance`, and `fraction_filled`. `Radiance` is the light emitted by the object unmodified by intervening objects (i.e. no atmospheric effects between the object and camera are applied). `Distance` is the z-depth range between the camera and the primary object in that pixel. The last common parameter, `fraction_filled`, is the fraction of each pixel occupied by that object.

For air, the compositing field `path_rad` is the light emitted by the air along a straight line path from the camera to the first object encountered (other than the air object). The field `no_air` is the entire image with all objects included, but without rendering the air-only portions of the image.

For ocean, the fields `sky`, `glitter`, and `whitecap` contain only the light due to sky reflection, sun reflection, and whitecap emission respectively. The sum of these three and the air `path_rad` gives the complete ocean image for simple cases. The field `reflectance` is the average specular reflectivity of the waves in each pixel, and the typical surface normal for those waves is in the field `normal`. The light from objects reflected from the ocean surface to the camera is in the field `object_reflected`, and if the object light is refracted, it is in the field `object_refracted`. The last two matte fields give information about the reflection of an individual object. The field `reflect-objectname` generates the reflected light of object objectname and the field `alpha_objectname` generates the reflectd alpha channel of object objectname.

For sprays, blobs, and clouds, `transmission` and `absorption` are just the total of those quantites integrated through the volume of the object in the direct the pixel is looking.

The scene compositing fields are only related to distance information. `scene_distance` is the distance from the camera to the nearest non-air object in the scene, whereas `scene_xyz` is the cartesian coordinates of the nearest non-air object in the scene. The third option, `scene_no_radiance`, is actually a flag to suppress the output of the final image.

### Scene File for Composite Fields

Below is a scene file which generates composite fields for various objects. Only those parameters relevant to this discussion have been bolded.

  `RenderWorld_data_file scene 2 2`
  ``
  `output_file` `stuff`
  output_format -`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 30 25`
  `nfile: sun.dat`
  ``
  `number_of_objects 2`
  ``
  `number_of_times 1`
  `time x y z theta phi chi`
  `0 0 0 -6.096 0 0 0`
  `name:` `airabc`
  `type: air`
  `input: air.dat`
  `priority 0`
  ``
  `number_of_times 1`
  `time x y z theta phi chi`
  `0 0.0 0.0 0.0 0 0 0`
  `name:` `oceanabc`
  `type: ocean`
  `input: ocean.dat`
  `priority 10`
  ``
  `Number_of_cameras 1`
  `Number_of_times 1`
  `time x y z theta phi chi`
  `0 0 0 35.9 95 37 0`
  `type: camera`
  `camera_file: camera.dat`
  `use_fields:` `1`
  `Number_of_Objects:` `2`
  `Object:` `airabc`
  `Number_of_Fields:` `5 radiance distance fraction_filled path_rad no_air`
  `Object:` `oceanabc`
  `Number_of_Fields:` `8 radiance distance fraction_filled sky glitter whitecap reflectance normal`
  ``
  `number_of_entries 2`
  `tod_flag 0`
  `frame time`
  `1 0.0`
  `31 1`
  `end`
  ``
  `initial_frame 1`
  `final_frame 1`
  `increment 1`

The first important item is that compositing fields are available only when scene files have the ``2 2'' or later version in the first line. Previous versions of scene input files will not produce compositing fields.

Next, all objects in the object list have an additional field: you must now give each object a unique name, located between the key-time history and the object type line.

For each camera, if you do not wish to generate compositing fields, specify `use_fields:` `0`, and all subsequent Number_of_Objects, `Object` and and `Number_of_Fields` lines are removed.``

When composite fields are desired, `use_fields:` `1` is set. The line after specifies how many of the objects in the object list will have composite fields generated. For each of the `Number_of_Objects` objects, a pair of lines is included. The first line of the pair gives the name of an object. For that object, the `Number_of_Fields` line holds first the number of compositing fields desired, followed by the list of those fields.

Upon output of an image (or a strip of an image), the image file is accompanied by a set of additional output files containing the compositing fields. The file names for these are the same as the image file name with

_<object name>_<object number>_<composite field name>

added before the frame number.

Any of the distance compositing fields can be converted into the equivalent cartesian position of the object at that distance, using the routine

  RWDistance2xyz.out [-fnn [-lnn [-inn]]] [-cnn] scenefile

This routine reads the input files and converts the distance fields to cartesian coordinates. The options are:

-f the first frame number

-l the last frame number

-i the increment on frame number

-c the number of the camera (if more than one is present in the scene file)

The cartesian coordinates appear in a three channel hdf file as float data, in units of meters.

Contents