# The Camera File

The camera model used in RenderWorld is relatively simple. It is fundamentally a pin-hole camera with a rectangular array of pixels. Presently there is no capability to generate lens flares or focusing. Lines 2 through 5 of the camera file define the field of view and resolution of the camera. In this example, the output images will be 640 pixels across by 480 pixels tall and will cover a 48 by 36 degree patch of the world.

           RenderWorld_data_file camera 1 1
           n_pixel_x 640
           n_pixel_y 480
           fov_x 48
           fov_y 36
           image_method 1
           picture_fraction_flag 0
           n_sub_x 1
           n_sub_y 1
           number_of_bands 3
           band_id 1 2 3
           mem 1
           format rgb
           scaling gamma 0.45
           min_rescale 0.6
           max_rescale 13.3
           end

The next modifiable parameter is the `picture_fraction_flag`, which allows for rendering only part of the image. If the `picture_fraction_flag` is set to `1`, two more lines must be placed after it:

           RenderWorld_data_file camera 1 1
           n_pixel_x 640
           n_pixel_y 480
           fov_x 48
           fov_y 36
           image_method 1
           picture_fraction_flag 1
           range_x  0 50
           range_y  0 479
           n_sub_x 1
           n_sub_y 1
           number_of_bands 3
           band_id 1 2 3
           mem 1
           format rgb
           scaling gamma 0.45
           min_rescale 0.6
           max_rescale 13.3
           end

Examine the differences between the two example camera files above. The first images the entire frame, while the second images just the leftmost 51 (pixels 0 through 50) pixels. The origin is in the lower-left-hand corner. Note that pixels are numbered from 0 to N-1 when the image is N pixels wide.

When rendering high resolution images, the memory needed just to store all the color bands and other buffers internally can become very large (each pixel requires about 50 bytes for a three color image) For example, a 2048 by 1556 image would require about 152 Mbytes. The next user modifiable line in the code, `mem`, allows you to split the image into pieces to get around this limitation. For example, a value of 5 on this line will split the image up into 5 pieces, rendering each one separately. This reduces the memory required for color buffers by a factor of 5. The downside is that there is a small loss of computational efficiency, so this number should be kept reasonably small. As each image piece is completed, it is written to disk in a temporary image file. After all of the pieces have been created, the full frame is assembled and the temporary pieces are deleted. There are additional options for rendering segments of the image described in the section on Launching the Rendering Engine.

The last three lines before the `end` of the camera file specify the image format and (when necessary) scaling from scientific units to 8-bit/channel RGB. When using the format choice `rgb`, images are output with the Silicon Graphics 8-bit/channel RGB format. The three choices for scaling are `no`, `log` , and `gamma`. Note that `gamma` has an additional parameter on the same line for the gamma value. For all three choices, the two lines following `format rgb` specify the range (minimum and maximum) for the scaling. When the two lines of scaling parameters are omitted, the image minimum and maximum are used. For the choice `no`, reasonable values for `min` and `max` are typically 0 and 300-500. `Log` scaling takes the log (base 10) of the image before scaling between `min` and `max`. Reasonable values for `min` and `max` are -0.5 and 2.5. `gamma` scaling raises the radiance to a power before scaling between `min` and `max`. Reasonable values for `min` and `max` depend upon the power chosen, but the number shown in the example file (`power = 0.45, min = 0.6, max = 13.3`) are a good starting point.

           RenderWorld_data_file camera 1 1
           n_pixel_x 640
           n_pixel_y 480
           fov_x 48
           fov_y 36
           image_method 1
           picture_fraction_flag 1
           subsection_x 0 50
           subsection_y 0 479
           n_sub_x 1
           n_sub_y 1
           number_of_bands 3
           band_id 1 2 3
           mem 1
           format hdf
           end

The second camera file example specifies the `format hdf`. This format uses the Hierarchical Data Format (hdf) routines maintained by the National Center for Supercomputing Applications (NCSA). In this format the images are stored as IEEE 32-bit/pixel/channel floating point numbers. Whereas integer-based formats lose information that RenderWorld provides, `hdf` holds the rendered frames with all the fidelity generated by the rendering engine. This is useful as a lossless intermediate format which allows the user to convert to many other formats, color spaces, bit depths, and gamma settings using separate stand-alone conversion routines.

### The Bobbing Camera

An interesting variation on the camera is the bobbing camera. This camera bounces around in response to the ocean waves directly under the camera. The bobbing camera is imagined to be on the end of a mast on a square raft. As waves role by, the raft pitches around as well as rising and falling. The size of the raft and the length of the mast are user definable. A smaller raft tilts around more, a larger raft is more stable. The length of the mast is just the altitude of the camera, which is determined by the camera's path in the scene file. The horizontal position of the bobbing camera specified in the key frame data in the scene file is the horizontal position of the center of the rectangular raft. Thus the raft can move along the ocean surface and the camera ride up and down on the imagined mast through the key frame data.

#### The Bobbing Camera File

To use a bobbing camera instead of a normal camera, change `type: camera` to `type: bobbing_camera` in the scene file. You also need to make a few changes to the camera file itself. If you look at the example bobbing camera file, you will see that it is identical to a camera file, except for 5 additional lines at the end of the file. Two of these have user modifiable quantities.

           RenderWorld_data_file camera 1 1
           n_pixel_x 640
           n_pixel_y 480
           fov_x 48
           fov_y 36
           image_method 1
           picture_fraction_flag 0
           n_sub_x 1
           n_sub_y 1
           number_of_bands 3
           band_id 1 2 3
           mem 1
           format rgb
           scaling gamma 0.45
           min_rescale 0.6
           max_rescale 13.3
           end
           RenderWorld_data_file bobbing_camera 1 1
           bobbing_height_threshold 500
           not_used 0
           base_length_meters 4
           end

The first, `bobbing_height_threshold` simply sets a maximum altitude for bobbing. In the example, if the camera has an altitude over 500 meters, it doesn't bob. Below 500 meters it does. Generally you may want to set this to a large number so that the camera always bobs.

The second parameter, `base_length_meters` is the length of the sides of the raft in meters. This is effectively a control of how much the camera swings around. Increase the number for less violent swings.

### Explicit Antialiasing

The individual object types in RenderWorld render using algorithms which antialias them automatically. When two objects intersect however, the intersection boundary must be antialiased by oversampling the image pixels on the boundary. In the `1 1` version of the camera file, this can be accomplished using the `n_sub_x` and `n_sub_y` parameters to explicitly oversample the entire image. However, a more efficient implementation is available in the version `2 2` camera file to allow you to oversample only the pixels on the intersection. A sample file is:

           RenderWorld_data_file camera 2 2
           n_pixel_x 640
           n_pixel_y 480
           fov_x 48
           fov_y 36
           image_method 1
           picture_fraction_flag 0
           n_sub_x 1
           n_sub_y 1
           number_of_bands 3
           band_id 1 2 3
           antialias 1
           n_sub_x 2
           n_sub_x 2
           mem 1
           format rgb
           scaling gamma 0.45
           min_rescale 0.6
           max_rescale 13.3
           end
           end

The `n_sub_x` and `n_sub_y` after the `antialias` flag specify the degree of oversampling performed on the pixels on the object-intersection boundary. If you wish to use this camera version but not antialias, choose `0` for the antialias flag, and omit the two lines after it.

Contents