API Documentation

This page provides detailed documentation for developers who want to use Starship Analyzer's components in their own projects or extend the functionality.

Core Modules

OCR Module

ocr.py

Main functions for optical character recognition:

def extract_text_from_roi(frame, roi, lang='en'):
    """
    Extract text from a region of interest in a frame.
    
    Args:
        frame (numpy.ndarray): The video frame to process
        roi (tuple): Region of interest as (x, y, width, height)
        lang (str, optional): Language for OCR. Defaults to 'en'.
        
    Returns:
        str: The extracted text
    """

engine_detection.py

Functions for detecting engine status:

def detect_active_engines(frame, engine_coordinates, threshold=WHITE_THRESHOLD):
    """
    Detect which engines are active based on brightness.
    
    Args:
        frame (numpy.ndarray): The video frame to process
        engine_coordinates (dict): Dictionary of engine coordinates
        threshold (int, optional): Brightness threshold. Defaults to WHITE_THRESHOLD.
        
    Returns:
        dict: Dictionary with engine status (True/False for each engine)
    """

Processing Module

video_processing.py

Functions for processing video files:

def process_video(video_path, output_path, frame_interval=1, batch_size=10):
    """
    Process a video file to extract telemetry and engine data.
    
    Args:
        video_path (str): Path to the video file
        output_path (str): Path to save the extracted data
        frame_interval (int, optional): Process every Nth frame. Defaults to 1.
        batch_size (int, optional): Number of frames to process in parallel. Defaults to 10.
        
    Returns:
        str: Path to the saved data file
    """

Plotting Module

flight_plotting.py

Functions for creating visualizations:

def plot_velocity_vs_engines(data_file, output_dir, vehicle_type='superheavy'):
    """
    Create a plot showing velocity vs active engines.
    
    Args:
        data_file (str): Path to the data file
        output_dir (str): Directory to save the plot
        vehicle_type (str, optional): 'superheavy' or 'starship'. Defaults to 'superheavy'.
        
    Returns:
        str: Path to the saved plot file
    """

Constants and Configuration

constants.py

Key constants used throughout the application:

# Engine coordinates
SUPERHEAVY_ENGINES = {
    "central_stack": [(109, 970), (120, 989), (98, 989)],
    "inner_ring": [
        (102, 1018), (82, 1006), (74, 986), (78, 964), (94, 950),
        (116, 948), (136, 958), (144, 978), (140, 1000), (124, 1016)
    ],
    "outer_ring": [
        # ... coordinates omitted for brevity ...
    ]
}

# Threshold values
WHITE_THRESHOLD = 220  # Brightness threshold for engine detection

# Plotting parameters
ENGINE_TIMELINE_PARAMS = {
    # ... parameters omitted for brevity ...
}

Utility Functions

utils/validators.py

Input validation functions:

def validate_number(value):
    """
    Validate that a value can be converted to a number.
    
    Args:
        value (any): Value to validate
        
    Returns:
        bool: True if valid number, False otherwise
    """

def validate_positive_number(value):
    """
    Validate that a value can be converted to a positive number.
    
    Args:
        value (any): Value to validate
        
    Returns:
        bool: True if valid positive number, False otherwise
    """

utils/logger.py

Logging functions:

def get_logger(name):
    """
    Get a logger with the specified name.
    
    Args:
        name (str): Name for the logger
        
    Returns:
        logging.Logger: Configured logger
    """

def set_global_log_level(level):
    """
    Set the global logging level.
    
    Args:
        level (int or str): Log level to set
    """

Usage Examples

Using the Engine Detection API

import cv2
from utils.constants import SUPERHEAVY_ENGINES
from ocr.engine_detection import detect_active_engines

# Load a video frame
frame = cv2.imread('path/to/frame.jpg')

# Detect active engines
active_engines = detect_active_engines(frame, SUPERHEAVY_ENGINES)

# Print active engine count
print(f"Active engines: {sum(active_engines.values())}")

Processing a Video

from processing.video_processing import process_video

# Process a video file
data_file = process_video(
    video_path='flight_recordings/starship_flight5.mp4',
    output_path='results/',
    frame_interval=5,  # Process every 5th frame
    batch_size=10      # Process 10 frames in parallel
)

print(f"Data saved to: {data_file}")

Creating a Plot

from plot.flight_plotting import plot_velocity_vs_engines

# Create a velocity vs engines plot
plot_file = plot_velocity_vs_engines(
    data_file='results/starship_flight5_data.csv',
    output_dir='results/plots/',
    vehicle_type='superheavy'
)

print(f"Plot saved to: {plot_file}")

Extending the Application

To add new functionality to Starship Analyzer:

1. Create new modules in the appropriate directory
2. Update constants in constants.py if needed
3. Add imports to __init__.py files
4. Add menu options in the UI modules
5. Update tests to cover new functionality
6. Document your changes

Refer to the Contributing page for more information on development practices.