pycoupole 0.1.0__py3-none-any.whl

pycoupole/__init__.py

@@ -0,0 +1,13 @@
+# Import the two end-user functions used for BRDF and uncertainties
+from .brdf import computeBRDFDeterministic, computeBRDFDistribution
+
+__all__ = ["computeBRDFDeterministic",        "computeBRDFDistribution",
+           "computeBRDFDeterministicFromCSV", "computeBRDFDistributionFromCSV",]
+
+
+# Dyanmic version based on metadata (obtained from repo tag)
+from importlib.metadata import version, PackageNotFoundError
+try:
+    __version__ = version("pycoupole")
+except PackageNotFoundError:
+    __version__ = "?.?.?"

pycoupole/brdf.py

@@ -0,0 +1,206 @@
+import numpy as np, warp as wp
+
+
+from .core._utils   import _pickDevice, _vec2ui, _vec3d
+from .core._kernels import _sampleBRDF, _sampleBRDFDistribution
+
+
+def computeBRDFDeterministic(
+    pixelID, channelID, pixelValueLSB, exposureTimeS,
+    lightCenter, lightNormal, triangleCenter, triangleNormal,
+    device=None
+):
+    """Compute the deterministic (point-estimate) BRDF for a single pixel-channel sample.
+
+    Evaluates the measurement equation once with all uncertainty sources
+    disabled, i.e. every input held at its nominal (mean) value. This is the
+    central value around which `computeBRDFDistribution` propagates uncertainties.
+
+    Parameters
+    ----------
+    pixelID : tuple of int
+        Pixel coordinates (column, row) in the sensor frame.
+    channelID : int
+        Colour channel index (0, 1, 2 for R, G, B).
+    pixelValueLSB : int
+        Raw pixel value in least-significant-bit units (digital number).
+    exposureTimeS : float
+        Exposure time of the acquisition, in seconds.
+    lightCenter, triangleCenter : array_like of float, shape (3,)
+        3D positions of the light-source centre and of the measured surface
+        element, in the scene coordinate system.
+    lightNormal, triangleNormal : array_like of float, shape (3,)
+        Unit normals of the light source and of the measured surface element.
+    device : str, optional
+        Warp device string (e.g. "cuda:0", "cpu"). Defaults to the first
+        available CUDA device, falling back to CPU.
+
+    Returns
+    -------
+    float
+        The BRDF value, in inverse steradians (sr^-1).
+
+    See Also
+    --------
+    computeBRDFDistribution : Monte Carlo uncertainty distribution of this value.
+    """
+
+    device = _pickDevice(device)
+
+    output = wp.empty(1, dtype=wp.float64, device=device)
+    wp.launch(
+        kernel  = _sampleBRDF,
+        dim     = 1,
+        inputs  = [
+            _vec2ui(pixelID), int(channelID), int(pixelValueLSB), float(exposureTimeS),
+            _vec3d(lightCenter), _vec3d(lightNormal), _vec3d(triangleCenter), _vec3d(triangleNormal),
+            True, 0
+        ],
+        outputs = [output],
+        device  = device,
+    )
+    wp.synchronize_device(device)
+    return float(output.numpy()[0])
+
+
+def computeBRDFDistribution(
+    pixelID, channelID, pixelValueLSB, exposureTimeS,
+    lightCenter, lightNormal, triangleCenter, triangleNormal,
+    nbBins:        int   = 1000,
+    pilotSize:     int   = 100_000,
+    batchSize:     int   = 10_000_000,
+    maxBatches:    int   = 10,
+    outlierCutoff: float = 10.0,
+    seed:          int   = 1,
+    device:        str   = None
+):
+    """Estimate the BRDF uncertainty distribution by Monte Carlo propagation.
+
+    Propagates the measurement uncertainties (calibration factor, Spectralon
+    reflectance, ...) through the BRDF measurement equation by repeated
+    stochastic sampling, and returns the resulting probability density.
+
+    The computation runs in two passes:
+
+    1. Pilot pass -- `pilotSize` samples are drawn to locate the distribution.
+       The histogram upper bound is set to ``outlierCutoff * median(pilot)``;
+       the lower bound is 0.
+    2. Sampling pass -- exactly `maxBatches` batches of `batchSize` samples each
+       are accumulated into a fixed-range histogram. Each batch uses a disjoint
+       RNG seed, so batches are independent draws.
+
+    Parameters
+    ----------
+    pixelID, channelID, pixelValueLSB, exposureTimeS :
+        Acquisition descriptors; see `computeBRDFDeterministic`.
+    lightCenter, lightNormal, triangleCenter, triangleNormal : array_like, shape (3,)
+        Measurement geometry; see `computeBRDFDeterministic`.
+    nbBins : int, default 1000
+        Number of histogram bins spanning the distribution support.
+    pilotSize : int, default 100_000
+        Number of samples in the pilot pass used to set the histogram range.
+    batchSize : int, default 10_000_000
+        Number of samples drawn per batch in the sampling pass.
+    maxBatches : int, default 10
+        Number of batches drawn. Total sample count is ``maxBatches * batchSize``.
+    outlierCutoff : float, default 10.0
+        Multiple of the pilot median used as the histogram upper bound. Samples
+        beyond this bound are counted as out-of-range and excluded from the density.
+    seed : int, default 1
+        Base RNG seed for the sampling pass; batch ``i`` uses ``seed + 1 + i``.
+        The pilot pass uses a fixed, disjoint seed independent of this value.
+    device : str, optional
+        Warp device string. Defaults to the first available CUDA device,
+        falling back to CPU.
+
+    Returns
+    -------
+    dict
+        pdf : numpy.ndarray, shape (nbBins,)
+            Probability density at each bin centre, in steradians (sr, the
+            inverse of the BRDF unit). Normalized so the area under the curve
+            integrates to 1 over the histogram support; equivalently, the density
+            conditioned on a sample lying in range.
+        brdfValues : numpy.ndarray, shape (nbBins,)
+            Bin-centre BRDF values, in inverse steradians (sr^-1).
+        nbTotal : int
+            Total number of samples drawn (``maxBatches * batchSize``).
+        nbAccepted : int
+            Number of samples that fell within the histogram range. The
+            out-of-range fraction is ``1 - nbAccepted / nbTotal``; a large value
+            indicates the histogram range is mis-set.
+
+    Notes
+    -----
+    The returned density is *conditional* on samples lying within the histogram
+    support. When the out-of-range fraction is negligible (the expected regime),
+    it coincides with the unconditional density. A large rejection fraction
+    signals that `outlierCutoff` should be widened or the pilot range revisited.
+
+    See Also
+    --------
+    computeBRDFDeterministic : Deterministic point estimate of the BRDF.
+    """
+
+    device = _pickDevice(device)
+
+    # We'll start by a first pass as a pilot
+    # This allows us to see the range of the
+    # output distribution
+    pilot = wp.empty(pilotSize, dtype=wp.float64, device=device)
+    wp.launch(
+        kernel  = _sampleBRDF,
+        dim     = pilotSize,
+        inputs  = [
+            _vec2ui(pixelID), int(channelID), int(pixelValueLSB), float(exposureTimeS),
+            _vec3d(lightCenter), _vec3d(lightNormal), _vec3d(triangleCenter), _vec3d(triangleNormal),
+            False, 0
+        ],
+        outputs = [pilot],
+        device  = device,
+    )
+    wp.synchronize_device(device)
+
+    histogramMin = 0.0
+    histogramMax = outlierCutoff * float(np.median(pilot.numpy()))
+
+    # The second pass will be the true Monte Carlo sampling
+    histogram  = wp.zeros(nbBins, dtype=wp.int64, device=device)
+    nbAccepted = wp.zeros(1,      dtype=wp.int64, device=device)
+
+    for batchID in range(maxBatches):
+        # We'll use a disjoint seed per batch,
+        # that is distinct from the pilot seed
+        batchSeed = seed + 1 + batchID
+
+        wp.launch(
+            kernel  = _sampleBRDFDistribution,
+            dim     = batchSize,
+            inputs  = [
+                _vec2ui(pixelID), int(channelID), int(pixelValueLSB), float(exposureTimeS),
+                _vec3d(lightCenter), _vec3d(lightNormal), _vec3d(triangleCenter), _vec3d(triangleNormal),
+                batchSeed, histogramMin, histogramMax, nbBins
+            ],
+            outputs = [histogram, nbAccepted],
+            device  = device,
+        )
+        wp.synchronize_device(device)
+
+    nbTotal = (batchID + 1) * batchSize
+
+    counts     = histogram.numpy()
+    binEdges   = np.linspace(histogramMin, histogramMax, nbBins + 1)
+    brdfValues = 0.5 * (binEdges[:-1] + binEdges[1:]) # bin centers
+    binWidth   = (histogramMax - histogramMin) / nbBins
+
+    # Normalize to a probability density: the area under the curve integrates to 1
+    # over the histogram support (counts.sum() == nbAccepted, the in-range samples)
+    inRange = counts.sum()
+    pdf     = counts / (inRange * binWidth) if inRange > 0 else np.zeros_like(counts, dtype=np.float64)
+
+    return {
+        "pdf":        pdf,
+        "brdfValues": brdfValues,
+        "nbTotal":    nbTotal,
+        "nbAccepted": int(nbAccepted.numpy()[0]),
+    }

pycoupole/core/_functions.py

@@ -0,0 +1,373 @@
+import warp as wp
+
+
+# Camera properties
+cameraDSNUE         = wp.float64(2.)       # DSNU (Dark Signal Non-Uniformity), in electrons
+cameraPRNUPercent   = wp.float64(0.0127)   # PRNU (Photo Response Non-Uniformity), in percent
+conversionFactorADC = wp.float64(3.33)     # ADC (Analog-to-Digital) factor, in electrons/bit
+cameraDarkIntensity = wp.float64(22.)      # Dark intensity (in electrons/second)
+cameraReadoutNoiseE = wp.float64(13.)      # Readout noise (in electrons)
+cameraSmallestTick  = wp.float64(0.000019) # Smallest camera tick (in seconds)
+
+# Flat field correction parameters (RGB channels)
+flatFieldAlpha0 = wp.vec3d(-0.11834731, -0.12480557, -0.11442123)
+flatFieldAlpha1 = wp.vec3d( 0.00827793,  0.00580036,  0.02310389)
+flatFieldAlpha2 = wp.vec3d(-0.06498365, -0.06220726, -0.03930921)
+flatFieldAlpha3 = wp.vec3d(-0.02969467, -0.01976859, -0.00969820)
+flatFieldAlpha4 = wp.vec3d( 0.99646296,  0.99836206,  0.99823554)
+
+flatFieldSigma0 = wp.vec3d(1.86561084e-04, 1.08971155e-04, 0.00084640)
+flatFieldSigma1 = wp.vec3d(9.63867472e-05, 5.62999256e-05, 0.00043729)
+flatFieldSigma2 = wp.vec3d(1.86500416e-04, 1.08935718e-04, 0.00084612)
+flatFieldSigma3 = wp.vec3d(9.63710605e-05, 5.62907629e-05, 0.00043722)
+flatFieldSigma4 = wp.vec3d(1.04160470e-04, 6.08405915e-05, 0.00047256)
+
+# Uncertainty associated to the LEDs
+uncertaintyLEDPosition = wp.float64(0.0007)   # in meters (700 µm)
+sizeLEDSide            = wp.float64(0.007)    # in meters (7 mm)
+# Uncertainty is uniformly distributed between ± 40 µm (so ± 20 µm on half size)
+# This value has been obtained by measuring the LED with a caliper (ref DIN 862)
+uncertaintyLEDSide = wp.float64(0.000040) # in meters (40 µm)
+
+# Uncertainty associated to the 3D scan
+reflectanceSpatialUncertainty = wp.float64(0.00020) # in meters (200 µm)
+geometricalSpatialUncertainty = wp.float64(0.00003) # in meters (30 µm)
+
+# Uncertainty associated to the triangle
+# it is supposed to be equilateral, with
+# a length of 200 µm
+circumscribedCircleTriangleRadius = wp.float64(0.000115470053) # R = 200 µm * sqrt(3) / 3
+
+# Spectralon uncertainty is 0.98 ± [-0.0054 : 0.0054]
+# More precisely, what does the LabSphere calibration
+# certificate say is:
+# 0.98 ± [-0.0054 : 0.0054] at 95 % confidence level
+# This can be modelled with a gaussian distribution,
+# with mean 0.98 and standard deviation 0.0054 / 2.
+spectralonReflectance = wp.float64(0.98)
+spectralonStandardDev = wp.float64(0.0054 / 2.)
+
+# Calibration factor uncertainty (RBG channels)
+calibrationFactorMean = wp.vec3d(12554958902.215567, 17434401087.369884, 12713082781.469217)
+calibrationFactorStd  = wp.vec3d(705685.39513860860, 702675.41479146033, 707437.30615753750)
+
+# Color balancing (RGB)
+colorBalance = wp.vec3d(1. / 0.9105837051966023, 1. / 0.83213626924054, 1. / 0.9071877745806616)
+
+
+@wp.func
+def _getPixelValue(
+    pixelValueLSB: wp.float64, # LSB value of the pixel (in bits)
+    exposureTimeS: wp.float64, # Pixel exposure time (in seconds)
+    noUncertainty: wp.bool,
+    rngState: wp.uint32) -> wp.float64:
+
+    if noUncertainty:
+        return pixelValueLSB
+
+    # 0. DAC (Digital-to-Analog) conversion
+    #    From LSB value to electrons number
+    pixelValueElectrons = pixelValueLSB * conversionFactorADC
+
+    # 1. PRNU (Photo Response Non-Uniformity) noise
+    #    Since it is given by the manufacturer as a
+    #    maximum limit, we'll use a uniform distrib
+    PRNU = wp.float64(1.0) + (wp.float64(2.0) * wp.float64(wp.randf(rngState)) - wp.float64(1.0)) * cameraPRNUPercent
+
+    # 2. Shot noise (Photon counting noise). It is the fundamental
+    #    limit on noise performance in light detection systems. It
+    #    can be well representated using a Poisson distribution if
+    #    we have computed the signal in terms of electrons number.
+    shotNoise = wp.float64(wp.poisson(rngState, wp.float32(pixelValueElectrons * PRNU)))
+
+    # 3. Dark noise (thermal noise). Somestimes called reset noise
+    #    or kTC noise. This can also be represented using Poisson.
+    darkNoise = wp.float64(wp.poisson(rngState, wp.float32(cameraDarkIntensity * exposureTimeS)))
+
+    # 4. Read noise, sometimes called the output amplifier noise.
+    #    More precisely, it can be separated in two parts, white
+    #    noise (also known as Johnson noise), and flicker noise.
+    #    We will follow here a Gaussian rule.
+    readoutNoise = wp.float64(wp.randn(rngState)) * cameraReadoutNoiseE
+
+    # 5. DSNU (Dark Signal Non-Uniformity)
+    #    Can be represented with Gaussian.
+    DSNU = wp.float64(wp.randn(rngState)) * cameraDSNUE
+
+    # Quantify using ADC (Analog-to-Digital) conversion
+    value = wp.round((shotNoise + darkNoise + readoutNoise + DSNU) / conversionFactorADC)
+
+    # 6. Quantization uncertainty, using a uniform
+    #    distribution of width that is equal to 1.
+    value += wp.float64(wp.randf(rngState)) - wp.float64(0.5)
+
+    return value
+
+@wp.func
+def _getFlatFieldCorrection(
+    pixelID  : wp.vec2ui,
+    channelID: wp.uint32,
+    noUncertainty: wp.bool,
+    rngState : wp.uint32) -> wp.float64:
+
+    x = wp.float64(2. * (wp.float32(pixelID[0]) / 4096.) - 1.)
+    y = wp.float64(2. * (wp.float32(pixelID[1]) / 3072.) - 1.)
+
+    if noUncertainty:
+        return (flatFieldAlpha0[channelID] * x * x +
+                flatFieldAlpha1[channelID] * x     +
+                flatFieldAlpha2[channelID] * y * y +
+                flatFieldAlpha3[channelID] * y     +
+                flatFieldAlpha4[channelID])
+
+    alpha0 = flatFieldAlpha0[channelID] + flatFieldSigma0[channelID] * wp.float64(wp.randn(rngState))
+    alpha1 = flatFieldAlpha1[channelID] + flatFieldSigma1[channelID] * wp.float64(wp.randn(rngState))
+    alpha2 = flatFieldAlpha2[channelID] + flatFieldSigma2[channelID] * wp.float64(wp.randn(rngState))
+    alpha3 = flatFieldAlpha3[channelID] + flatFieldSigma3[channelID] * wp.float64(wp.randn(rngState))
+    alpha4 = flatFieldAlpha4[channelID] + flatFieldSigma4[channelID] * wp.float64(wp.randn(rngState))
+
+    return alpha0 * x * x + alpha1 * x + alpha2 * y * y + alpha3 * y + alpha4
+
+@wp.func
+def _branchlessONB(normal: wp.vec3d):
+    # Branchless orthonormal tangent frame (u, v) from a normal n
+    # Duff et al., 2017, JCGT. (n, u, v) right-handed orthonormal
+    # Requires |n| = 1.
+    x, y, z = normal[0], normal[1], normal[2]
+
+    sign = wp.copysign(wp.float64(1.), z)
+
+    a = -wp.float64(1.) / (sign + z)
+    b =  x * y * a
+
+    u = wp.vec3d(wp.float64(1.) + sign * x * x * a, sign * b, -sign * x)
+    v = wp.vec3d(b, sign + y * y * a, -y)
+
+    return u, v
+
+@wp.func
+def _getLEDNormal(
+    normal  : wp.vec3d, # LED normal
+    noUncertainty: wp.bool,
+    rngState: wp.uint32) -> wp.vec3d:
+
+    if noUncertainty:
+        return normal
+
+    # Orthonormal tangent frame
+    u, v = _branchlessONB(normal)
+
+    radius    = wp.float64(0.250) # 25 cm radius
+    angleInit = wp.float64(wp.randf(rngState) * wp.tau) # [0; 2]
+    angle120  = angleInit + wp.float64(2.0943951023931953)
+    angle240  = angleInit + wp.float64(4.1887902047863905)
+
+    p0 = radius * (wp.cos(angleInit) * u + wp.sin(angleInit) * v)
+    p1 = radius * (wp.cos(angle120)  * u + wp.sin(angle120)  * v)
+    p2 = radius * (wp.cos(angle240)  * u + wp.sin(angle240)  * v)
+
+    # Every vertex (LED) has its own uncertainty that we will add
+    p0 += wp.vec3d(wp.sample_unit_sphere(rngState)) * uncertaintyLEDPosition
+    p1 += wp.vec3d(wp.sample_unit_sphere(rngState)) * uncertaintyLEDPosition
+    p2 += wp.vec3d(wp.sample_unit_sphere(rngState)) * uncertaintyLEDPosition
+
+    ledNormal = wp.normalize(wp.cross(p1 - p0, p2 - p0))
+
+    # Should we flip the new normal to be sure it will
+	# point in the same direction as the original one?
+    flipFactor = wp.copysign(wp.float64(1.), wp.dot(ledNormal, normal))
+    return flipFactor * ledNormal
+
+@wp.func
+def _getTriangleNormal(
+    normal  : wp.vec3d, # Triangle normal
+    noUncertainty: wp.bool,
+    rngState: wp.uint32) -> wp.vec3d:
+
+    if noUncertainty:
+        return normal
+
+    # Orthonormal tangent frame
+    u, v = _branchlessONB(normal)
+
+    angleInit = wp.float64(wp.randf(rngState) * wp.tau) # [0; 2]
+    angle120  = angleInit + wp.float64(2.0943951023931953)
+    angle240  = angleInit + wp.float64(4.1887902047863905)
+
+    p0 = circumscribedCircleTriangleRadius * (wp.cos(angleInit) * u + wp.sin(angleInit) * v)
+    p1 = circumscribedCircleTriangleRadius * (wp.cos(angle120)  * u + wp.sin(angle120)  * v)
+    p2 = circumscribedCircleTriangleRadius * (wp.cos(angle240)  * u + wp.sin(angle240)  * v)
+
+    # Every vertex has its own uncertainty that we will add
+    p0 += wp.vec3d(wp.sample_unit_sphere(rngState)) * geometricalSpatialUncertainty
+    p1 += wp.vec3d(wp.sample_unit_sphere(rngState)) * geometricalSpatialUncertainty
+    p2 += wp.vec3d(wp.sample_unit_sphere(rngState)) * geometricalSpatialUncertainty
+
+    triangleNormal = wp.normalize(wp.cross(p1 - p0, p2 - p0))
+
+    # Should we flip the new normal to be sure it will
+	# point in the same direction as the original one?
+    flipFactor = wp.copysign(wp.float64(1.), wp.dot(triangleNormal, normal))
+    return flipFactor * triangleNormal
+
+@wp.func
+def _getCalibrationFactor(
+    channelID: wp.uint32,
+    noUncertainty: wp.bool,
+    rngState: wp.uint32) -> wp.float64:
+    # See Eq. S19 of Supplemental Document
+    # DOI: 10.6084/m9.figshare.31418393.v1
+
+    # The calibration factor corresponds to the second term in teal
+    # This one is independant of the measurement configuration. The
+    # two terms composing it are the numerator and the denominator.
+
+    if noUncertainty:
+        numerator   = spectralonReflectance / wp.float64(wp.pi)
+        denominator = calibrationFactorMean[channelID]
+        return colorBalance[channelID] * numerator / denominator
+
+    numerator   = spectralonReflectance * (wp.float64(1.) + spectralonStandardDev * wp.float64(wp.randn(rngState))) / wp.float64(wp.pi)
+    denominator = calibrationFactorMean[channelID] + calibrationFactorStd[channelID] * wp.float64(wp.randn(rngState))
+
+    return colorBalance[channelID] * numerator / denominator
+
+@wp.func
+def _getEdgeContribution(
+    x       : wp.vec3d,
+    p0Vertex: wp.vec3d,
+    p1Vertex: wp.vec3d) -> wp.vec3d:
+    # See Eq. 14 of Supplemental Document:
+    # DOI: 10.6084/m9.figshare.31418393.v1
+    v0 = wp.normalize(p0Vertex - x)
+    v1 = wp.normalize(p1Vertex - x)
+
+    cross = wp.normalize(wp.cross(v0, v1))
+
+    return wp.acos(wp.dot(v0, v1)) * cross
+
+@wp.func
+def _getGeometricVector(
+    x       : wp.vec3d,
+    p0Vertex: wp.vec3d,
+    p1Vertex: wp.vec3d,
+    p2Vertex: wp.vec3d,
+    p3Vertex: wp.vec3d) -> wp.vec3d:
+    # See Eq. S14 of Supplemental Document
+    # DOI: 10.6084/m9.figshare.31418393.v1
+    return (_getEdgeContribution(x, p0Vertex, p1Vertex) +
+            _getEdgeContribution(x, p1Vertex, p2Vertex) +
+            _getEdgeContribution(x, p2Vertex, p3Vertex) +
+            _getEdgeContribution(x, p3Vertex, p0Vertex))
+
+@wp.func
+def _getGeometricFactor(
+    initialLightCenter: wp.vec3d,
+    initialLightNormal: wp.vec3d,
+    initialTriangleCenter: wp.vec3d,
+    initialTriangleNormal: wp.vec3d,
+    noUncertainty: wp.bool,
+    rngState: wp.uint32) -> wp.float64:
+    # See Eq. S19 of Supplemental Document
+    # DOI: 10.6084/m9.figshare.31418393.v1
+
+    triangleNormal = _getTriangleNormal(initialTriangleNormal, noUncertainty, rngState)
+    lightNormal    = _getLEDNormal(initialLightNormal, noUncertainty, rngState)
+
+    if noUncertainty:
+        triangleCenter = initialTriangleCenter
+        lightCenter    = initialLightCenter
+        halfSizeLED    = sizeLEDSide * wp.float64(0.5)
+
+        # LED corners (deterministic)
+        u, v = _branchlessONB(lightNormal)
+        u *= halfSizeLED
+        v *= halfSizeLED
+        p0Light = lightCenter - u - v
+        p1Light = lightCenter + u - v
+        p2Light = lightCenter + u + v
+        p3Light = lightCenter - u + v
+
+        # No surface sampling — use centers
+        lightPosition = lightCenter
+        xPosition     = triangleCenter
+    else:
+        triangleCenter = initialTriangleCenter + wp.vec3d(wp.sample_unit_sphere(rngState)) * reflectanceSpatialUncertainty
+        lightCenter    = initialLightCenter    + wp.vec3d(wp.sample_unit_sphere(rngState)) * uncertaintyLEDPosition
+        halfSizeLED    = (sizeLEDSide + wp.float64(2. * wp.randf(rngState) - 1.) * uncertaintyLEDSide) * wp.float64(0.5)
+
+        # LED corners
+        u = wp.cross(lightNormal, wp.vec3d(0., 0., 1.))
+        v = wp.cross(lightNormal, u)
+        u, v = _branchlessONB(lightNormal)
+        u *= halfSizeLED
+        v *= halfSizeLED
+        p0Light = lightCenter - u - v
+        p1Light = lightCenter + u - v
+        p2Light = lightCenter + u + v
+        p3Light = lightCenter - u + v
+
+        # Uniform sample on LED square
+        uv            = wp.vec2d(wp.vec2f(wp.randf(rngState), wp.randf(rngState)))
+        lightPosition = p0Light + wp.float64(2.) * u * uv[0] + wp.float64(2.) * v * uv[1]
+
+        # Uniform sample on equilateral triangle (centroid = triangleCenter)
+        a, b = _branchlessONB(triangleNormal)
+        a *= wp.float64(0.0002)
+        b *= wp.float64(0.0002)
+        T0 = triangleCenter - wp.float64(0.5) * a - wp.float64(wp.sqrt(3.) / 6.) * b
+        T1 = triangleCenter + wp.float64(0.5) * a - wp.float64(wp.sqrt(3.) / 6.) * b
+        T2 = triangleCenter           + wp.float64((wp.sqrt(3.) / 3.)) * b
+        ab = wp.vec2d(wp.sample_triangle(rngState))
+        xPosition = T0 * (wp.float64(1.) - ab[0] - ab[1]) + T1 * ab[0] + T2 * ab[1]
+
+    # Compute geometric vector
+    geometricVector = _getGeometricVector(xPosition, p0Light, p1Light, p2Light, p3Light)
+
+    # Compute direction from surface to light.
+    lightDirection = wp.normalize(lightPosition - xPosition)
+
+    return wp.abs(wp.dot(geometricVector, triangleNormal) * wp.abs(wp.dot(lightNormal, lightDirection)))
+
+@wp.func
+def _getBRDFValue(
+    pixelID      : wp.vec2ui,
+    channelID    : wp.uint32,
+    pixelValueLSB: wp.uint16,
+    exposureTimeS: wp.float64,
+
+    lightCenter   : wp.vec3d,
+    lightNormal   : wp.vec3d,
+    triangleCenter: wp.vec3d,
+    triangleNormal: wp.vec3d,
+
+    noUncertainty: wp.bool,
+    rngState: wp.uint32) -> wp.float64:
+
+    # Adding an uncertainty over the exposure time
+    # Let's take the smallest camera tick possible
+    actualExposureS = exposureTimeS
+    if not noUncertainty:
+        actualExposureS = exposureTimeS + cameraSmallestTick * wp.float64((2. * wp.randf(rngState) - 1.))
+        actualExposureS = wp.max(actualExposureS, cameraSmallestTick)
+
+    # Compute the flat field correction with uncertainty
+    flatFieldCorrection = _getFlatFieldCorrection(pixelID, channelID, noUncertainty, rngState)
+
+    # Compute the pixel value with uncertainty
+    pixelValueLSBf = _getPixelValue(wp.float64(pixelValueLSB), actualExposureS, noUncertainty, rngState)
+
+    # f_# number (or aperture) squared
+    # is supposed without uncertainty.
+    apertureSquared = wp.float64(64.) # 8²
+
+    # Compute the uncertainty of the calibration factor
+    calibrationFactor = _getCalibrationFactor(channelID, noUncertainty, rngState)
+
+    # Compute the geometric factor
+    geometricFactor = _getGeometricFactor(lightCenter, lightNormal, triangleCenter, triangleNormal, noUncertainty, rngState)
+
+    # See Eq. S19 of Supplemental Document
+    # DOI: 10.6084/m9.figshare.31418393.v1
+    BRDF = (pixelValueLSBf / flatFieldCorrection) * apertureSquared * calibrationFactor / (actualExposureS * geometricFactor)
+    return BRDF

pycoupole/core/_kernels.py

@@ -0,0 +1,55 @@
+import warp as wp
+
+from ._functions import _getBRDFValue
+
+
+@wp.kernel
+def _sampleBRDF(
+    pixelID:                wp.vec2ui,
+    channelID:              wp.uint32,
+    pixelValueLSB:          wp.uint16,
+    exposureTimeS:          wp.float64,
+    lightCenter:            wp.vec3d,
+    lightNormal:            wp.vec3d,
+    triangleCenter:         wp.vec3d,
+    triangleNormal:         wp.vec3d,
+    removeAllUncertainties: wp.bool,
+    seed:                   int,
+    samples:                wp.array(dtype=wp.float64)
+):
+    ID = wp.tid()
+    rngState = wp.rand_init(seed, ID)
+
+    samples[ID] = _getBRDFValue(pixelID, channelID, pixelValueLSB, exposureTimeS,
+                                lightCenter, lightNormal, triangleCenter, triangleNormal,
+                                removeAllUncertainties, rngState)
+
+@wp.kernel
+def _sampleBRDFDistribution(
+    pixelID:                wp.vec2ui,
+    channelID:              wp.uint32,
+    pixelValueLSB:          wp.uint16,
+    exposureTimeS:          wp.float64,
+    lightCenter:            wp.vec3d,
+    lightNormal:            wp.vec3d,
+    triangleCenter:         wp.vec3d,
+    triangleNormal:         wp.vec3d,
+    seed:                   int,
+    histogramMin:           wp.float64,
+    histogramMax:           wp.float64,
+    nbBins:                 wp.int32,
+
+    histogram:              wp.array(dtype=wp.int64),
+    nbAccepted:             wp.array(dtype=wp.int64),
+):
+    ID = wp.tid()
+    rngState = wp.rand_init(seed, ID)
+
+    brdf = _getBRDFValue(pixelID, channelID, pixelValueLSB, exposureTimeS,
+                         lightCenter, lightNormal, triangleCenter, triangleNormal,
+                         False, rngState)
+
+    if brdf >= histogramMin and brdf < histogramMax:
+        binID = wp.int32((brdf - histogramMin) / (histogramMax - histogramMin) * wp.float64(nbBins))
+        wp.atomic_add(histogram, binID, wp.int64(1))
+        wp.atomic_add(nbAccepted, 0, wp.int64(1))

pycoupole/core/_utils.py

@@ -0,0 +1,13 @@
+import warp as wp
+
+
+def _pickDevice(device):
+    if device is not None:
+        return device
+    return "cuda:0" if wp.is_cuda_available() else "cpu"
+
+def _vec3d(vec):
+    return wp.vec3d(float(vec[0]), float(vec[1]), float(vec[2]))
+
+def _vec2ui(vec):
+    return wp.vec2ui(int(vec[0]), int(vec[1]))

pycoupole/io.py

@@ -0,0 +1,104 @@
+import csv
+from pathlib import Path
+
+from .brdf import computeBRDFDeterministic, computeBRDFDistribution
+
+
+def _readRows(path, rows):
+    if rows is None:
+        wanted = None
+    elif isinstance(rows, int):
+        wanted = {rows}
+    else:
+        wanted = set(rows)
+
+    selected = []
+    with Path(path).open(newline="") as f:
+        reader = csv.DictReader(f)
+        for index, record in enumerate(reader):
+            if wanted is None or index in wanted:
+                selected.append((index, record))
+                if wanted is not None and len(selected) == len(wanted):
+                    break # stop early once every requested row is found
+
+    if wanted is not None and len(selected) != len(wanted):
+        found   = {index for index, _ in selected}
+        missing = sorted(wanted - found)
+        raise IndexError(f"CSV row(s) not found in {path}: {missing}")
+
+    return selected
+
+def _rowToKwargs(row):
+    return dict(
+        pixelID        = (int(row["i"]), int(row["j"])),
+        channelID      =  int(row["color"]),
+        pixelValueLSB  =  int(row["valuePixel"]),
+        exposureTimeS  =  float(row["exposure"]),
+        lightCenter    = (float(row["l.x"]),  float(row["l.y"]),  float(row["l.z"])),
+        lightNormal    = (float(row["nl.x"]), float(row["nl.y"]), float(row["nl.z"])),
+        triangleCenter = (float(row["x.x"]),  float(row["x.y"]),  float(row["x.z"])),
+        triangleNormal = (float(row["nt.x"]), float(row["nt.y"]), float(row["nt.z"])),
+    )
+
+
+def computeBRDFDeterministicFromCSV(path, rows=None, device=None):
+    """Run the deterministic BRDF estimate on selected rows of a measurement CSV
+
+    Parameters
+    ----------
+    path : str or pathlib.Path
+        Path to the measurement CSV.
+    rows : int, iterable of int, or None, default None
+        Zero-based data-row indices to process. A single int processes one row;
+        None processes every row.
+    device : str, optional
+        Warp device string. Defaults to the first available CUDA device,
+        falling back to CPU.
+
+    Returns
+    -------
+    list of (int, float)
+        Pairs of (row index, BRDF value in sr^-1), in increasing index order.
+
+    Notes
+    -----
+    This runs one single-thread GPU launch per row, which is convenient but not
+    efficient for very large files. A GPU parallelized version may be done soon
+    """
+
+    return [(index, computeBRDFDeterministic(device=device, **_rowToKwargs(record)))
+           for index, record in _readRows(path, rows)]
+
+
+def computeBRDFDistributionFromCSV(path, row, device=None, **kwargs):
+    """Run the Monte Carlo BRDF distribution on a single row of a measurement CSV.
+
+    Unlike the deterministic helper, this accepts exactly one row: a single
+    distribution already saturates the GPU, and per-row results are typically
+    inspected or stored individually rather than aggregated.
+
+    Parameters
+    ----------
+    path : str or pathlib.Path
+        Path to the measurement CSV.
+    row : int
+        Zero-based data-row index to process.
+    device : str, optional
+        Warp device string. Defaults to the first available CUDA device,
+        falling back to CPU.
+    **kwargs
+        Forwarded to `computeBRDFDistribution` (e.g. nbBins, batchSize, seed).
+
+    Returns
+    -------
+    dict
+        The distribution dict returned by `computeBRDFDistribution`
+        (keys: pdf, brdfValues, nbTotal, nbAccepted).
+    """
+
+    if not isinstance(row, int):
+        raise TypeError("computeBRDFDistributionFromCSV processes single row; got"
+                       f" {type(row).__name__}. Loop in Python for multiple rows.")
+
+    (_, record), = _readRows(path, row)
+    return computeBRDFDistribution(device=device, **_rowToKwargs(record), **kwargs)

pycoupole-0.1.0.dist-info/METADATA

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: pycoupole
+Version: 0.1.0
+Summary: GPU-accelerated Monte Carlo uncertainty quantification for SVBRDF measurements on the La Coupole setup. Companion code to the associated Optics Express paper and dataset.
+Author-email: François Margall <francois.margall@inria.fr>
+License-Expression: MIT
+Project-URL: Homepage, https://lacoupole.gitlabpages.inria.fr
+Project-URL: Repository, https://gitlab.inria.fr/lacoupole/pycoupole
+Project-URL: Tracker, https://gitlab.inria.fr/lacoupole/pycoupole/-/boards
+Project-URL: Article, https://doi.org/10.1364/OE.587877
+Project-URL: Supplemental, https://doi.org/10.6084/m9.figshare.31418393.v1
+Keywords: monte-carlo,nvidia,uncertainty,metrology,warp,brdf,gum,coupole
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Development Status :: 5 - Production/Stable
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: warp-lang>=1.14.0
+Dynamic: license-file
+
+# PyCoupole
+
+GPU-accelerated Monte Carlo uncertainty quantification for SVBRDF measurements
+on the La Coupole setup. Companion code to the associated Optics Express paper
+and measured dataset.
+
+## Interpreting the output
+
+`computeBRDFDistribution` returns a probability density, not a histogram of
+counts. The density carries the inverse unit of the BRDF (sr), and integrates
+to 1 over its support — so its values are not bounded by 1 and will be large
+for a sharply peaked distribution. Recover the per-bin probability mass, then
+the moments and credible intervals, as:
+
+```python
+binWidth = brdfValues[1] - brdfValues[0]
+mass     = pdf * binWidth                    # sums to 1
+
+mean   = float(np.sum(mass * brdfValues))
+std    = float(np.sqrt(np.sum(mass * (brdfValues - mean) ** 2)))
+
+cdf      = np.cumsum(mass)
+median   = float(np.interp(0.50,  cdf, brdfValues))
+ci95_low = float(np.interp(0.025, cdf, brdfValues))
+ci95_up  = float(np.interp(0.975, cdf, brdfValues))
+```
+
+For a well-conditioned acquisition the deterministic value sits near the centre
+of the distribution and the out-of-range fraction (`1 - nbAccepted / nbTotal`)
+is negligible.
+
+
+## Citation
+If you use this software, please cite the associated paper as below (see also [CITATION.cff](./CITATION.cff)).
+
+> **La Coupole: an SVBRDF measurement device for large and non-planar objects**.
+> *Antoine Lucat, Pierre Mézières, François Margall, Louis De Oliveira,
+> Marjorie Paillet, Arnaud Tizon, Pierre Bénard, Romain Pacanowski*.
+> Optics Express, Vol. 34, Issue 7, pp. 11695-11709 (March 2026).
+> DOI: [10.1364/OE.587877](https://doi.org/10.1364/OE.587877).
+
+<details>
+<summary>Associated BibTeX entry</summary>
+
+```bibtex
+@article{Lucat:26,
+  author    = {Antoine Lucat and Pierre M\'{e}zi\`{e}res and Fran\c{c}ois Margall and Louis De Oliveira and Marjorie Paillet and Arnaud Tizon and Pierre B\'{e}nard and Romain Pacanowski},
+  journal   = {Optics Express},
+  keywords  = {Camera calibration; Imaging systems; Light sources; Physiology; Printed circuit boards; Spatial resolution},
+  number    = {7},
+  pages     = {11695--11709},
+  publisher = {Optica Publishing Group},
+  title     = {La Coupole: an SVBRDF measurement device for large and non-planar objects},
+  volume    = {34},
+  month     = {Apr},
+  year      = {2026},
+  url       = {https://opg.optica.org/oe/abstract.cfm?URI=oe-34-7-11695},
+  doi       = {10.1364/OE.587877},
+}
+```
+
+</details>
+
+> [!note]
+> For a detailed derivation of the uncertainty estimation method, including assumptions, propagation steps, and validation, see Section 3 (pp. 14–20) of the associated Supplemental Material (DOI: [10.6084/m9.figshare.31418393.v1](https://doi.org/10.6084/m9.figshare.31418393.v1)).
+
+## License
+
+PyCoupole is distributed under the MIT License. See [LICENSE.txt](./LICENSE.txt) for more information.

pycoupole-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pycoupole/__init__.py,sha256=qoENccDZLPKvQ5mRVzpOzg2iH74FHqFsZEPUJHEMcSA,514
+pycoupole/brdf.py,sha256=TVLZ4oAOk6sxmUrfd7kV66QzI3lhzfFnNKjq2EtCXQw,8204
+pycoupole/io.py,sha256=Ws9ArBj5ojAmCdlI7v9sq89gZdZeXz9SDNOTht9zP5A,3745
+pycoupole/core/_functions.py,sha256=Qsuslc0JBWZ5yIdDpiJdKrMzrKBpreT4TAVgKdan_rA,15466
+pycoupole/core/_kernels.py,sha256=PEiF7AzXWjq65dOKhvQUD8max-0zN7V9wg-wJEx8nMQ,1947
+pycoupole/core/_utils.py,sha256=ZDo2137qofd1asFBRrFJaEHSeRFvA2n80J8Ja3T00fA,300
+pycoupole-0.1.0.dist-info/licenses/LICENSE.txt,sha256=9jZf9VltRyFXHRifPQbC-HO4PjUTawjmHEiqIc_SYjw,1074
+pycoupole-0.1.0.dist-info/METADATA,sha256=Hfykaxdedboj_e0jI4IuwUvXDKS5vWxZz1S4YZAlsCg,3989
+pycoupole-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pycoupole-0.1.0.dist-info/top_level.txt,sha256=sSK5XteiSw6vOUDLQCb2_o3zZAhBESQ7QDbk5X_zBXY,10
+pycoupole-0.1.0.dist-info/RECORD,,

pycoupole-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pycoupole-0.1.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MARGALL François
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pycoupole-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pycoupole