nrl-tracker 1.9.0__py3-none-any.whl → 1.9.2__py3-none-any.whl

pytcl/terrain/visibility.py

@@ -160,6 +160,20 @@ def line_of_sight(
     The refraction coefficient models atmospheric bending of radio waves.
     A typical value for radio frequencies is 0.13 (4/3 Earth model).
     For optical line of sight, use 0.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.terrain.dem import create_flat_dem
+    >>> dem = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119), elevation=100)
+    >>> result = line_of_sight(
+    ...     dem,
+    ...     np.radians(35.3), np.radians(-119.7), 10,
+    ...     np.radians(35.7), np.radians(-119.3), 10)
+    >>> result.visible  # Clear LOS over flat terrain
+    True
     """
     # Effective Earth radius for refraction
     if refraction_coeff > 0:
@@ -296,6 +310,19 @@ def viewshed(
     -------
     ViewshedResult
         Viewshed computation result with visibility grid.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.terrain.dem import create_flat_dem
+    >>> dem = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119), elevation=100)
+    >>> result = viewshed(
+    ...     dem, np.radians(35.5), np.radians(-119.5), 20,
+    ...     max_range=10000, n_radials=36, samples_per_radial=10)
+    >>> result.visible.any()  # Some cells visible
+    True
     """
     # Convert max range to angular distance
     max_angular_range = max_range / earth_radius
@@ -428,6 +455,19 @@ def compute_horizon(
     -------
     list of HorizonPoint
         Horizon points for each azimuth direction.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.terrain.dem import create_flat_dem
+    >>> dem = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119), elevation=100)
+    >>> horizon = compute_horizon(
+    ...     dem, np.radians(35.5), np.radians(-119.5), 10,
+    ...     n_azimuths=8, max_range=10000, samples_per_radial=10)
+    >>> len(horizon)
+    8
     """
     max_angular_range = max_range / earth_radius
 
@@ -534,6 +574,18 @@ def terrain_masking_angle(
     -------
     float
         Masking angle in radians above horizontal.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.terrain.dem import create_flat_dem
+    >>> dem = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119), elevation=100)
+    >>> angle = terrain_masking_angle(
+    ...     dem, np.radians(35.5), np.radians(-119.5), 10, azimuth=0)
+    >>> -np.pi/2 <= angle <= np.pi/2  # Valid angle range
+    True
     """
     max_angular_range = max_range / earth_radius
 
@@ -628,6 +680,19 @@ def radar_coverage_map(
     -------
     ViewshedResult
         Radar coverage map.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.terrain.dem import create_flat_dem
+    >>> dem = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119), elevation=100)
+    >>> coverage = radar_coverage_map(
+    ...     dem, np.radians(35.5), np.radians(-119.5), 30,
+    ...     max_range=20000, n_radials=36, samples_per_radial=20)
+    >>> coverage.visible.any()  # Some coverage exists
+    True
     """
     # Compute basic viewshed with refraction
     result = viewshed(

pytcl/trackers/hypothesis.py

@@ -208,6 +208,29 @@ def compute_association_likelihood(
     -------
     likelihood : float
         Joint likelihood of the association.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # 2 tracks, 2 measurements
+    >>> likelihood_matrix = np.array([[0.9, 0.1],
+    ...                                [0.1, 0.8]])
+    >>> # Association: track 0 -> meas 0, track 1 -> meas 1
+    >>> association = {0: 0, 1: 1}
+    >>> lik = compute_association_likelihood(
+    ...     association, likelihood_matrix,
+    ...     detection_prob=0.9, clutter_density=1e-6, n_meas=2
+    ... )
+    >>> lik > 0
+    True
+    >>> # Association with missed detection
+    >>> assoc_miss = {0: 0, 1: -1}  # track 1 misses
+    >>> lik_miss = compute_association_likelihood(
+    ...     assoc_miss, likelihood_matrix,
+    ...     detection_prob=0.9, clutter_density=1e-6, n_meas=2
+    ... )
+    >>> lik > lik_miss  # Full detection more likely
+    True
     """
     likelihood = 1.0
 
@@ -259,6 +282,31 @@ def n_scan_prune(
     committed_track_ids : set
         Track IDs that are now committed (survived N-scan).
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.trackers.hypothesis import (
+    ...     Hypothesis, MHTTrack, MHTTrackStatus, n_scan_prune
+    ... )
+    >>> # Two hypotheses, tracks with different creation scans
+    >>> track1 = MHTTrack(id=0, state=np.zeros(2), covariance=np.eye(2),
+    ...                   score=1.0, status=MHTTrackStatus.CONFIRMED,
+    ...                   history=[0], parent_id=-1, scan_created=0,
+    ...                   n_hits=3, n_misses=0)
+    >>> track2 = MHTTrack(id=1, state=np.zeros(2), covariance=np.eye(2),
+    ...                   score=0.5, status=MHTTrackStatus.TENTATIVE,
+    ...                   history=[1], parent_id=-1, scan_created=2,
+    ...                   n_hits=1, n_misses=0)
+    >>> tracks = {0: track1, 1: track2}
+    >>> hyp1 = Hypothesis(id=0, probability=0.8, track_ids=[0],
+    ...                   scan_created=0, parent_id=-1)
+    >>> hyp2 = Hypothesis(id=1, probability=0.2, track_ids=[1],
+    ...                   scan_created=2, parent_id=-1)
+    >>> pruned, committed = n_scan_prune([hyp1, hyp2], tracks, n_scan=2,
+    ...                                   current_scan=3)
+    >>> len(pruned) >= 1
+    True
+
     Notes
     -----
     N-scan pruning works by:
@@ -338,6 +386,23 @@ def prune_hypotheses_by_probability(
     -------
     pruned : list of Hypothesis
         Pruned and renormalized hypotheses.
+
+    Examples
+    --------
+    >>> from pytcl.trackers.hypothesis import Hypothesis, prune_hypotheses_by_probability
+    >>> # 5 hypotheses with varying probabilities
+    >>> hyps = [
+    ...     Hypothesis(id=0, probability=0.5, track_ids=[0], scan_created=0, parent_id=-1),
+    ...     Hypothesis(id=1, probability=0.3, track_ids=[1], scan_created=0, parent_id=-1),
+    ...     Hypothesis(id=2, probability=0.1, track_ids=[2], scan_created=0, parent_id=-1),
+    ...     Hypothesis(id=3, probability=0.05, track_ids=[3], scan_created=0, parent_id=-1),
+    ...     Hypothesis(id=4, probability=1e-8, track_ids=[4], scan_created=0, parent_id=-1),
+    ... ]
+    >>> pruned = prune_hypotheses_by_probability(hyps, max_hypotheses=3)
+    >>> len(pruned)  # Only top 3 kept
+    3
+    >>> sum(h.probability for h in pruned)  # Renormalized to 1
+    1.0
     """
     if not hypotheses:
         return []