Finalised directional sampling of volume emitters, and appropriately implemented tests.

Author: Microno95

include/mitsuba/python/docstr.h

@@ -4508,7 +4508,9 @@ static const char *__doc_mitsuba_Mesh_parameters_changed = R"doc()doc";
 
 static const char *__doc_mitsuba_Mesh_parameters_grad_enabled = R"doc()doc";
 
-static const char *__doc_mitsuba_Mesh_pdf_position = R"doc()doc";
+static const char *__doc_mitsuba_Mesh_pdf_position_surface = R"doc()doc";
+
+static const char *__doc_mitsuba_Mesh_pdf_position_volume = R"doc()doc";
 
 static const char *__doc_mitsuba_Mesh_primitive_count = R"doc()doc";
 
@@ -4545,7 +4547,9 @@ static const char *__doc_mitsuba_Mesh_recompute_bbox = R"doc(Recompute the bound
 
 static const char *__doc_mitsuba_Mesh_recompute_vertex_normals = R"doc(Compute smooth vertex normals and replace the current normal values)doc";
 
-static const char *__doc_mitsuba_Mesh_sample_position = R"doc()doc";
+static const char *__doc_mitsuba_Mesh_sample_position_surface = R"doc()doc";
+
+static const char *__doc_mitsuba_Mesh_sample_position_volume = R"doc()doc";
 
 static const char *__doc_mitsuba_Mesh_set_scene = R"doc()doc";
 
@@ -7513,8 +7517,20 @@ static const char *__doc_mitsuba_Shape_parameters_grad_enabled =
 R"doc(Return whether any shape's parameters require gradients (default
 return false))doc";
 
-static const char *__doc_mitsuba_Shape_pdf_direction =
-R"doc(Query the probability density of sample_direction()
+static const char *__doc_mitsuba_Shape_pdf_direction_surface =
+    R"doc(Query the probability density of sample_direction_surface()
+
+Parameter ``it``:
+    A reference position somewhere within the scene.
+
+Parameter ``ps``:
+    A position record describing the sample in question
+
+Returns:
+    The probability density per unit solid angle)doc";
+
+static const char *__doc_mitsuba_Shape_pdf_direction_volume =
+    R"doc(Query the probability density of sample_direction_volume()
 
 Parameter ``it``:
     A reference position somewhere within the scene.
@@ -7525,8 +7541,8 @@ Parameter ``ps``:
 Returns:
     The probability density per unit solid angle)doc";
 
-static const char *__doc_mitsuba_Shape_pdf_position =
-R"doc(Query the probability density of sample_position() for a particular
+static const char *__doc_mitsuba_Shape_pdf_position_surface =
+R"doc(Query the probability density of sample_position_surface() for a particular
 point on the surface.
 
 Parameter ``ps``:
@@ -7535,8 +7551,8 @@ Parameter ``ps``:
 Returns:
     The probability density per unit area)doc";
 
-static const char *__doc_mitsuba_Shape_pdf_position_3d =
-R"doc(Query the probability density of sample_position() for a particular
+static const char *__doc_mitsuba_Shape_pdf_position_volume =
+R"doc(Query the probability density of sample_position_surface() for a particular
 point in the volume.
 
 Parameter ``ps``:
@@ -7619,8 +7635,8 @@ static const char *__doc_mitsuba_Shape_ray_test_packet_3 = R"doc()doc";
 
 static const char *__doc_mitsuba_Shape_ray_test_scalar = R"doc()doc";
 
-static const char *__doc_mitsuba_Shape_sample_direction =
-R"doc(Sample a direction towards this shape with respect to solid angles
+static const char *__doc_mitsuba_Shape_sample_direction_surface =
+    R"doc(Sample a direction towards this shape with respect to solid angles
 measured at a reference position within the scene
 
 An ideal implementation of this interface would achieve a uniform
@@ -7633,7 +7649,7 @@ per unit solid angle associated with the sample.
 
 When the Shape subclass does not supply a custom implementation of
 this function, the Shape class reverts to a fallback approach that
-piggybacks on sample_position(). This will generally lead to a
+piggybacks on sample_position_surface(). This will generally lead to a
 suboptimal sample placement and higher variance in Monte Carlo
 estimators using the samples.
 
@@ -7646,7 +7662,34 @@ Parameter ``sample``:
 Returns:
     A DirectionSample instance describing the generated sample)doc";
 
-static const char *__doc_mitsuba_Shape_sample_position =
+static const char *__doc_mitsuba_Shape_sample_direction_volume =
+    R"doc(Sample a direction towards this shape with respect to solid angles
+measured at a reference position within the scene
+
+An ideal implementation of this interface would achieve a uniform
+solid angle density within the volume region that is visible from the
+reference position ``it.p`` (though such an ideal implementation is
+usually neither feasible nor advisable due to poor efficiency).
+
+The function returns the sampled position and the inverse probability
+per unit solid angle associated with the sample.
+
+When the Shape subclass does not supply a custom implementation of
+this function, the Shape class reverts to a fallback approach that
+piggybacks on sample_position_volume(). This will generally lead to a
+suboptimal sample placement and higher variance in Monte Carlo
+estimators using the samples.
+
+Parameter ``it``:
+    A reference position somewhere within the scene.
+
+Parameter ``sample``:
+    A uniformly distributed 3D point on the domain ``[0,1]^3``
+
+Returns:
+    A DirectionSample instance describing the generated sample)doc";
+
+static const char *__doc_mitsuba_Shape_sample_position_surface =
 R"doc(Sample a point on the surface of this shape
 
 The sampling strategy is ideally uniform over the surface, though
@@ -7663,7 +7706,7 @@ Parameter ``sample``:
 Returns:
     A PositionSample instance describing the generated sample)doc";
 
-static const char *__doc_mitsuba_Shape_sample_position_3d =
+static const char *__doc_mitsuba_Shape_sample_position_volume =
 R"doc(Sample a point in the volume of this shape
 
 The sampling strategy is ideally uniform over the volume, though
@@ -8990,7 +9033,7 @@ default implementation throws an exception.
 Even if the operation is provided, it may only return an
 approximation.)doc";
 
-static const char *__doc_mitsuba_Texture_pdf_position = R"doc(Returns the probability per unit area of sample_position())doc";
+static const char *__doc_mitsuba_Texture_pdf_position = R"doc(Returns the probability per unit area of sample_position_surface())doc";
 
 static const char *__doc_mitsuba_Texture_pdf_spectrum =
 R"doc(Evaluate the density function of the sample_spectrum() method as a

include/mitsuba/render/mesh.h

@@ -170,15 +170,23 @@ class MI_EXPORT_LIB Mesh : public Shape<Float, Spectrum> {
 
     virtual Float volume() const override;
 
-    virtual PositionSample3f sample_position(Float time, const Point2f &sample,
+    virtual PositionSample3f
+    sample_position_surface(Float time, const Point2f &sample,
                                              Mask active = true) const override;
 
-    virtual Float pdf_position(const PositionSample3f &ps, Mask active = true) const override;
+    virtual Float pdf_position_surface(const PositionSample3f &ps, Mask active = true) const override;
 
-    virtual PositionSample3f sample_position_3d(Float time, const Point3f &sample,
+    virtual DirectionSample3f sample_direction_volume(const Interaction3f &it, const Point3f &sample,
+                                                      Mask active = true) const override;
+
+    virtual Float pdf_direction_volume(const Interaction3f &it, const DirectionSample3f &ds,
+                                       Mask active = true) const override;
+
+    virtual PositionSample3f
+    sample_position_volume(Float time, const Point3f &sample,
                                              Mask active = true) const override;
 
-    virtual Float pdf_position_3d(const PositionSample3f &ps, Mask active = true) const override;
+    virtual Float pdf_position_volume(const PositionSample3f &ps, Mask active = true) const override;
 
     virtual Point3f
     barycentric_coordinates(const SurfaceInteraction3f &si,
@@ -339,7 +347,7 @@ class MI_EXPORT_LIB Mesh : public Shape<Float, Spectrum> {
      * ray/object intersections.
      *
      * Internally, the function creates a nested scene to leverage optimized
-     * ray tracing functionality in \ref pdf_position_3d()
+     * ray tracing functionality in \ref pdf_position_volume()
      */
     void build_volume_parameterization();
 

include/mitsuba/render/shape.h

@@ -53,11 +53,11 @@ class MI_EXPORT_LIB Shape : public Object {
      * \return
      *     A \ref PositionSample instance describing the generated sample
      */
-    virtual PositionSample3f sample_position(Float time, const Point2f &sample,
+    virtual PositionSample3f sample_position_surface(Float time, const Point2f &sample,
                                              Mask active = true) const;
 
     /**
-     * \brief Query the probability density of \ref sample_position() for
+     * \brief Query the probability density of \ref sample_position_surface() for
      * a particular point on the surface.
      *
      * \param ps
@@ -66,7 +66,7 @@ class MI_EXPORT_LIB Shape : public Object {
      * \return
      *     The probability density per unit area
      */
-    virtual Float pdf_position(const PositionSample3f &ps, Mask active = true) const;
+    virtual Float pdf_position_surface(const PositionSample3f &ps, Mask active = true) const;
 
     /**
      * \brief Sample a point in the volume of this shape
@@ -85,11 +85,11 @@ class MI_EXPORT_LIB Shape : public Object {
      * \return
      *     A \ref PositionSample instance describing the generated sample
      */
-    virtual PositionSample3f sample_position_3d(Float time, const Point3f &sample,
+    virtual PositionSample3f sample_position_volume(Float time, const Point3f &sample,
                                                 Mask active = true) const;
 
     /**
-     * \brief Query the probability density of \ref sample_position() for
+     * \brief Query the probability density of \ref sample_position_volume() for
      * a particular point in the volume.
      *
      * \param ps
@@ -98,7 +98,7 @@ class MI_EXPORT_LIB Shape : public Object {
      * \return
      *     The probability density per unit volume
      */
-    virtual Float pdf_position_3d(const PositionSample3f &ps, Mask active = true) const;
+    virtual Float pdf_position_volume(const PositionSample3f &ps, Mask active = true) const;
 
     /**
      * \brief Sample a direction towards this shape with respect to solid
@@ -114,7 +114,7 @@ class MI_EXPORT_LIB Shape : public Object {
      *
      * When the Shape subclass does not supply a custom implementation of this
      * function, the \ref Shape class reverts to a fallback approach that
-     * piggybacks on \ref sample_position(). This will generally lead to a
+     * piggybacks on \ref sample_position_surface(). This will generally lead to a
      * suboptimal sample placement and higher variance in Monte Carlo
      * estimators using the samples.
      *
@@ -127,11 +127,59 @@ class MI_EXPORT_LIB Shape : public Object {
      * \return
      *     A \ref DirectionSample instance describing the generated sample
      */
-    virtual DirectionSample3f sample_direction(const Interaction3f &it, const Point2f &sample,
-                                               Mask active = true) const;
+    virtual DirectionSample3f
+    sample_direction_surface(const Interaction3f &it, const Point2f &sample,
+                             Mask active = true) const;
+
+    /**
+     * \brief Query the probability density of \ref sample_direction_surface()
+     *
+     * \param it
+     *    A reference position somewhere within the scene.
+     *
+     * \param ps
+     *     A position record describing the sample in question
+     *
+     * \return
+     *     The probability density per unit solid angle
+     */
+    virtual Float pdf_direction_surface(const Interaction3f &it, const DirectionSample3f &ds,
+                                        Mask active = true) const;
+
+    /**
+     * \brief Sample a direction towards a point contained within this shape
+     * with respect to solid angles measured at a reference position
+     * within the scene
+     *
+     * An ideal implementation of this interface would achieve a uniform solid
+     * angle density within the volume that is visible from the
+     * reference position <tt>it.p</tt> (though such an ideal implementation
+     * is usually neither feasible nor advisable due to poor efficiency).
+     *
+     * The function returns the sampled position and the inverse probability
+     * per unit solid angle associated with the sample.
+     *
+     * When the Shape subclass does not supply a custom implementation of this
+     * function, the \ref Shape class reverts to a fallback approach that
+     * piggybacks on \ref sample_position_volume(). This will generally lead to a
+     * suboptimal sample placement and higher variance in Monte Carlo
+     * estimators using the samples.
+     *
+     * \param it
+     *    A reference position somewhere within the scene.
+     *
+     * \param sample
+     *     A uniformly distributed 3D point on the domain <tt>[0,1]^3</tt>
+     *
+     * \return
+     *     A \ref DirectionSample instance describing the generated sample
+     */
+    virtual DirectionSample3f
+    sample_direction_volume(const Interaction3f &it, const Point3f &sample,
+                             Mask active = true) const;
 
     /**
-     * \brief Query the probability density of \ref sample_direction()
+     * \brief Query the probability density of \ref sample_direction_volume()
      *
      * \param it
      *    A reference position somewhere within the scene.
@@ -142,8 +190,8 @@ class MI_EXPORT_LIB Shape : public Object {
      * \return
      *     The probability density per unit solid angle
      */
-    virtual Float pdf_direction(const Interaction3f &it, const DirectionSample3f &ds,
-                                Mask active = true) const;
+    virtual Float pdf_direction_volume(const Interaction3f &it, const DirectionSample3f &ds,
+                                        Mask active = true) const;
 
     //! @}
     // =============================================================
@@ -699,12 +747,14 @@ DRJIT_VCALL_TEMPLATE_BEGIN(mitsuba::Shape)
     DRJIT_VCALL_METHOD(ray_intersect_preliminary)
     DRJIT_VCALL_METHOD(ray_intersect)
     DRJIT_VCALL_METHOD(ray_test)
-    DRJIT_VCALL_METHOD(sample_position)
-    DRJIT_VCALL_METHOD(pdf_position)
-    DRJIT_VCALL_METHOD(sample_position_3d)
-    DRJIT_VCALL_METHOD(pdf_position_3d)
-    DRJIT_VCALL_METHOD(sample_direction)
-    DRJIT_VCALL_METHOD(pdf_direction)
+    DRJIT_VCALL_METHOD(sample_position_surface)
+    DRJIT_VCALL_METHOD(pdf_position_surface)
+    DRJIT_VCALL_METHOD(sample_position_volume)
+    DRJIT_VCALL_METHOD(pdf_position_volume)
+    DRJIT_VCALL_METHOD(sample_direction_surface)
+    DRJIT_VCALL_METHOD(pdf_direction_surface)
+    DRJIT_VCALL_METHOD(sample_direction_volume)
+    DRJIT_VCALL_METHOD(pdf_direction_volume)
     DRJIT_VCALL_METHOD(surface_area)
     DRJIT_VCALL_METHOD(volume)
     DRJIT_VCALL_GETTER(emitter, const typename Class::Emitter *)

src/emitters/area.cpp

@@ -125,7 +125,8 @@ class AreaLight final : public Emitter<Float, Spectrum> {
         // One of two very different strategies is used depending on 'm_radiance'
         if (likely(!m_radiance->is_spatially_varying())) {
             // Texture is uniform, try to importance sample the shape wrt. solid angle at 'it'
-            ds = m_shape->sample_direction(it, Point2f(sample.x(), sample.y()), active);
+            ds = m_shape->sample_direction_surface(
+                it, Point2f(sample.x(), sample.y()), active);
             active &= dr::dot(ds.d, ds.n) < 0.f && dr::neq(ds.pdf, 0.f);
 
             si = SurfaceInteraction3f(ds, it.wavelengths);
@@ -168,7 +169,7 @@ class AreaLight final : public Emitter<Float, Spectrum> {
 
         Float value;
         if (!m_radiance->is_spatially_varying()) {
-            value = m_shape->pdf_direction(it, ds, active);
+            value = m_shape->pdf_direction_surface(it, ds, active);
         } else {
             // This surface intersection would be nice to avoid..
             SurfaceInteraction3f si = m_shape->eval_parameterization(ds.uv, +RayFlags::dPdUV, active);
@@ -203,7 +204,8 @@ class AreaLight final : public Emitter<Float, Spectrum> {
         PositionSample3f ps;
         if (!m_radiance->is_spatially_varying()) {
             // Radiance not spatially varying, use area-based sampling of shape
-            ps = m_shape->sample_position(time, Point2f(sample.x(), sample.y()), active);
+            ps = m_shape->sample_position_surface(
+                time, Point2f(sample.x(), sample.y()), active);
         } else {
             // Importance sample texture
             auto [uv, pdf] = m_radiance->sample_position(Point2f(sample.x(), sample.y()), active);

src/emitters/directionalarea.cpp

@@ -130,7 +130,8 @@ class DirectionalArea final : public Emitter<Float, Spectrum> {
     sample_position(Float time, const Point3f &sample,
                     Mask active) const override {
         Assert(m_shape, "Can't sample from an area emitter without an associated Shape.");
-        PositionSample3f ps = m_shape->sample_position(time, Point2f(sample.x(), sample.y()), active);
+        PositionSample3f ps = m_shape->sample_position_surface(
+            time, Point2f(sample.x(), sample.y()), active);
         Float weight        = dr::select(ps.pdf > 0.f, dr::rcp(ps.pdf), 0.f);
         return { ps, weight };
     }

src/emitters/tests/test_area.py

@@ -84,7 +84,7 @@ def test03_sample_ray(variants_vec_spectral, spectrum_key):
     wav, spec = spectrum.sample_spectrum(it, mi.sample_shifted(wavelength_sample))
 
     # Sample a position on the shape
-    ps = shape.sample_position(time, pos_sample[:2])
+    ps = shape.sample_position_surface(time, pos_sample[:2])
 
     assert dr.allclose(res, spec * shape.surface_area() * dr.pi)
     assert dr.allclose(ray.time, time)
@@ -112,7 +112,7 @@ def test04_sample_direction(variants_vec_spectral, spectrum_key):
     ds, res = emitter.sample_direction(it, samples)
 
     # Sample direction on the shape
-    shape_ds = shape.sample_direction(it, samples[:2])
+    shape_ds = shape.sample_direction_surface(it, samples[:2])
 
     assert dr.allclose(ds.pdf, shape_ds.pdf)
     assert dr.allclose(ds.pdf, emitter.pdf_direction(it, ds))

src/emitters/tests/test_directionalarea.py

@@ -84,7 +84,7 @@ def test03_sample_ray(variants_vec_spectral, spectrum_key):
     wav, spec = spectrum.sample_spectrum(it, mi.sample_shifted(wavelength_sample))
 
     # Sample a position on the shape
-    ps = shape.sample_position(time, pos_sample[:2])
+    ps = shape.sample_position_surface(time, pos_sample[:2])
 
     assert dr.allclose(res, spec * shape.surface_area())
     assert dr.allclose(ray.time, time)