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 vExposureFStop =
+            sceneDelegate->GetCameraParamValue(
+                id, HdCameraTokens->exposureFStop);
+        if (!vExposureFStop.IsEmpty()) {
+            _exposureFStop = vExposureFStop.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)                                                 \
+    (exposureFStop)                                               \
+    (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                   _exposureFStop;
+    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::GetExposureFStopAttr() const
+{
+    return GetPrim().GetAttribute(UsdGeomTokens->exposureFStop);
+}
+
+UsdAttribute
+UsdGeomCamera::CreateExposureFStopAttr(VtValue const &defaultValue, bool writeSparsely) const
+{
+    return UsdSchemaBase::_CreateAttr(UsdGeomTokens->exposureFStop,
+                       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->exposureFStop,
+        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 exposureFStop = 1.0f;
+    float exposureResponsivity = 1.0f;
+    float exposureCompensation = 0.0f;
+
+    GetExposureTimeAttr().Get(&exposureTime, time);
+    GetExposureIsoAttr().Get(&exposureIso, time);
+    GetExposureFStopAttr().Get(&exposureFStop, time);
+    GetExposureResponsivityAttr().Get(&exposureResponsivity, time);
+    GetExposureAttr().Get(&exposureCompensation, time);
+
+    return (exposureTime * exposureIso * powf(2.0f, exposureCompensation) * 
+            exposureResponsivity) / (100.0f * exposureFStop * exposureFStop);
+}
+
 PXR_NAMESPACE_CLOSE_SCOPE

pxr/usd/usdGeom/camera.h

@@ -99,6 +99,36 @@ 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 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 = exposureResponsivity * 
+/// (exposureTime * (exposureIso/100) * pow(2, exposure)) 
+/// / (exposureFStop * exposureFStop)
+/// \endcode
+/// 
+/// This scaling factor is combined from two parts: The first, known as the __imaging ratio__ 
+/// (in _steradian-second_), converts from incident luminance at the front 
+/// of the lens system, in _nit_ (_cd/m^2_), to photometric exposure at the sensor
+/// in _lux-second_. The second, `exposureResponsivity` 
+/// (in _inverse lux-second_), converts from photometric exposure at the sensor, in _lux-second_,
+/// to a unitless output signal.
+/// 
+/// 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 scale of 1.0.
 /// 
 /// \sa \ref UsdGeom_LinAlgBasics
 /// 
@@ -394,7 +424,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 +521,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 +543,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 +564,108 @@ 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.
+    /// Note that shutter:open and shutter:close model essentially the 
+    /// same property of a physical camera, but are for specifying the 
+    /// size of the motion blur streak which is for practical purposes
+    /// useful to keep separate.
+    ///
+    /// | ||
+    /// | -- | -- |
+    /// | 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:
+    // --------------------------------------------------------------------- //
+    // EXPOSUREFSTOP 
+    // --------------------------------------------------------------------- //
+    /// f-stop of the aperture when calculating exposure. Smaller numbers
+    /// create a brighter image, larger numbers darker.
+    /// Note that the `fStop` attribute also models the diameter of the camera
+    /// aperture, but for specifying depth of field.  For practical 
+    /// purposes it is useful to keep the exposure and the depth of field
+    /// controls separate.
+    /// 
+    ///
+    /// | ||
+    /// | -- | -- |
+    /// | Declaration | `float exposure:fStop = 1` |
+    /// | C++ Type | float |
+    /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
+    USDGEOM_API
+    UsdAttribute GetExposureFStopAttr() const;
+
+    /// See GetExposureFStopAttr(), 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 CreateExposureFStopAttr(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 +706,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