occlusion-geometry 0.1.1

Exact and efficient occlusion determination for convex geometries under spherical occlusion

occlusion-geometry

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

pip install occlusion-geometry

Install for development

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

Quick Start

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

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:

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:

benchmarks/

Testing

Run the test suite:

pytest tests -v

Project Structure

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.

@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.