Metadata-Version: 2.4
Name: occlusion-geometry
Version: 0.1.0
Summary: Exact analytical occlusion判定 for convex geometries
Author: Occlusion Geometry Team
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

Exact analytical occlusion判定 for convex geometries.

## Overview

This library provides exact analytical methods for determining if convex geometric bodies are fully occluded by spherical occluders from a point observer's viewpoint.

The core insight is that for a convex body B to be fully occluded by a sphere S from observer A, B must be completely contained within the "shadow cone" (umbra) formed by A and S.

For cylinders, the library implements the exact quartic equation method derived in the accompanying paper, which reduces the occlusion problem to finding roots of a quartic polynomial via the companion matrix method.

## Key Features

- **Exact analytical判定**: No approximations or sampling for cylinder occlusion
- **Quartic equation solver**: Companion matrix eigenvalue method for numerical stability
- **Multiple geometry support**: Cylinders, cones, cuboids, prisms, frustums, and generic convex bodies
- **Coordinate transformations**: Automatic alignment to standard cone-oriented frame
- **Comprehensive testing**: Numerical validation against dense ray sampling

## Installation

```bash
pip install -e .
```

## Quick Start

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

# Define observer, occluder, and occluded body
observer = Point([0, 0, 0])
sphere = Sphere([0, 0, -10], 5)
cylinder = Cylinder([0, 0, -15], [0, 0, 1], 2, 5)

# Check occlusion
is_occluded = is_fully_occluded(observer, sphere, cylinder)
print(f"Cylinder is {'occluded' if is_occluded else 'visible'}")
```

## Mathematical Background

### Shadow Cone (Umbra)

For a spherical occluder with center C and radius R, viewed from observer position A, the shadow cone (umbra) is defined by:

- **Apex**: Observer position A
- **Axis**: Unit vector from A toward C
- **Half-angle**: α = arcsin(R / |AC|)

### Cylinder Occlusion Criterion

For a cylinder to be fully occluded, both its circular edges must be completely inside the shadow cone. For each circular edge:

1. Parameterize the circle: P(φ) = C + R·(u·cos(φ) + v·sin(φ))
2. Find the point with maximum angle to cone axis by solving f'(φ) = 0
3. Using Weierstrass substitution s = tan(φ/2), this becomes a quartic equation
4. The cylinder is occluded if the maximum angle ≤ cone half-angle for both edges

### Quartic Equation

The critical points are found by solving:
```
p4·s^4 + p3·s^3 + p2·s^2 + p1·s + p0 = 0
```

Where coefficients are derived from geometric parameters (see paper for full derivation).

## API Reference

### Primitives

- `Point(position)`: 3D point observer
- `Sphere(center, radius)`: Spherical occluder
- `Cylinder(center, axis, radius, height)`: Cylindrical body
- `ConeBody(apex, base_center, base_radius)`: Conical body
- `Cuboid(center, axes, dimensions)`: Rectangular box
- `Prism(center, axis, n_sides, circumradius, height)`: Regular N-sided prism
- `Frustum(bottom_center, top_center, bottom_radius, top_radius, n_sides)`: Truncated pyramid
- `ConvexBody(vertices, support_func)`: Generic convex body

### Main Function

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

Returns `True` if body is fully occluded by sphere from observer's viewpoint.

## Testing

Run tests with pytest:

```bash
pytest tests/ -v
```

### Numerical Validation

The analytical判定 for cylinders is validated against dense ray sampling (ground truth) with 10,000+ random configurations. The判定 matches ground truth 100% within numerical tolerance.

## Project Structure

```
occlusion-geometry/
├── src/occlusion_geometry/
│   ├── primitives/      # Geometric primitives
│   ├── core/            # Core algorithms (shadow cone, quartic solver)
│   ├── analytic/        # Analytical判定 for each geometry
│   ├── transforms/      # Coordinate transformations
│   └── occlusion.py     # Unified API
├── tests/
│   ├── numerical/       # Numerical validation tests
│   └── test_*.py        # Unit tests
└── benchmarks/          # Performance benchmarks
```

## License

MIT License

## Citation

If you use this library in your research, please cite the accompanying paper on analytical occlusion判定.
