API Navigation Guide

Overview

The Tracker Component Library provides 1,070+ functions across 153 modules. This guide shows how to discover and use them effectively.

Key Resources:

API Documentation: Auto-generated from docstrings (API Reference)
Architecture Guide: Module organization and structure (Library Architecture)
Examples: Working code in examples/ folder
Tutorials: Interactive notebooks in docs/notebooks/

Quick Discovery Methods

Method 1: Python `help()` and `dir()`

Explore module contents:

import pytcl

# List all modules
print(dir(pytcl))

# List functions in a submodule
from pytcl import coordinate_systems
print([x for x in dir(coordinate_systems) if not x.startswith('_')])

# Get help on a function
from pytcl.coordinate_systems import sphere2cart
help(sphere2cart)  # Shows docstring, signature, examples

Output shows:

Function signature with type hints
Docstring describing what it does
Parameters and return values
Usage examples (often included)

Method 2: Interactive Discovery

Use IDE autocomplete:

from pytcl.dynamic_estimation import kalman
kalman.  # Press Tab - shows all available functions
# kf_predict, kf_update, extended_kalman_filter, etc.

Use Jupyter notebook autocomplete:

import pytcl.coordinate_systems.rotations as rot
rot.euler  # Press Tab
# Suggestions: euler2dcm, euler2quat, euler_rate2body_rate, etc.

Method 3: Search Functions by Category

Find functions related to a task:

# All Kalman filter variants
from pytcl.dynamic_estimation import kalman
print([x for x in dir(kalman) if 'kalman' in x.lower()])
# extended_kalman_filter, unscented_kalman_filter, cubature_kalman_filter

# All coordinate conversions
from pytcl.coordinate_systems import conversions
print([x for x in dir(conversions) if '2' in x])
# cart2sphere, sphere2cart, cart2pol, pol2cart, etc.

Method 4: Search Documentation Online

Browse Sphinx API docs:

Visit the documentation at https://readthedocs.org/ and search:

Click “API” in the navigation
Click a module name (e.g., kalman)
Browse all functions with full documentation

Common Discovery Workflows

Workflow 1: “I need to do Kalman filtering”

Step 1: Visit API Reference and search for “kalman”

Step 2: See available filters:

kf_predict, kf_update - Linear Kalman filter
extended_kalman_filter - Nonlinear (using Jacobians)
unscented_kalman_filter - Nonlinear (using sigma points)
cubature_kalman_filter - Deterministic points
imm_filter - Multiple model

Step 3: Pick the right one:

# Linear system → use standard KF
from pytcl.dynamic_estimation.kalman import kf_predict, kf_update

# Nonlinear, need Jacobian → use EKF
from pytcl.dynamic_estimation.kalman import extended_kalman_filter

# Nonlinear, don't want Jacobian code → use UKF
from pytcl.dynamic_estimation.kalman import unscented_kalman_filter

Step 4: See tuning guide at Kalman Filter Tuning Guide

Workflow 2: “I need coordinate conversion”

Step 1: Find what conversions are available:

from pytcl.coordinate_systems import conversions

# List all conversion functions
funcs = [x for x in dir(conversions) if not x.startswith('_')]
print(funcs)
# Output: ['cart2cyl', 'cart2pol', 'cart2ruv', 'cart2sphere',
#          'cyl2cart', 'pol2cart', 'ruv2cart', 'sphere2cart',
#          'ecef2enu', 'enu2ecef', 'ecef2geodetic', ...]

Step 2: Match your need:

# Cartesian to spherical coordinates
from pytcl.coordinate_systems.conversions import cart2sphere

# ECEF (Earth-Centered Earth-Fixed) to geodetic
from pytcl.coordinate_systems.conversions import ecef2geodetic

# East-North-Up to Cartesian
from pytcl.coordinate_systems.conversions import enu2ecef

Step 3: Use it:

import numpy as np
cart_coords = np.array([1.0, 0.0, 0.0])
spherical = cart2sphere(cart_coords)
print(spherical)  # [1., 0., 0.] (range, azimuth, elevation)

Workflow 3: “I need data association”

Step 1: Look at assignment algorithms:

from pytcl.assignment import optimization

# Available methods
print(dir(optimization))
# assignment_nd, assignment_nd_sparse, murty_algorithm, etc.

Step 2: Understand when to use each:

# Small problems (< 500 assignments): any method works
from pytcl.assignment.optimization import assignment_nd
assignments = assignment_nd(cost_matrix)

# Large problems (> 1000): consider auction or sparse
from pytcl.assignment.optimization import assignment_nd
assignments = assignment_nd(cost_matrix, method='auction')

# Top-K solutions (need multiple options)
from pytcl.assignment.optimization import murty_algorithm
top_k_solutions = murty_algorithm(cost_matrix, k=5)

Step 3: See performance guide at Performance Optimization Guide

Workflow 4: “I need navigation functions”

Step 1: Browse navigation modules:

from pytcl.navigation import (
    geodesy,           # Great circle, rhumb line
    ins_gnss,          # INS/GNSS fusion
    ephemerides,       # Celestial bodies
    tdoa                # Time difference localization
)

Step 2: Pick the right module:

# Distance/bearing between lat/lon points
from pytcl.navigation.geodesy import great_circle_distance

# INS propagation with gravity
from pytcl.navigation.ins_gnss import ins_update

# Sun, Moon, planet positions
from pytcl.astronomical.ephemerides import get_sun_position

Step 3: Use it with coordinate conversions:

from pytcl.navigation.geodesy import great_circle_distance

# New York to London
nyc = np.array([40.7128, -74.0060])  # lat, lon
london = np.array([51.5074, -0.1278])
distance = great_circle_distance(nyc, london)
print(f"{distance / 1000:.1f} km")  # ~5570 km

Function Naming Conventions

Conversion Functions: source2destination

cart2sphere      # Cartesian → Spherical
sphere2cart      # Spherical → Cartesian
ecef2geodetic    # ECEF → Geodetic
ecef2enu         # ECEF → East-North-Up
euler2dcm        # Euler angles → Direction Cosine Matrix

Prediction/Update: verb_noun

kf_predict, kf_update           # Kalman filter
ekf_predict, ekf_update         # Extended Kalman filter
particle_filter_predict         # Particle filter

Property/Getter Functions: get_noun or compute_noun

get_sun_position()              # Astronomy
compute_distance()              # Math
get_magnetic_field()            # Geophysics

Check/Validate Functions: is_noun or check_noun

is_positive_definite()          # Utility
is_proper_rotation()            # Rotations

API Reference by Use Case

Multi-Target Tracking

Essential Functions:

# Tracking system
from pytcl.trackers.multi_tracker_gnn import GNNTracker

# Data structures
from pytcl.containers import TrackSet, Track

# Coordinate conversions
from pytcl.coordinate_systems.conversions import sphere2cart

# Filter (inside tracker)
from pytcl.dynamic_estimation.kalman import extended_kalman_filter

# Dynamic model
from pytcl.dynamic_models import f_constant_velocity, q_constant_velocity

# Data association (inside tracker, but useful for custom)
from pytcl.assignment.optimization import assignment_nd

# Performance evaluation
from pytcl.performance_evaluation.metrics import (
    nees, nis, cramer_rao_bound
)

See: Library Architecture section “Pattern 2: Multi-Target Tracking”

Navigation and Geomatics

Essential Functions:

# Geodetic calculations
from pytcl.navigation.geodesy import (
    geodetic2ecef, ecef2geodetic, great_circle_distance
)

# INS mechanization
from pytcl.navigation.ins_gnss import ins_update_discrete

# Coordinate frames
from pytcl.coordinate_systems.rotations import (
    euler2dcm, dcm2euler, quat2dcm
)

# Projections (map coordinates)
from pytcl.coordinate_systems.projections import (
    geographic2utm, utm2geographic
)

# Geophysical models
from pytcl.gravity import gravity_models
from pytcl.magnetism import magnetic_models
from pytcl.atmosphere import atmosphere_models

See: Library Architecture section “Pattern 3: INS/GNSS Navigation”

Satellite Operations

Essential Functions:

# Orbit propagation
from pytcl.astronomical.orbital_mechanics import propagate_kepler

# Reference frame transforms
from pytcl.astronomical.reference_frames import (
    ecef2eci, eci2ecef, apply_precession_nutation
)

# Ephemeris (planets, sun, moon)
from pytcl.astronomical.ephemerides import (
    get_sun_position, get_moon_position
)

# SGP4 (TLE propagation)
from pytcl.astronomical.sgp4 import sgp4_propagator

# Perturbations
from pytcl.astronomical.relativity import schwarzschild_correction

See: Library Architecture section “Pattern 4: Satellite Propagation”

Advanced Signal Processing

Essential Functions:

# CFAR detection
from pytcl.signal_processing.detection import cfar_1d, cfar_2d

# Filtering
from pytcl.signal_processing.filtering import (
    design_butterworth, apply_filter
)

# Optimal detection
from pytcl.signal_processing.optimal import (
    matched_filter, likelihood_ratio_test
)

# Special functions (for detection threshold calculation)
from pytcl.mathematical_functions.special_functions import marcum_q

Searching for Functions: Advanced Tips

Search by keyword using grep:

# Find all "distance" functions in the codebase
grep -r "def.*distance" pytcl/

# Find functions with "kalman" in name
grep -r "def kalman" pytcl/

Search in Jupyter:

# Find all functions containing "filter"
import pytcl
import inspect

def find_functions(keyword):
    for name in dir(pytcl):
        module = getattr(pytcl, name)
        if inspect.ismodule(module):
            for func_name in dir(module):
                if keyword.lower() in func_name.lower():
                    func = getattr(module, func_name)
                    if callable(func):
                        print(f"{name}.{func_name}")

find_functions("filter")

View function source code:

from pytcl.coordinate_systems import sphere2cart
import inspect

# View source
print(inspect.getsource(sphere2cart))

# Find where function is defined
print(inspect.getfile(sphere2cart))

Type Hints and Signatures

All functions have complete type hints:

from pytcl.coordinate_systems.conversions import cart2sphere
import inspect

sig = inspect.signature(cart2sphere)
print(sig)
# (cart_coords: NDArray[np.floating[Any]], ...) -> NDArray[np.floating[Any]]

# Understand the parameters
for param_name, param in sig.parameters.items():
    print(f"{param_name}: {param.annotation}")

Benefits:

IDE autocomplete shows expected types
Type checking (mypy, pyright) catches errors
Self-documenting code

Common Errors and Solutions

ImportError: No module named ‘pytcl.xxx’

Solution: Check the correct import path

# ❌ Wrong
from pytcl.kalman import kf_predict  # Module doesn't exist here

# ✅ Correct
from pytcl.dynamic_estimation.kalman import kf_predict

TypeError: Unexpected argument type

Solution: Check function signature

from pytcl.coordinate_systems.conversions import cart2sphere
help(cart2sphere)  # Shows expected types

# ❌ Wrong: function expects ndarray
cart2sphere([1.0, 0.0, 0.0])  # List instead of ndarray

# ✅ Correct
import numpy as np
cart2sphere(np.array([1.0, 0.0, 0.0]))

“Function not found” but you know it exists

Solution: Check alternative names

# Maybe it's in a different module
import pytcl

# Search all modules
for module_name in dir(pytcl):
    module = getattr(pytcl, module_name)
    if hasattr(module, 'your_function_name'):
        print(f"Found in pytcl.{module_name}")

Getting Help

In Python REPL:

from pytcl.dynamic_estimation.kalman import kf_predict

# View docstring
help(kf_predict)

# View signature
import inspect
print(inspect.signature(kf_predict))

In IPython/Jupyter:

from pytcl.dynamic_estimation.kalman import kf_predict

# View docstring in sidebar
kf_predict?

# View source code
kf_predict??

Online Resources:

API Reference - Full API reference
Library Architecture - Module organization
Kalman Filter Tuning Guide - Filter usage guide
GPU Acceleration Guide - GPU usage
examples/ - Working code samples
docs/notebooks/ - Interactive tutorials

API Patterns and Conventions

NumPy Arrays:

Most functions accept/return N-dimensional NumPy arrays:

import numpy as np

# Single value
result = func(np.array([1.0, 2.0, 3.0]))  # shape (3,)

# Multiple values
results = func(np.array([[1.0, 2.0, 3.0],
                         [4.0, 5.0, 6.0]]))  # shape (2, 3)

Return Values:

Most functions return named tuples or dataclasses for clarity:

from pytcl.dynamic_estimation.kalman import KalmanResult

result = kf_predict(x, P, F, Q)
# result.x = predicted state
# result.P = predicted covariance
# result.S = innovation covariance (if applicable)

Optional Parameters:

Many functions have optional parameters with sensible defaults:

from pytcl.assignment.optimization import assignment_nd

# Simple usage with default method
assignments = assignment_nd(cost_matrix)

# Advanced: specify method
assignments = assignment_nd(cost_matrix, method='hungarian')

Best Practices

Start with the highest-level API

✅ Use: from pytcl.trackers import GNNTracker

❌ Avoid: Implementing by combining 10 lower-level functions
Check examples for your use case

examples/ folder has code for: - Multi-target tracking - INS/GNSS navigation - Satellite operations - Signal processing
Use the type hints

✅ Enable mypy checking in your IDE

✅ Trust IDE autocomplete

❌ Don’t ignore type errors
Understand the math

✅ Reference Kalman Filter Tuning Guide for filter parameters

✅ Use Performance Optimization Guide for profiling

❌ Don’t guess at parameters
Profile before optimizing

✅ Use cProfile to find bottlenecks

✅ See Performance Optimization Guide for GPU acceleration

❌ Don’t prematurely optimize

API Navigation Guide

Overview

Quick Discovery Methods

Method 1: Python help() and dir()

Method 2: Interactive Discovery

Method 3: Search Functions by Category

Method 4: Search Documentation Online

Common Discovery Workflows

Workflow 1: “I need to do Kalman filtering”

Workflow 2: “I need coordinate conversion”

Workflow 3: “I need data association”

Workflow 4: “I need navigation functions”

Function Naming Conventions

API Reference by Use Case

Multi-Target Tracking

Navigation and Geomatics

Satellite Operations

Advanced Signal Processing

Searching for Functions: Advanced Tips

Type Hints and Signatures

Common Errors and Solutions

Getting Help

API Patterns and Conventions

Best Practices

See Also

Method 1: Python `help()` and `dir()`