12 KiB
12 KiB
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
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:
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:
- Immutable channels -- transforms return new Channel objects; raw data never modified.
.impakt/subfolder -- session state stored alongside test data, not in a central DB.- Template/session split -- templates are global recipes; sessions are per-test instances with overrides.
- Two MME format variants -- real ISO 13499 and simplified INI. Reader auto-detects.
- 16-char channel codes -- positions 11-12 can be dummy type (H3/P3/PC) or measurement type; parser auto-detects.
- 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
- File/test management -- open test from UI (path input), open additional tests for overlay, recent tests list, test metadata panel
- Proper channel tree -- collapsible hierarchy (Object > Region > Measurement), select-all per group, preview (peak, unit, rate), color indicators for plotted channels, multi-test awareness
- Multi-pane plot layout -- configurable grid (1x1 through 3x2), drag channels to panes, independent zoom with optional sync, per-pane axis labels
- 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
- Plot export -- download PNG/SVG/PDF per pane, copy to clipboard, export CSV of plotted data
Priority 2 -- Makes the tool genuinely productive
- Template management UI -- template browser, apply/save/edit from UI, session auto-save
- Enhanced transform controls -- per-channel CFC, X-align/Y-align controls, one-click resultant
- Corridor management -- load from CSV, draw on plot, corridor library with templates
- Channel inspector -- tabular data view, statistics (min/max/RMS/peak time), peak detection
- Math expression builder -- formula input with autocomplete, variable binding dropdowns, live preview
Priority 3 -- Differentiators
- Annotations -- text on plots, measurement lines, highlight regions
- Comparison mode -- side-by-side tests, delta plots, synced cursors
- Report builder -- drag-and-drop report composer, PDF preview
- 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
- 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").
- Speed displayed as raw float (e.g., 55.900001530350906 km/h) -- should round.
- report/pdf.py referenced in
pyproject.tomldirectory structure but doesn't exist as separate file (functionality is inengine.py). - web/assets/ directory exists but is empty -- no custom CSS yet.
- No .gitignore -- should exclude .venv/, pycache/, .pytest_cache/, .ruff_cache/, .impakt/ session dirs.