# Impakt -- Project Status **Date:** 2026-04-10 **Version:** 0.1.0 **Tests:** 171 passing **Source:** ~9,200 lines Python | ~1,900 lines tests | ~3,400 lines web (py+js+css) | ~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 171 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 .gitignore 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 auto-detect) 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 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 # App factory: create_app(), serve() state.py # AppState: server-side multi-test state manager layout.py # Top-level layout: tabs, flex splitter, component assembly components/ # Reusable layout components header.py # Navbar, test info panel, open/overlay modals channel_grid.py # Flat sortable DataTable with wildcard filter + facets transforms.py # CFC/align/resultant control panel plot_grid.py # Multi-pane plot area (1x1, 2x1, 1x2, 2x2, 3x1) cursors.py # Cursor values grid (live hover + X1/X2 locked) criteria.py # Auto-compute criteria, protocol scoring, results display report.py # Export panel (PNG/SVG/PDF, CSV, protocol report) callbacks/ # Feature-specific callback modules __init__.py # Registration hub: register_callbacks() channel_callbacks.py # Channel selection, filtering, badge display plot_callbacks.py # Plot rendering, transform pipeline cursor_callbacks.py # Live cursor grid updates via polled JS hover criteria_callbacks.py # Compute All button, protocol scoring file_callbacks.py # Open test / add overlay modals export_callbacks.py # CSV export, report generation assets/ # Browser-side static files style.css # Custom CSS (compact layout, splitter, scrollbars) splitter.js # Draggable panel splitter (pure JS, no deps) cursor_tracker.js # Live cursor tracking (mousemove -> pixel-to-data-X) 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 test_web/ # AppState, app creation, channel grid, criteria auto-compute 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 ### All modules 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). | | **Channel model** | Complete | Immutable channels, auto-grouping X/Y/Z, resultant computation. | | **MME reader** | Complete | Real ISO 13499 (.mme + .chn index + .NNN data files) + simplified INI. Tested against 5 real datasets. | | **CFC filtering** | Complete | SAE J211 compliant. 4th-order Butterworth, zero-phase. 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. | | **Chest deflection** | Complete | Peak sternal displacement with unit/sanity validation. | | **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. | | **Plugin registry** | Complete | Entry point + directory + API discovery. | | **CLI** | Complete | `impakt serve/info/channels/evaluate`. | | **Web UI** | **Functional** | See details below. | ### Web UI -- Current State The web UI has been through a major overhaul and is now functional for daily use: **Layout:** - Two tabs: **Data** (channels + plot + cursor grid) and **Analysis** (criteria + export) - Draggable splitter between left panel and plot area (pure JS, no deps) - Left panel resizable from 200px to 600px **Channel Grid (left panel):** - Flat sortable DataTable showing: #, ISO Code, Description, Unit, Min, Max - Wildcard filter bar (`*HEAD*AC*`, `11*FO*Z*`, or partial text auto-wrapped) - Facet dropdowns: body region, measurement type, direction - Multi-select checkboxes, selected channels shown as color-coded badges - Columns sortable and resizable (CSS resize) **Plot Area (right side):** - Multi-pane layout presets (1x1, 2x1, 1x2, 2x2, 3x1) - Transform controls: CFC filter, Y-align, X-align (manual/threshold), resultant toggle - X1/X2 reference lines drawn on plot (red dashed / blue dashed) **Cursor Values Grid (below plot):** - Live updating: vertical crosshair and cursor values track mouse movement anywhere in plot area - Custom JS cursor tracker (mousemove -> Plotly axis p2d/p2l -> data coordinates) - Polled via dcc.Interval (80ms) -> clientside callback -> server-side interpolation - Columns: Channel, Unit, Cursor (live), X1 (locked), X2 (locked) **Analysis Tab:** - Auto-detect channels by ISO naming and compute HIC15, 3ms clip, Nij, chest defl, femur, tibia - Protocol scoring: Euro NCAP / US NCAP / IIHS with color-coded results table and star ratings - CSV export of plotted channel data (with transforms applied) - Protocol report generation (HTML) **File Management:** - Open Test / Add Overlay buttons with modal dialogs - Test info panel showing all loaded tests with metadata - Multi-test support in channel grid and plot labels ### Key design decisions: 1. **Immutable channels** -- transforms return new Channel objects; raw data never modified. 2. **`.impakt/` subfolder** -- session state stored alongside test data. 3. **Template/session split** -- templates are global recipes; sessions are per-test instances. 4. **AppState is server-side** -- numpy arrays stay in Python memory; Dash stores hold only lightweight keys. 5. **Channel keys use `test_id::channel_name`** -- enables multi-test overlay. 6. **Custom JS cursor tracking** -- bypasses Plotly's hover system (which only fires near data points) with raw mousemove + pixel-to-data conversion using Plotly's internal axis API. 7. **uv for package management** -- dev deps in `[dependency-groups]`. --- ## Next Steps (Priority 2) These are the next features to build, now that Priority 1 is complete: 1. **Template management UI** -- template browser, apply/save/edit from UI, session auto-save 2. **Enhanced transform controls** -- per-channel CFC, per-channel X/Y-align 3. **Corridor management** -- load from CSV, draw on plot, corridor library 4. **Channel inspector** -- tabular data view, statistics (min/max/RMS/peak time) 5. **Math expression builder** -- formula input with autocomplete, live preview --- ## 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 | | `mme_data/AK3T02FO/` | BASt | Frontal 40% offset | 97 | Multi-occupant | | `mme_data/AK3T02SI/` | BASt | Side impact | 97 | Side impact protocols | | `mme_data/VW1FGS15/` | Volkswagen | Pedestrian headform | 10 | Impactor codes (D0) | | `mme_data/98_7707/` | UTAC | Vehicle-to-vehicle | 0 | Metadata-only | --- ## 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 (.mme format embeds year in vehicle name string). 2. **Speed displayed as raw float** (55.900001530350906 km/h) -- should round. 3. **DataTable deprecation warning** -- Dash recommends migrating to dash-ag-grid. Functional for now. 4. **Cursor poll interval (80ms)** -- adds slight latency to cursor grid updates. Could use WebSocket for lower latency in future. 5. **Chest deflection auto-detect** skips DS channels with peak > 150mm (avoids steering column displacement). May miss some legitimate high-deflection data.