occlusion-geometry 0.1.0

Exact analytical occlusion判定 for convex geometries

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

pip install -e .

Quick Start

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

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:

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判定.