bowling-analysis-system/README.md

A comprehensive system for analyzing bowling techniques using video processing and metrics calculation

# Bowling Metrics Processing Utilities

A comprehensive set of utilities for processing and validating bowling metrics time series data. This library provides functionality for normalizing, extracting, analyzing, and visualizing time series data with a focus on bowling metrics.

## Features

- **Time Series Data Extraction**: Extract specific metrics or segments between events
- **Left/Right Normalization**: Standardize left/right pair metrics with average calculations
- **Metrics Validation**: Validate metrics against required structure and events
- **Statistical Analysis**: Calculate key statistics for time series data
- **Visualization Configuration**: Generate configuration for charting time series data

## Installation

```bash
npm install
```

## Quick Start

```javascript
import { timeSeriesUtils, metricsValidator } from './src/utils';

// Load your metrics data
const metricsData = JSON.parse(fs.readFileSync('path/to/metrics.json', 'utf8'));

// Validate metrics
const validationResult = metricsValidator.validateMetrics(metricsData);
console.log(`Metrics validation: ${validationResult.isValid ? 'PASSED' : 'FAILED'}`);

// Extract time series data
const armAngles = timeSeriesUtils.extractByPath(metricsData, 'timeSeries.angles.armAngles');

// Calculate statistics
const stats = timeSeriesUtils.calculateStatistics(armAngles, true);
console.log('Left arm stats:', stats.left);
console.log('Right arm stats:', stats.right);
console.log('Average stats:', stats.average);

// Extract data between events
const dataSegment = timeSeriesUtils.extractBetweenEvents(
    metricsData,
    'timeSeries.angles.armAngles',
    'backFootLanding',
    'releasePoint'
);

// Create visualization config
const chartConfig = timeSeriesUtils.createVisualizationConfig(
    armAngles,
    {
        title: 'Arm Angles During Bowling',
        xLabel: 'Frame',
        yLabel: 'Angle (degrees)',
        hasLeftRight: true
    },
    metricsData.events
);
```

## Validation Rules

The `metricsValidator` module enforces the following validation rules:

- **Required Events**: `frontFootLanding`, `backFootLanding`, `releasePoint`
- **Required Categories**: `angles`, `position`, `velocity`
- **Structural Validation**: Consistent array lengths across time series
- **Left/Right Validation**: Proper format with left, right, and average properties

## Time Series Utilities

The `timeSeriesUtils` module provides the following key functions:

- `normalizeTimeSeries()`: Convert time series data to standard left/right/average format
- `extractByPath()`: Extract data from a nested object using dot notation
- `extractBetweenEvents()`: Extract time series data between two events
- `calculateStatistics()`: Calculate statistics for time series data
- `createVisualizationConfig()`: Create chart configuration for time series data
- `validateTimeSeriesStructure()`: Validate time series structure
- `discoverTimeSeriesMetrics()`: Find all available time series metrics

## Running Tests

```bash
npm test
```

## License

MIT

## Metrics Pipeline

The bowling analysis system processes keypoint data through a three-phase metrics pipeline:

1. **Phase One**: Calculates biomechanical metrics using various calculators (angles, position, velocity, power, balance, etc.)
2. **Phase Two**: Detects bowling events and calculates event-based metrics
3. **Phase Three**: Generates higher-level metrics for technique, efficiency, consistency, and performance

### Recent Improvements

The following improvements were made to the metrics pipeline:

1. Enhanced error handling in all processors to ensure logging operations don't throw errors
2. Fixed the calculators to directly return metrics with realistic values:
   - Updated `AngleCalculator` to return proper angle metrics
   - Updated `BalanceCalculator` to return balance-related metrics
   - Updated `PowerCalculator` to return power metrics
   - Updated `PositionCalculator` to return position metrics
3. Improved the metrics merging process to ensure all metrics are included in the final output
4. Fixed time series data handling to correctly generate and merge time series
5. Enhanced validation and reporting to ensure complete metrics output
6. **Consolidated redundant code** to improve maintainability (see [CODEBASE_CLEANUP.md](docs/CODEBASE_CLEANUP.md))
7. **Unified BiasCalculator implementation** to replace multiple deprecated implementations

### Usage

To run the metrics pipeline:

```
node run.js <keypoint_file> <output_file> [bias_file]
```

Example:
```
node run.js keypoint.json complete_metrics.json bias.json
```

The output file will contain:
- Metrics for each category (angles, position, velocity, etc.)
- Detected events (release point, foot landings, etc.)
- Time series data for visualization
- Analysis of the bowling technique
- Bias data for event detection