Auto Exposure

When rendering a phyically based scene it is typically necessary to tonemap the results as the lighting units are usually well above the 0 to 1 range that is representable in an LDR image (like jpeg or png). In Iray this is often done using the Photographic Tonemapper by setting the tm_tonemapper attribute on the camera to mia_exposure_photographic.

This tonemapper then needs to be configured by setting f number, iso and shutter speeds just like an SLR camera. And just like an SLR camera this can be tricky and a trial and error process for the normal user.

The falsecolor render loop handler improves on this situation by adding an auto expose feature, just like compact and SLR cameras have. When an auto expose is triggered a small HDR image is rendered and analyzed to calculate appropriate tonemapping settings (f number and shutter speed) to produce a well exposed image. The results of this can either be returned to the user or automatically set on the scene camera to be used in subsequent renders.

Auto exposure is controlled via attributes on the scene's camera. A request is made by setting a request ID and parameter attributes on the camera and responses are read from attributes on the camera once the auto expose is complete.

Triggering requests and receiving results

As performing an auto exposure is an asynchronous process a mechanism is needed to trigger the exposure and then discover when it is completed. This is done by using the attributes ae_request and ae_response on the scene camera. These attributes are numeric ids that are used to detect when to perform an auto exposure and when the results are available.

To perform an auto expose simply set a value on the ae_request attribute. Before the render handler performs the next render it will check the value of this attribute, and if it has changed an auto expose will be performed.

Once the auto expose has been completed the handler sets the ae_response attribute to be the same as ae_request. The user should use element_get_attribute to poll for the value of this attribute, and when it matches the request value used, the auto expose results can be read off the camera.

Example: Trigger an auto exposure

let auto_expose_request = 0;

auto_expose_request++;
send_realityserver_command(
    {
        "method": "element_set_attribute",
        "params": {
            "element_name": "my_camera",
            "attribute_name: "ae_request",
            "attribute_value": auto_expose_request,
            "attribute_type": "Sint32",
            "create": true
        }
    }
);

Example: Poll for the result

let auto_expose_response = send_realityserver_command({
            "method": "element_get_attribute",
            "params": {
                "element_name": "my_camera",
                "attribute_name: "ae_response"
            }
        }
    );
while (auto_expose_response !== auto_expose_request) {
    sleep(5); // wait 5 seconds then poll again
    auto_expose_response = send_realityserver_command({
            "method": "element_get_attribute",
            "params": {
                "element_name": "my_camera",
                "attribute_name: "ae_response"
            }
        }
    );
}
// auto expose is complete, the results can now be fetched off the camera if required.

Auto exposure settings

Auto exposure calculation is controlled via various attributes on the scene camera.

Example: Trigger an auto exposure with settings and automatically sets the photographic tonemapper values

auto_expose_request++;
send_realityserver_command(
    {
        "method": "element_set_attributes",
        "params": {
            "element_name": "my_camera",
            "attributes": {
                "ae_request": {
                    "value": auto_expose_request,
                    "type": "Sint32"
                },
                "ae_metering_mode": {
                    "value": "spot",
                    "type": "String"
                },
                "ae_exposure_compensation": {
                    "value": 0,
                    "type": "Float32"
                },
                "ae_resolution_x": {
                    "value": 30,
                    "type": "Sint32"
                },
                "ae_resolution_y": {
                    "value": 30,
                    "type": "Sint32"
                },
                "ae_set_onto_camera": {
                    "value": 2,
                    "type": "Sint32"
                }
            }
            "create": true
        }    
    }
);

Auto exposure results

Once complete the following attributes are set on the scene camera to provide the results.

Changing Tonemapper

By default, after performing an auto exposure the tm_tonemapper will be set back to it's previous value. However it is often useful to use the auto exposure to calculate initial values for a given tonemapper when switching to that tonemapper. For example you may want to enable the false color tonemapper and use auto exposure to calculate sensible initial values. The typical workflow for this would be:

// trigger auto exposure and set the falsecolor tonemapping attributes
auto_expose_request++;
send_realityserver_command(
    {
        "method": "element_set_attributes",
        "params": {
            "element_name": "my_camera",
            "attributes": {
                "ae_request": {
                    "value": auto_expose_request,
                    "type": "Sint32"
                },
                "ae_set_onto_camera": {
                    "value": 1,
                    "type": "Sint32"
                }
            }
            "create": true
        }    
    }
);
// wait until complete 
let auto_expose_response = send_realityserver_command({
            "method": "element_get_attribute",
            "params": {
                "element_name": "my_camera",
                "attribute_name: "ae_response"
            }
        }
    );
while (auto_expose_response !== auto_expose_request) {
    sleep(5); // wait 5 seconds then poll again
    auto_expose_response = send_realityserver_command({
            "method": "element_get_attribute",
            "params": {
                "element_name": "my_camera",
                "attribute_name: "ae_response"
            }
        }
    );
}
// tonemapping attributes will now be set, activate the tonemapper
send_realityserver_command(
    {
        "method": "element_set_attribute",
        "params": {
            "element_name": "my_camera",
            "attribute_name":  "tm_tonemapper",
            "attribute_value": "falsecolor",
             "attribute_type": "String",
            "create": true
        }    
    }
); 

While this system works it involves (potentially) many roundtrips to check for completion and delays the activation of the tonemapper

As a convenience the auto exposure system supports the ae_tonemapper attribute. If this attribute exists, then after tonemapping it's value is transferred to the tm_tonemapper to activate the new tonemapper. ae_tonemapper is then deleted to ensure it isn't applied again the next time an auto expose occurs.

The above example can now be simply performed as:

// trigger auto exposure and set the falsecolor tonemapping attributes
// once auto expose is complete activate the falsecolor tonemapper.
auto_expose_request++;
send_realityserver_command(
    {
        "method": "element_set_attributes",
        "params": {
            "element_name": "my_camera",
            "attributes": {
                "ae_request": {
                    "value": auto_expose_request,
                    "type": "Sint32"
                },
                "ae_set_onto_camera": {
                    "value": 1,
                    "type": "Sint32"
                },
                "ae_tonemapper": {
                    "value": "falsecolor",
                    "type": "String"
                }
            }
            "create": true
        }    
    }
);