Add exposure controls to UsdGeomCamera

pxr/imaging/hd/camera.cpp

@@ -255,6 +255,41 @@ HdCamera::Sync(HdSceneDelegate * sceneDelegate,
             _exposure = vExposure.Get<float>();
         }
 
+        const VtValue vExposureCompensation =
+            sceneDelegate->GetCameraParamValue(
+                id, HdCameraTokens->exposureCompensation);
+        if (!vExposureCompensation.IsEmpty()) {
+            _exposureCompensation = vExposureCompensation.Get<float>();
+        }
+
+        const VtValue vExposureTime =
+            sceneDelegate->GetCameraParamValue(
+                id, HdCameraTokens->exposureTime);
+        if (!vExposureTime.IsEmpty()) {
+            _exposureTime = vExposureTime.Get<float>();
+        }
+
+        const VtValue vExposureIso =
+            sceneDelegate->GetCameraParamValue(
+                id, HdCameraTokens->exposureIso);
+        if (!vExposureIso.IsEmpty()) {
+            _exposureIso = vExposureIso.Get<float>();
+        }
+
+        const VtValue vExposureFNumber =
+            sceneDelegate->GetCameraParamValue(
+                id, HdCameraTokens->exposureFNumber);
+        if (!vExposureFNumber.IsEmpty()) {
+            _exposureFNumber = vExposureFNumber.Get<float>();
+        }
+
+        const VtValue vExposureResponsivity =
+            sceneDelegate->GetCameraParamValue(
+                id, HdCameraTokens->exposureResponsivity);
+        if (!vExposureResponsivity.IsEmpty()) {
+            _exposureResponsivity = vExposureResponsivity.Get<float>();
+        }
+
         const VtValue vLensDistortionType =
             sceneDelegate->GetCameraParamValue(
                 id, HdCameraTokens->lensDistortionType);

pxr/imaging/hd/camera.h

@@ -74,6 +74,11 @@ PXR_NAMESPACE_OPEN_SCOPE
     (shutterOpen)                                                 \
     (shutterClose)                                                \
     (exposure)                                                    \
+    (exposureTime)                                                \
+    (exposureIso)                                                 \
+    (exposureFNumber)                                             \
+    (exposureResponsivity)                                        \
+    (exposureCompensation)                                        \
                                                                   \
     /* how to match window with different aspect */               \
     (windowPolicy)                                                \
@@ -253,6 +258,11 @@ class HdCamera : public HdSprim
         return _shutterClose;
     }
 
+    /// Get the computed exposure scale from the underlying camera.
+    ///
+    /// Scaling the image brightness by this value will cause the various exposure
+    /// controls on \ref UsdGeomCamera to behave like those of a real camera to 
+    /// control the exposure of the image.
     float GetExposure() const {
         return _exposure;
     }
@@ -330,10 +340,17 @@ class HdCamera : public HdSprim
     float                   _splitDiopterWidth2;
     float                   _splitDiopterFocusDistance2;
 
-    // shutter/lighting
+    // shutter
     double                  _shutterOpen;
     double                  _shutterClose;
+
+    // exposure
     float                   _exposure;
+    float                   _exposureCompensation;
+    float                   _exposureTime;
+    float                   _exposureIso;
+    float                   _exposureFNumber;
+    float                   _exposureResponsivity;
 
     // lens distortion
     TfToken                 _lensDistortionType;

pxr/usd/usdGeom/camera.cpp

@@ -341,6 +341,74 @@ UsdGeomCamera::CreateExposureAttr(VtValue const &defaultValue, bool writeSparsel
                        writeSparsely);
 }
 
+UsdAttribute
+UsdGeomCamera::GetExposureIsoAttr() const
+{
+    return GetPrim().GetAttribute(UsdGeomTokens->exposureIso);
+}
+
+UsdAttribute
+UsdGeomCamera::CreateExposureIsoAttr(VtValue const &defaultValue, bool writeSparsely) const
+{
+    return UsdSchemaBase::_CreateAttr(UsdGeomTokens->exposureIso,
+                       SdfValueTypeNames->Float,
+                       /* custom = */ false,
+                       SdfVariabilityVarying,
+                       defaultValue,
+                       writeSparsely);
+}
+
+UsdAttribute
+UsdGeomCamera::GetExposureTimeAttr() const
+{
+    return GetPrim().GetAttribute(UsdGeomTokens->exposureTime);
+}
+
+UsdAttribute
+UsdGeomCamera::CreateExposureTimeAttr(VtValue const &defaultValue, bool writeSparsely) const
+{
+    return UsdSchemaBase::_CreateAttr(UsdGeomTokens->exposureTime,
+                       SdfValueTypeNames->Float,
+                       /* custom = */ false,
+                       SdfVariabilityVarying,
+                       defaultValue,
+                       writeSparsely);
+}
+
+UsdAttribute
+UsdGeomCamera::GetExposureFNumberAttr() const
+{
+    return GetPrim().GetAttribute(UsdGeomTokens->exposureFNumber);
+}
+
+UsdAttribute
+UsdGeomCamera::CreateExposureFNumberAttr(VtValue const &defaultValue, bool writeSparsely) const
+{
+    return UsdSchemaBase::_CreateAttr(UsdGeomTokens->exposureFNumber,
+                       SdfValueTypeNames->Float,
+                       /* custom = */ false,
+                       SdfVariabilityVarying,
+                       defaultValue,
+                       writeSparsely);
+}
+
+UsdAttribute
+UsdGeomCamera::GetExposureResponsivityAttr() const
+{
+    return GetPrim().GetAttribute(UsdGeomTokens->exposureResponsivity);
+}
+
+UsdAttribute
+UsdGeomCamera::CreateExposureResponsivityAttr(VtValue const &defaultValue, bool writeSparsely) const
+{
+    return UsdSchemaBase::_CreateAttr(UsdGeomTokens->exposureResponsivity,
+                       SdfValueTypeNames->Float,
+                       /* custom = */ false,
+                       SdfVariabilityVarying,
+                       defaultValue,
+                       writeSparsely);
+}
+
 namespace {
 static inline TfTokenVector
 _ConcatenateAttributeNames(const TfTokenVector& left,const TfTokenVector& right)
@@ -372,6 +440,10 @@ UsdGeomCamera::GetSchemaAttributeNames(bool includeInherited)
         UsdGeomTokens->shutterOpen,
         UsdGeomTokens->shutterClose,
         UsdGeomTokens->exposure,
+        UsdGeomTokens->exposureIso,
+        UsdGeomTokens->exposureTime,
+        UsdGeomTokens->exposureFNumber,
+        UsdGeomTokens->exposureResponsivity,
     };
     static TfTokenVector allNames =
         _ConcatenateAttributeNames(
@@ -581,4 +653,23 @@ UsdGeomCamera::SetFromCamera(const GfCamera &camera, const UsdTimeCode &time)
     GetFocusDistanceAttr().Set(camera.GetFocusDistance(), time);
 }
 
+float
+UsdGeomCamera::GetExposureScale(UsdTimeCode time) const 
+{   
+    float exposureTime = 1.0f;
+    float exposureIso = 100.0f;
+    float exposureFNumber = 1.0f;
+    float exposureResponsivity = 1.0f;
+    float exposureCompensation = 0.0f;
+
+    GetExposureTimeAttr().Get(&exposureTime, time);
+    GetExposureIsoAttr().Get(&exposureIso, time);
+    GetExposureFNumberAttr().Get(&exposureFNumber, time);
+    GetExposureResponsivityAttr().Get(&exposureResponsivity, time);
+    GetExposureAttr().Get(&exposureCompensation, time);
+
+    return (exposureTime * exposureIso * powf(2.0f, exposureCompensation) * 
+            exposureResponsivity) / (100.0f * exposureFNumber * exposureFNumber);
+}
+
 PXR_NAMESPACE_CLOSE_SCOPE

pxr/usd/usdGeom/camera.h

@@ -99,6 +99,35 @@ class SdfAssetPath;
 /// However, it follows that if even one property is authored in the correct
 /// scene units, then they all must be.
 /// 
+/// \section UsdGeom_CameraExposure Camera Exposure Model
+/// 
+/// UsdGeomCamera models exposure by a camera in terms of exposure time, ISO,
+/// f-number, and exposure compensation, mirroring the controls on a real camera.
+/// These parameters are provided by \ref UsdGeomCamera::GetExposureTimeAttr(),
+/// \ref UsdGeomCamera::GetExposureIsoAttr(), \ref UsdGeomCamera::GetExposureFNumberAttr(), 
+/// and \ref UsdGeomCamera::GetExposureAttr(), respectively. 
+/// \ref UsdGeomCamera::GetExposureResponsivityAttr() provides an additional scaling
+/// factor to model the overall responsivity of the system, including response of 
+/// the sensor and loss by the lens.
+/// 
+/// The combination of these parameters gives an exposure scaling factor (also 
+/// referred to as the __imaging ratio__) that converts from incident luminance at
+/// the sensor in __nits__, to an output signal based on photometric exposure in 
+/// __lux-seconds__. 
+/// 
+/// The calculated scaling factor can be obtained from 
+/// \ref UsdGeomCamera::GetExposureScale(), which is also the value provided by 
+/// \ref HdCamera::GetExposure(). It is computed as:
+/// \code
+/// exposureScale = 
+/// (exposureTime * exposureIso * pow(2, exposure) * exposureResponsivity) 
+/// / (100 * exposureFNumber * exposureFNumber)
+/// \endcode
+/// 
+/// Renderers should simply multiply the brightness of the image by the exposure 
+/// scale. The default values for the exposure-related attributes combine to give
+/// a multiplier of 1.0.
+/// 
 /// 
 /// \sa \ref UsdGeom_LinAlgBasics
 /// 
@@ -394,7 +423,7 @@ class UsdGeomCamera : public UsdGeomXformable
     // --------------------------------------------------------------------- //
     // FSTOP 
     // --------------------------------------------------------------------- //
-    /// Lens aperture. Defaults to 0.0, which turns off focusing.
+    /// Lens aperture. Defaults to 0.0, which turns off depth of field effects.
     ///
     /// | ||
     /// | -- | -- |
@@ -491,7 +520,7 @@ class UsdGeomCamera : public UsdGeomXformable
     /// Frame relative shutter close time, analogous comments from
     /// shutter:open apply. A value greater or equal to shutter:open
     /// should be authored, otherwise there is no exposure and a
-    /// renderer should produce a black image.
+    /// renderer should produce a black image. Used for motion blur.
     ///
     /// | ||
     /// | -- | -- |
@@ -513,7 +542,7 @@ class UsdGeomCamera : public UsdGeomXformable
     // --------------------------------------------------------------------- //
     // EXPOSURE 
     // --------------------------------------------------------------------- //
-    /// Exposure adjustment, as a log base-2 value.  The default
+    /// Exposure compensation, as a log base-2 value.  The default
     /// of 0.0 has no effect.  A value of 1.0 will double the
     /// image-plane intensities in a rendered image; a value of
     /// -1.0 will halve them.
@@ -534,6 +563,99 @@ class UsdGeomCamera : public UsdGeomXformable
     USDGEOM_API
     UsdAttribute CreateExposureAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
 
+public:
+    // --------------------------------------------------------------------- //
+    // EXPOSUREISO 
+    // --------------------------------------------------------------------- //
+    /// The speed rating of the sensor or film when calculating exposure.
+    /// Higher numbers give a brighter image, lower numbers darker.
+    ///
+    /// | ||
+    /// | -- | -- |
+    /// | Declaration | `float exposure:iso = 100` |
+    /// | C++ Type | float |
+    /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
+    USDGEOM_API
+    UsdAttribute GetExposureIsoAttr() const;
+
+    /// See GetExposureIsoAttr(), and also 
+    /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+    /// If specified, author \p defaultValue as the attribute's default,
+    /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+    /// the default for \p writeSparsely is \c false.
+    USDGEOM_API
+    UsdAttribute CreateExposureIsoAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
+
+public:
+    // --------------------------------------------------------------------- //
+    // EXPOSURETIME 
+    // --------------------------------------------------------------------- //
+    /// Time in seconds that the sensor is exposed to light when calculating exposure.
+    /// Longer exposure times create a brighter image, shorter times darker.
+    ///
+    /// | ||
+    /// | -- | -- |
+    /// | Declaration | `float exposure:time = 1` |
+    /// | C++ Type | float |
+    /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
+    USDGEOM_API
+    UsdAttribute GetExposureTimeAttr() const;
+
+    /// See GetExposureTimeAttr(), and also 
+    /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+    /// If specified, author \p defaultValue as the attribute's default,
+    /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+    /// the default for \p writeSparsely is \c false.
+    USDGEOM_API
+    UsdAttribute CreateExposureTimeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
+
+public:
+    // --------------------------------------------------------------------- //
+    // EXPOSUREFNUMBER 
+    // --------------------------------------------------------------------- //
+    /// f-number of the aperture when calculating exposure. Smaller numbers
+    /// create a brighter image, larger numbers darker.
+    ///
+    /// | ||
+    /// | -- | -- |
+    /// | Declaration | `float exposure:fNumber = 1` |
+    /// | C++ Type | float |
+    /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
+    USDGEOM_API
+    UsdAttribute GetExposureFNumberAttr() const;
+
+    /// See GetExposureFNumberAttr(), and also 
+    /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+    /// If specified, author \p defaultValue as the attribute's default,
+    /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+    /// the default for \p writeSparsely is \c false.
+    USDGEOM_API
+    UsdAttribute CreateExposureFNumberAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
+
+public:
+    // --------------------------------------------------------------------- //
+    // EXPOSURERESPONSIVITY 
+    // --------------------------------------------------------------------- //
+    /// Scalar multiplier representing overall responsivity of the 
+    /// sensor system to light when calculating exposure. Intended to be
+    /// used as a per camera/lens system measured scaling value.
+    ///
+    /// | ||
+    /// | -- | -- |
+    /// | Declaration | `float exposure:responsivity = 1` |
+    /// | C++ Type | float |
+    /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
+    USDGEOM_API
+    UsdAttribute GetExposureResponsivityAttr() const;
+
+    /// See GetExposureResponsivityAttr(), and also 
+    /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+    /// If specified, author \p defaultValue as the attribute's default,
+    /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+    /// the default for \p writeSparsely is \c false.
+    USDGEOM_API
+    UsdAttribute CreateExposureResponsivityAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
+
 public:
     // ===================================================================== //
     // Feel free to add custom code below this line, it will be preserved by 
@@ -574,6 +696,19 @@ class UsdGeomCamera : public UsdGeomXformable
     ///
     USDGEOM_API
     void SetFromCamera(const GfCamera &camera, const UsdTimeCode &time);
+
+    /// Computes the ratio between incident luminance and photometric exposure 
+    /// (in lux-seconds), given the <tt>exposure</tt>, <tt>exposure:iso</tt>, 
+    /// <tt>exposure:fnumber</tt>, <tt>exposure:time</tt> and <tt>exposure:responsivity</tt> 
+    /// attributes.
+    ///
+    /// This is expected to be applied as a multiplier to the brightness of the 
+    /// image generated by the renderer, and given physically meaningful lighting
+    /// values in the scene, allows the exposure controls on UsdGeomCamera to behave
+    /// like those of a real camera.
+    ///
+    USDGEOM_API
+    float GetExposureScale(UsdTimeCode time=UsdTimeCode::Default()) const;
 };
 
 PXR_NAMESPACE_CLOSE_SCOPE