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.
