Metadata-Version: 2.4
Name: pyviewfactor
Version: 1.1.0
Summary: "A lightweight open-source Python library for exact view-factor computations on polygonal meshes"
Home-page: https://gitlab.com/arep-dev/pyViewFactor/
Author: Mateusz BOGDAN, Edouard WALTHER
Author-email: mateusz.bogdan@arep.fr
License: MIT
Keywords: radiative-transfer,radiation,vtk,geometry,viewfactor,visibility
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: numba>=0.61
Requires-Dist: pyvista>=0.45
Dynamic: license-file

# PyViewFactor


<div align="center">
<img src="https://gitlab.com/arep-dev/pyViewFactor/-/raw/da36d4a0b08308009d9e71876091492ecb97d476/img/Logo%20pVF%20512x512%20v3%20transparent%20crop.png" alt="pvf_logo" width="256px"/>
</div>


> `pyViewFactor` is a lightweight open-source Python library for exact view-factor computations on polygonal meshes.
> It provides robust tools for:
> - geometric visibility analysis,
> - obstruction detection,
> - accurate view factor computation.

*Full documentation available at [arep-dev.gitlab.io/pyViewFactor](https://arep-dev.gitlab.io/pyViewFactor/).*


<img src="https://gitlab.com/arep-dev/pyViewFactor/-/raw/3d40d1804eccbaefbc8b1736ff30d0d9f08141ad/img/FF_sceneUrbaine_cyl_RT.png" alt="Urban View Factor" width="800" />

 [![Latest Release](https://gitlab.com/arep-dev/pyViewFactor/-/badges/release.svg)](https://gitlab.com/arep-dev/pyViewFactor/-/releases)
 [![pipeline status](https://gitlab.com/arep-dev/pyViewFactor/badges/main/pipeline.svg)](https://gitlab.com/arep-dev/pyViewFactor/pipelines)
 [![codecov](https://codecov.io/gl/arep-dev/pyViewFactor/graph/badge.svg?token=HPHU835UZ8)](https://codecov.io/gl/arep-dev/pyViewFactor)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Pypi Version](https://img.shields.io/pypi/v/pyviewfactor)](https://pypi.org/project/pyviewfactor/)
 [![Pypi Downloads](https://img.shields.io/pypi/dm/pyviewfactor.svg?label=pypi%20downloads)](https://pypi.org/project/pyviewfactor/)
 [![status](https://joss.theoj.org/papers/cc7d3aebf5e8ed25b343c6dd822f70b4/status.svg)](https://joss.theoj.org/papers/cc7d3aebf5e8ed25b343c6dd822f70b4)


## Features

* This library enables the computation of radiation view factors between planar polygons using an **accurate** double‐contour integration method described in
[(Mazumder and Ravishankar 2012)](https://www.academia.edu/download/77459051/Viewfactor_paper_IJHMT.pdf)
with insights from [(Schmid 2016)](https://hal.archives-ouvertes.fr/tel-01734545/).
* It uses the handy [`Pyvista`](https://docs.pyvista.org/) package to deal with geometry imports (`*.stl`, `*.vtk`, `*.obj`, ...),
geometry creations, and some other mesh functionalities under the hood. 
* It enables:
    - 🔺 View factor computation between planar polygons via the **SA-30 semi-analytic kernel** — handles touching and coplanar faces analytically, no epsilon shift
    - 👁️ Visibility checks based on face orientation
    - 🚧 Obstruction detection using Möller–Trumbore ray-triangle intersection, **BVH-accelerated** (O(log N) per ray)
    - ⚙️ Strict / non-strict modes for robustness control
    - ⚡ Full N×N view-factor matrix with Numba `prange` parallelism (~33× faster than v1.0)
    - 📦 Built on `numpy`, `scipy`, `pyvista`, `numba`



## Installation
`pyViewFactor` can be installed from [PyPi](https://pypi.org/project/pyviewfactor/) 
using `pip` on Python >= 3.10:
```shell
pip install pyviewfactor
```
You can also visit [PyPi](https://pypi.org/project/pyviewfactor/) or
[Gitlab](https://gitlab.com/arep-dev/pyViewFactor) to download the sources.

Requirements: 
```
numpy==1.26.4
pyvista==0.45
scipy==1.11.4
numba==0.61.2
tqdm==4.65.0

```
The code will probably work with lower versions of the required packages, however this has not been tested.

> [!NOTE]
> `numba` is optional but strongly recommended. Without it, all kernels fall back to sequential pure-Python with identical results — no need to pin an older version.


## Quick Start

Suppose we want to compute the radiation view factor between a triangle
and a rectangle facing each other:

<img src="https://gitlab.com/arep-dev/pyViewFactor/-/raw/9dbd31d124eb898cc5d17913cfc1f010116e2245/img/mwe.png" alt="Triangle and rectangle configuration" width="260"/>

You are few lines of code away from your first view factor computation:

```python
import pyvista as pv
import pyviewfactor as pvf

# Create a rectangle and a triangle facing each other
pointa1 = [0.0, 0.0, 0.0]
pointb1 = [1.0, 0.0, 0.0]
pointc1 = [0.0, 1.0, 0.0]
rectangle = pv.Rectangle([pointa1, pointb1, pointc1])

pointa2 = [0.0, 0.0, 1.0]
pointb2 = [0.0, 1.0, 1.0]
pointc2 = [1.0, 1.0, 1.0]
triangle = pv.Triangle([pointa2, pointb2, pointc2])

if pvf.get_visibility(rectangle, triangle)[0]:
    F = pvf.compute_viewfactor(triangle, rectangle)
    print("VF from rectangle to triangle :", F)
else:
    print("Not facing each other")

pl = pv.Plotter()
pl.add_mesh(rectangle, color="lightblue", opacity=0.7)
pl.add_mesh(triangle, color="salmon", opacity=0.7)

# compute and glyph normals for mesh1
n1 = rectangle.compute_normals(cell_normals=True, point_normals=False)
arrows1 = n1.glyph(orient="Normals", factor=0.1)
pl.add_mesh(arrows1, color="blue")
# similarly for mesh2
n2 = triangle.compute_normals(cell_normals=True, point_normals=False)
arrows2 = n2.glyph(orient="Normals", factor=0.1)
pl.add_mesh(arrows2, color="darkred")

pl.show()
```

You want to import your own geometry from a different format? 
(`*.dat`, `*.idf`, `*.stl`,  ...)

Check pyvista's documentation on [how to generate a PolyData facet from points](https://docs.pyvista.org/examples/00-load/create-poly.html).

## Documentation

For detailed explanations and advanced usage, see:

https://arep-dev.gitlab.io/pyViewFactor/

The documentation includes:
* Theory: view factor integral, SA-30 semi-analytic kernel, BVH obstruction engine,
* Implementation: architecture, visibility & obstruction semantics, performance guide,
* Extended examples with analytical validations.


## Citation & Acknowledgments
* Main contributors:
    * Mateusz BOGDAN,
    * Edouard WALTHER.
* Acknowledgment: The authors would like to acknowledge *M. Alecian* for his initial work on the quadrature
code and *M. Chapon* for her contribution to the code validation.

There is even a [conference paper](https://www.researchgate.net/publication/360835982_Calcul_des_facteurs_de_forme_entre_polygones_-Application_a_la_thermique_urbaine_et_aux_etudes_de_confort), showing analytical validations. 

So if you use `pyViewFactor` in your work, please cite:
> [!IMPORTANT] Citation:
> Mateusz BOGDAN, Edouard WALTHER, Marc ALECIAN and Mina CHAPON. *Calcul des facteurs de forme entre polygones - Application à la thermique urbaine et aux études de confort*. IBPSA France 2022, Châlons-en-Champagne. 

Bibtex entry:
``` latex
@inproceedings{pyViewFactor22bogdan,
  author       = "Mateusz BOGDAN and Edouard WALTHER and Marc ALECIAN and Mina CHAPON",
  title        = "Calcul des facteurs de forme entre polygones - Application à la thermique urbaine et aux études de confort",
  year         = "2022",
  organization = "IBPSA France",
  venue        = "Châlons-en-Champagne, France"
  note         = "IBPSA France 2022",
}
```

## License
MIT License - Copyright (c) AREP 2025
