From 4253aa01b827c27399d4f9b110b3ae137e915738 Mon Sep 17 00:00:00 2001 From: noisedestroyers Date: Fri, 10 Apr 2026 14:46:53 -0400 Subject: [PATCH] bookmark - modules initialized --- README.md | 25 ++++++ docs/STATUS.md | 214 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 239 insertions(+) create mode 100644 docs/STATUS.md diff --git a/README.md b/README.md index 7a1a5b7..46e426c 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,31 @@ Impakt is a modular, scriptable Python toolkit for working with automotive crash test data. It reads ISO 13499 MME data natively, provides non-destructive signal processing, interactive web-based visualization, injury criteria calculation, and protocol-compliant report generation for Euro NCAP, US NCAP, and IIHS. +## Quick Start + +```bash +# Install +uv sync --dev + +# Run tests (136 tests) +uv run pytest tests/ + +# View test metadata +uv run impakt info tests/mme_data/3239 + +# Launch web UI +uv run impakt serve tests/mme_data/3239 + +# Python scripting +uv run python -c " +from impakt import Session +s = Session.open('tests/mme_data/3239') +print(s) # Session(3239, 133 channels) +" +``` + +> See [[docs/STATUS.md]] for detailed project state, known issues, and next steps. + --- ## Contents diff --git a/docs/STATUS.md b/docs/STATUS.md new file mode 100644 index 0000000..a37122f --- /dev/null +++ b/docs/STATUS.md @@ -0,0 +1,214 @@ +# 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.