# Impakt -- Project Status

**Date:** 2026-04-10
**Version:** 0.1.0
**Tests:** 136 passing, 0 warnings
**Source:** ~6,900 lines Python | ~1,600 lines tests | ~190 lines HTML templates
**Tooling:** uv (Python 3.12.12), hatchling build backend

---

## Quick Start

```bash
cd /Users/noise/Code/impakt
uv sync --dev          # install all dependencies
uv run pytest tests/   # run all 136 tests
uv run impakt info tests/mme_data/3239         # show test metadata
uv run impakt serve tests/mme_data/3239        # launch web UI on :8050
```

Scripting:
```python
from impakt import Session
s = Session.open("tests/mme_data/3239")
s.plot("11HEAD0000H3ACXP", "11HEAD0000H3ACYP", "11HEAD0000H3ACZP", cfc=1000)
```

---

## Repository Layout

```
impakt/
  pyproject.toml                # PEP 621 + uv dependency-groups
  uv.lock                      # lockfile
  README.md                    # Architecture docs with 16 Mermaid diagrams
  BRAINSTORM.md                # 80+ feature ideas
  docs/
    STATUS.md                  # <-- you are here
  src/impakt/
    __init__.py                # exports Session, Template
    channel/                   # Data model layer
      code.py                  #   ISO channel code parser (14-char + 16-char)
      model.py                 #   Channel, ChannelGroup, TestData, TestMetadata
      group.py                 #   Auto-grouping utilities
      lookup.py                #   ISO naming lookup tables (150+ entries)
    io/                        # I/O layer
      reader.py                #   ReaderProtocol, ReaderRegistry
      mme.py                   #   MMEReader (real ISO 13499 + synthetic INI)
    transform/                 # Signal processing
      base.py                  #   Transform protocol, TransformChain
      cfc.py                   #   SAE J211 CFC filter (60/180/600/1000)
      align.py                 #   X-align (time-zero), Y-align (offset)
      resultant.py             #   Vector magnitude from X/Y/Z
      math_expr.py             #   Free-form math expressions
      resample.py              #   Trim, Resample
    criteria/                  # Injury criteria
      base.py                  #   CriterionResult, InjuryCriterion protocol
      hic.py                   #   HIC15, HIC36
      clip3ms.py               #   3ms chest clip
      nij.py                   #   Nij (4 modes, per-dummy intercepts)
      chest.py                 #   Chest deflection, Viscous criterion
      femur.py                 #   Femur load
      tibia.py                 #   Tibia index
    protocol/                  # Rating protocols
      base.py                  #   ProtocolResult, BodyRegionScore, Color, Rating
      euro_ncap.py             #   Euro NCAP (color/points/stars, versioned)
      us_ncap.py               #   US NCAP (injury probability/stars)
      iihs.py                  #   IIHS (G/A/M/P)
    plot/                      # Visualization
      engine.py                #   PlotEngine (Plotly), cursor_values()
      spec.py                  #   PlotSpec, ChannelRef, Corridor, CursorValues
      cursor.py                #   Dual X-cursor logic
      export.py                #   PNG/SVG/PDF/HTML export
    template/                  # Templates & sessions
      model.py                 #   TemplateSpec, SessionState (YAML serializable)
      library.py               #   TemplateLibrary (~/.impakt/templates/)
      session.py               #   SessionManager (.impakt/ per test)
    report/                    # Report generation
      engine.py                #   PDF/HTML via WeasyPrint + Jinja2
      templates/               #   3 Jinja2 HTML templates
        plot_sheet.html
        injury_summary.html
        protocol_report.html
    web/                       # Dash web application
      app.py                   #   create_app(), serve()
      layout.py                #   build_layout() -- UI structure
      callbacks.py             #   register_callbacks() -- interactivity
    plugin/                    # Plugin system
      registry.py              #   PluginRegistry, discovery (entrypoints + dir)
    script/                    # Scripting API + CLI
      api.py                   #   Session, ChannelHandle, TransformProxy, Template
      cli.py                   #   argparse CLI (serve/info/channels/evaluate)
  tests/
    conftest.py                # Synthetic channel fixtures
    test_integration.py        # Full pipeline against synthetic MME fixture
    test_real_mme.py           # 46 tests against 5 real ISO 13499 datasets
    test_channel/              # ChannelCode parser, Channel model, TestData
    test_criteria/             # HIC, Nij
    test_io/                   # MMEReader
    test_protocol/             # Euro NCAP scoring
    test_transform/            # CFC filter, alignment
    fixtures/
      generate_mme.py          # Synthetic MME generator (26 channels, half-sine)
      sample_mme/              # Generated synthetic test data
    mme_data/                  # REAL ISO 13499 test data (5 datasets)
      3239/                    #   NHTSA/Calspan, VW Passat frontal, 133 channels
      AK3T02FO/                #   BASt, frontal 40% offset, 97 channels
      AK3T02SI/                #   BASt, side impact, 97 channels
      VW1FGS15/                #   Volkswagen, pedestrian headform, 10 channels
      98_7707/                 #   UTAC, vehicle-to-vehicle (metadata only)
      *.pdf, *.doc             #   ISO/TS 13499 reference documents
```

---

## What Works

### Fully implemented and tested:

| Module | Status | Notes |
|---|---|---|
| **Channel code parser** | Complete | Auto-detects 14-char (no dummy) vs 16-char (with dummy H3/P3/PC). Handles real-world codes from NHTSA, BASt, VW, UTAC. |
| **Channel model** | Complete | Immutable channels, auto-grouping X/Y/Z, resultant computation, hierarchical tree builder. |
| **MME reader** | Complete | Two-format support: (1) Real ISO 13499 (.mme + .chn index + .NNN data files), (2) simplified INI format. Tested against 5 real datasets. |
| **CFC filtering** | Complete | SAE J211 compliant. 4th-order Butterworth, zero-phase (filtfilt). All 4 CFC classes. |
| **Alignment transforms** | Complete | X-align (manual/threshold/trigger), Y-align (baseline window). |
| **Resultant** | Complete | From ChannelGroup or arbitrary channels. |
| **Math expressions** | Complete | Safe eval with numpy functions. |
| **HIC** | Complete | HIC15/HIC36, cumulative integration, optimal window search. |
| **3ms clip** | Complete | Cumulative exceedance method. |
| **Nij** | Complete | 4 modes (NTE/NTF/NCE/NCF), per-dummy intercepts (H3 50M/5F/95M, child dummies). |
| **Chest deflection** | Complete | Peak sternal displacement. |
| **Viscous criterion** | Complete | V(t)*C(t) with chest depth per dummy type. |
| **Femur load** | Complete | Left/right, unit conversion. |
| **Tibia index** | Complete | M/Mc + F/Fc with intercepts. |
| **Euro NCAP** | Complete | Sliding-scale color/points, percentage to stars. Versioned thresholds. |
| **US NCAP** | Complete | Logistic injury risk functions, combined probability, star rating. |
| **IIHS** | Complete | G/A/M/P per body region, worst-case overall. |
| **Plot engine** | Complete | Plotly rendering, corridors, cursor values, export. |
| **Template model** | Complete | YAML serialize/deserialize, library manager, session persistence. |
| **Report engine** | Complete | HTML+WeasyPrint PDF, 3 Jinja2 templates. Falls back to HTML if WeasyPrint unavailable. |
| **Plugin registry** | Complete | Entry point + directory + API discovery. |
| **CLI** | Complete | `impakt serve/info/channels/evaluate`. |
| **Web UI** | Minimal | Basic Dash app: flat channel list, single CFC dropdown, cursor inputs. Functional but needs major overhaul. |

### Key design decisions already made:

1. **Immutable channels** -- transforms return new Channel objects; raw data never modified.
2. **`.impakt/` subfolder** -- session state stored alongside test data, not in a central DB.
3. **Template/session split** -- templates are global recipes; sessions are per-test instances with overrides.
4. **Two MME format variants** -- real ISO 13499 and simplified INI. Reader auto-detects.
5. **16-char channel codes** -- positions 11-12 can be dummy type (H3/P3/PC) or measurement type; parser auto-detects.
6. **uv for package management** -- dev deps in `[dependency-groups]`, lockfile committed.

---

## What Needs Building Next: Web UI Overhaul

The web UI is the top priority. Current state is a proof-of-concept; needs to become a daily-use tool. The planned features, in priority order:

### Priority 1 -- Must have for the tool to be usable

1. **File/test management** -- open test from UI (path input), open additional tests for overlay, recent tests list, test metadata panel
2. **Proper channel tree** -- collapsible hierarchy (Object > Region > Measurement), select-all per group, preview (peak, unit, rate), color indicators for plotted channels, multi-test awareness
3. **Multi-pane plot layout** -- configurable grid (1x1 through 3x2), drag channels to panes, independent zoom with optional sync, per-pane axis labels
4. **Working criteria panel** -- auto-detect channels from ISO naming, compute all criteria, results table with pass/fail colors, click to highlight time window on plot
5. **Plot export** -- download PNG/SVG/PDF per pane, copy to clipboard, export CSV of plotted data

### Priority 2 -- Makes the tool genuinely productive

6. **Template management UI** -- template browser, apply/save/edit from UI, session auto-save
7. **Enhanced transform controls** -- per-channel CFC, X-align/Y-align controls, one-click resultant
8. **Corridor management** -- load from CSV, draw on plot, corridor library with templates
9. **Channel inspector** -- tabular data view, statistics (min/max/RMS/peak time), peak detection
10. **Math expression builder** -- formula input with autocomplete, variable binding dropdowns, live preview

### Priority 3 -- Differentiators

11. **Annotations** -- text on plots, measurement lines, highlight regions
12. **Comparison mode** -- side-by-side tests, delta plots, synced cursors
13. **Report builder** -- drag-and-drop report composer, PDF preview
14. **Keyboard shortcuts** -- Ctrl+O, Ctrl+S, 1-9 pane switch, F fullscreen, R reset zoom

---

## Test Data Available

| Dataset | Lab | Type | Channels | Good for testing |
|---|---|---|---|---|
| `fixtures/sample_mme/` | Synthetic | Frontal barrier | 26 | Unit tests, known values |
| `mme_data/3239/` | NHTSA/Calspan | Frontal barrier (VW Passat) | 133 | Full pipeline, real data, driver+rear passenger |
| `mme_data/AK3T02FO/` | BASt | Frontal 40% offset | 97 | Multi-occupant (driver, rear, child) |
| `mme_data/AK3T02SI/` | BASt | Side impact | 97 | Side impact protocols |
| `mme_data/VW1FGS15/` | Volkswagen | Pedestrian headform | 10 | Impactor codes (D0), pre-computed resultant |
| `mme_data/98_7707/` | UTAC | Vehicle-to-vehicle | 0 | Metadata-only, graceful empty handling |

---

## Dependencies

Core: numpy, scipy, plotly, dash, dash-bootstrap-components, pandas, pyyaml, jinja2, weasyprint, pydantic
Dev: pytest, pytest-cov, ruff, mypy
Optional: nptdms (for future TDMS reader plugin)

---

## Known Issues / Technical Debt

1. **VehicleInfo.year parsed as 0** for real MME data (the .mme format doesn't have a vehicle_year field; it's embedded in the vehicle name string like "VOLKSWAGEN PASSAT 2000").
2. **Speed displayed as raw float** (e.g., 55.900001530350906 km/h) -- should round.
3. **report/pdf.py** referenced in `pyproject.toml` directory structure but doesn't exist as separate file (functionality is in `engine.py`).
4. **web/assets/** directory exists but is empty -- no custom CSS yet.
5. **No .gitignore** -- should exclude .venv/, __pycache__/, .pytest_cache/, .ruff_cache/, .impakt/ session dirs.
