sstent/FitTrack_ReportGenerator
1
0
Fork 0
mirror of https://github.com/sstent/FitTrack_ReportGenerator.git synced 2025-12-06 08:01:40 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
3886dcb9ab9dea91a1ffe3d4515859f162d11061
FitTrack_ReportGenerator/initialspec.md
sstent 9e0bd322d3 feat: Initial implementation of FitTrack Report Generator 
This commit introduces the initial version of the FitTrack Report Generator, a FastAPI application for analyzing workout files.

Key features include:
- Parsing of FIT, TCX, and GPX workout files.
- Analysis of power, heart rate, speed, and elevation data.
- Generation of summary reports and charts.
- REST API for single and batch workout analysis.

The project structure has been set up with a `src` directory for core logic, an `api` directory for the FastAPI application, and a `tests` directory for unit, integration, and contract tests.

The development workflow is configured to use Docker and modern Python tooling.
2025-10-11 09:54:13 -07:00

8.6 KiB
Raw Blame History

Purpose

Perform deterministic workout analysis and generate reports/charts

Core Requirements

  • Analysis Capabilities

    • FIT/TCX/GPX file parsing
    • Power, heart rate, and speed analysis
    • Training metrics calculation (TSS, IF, NP)
    • Zone distribution analysis
    • Chart generation (power curves, elevation profiles)
    • docs defining each analysis function

  • Re-usable components

    • Parsing: Garmin_Analyser/parsers/file_parser.py::FileParser
    • Analysis: Garmin_Analyser/analyzers/workout_analyzer.py::WorkoutAnalyzer
    • Data Models: Garmin_Analyser/models/workout.py and Garmin_Analyser/models/zones.py
    • Reporting: Garmin_Analyser/visualizers/report_generator.py::ReportGenerator
    • Charting: Garmin_Analyser/visualizers/chart_generator.py::ChartGenerator
    • Power Estimation: Garmin_Analyser/analyzers/workout_analyzer.py::_estimate_power
    • Gear Estimation: Garmin_Analyser/utils/gear_estimation.py and Garmin_Analyser/analyzers/workout_analyzer.py::_analyze_gear

  • Version 1 List of analysis functions to implement:

    • FileParser.parse_file
      • Purpose: Parses FIT, TCX, and GPX files and extracts workout data into a structured WorkoutData object.
      • Inputs: file_path (str).
      • Outputs: A WorkoutData object.
    • WorkoutAnalyzer.analyze_workout
      • Purpose: Orchestrates the entire analysis process for a given workout.
      • Inputs: workout (WorkoutData object).
      • Outputs: A dictionary containing a comprehensive analysis of the workout.
    • ReportGenerator.generate_workout_report
      • Purpose: Generates a complete workout report in various formats (HTML, PDF, Markdown).
      • Inputs: analysis_data (dict), output_format (str).
      • Outputs: A generated report file.
    • ChartGenerator.generate_workout_charts
      • Purpose: Generates a suite of charts for a workout.
      • Inputs: analysis_data (dict).
      • Outputs: A set of chart files (e.g., PNG).
    • _calculate_summary_metrics
      • Purpose: Calculates core summary metrics for a workout, including duration, distance, average/max speed, average/max power, average/max heart rate, elevation gain, calories, work in kJ, normalized power, intensity factor, and training stress score.
      • Inputs: workout (WorkoutData object), estimated_power (Optional[List[float]]).
      • Outputs: A dictionary containing various summary metrics.
    • _analyze_power
      • Purpose: Analyzes power data to calculate average, max, min power, standard deviation, variability, normalized power, power zones, power spikes, and power distribution.
      • Inputs: workout (WorkoutData object), estimated_power (Optional[List[float]]).
      • Outputs: A dictionary with power analysis metrics.
    • _analyze_heart_rate
      • Purpose: Analyzes heart rate data to calculate average, max, min heart rate, standard deviation, heart rate zones, heart rate recovery (currently not implemented), and heart rate distribution.
      • Inputs: workout (WorkoutData object).
      • Outputs: A dictionary with heart rate analysis metrics.
    • _analyze_speed
      • Purpose: Analyzes speed data to calculate average, max, min speed, standard deviation, moving time, distance, speed zones, and speed distribution.
      • Inputs: workout (WorkoutData object).
      • Outputs: A dictionary with speed analysis metrics.
    • _analyze_elevation
      • Purpose: Analyzes elevation data to calculate elevation gain/loss, max/min elevation, average/max/min gradient, and climbing ratio.
      • Inputs: workout (WorkoutData object).
      • Outputs: A dictionary with elevation analysis metrics.
    • _detect_intervals
      • Purpose: Detects high-intensity intervals in the workout based on power values.
      • Inputs: workout (WorkoutData object), estimated_power (Optional[List[float]]).
      • Outputs: A list of dictionaries, each representing an interval with start/end indices, duration, average/max power, and type.
    • _calculate_zone_distribution
      • Purpose: Calculates the time spent in different power, heart rate, and speed training zones.
      • Inputs: workout (WorkoutData object), estimated_power (Optional[List[float]]).
      • Outputs: A dictionary with zone distributions for power, heart rate, and speed.
    • _calculate_efficiency_metrics
      • Purpose: Calculates efficiency metrics such as power-to-heart rate ratio and decoupling (power vs. heart rate drift).
      • Inputs: workout (WorkoutData object), estimated_power (Optional[List[float]]).
      • Outputs: A dictionary with efficiency metrics.
    • _calculate_normalized_power
      • Purpose: Calculates normalized power (NP) using a 30-second rolling average.
      • Inputs: power_values (List[float]).
      • Outputs: A float representing the normalized power.
    • _detect_power_spikes
      • Purpose: Detects power spikes in the data, defined as power values more than 2 standard deviations above the mean.
      • Inputs: power_values (List[float]).
      • Outputs: A list of dictionaries, each representing a spike with its index, power value, and deviation.
    • _calculate_power_distribution
      • Purpose: Calculates power distribution statistics, specifically the 5th, 25th, 50th, 75th, and 95th percentiles.
      • Inputs: power_values (List[float]).
      • Outputs: A dictionary with power percentile values.
    • _calculate_hr_distribution
      • Purpose: Calculates heart rate distribution statistics, specifically the 5th, 25th, 50th, 75th, and 95th percentiles.
      • Inputs: hr_values (List[float]).
      • Outputs: A dictionary with heart rate percentile values.
    • _calculate_speed_distribution
      • Purpose: Calculates speed distribution statistics, specifically the 5th, 25th, 50th, 75th, and 95th percentiles.
      • Inputs: speed_values (List[float]).
      • Outputs: A dictionary with speed percentile values.
    • _calculate_hr_recovery
      • Purpose: Placeholder for calculating heart rate recovery. Currently not implemented.
      • Inputs: workout (WorkoutData object).
      • Outputs: None.
    • _calculate_climbing_ratio
      • Purpose: Calculates the climbing ratio (elevation gain per kilometer).
      • Inputs: elevation_values (List[float]).
      • Outputs: A float representing the climbing ratio in m/km.
    • _analyze_gear
      • Purpose: Analyzes gear data to provide statistics such as time in top gear, top gears used, unique gear count, and gear distribution.
      • Inputs: workout (WorkoutData object).
      • Outputs: A dictionary with gear analysis metrics.
    • _analyze_cadence
      • Purpose: Analyzes cadence data to calculate average, max, min cadence, and standard deviation.
      • Inputs: workout (WorkoutData object).
      • Outputs: A dictionary with cadence analysis metrics.
    • _estimate_power
      • Purpose: Estimates power using a physics-based model for both indoor and outdoor workouts.
      • Inputs: workout (WorkoutData object), cog_size (int, default 16).
      • Outputs: A list of estimated power values (floats).
    • SinglespeedAnalyzer.analyze_gear_ratio
      • Purpose: Determines the most likely singlespeed gear ratio (chainring and cog combination) from speed, cadence, and gradient data. It also calculates related gear metrics like gear inches and development in meters.
      • Inputs:
        • speed_data: List of speed values.
        • cadence_data: List of cadence values.
        • gradient_data: List of gradient values.
      • Outputs: A dictionary containing the estimated gear ratio and related metrics.
    • PowerEstimator.estimate_peak_power
      • Purpose: Calculates peak power for various durations. (Currently a placeholder, marked for Phase 3 implementation).
      • Inputs: power_values (List[float]), durations (List[int]).
      • Outputs: A dictionary where keys are durations and values are corresponding peak power.

  • API Endpoints

    • POST /api/analyze/workout - Analyze single workout
    • POST /api/analyze/batch - Analyze multiple workouts
    • GET /api/analysis/{id}/charts - Generate charts
    • GET /api/analysis/{id}/summary - LLM-ready summary

  • Technical

    • CPU-intensive processing isolation

    • Support for existing GarminAnalyser codebase

    • Chart generation (PNG, HTML, PDF)

    • Standardized output format for LLM consumption

    • Result caching

    • Existing Code

    • Use @GarminAnalyser.md to pull code from the existing implementation

    • use @DB_API_SPEC.json to get the API spec for the CentralDB that will store the Activity files and artifacts that we create

Reference in New Issue View Git Blame Copy Permalink