Metadata-Version: 2.4
Name: occlusion-geometry
Version: 0.1.1
Summary: Exact and efficient occlusion determination for convex geometries under spherical occlusion
Author: Wei Siyu, Zhao Xuanbing
License: MIT
Project-URL: Homepage, https://github.com/Bing-Yu-Research/occlusion-geometry
Project-URL: Documentation, https://github.com/Bing-Yu-Research/occlusion-geometry#readme
Project-URL: Repository, https://github.com/Bing-Yu-Research/occlusion-geometry
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: benchmark
Requires-Dist: matplotlib>=3.5.0; extra == "benchmark"
Requires-Dist: seaborn>=0.12.0; extra == "benchmark"
Requires-Dist: pandas>=1.3.0; extra == "benchmark"
Dynamic: license-file


# occlusion-geometry

[![PyPI version](https://img.shields.io/pypi/v/occlusion-geometry.svg)](https://pypi.org/project/occlusion-geometry/)
[![Python versions](https://img.shields.io/pypi/pyversions/occlusion-geometry.svg)](https://pypi.org/project/occlusion-geometry/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A Python library for exact analytical and geometry-exact occlusion determination for convex bodies under spherical occlusion.

## Overview

`occlusion-geometry` provides efficient and exact occlusion tests for the following setting:

- a **point observer** \(A\),
- a **spherical occluder** \(S\),
- a **convex target body** \(B\),
- and **pure geometric occlusion only** (no transparency, no radiometric effects).

The core idea is:

> A convex body \(B\) is fully occluded by a spherical occluder \(S\) from observer \(A\) if and only if \(B\) is fully contained in the shadow cone (umbra) induced by \(A\) and \(S\), together with the required depth ordering.

For cylindrical targets, this library implements an exact analytical criterion derived from a quartic equation.  
For polyhedral convex bodies, exact occlusion checking is performed through cone containment of the relevant extreme points.

This repository accompanies our research on fast and exact occlusion determination for convex geometries.

## Features

- **Exact analytical cylinder occlusion**
  - Reduces the continuous circle-extremum problem to quartic root finding.
- **Exact geometric occlusion for polyhedral convex bodies**
  - Includes cuboids, prisms, frustums, and vertex-defined convex bodies.
- **No sampling in core decision logic**
  - Sampling is used only in validation and benchmarking.
- **Efficient coordinate normalization**
  - Automatically transforms scenes into a cone-aligned frame.
- **Research-oriented implementation**
  - Includes tests, numerical validation, and benchmark scripts.

## Installation

### Install from PyPI

```bash
pip install occlusion-geometry
```

### Install for development

```bash
git clone https://github.com/Bing-Yu-Research/occlusion-geometry.git
cd occlusion-geometry
pip install -e .[dev]
```

## Quick Start

```python
from occlusion_geometry import Point, Sphere, Cylinder, is_fully_occluded

observer = Point([0.0, 0.0, 0.0])
sphere = Sphere([0.0, 0.0, -10.0], 5.0)
cylinder = Cylinder(
    center=[0.0, 0.0, -15.0],
    axis=[0.0, 0.0, 1.0],
    radius=2.0,
    height=5.0,
)

is_occluded = is_fully_occluded(observer, sphere, cylinder)
print(is_occluded)
```

### With diagnostic details

```python
result, details = is_fully_occluded(observer, sphere, cylinder, return_details=True)

print("Occluded:", result)
print(details)
```

## Supported Geometries

The current library supports:

- `Point`
- `Sphere`
- `Cylinder`
- `ConeBody`
- `Cuboid`
- `Prism`
- `Frustum`
- `ConvexBody`

Typical usage entry point:

```python
is_fully_occluded(observer, sphere, body, return_details=False)
```

## Mathematical Notes

### Shadow cone

Given observer \(A\) and spherical occluder \(S\) with center \(C\) and radius \(R\), the shadow cone is defined by:

- **apex**: \(A\)
- **axis**: direction from \(A\) to \(C\)
- **half-angle**:
  \[
  \alpha = \arcsin\left(\frac{R}{\|C-A\|}\right)
  \]

### Cylinder criterion

For a cylinder, full occlusion reduces to checking whether both circular boundary rims are fully contained in the shadow cone.

After parameterizing a circular rim,
\[
P(\phi)=C + R(u\cos\phi + v\sin\phi),
\]
the extremal angular condition can be reduced to a quartic polynomial in the Weierstrass variable
\[
s=\tan(\phi/2).
\]

This yields a closed-form algebraic decision pipeline rather than a sampling-based approximation.

## Validation and Benchmarks

The implementation has been extensively tested through:

- unit tests,
- randomized numerical validation,
- dense surface sampling cross-checks,
- adversarial near-boundary benchmarks.

In ordinary random scenes, sampling-based methods may appear competitive.  
However, in near-tangent and boundary-focused cases, analytical determination remains deterministic while sampling-based methods can suffer from discretization error.

Benchmark scripts are available in:

```text
benchmarks/
```

## Testing

Run the test suite:

```bash
pytest tests -v
```

## Project Structure

```text
occlusion-geometry/
├── src/occlusion_geometry/
│   ├── primitives/
│   ├── core/
│   ├── analytic/
│   ├── transforms/
│   └── occlusion.py
├── tests/
├── benchmarks/
└── README.md
```

## Citation

If you use this library in academic work, please cite the accompanying paper.

```bibtex
@misc{occlusion_geometry_2025,
  title={Exact Analytical Occlusion Determination for Convex Geometries under Spherical Occlusion},
  author={Bing-Yu Research Team},
  year={2025},
  note={Software available at https://github.com/Bing-Yu-Research/occlusion-geometry}
}
```

## License

This project is released under the MIT License.
