# Impakt — Brainstorm

Ideas, feature proposals, and design thoughts. Organized by user workflow and informed by the competitive landscape survey (see `research/landscape.md`).

Priority tiers:
- **P0** — Unlocks significant capability or addresses a clear gap vs. commercial tools
- **P1** — Strong quality-of-life improvement for daily use
- **P2** — Nice to have, longer-term, or exploratory

Where an existing open-source library enables a feature, it's noted with `[lib: name]`. Repos are cloned in `research/repos/`.

---

## The Core Experience

The crash test engineer's workflow is: **receive data -> inspect -> filter -> compute -> score -> report**. Every feature below should make one of those steps faster, more reliable, or more insightful.

What we learned from the landscape: commercial tools (measX X-Crash, NI DIAdem, Kistler) dominate because they nail this loop end-to-end with zero friction. No open-source web-based tool does this today. That's Impakt's opportunity.

---

## Rendering & Performance

The most impactful near-term improvements. Large crash test datasets (133+ channels, 10k+ samples each at up to 100kHz) need to render smoothly.

- [ ] **P0 — Integrate plotly-resampler** — Drop-in wrapper for Plotly figures that handles 110M+ points via LTTB downsampling. Replace `go.Figure()` with `FigureResampler(go.Figure())` in the plot engine. Works natively with Dash. `[lib: plotly-resampler]`
- [ ] **P1 — Progressive rendering** — Show plots immediately with decimated data, refine with full resolution once loaded. Plotly-resampler does this automatically, but the UX should show a loading indicator during refinement.
- [ ] **P1 — Memory-mapped data** — For very large datasets, use `numpy.memmap` to avoid loading everything into RAM. Enables tests with 500+ channels and multi-GB data files.
- [ ] **P1 — Lazy channel loading** — Load `.dat` files only when a channel is first accessed. Load headers eagerly, data lazily. Keeps `Session.open()` fast for large tests.
- [ ] **P2 — Channel cache** — Cache frequently-accessed transformed channels to avoid recomputing CFC filters every time a plot refreshes.
- [ ] **P2 — Parallel criteria computation** — Compute all injury criteria in parallel using `concurrent.futures`. The individual computations are independent.

---

## Visualization

What makes crash test analysis *fast* is the ability to visually scan, compare, and correlate signals. The best commercial tools (measX, DIAdem, Altair HyperGraph) invest heavily here.

### Multi-signal navigation

- [ ] **P0 — Synchronized zoom/pan** — When plotting multiple subplots, zoom/pan actions sync across all panes sharing an X axis. Bokeh does this natively with linked ranges; in Plotly/Dash this requires shared `xaxis` config or callback-based sync. This is the single most-requested feature in crash test visualization.
- [ ] **P1 — Channel sparklines** — In the channel grid sidebar, show tiny inline sparklines next to each channel name. Engineers visually identify signals before selecting them. The grid already has Min/Max columns; a 60px-wide sparkline column would be transformative for browsing 100+ channels.
- [ ] **P1 — Peak annotation** — Auto-annotate peak value and time on plots as a togglable Plotly annotation. Shows a marker + text label at the global peak. Optionally annotate at cursor positions too.
- [ ] **P1 — Dark mode** — Engineers often work in labs with varying lighting. A Dash Bootstrap dark theme (DARKLY or CYBORG) is a one-line change in `app.py`.

### Multi-test comparison

- [ ] **P0 — Quick comparison mode** — Two tests side-by-side with synchronized cursors. One-click "compare" button. Each test gets its own color family; channels within a test share the hue, differentiated by line dash. This is the most natural workflow after single-test analysis.
- [ ] **P1 — Statistical overlays** — When viewing multiple tests, show mean +/- 1 sigma envelope, min/max envelope. Essential for repeatability studies and fleet testing.
- [ ] **P1 — Delta channel** — Compute the difference between the same channel across two tests. Useful for design iteration comparisons (e.g., "how did the head acceleration change after we modified the airbag?").
- [ ] **P2 — Color-by-test vs color-by-channel toggle** — Let the user choose: each test gets a color, or each channel gets a color.

### Advanced visualization

- [ ] **P1 — Frequency spectrum viewer** — FFT / power spectral density of a channel. Helps diagnose noise, identify resonant frequencies, and verify CFC filter behavior. Show alongside the time-domain plot in a split view.
- [ ] **P2 — Waterfall / 3D surface plots** — For barrier face loads at multiple spatial locations, a waterfall view shows spatial distribution over time. Taipy and Plotly both support 3D surface natively.
- [ ] **P2 — Animation mode** — Playback the crash event in time with a vertical cursor sweeping across all plots. Sync with video if available (see Video Sync below).
- [ ] **P2 — Custom subplot grids** — Allow user-defined subplot grids beyond the current presets. Let users drag-resize panes.

---

## Data Import & Format Support

Impakt currently reads ISO 13499 MME (real + synthetic). The landscape shows several adjacent formats that would broaden the tool's reach significantly.

### High-priority formats

- [ ] **P0 — UDS reader** — NHTSA's proprietary binary format. Required to access the largest public crash test database in the world (NHTSA NCAP). The NHTSA-Tools Fortran source documents the UDS spec thoroughly. Build as a reader plugin. `[ref: NHTSA-Tools]`
- [ ] **P0 — ASAM MDF reader** — The standard for ECU/CAN bus measurement data. Many crash test labs record vehicle bus data alongside instrumentation in MDF format. asammdf is a mature, well-tested library. Add as an optional dependency like TDMS. `[lib: asammdf]`
- [ ] **P1 — CSV/TSV flexible reader** — The current CSV reader is basic. Engineers frequently receive data as CSV exports from other tools with varying column layouts, header conventions, and delimiter styles. A flexible CSV reader with column mapping would cover many edge cases.

### Medium-priority formats

- [ ] **P1 — LS-DYNA binout/D3plot** — Simulation results for test-vs-CAE correlation. lasso-python is the maintained Python library for this. Enables overlay of physical test data with simulation predictions — a major workflow in automotive safety development. `[lib: lasso-python]`
- [ ] **P2 — Abaqus ODB** — Another major FEA solver used in safety simulation.
- [ ] **P2 — MADYMO** — Occupant simulation results (TNO format).

### Data enrichment

- [ ] **P1 — Channel aliasing** — Allow human-friendly aliases (e.g., `"head_ax" -> "11HEAD0000H3ACXP"`). Aliases stored in templates or user config. Especially useful for teams that have their own naming conventions.
- [ ] **P1 — Channel metadata editor** — Non-destructive override for wrong units or missing metadata in `.chn` files. Overrides stored in the session's `.impakt/` folder.
- [ ] **P1 — Auto-detect signal type from channel code** — Use the measurement code (AC, FO, MO, DC) to automatically suggest CFC class, axis labels, and unit handling. The lookup tables in `channel/lookup.py` already have this data.
- [ ] **P2 — Batch loader** — `Session.open_batch("/tests/series_2024/")` loads an entire directory. Returns a `Series` object with cross-test operations (mean, overlay, delta).
- [ ] **P2 — NHTSA open data integration** — Build a UDS-to-MME converter or direct UDS reader. The NCAP database Access DB contains summary results; contact NHTSA for time-history channel data access.

---

## Signal Processing

Currently: CFC filtering, alignment, resultant, trim, resample, math expressions. The landscape shows several gaps.

- [ ] **P1 — Integration / differentiation** — Integrate acceleration to get velocity/displacement. Differentiate displacement to get velocity. Track cumulative units (m/s² -> m/s -> m). Fundamental for kinematic analysis.
- [ ] **P1 — Savitzky-Golay filter** — Alternative to CFC for smoothing that better preserves peaks. Useful when the SAE J211 Butterworth roll-off is too aggressive for a specific analysis.
- [ ] **P1 — Event detection** — Automatically detect impact events from acceleration signals (threshold crossing, change-point detection). Useful for multi-event tests (primary impact + rebound).
- [ ] **P2 — Cross-correlation** — Find time lag between two channels. Useful for understanding signal propagation through the vehicle structure.
- [ ] **P2 — Envelope detection** — Hilbert transform for amplitude trends.
- [ ] **P2 — Window functions** — Hanning, Hamming, etc. for spectral analysis pre-processing (depends on FFT viewer).
- [ ] **P2 — Signal quality metrics** — Detect clipping, saturation, dropout, excessive noise. Flag channels with potential data quality issues. Display as badges in the channel grid.

---

## Injury Criteria & Protocol Scoring

Currently: HIC15/36, 3ms clip, Nij, chest deflection, viscous criterion, femur load, tibia index. Euro NCAP, US NCAP, IIHS scoring. The landscape reveals several additional criteria in active use.

### Cross-validation (leverage landscape research)

- [ ] **P0 — Validate injury criteria against reference implementations** — Four independent implementations are now available for comparison: NHTSA-Tools (Fortran, authoritative), pyisomme (Python), PyAvia (CFC filter), and EPFL crash-tests-service-robots. Build a validation test suite that runs Impakt's criteria against these reference outputs for the same input data. `[ref: NHTSA-Tools, pyisomme, pyavia, crash-tests-service-robots]`

### Additional criteria

- [ ] **P1 — BrIC (Brain Injury Criterion)** — Rotational brain injury metric using angular velocity. Increasingly required in newer Euro NCAP protocols.
- [ ] **P1 — DAMAGE** — Diffuse Axonal Multi-Axis General Evaluation. Related to BrIC, uses angular acceleration. pyisomme includes an implementation. `[ref: pyisomme]`
- [ ] **P1 — Thorax Trauma Index (TTI)** — Side impact chest criterion. Required for US NCAP side impact.
- [ ] **P1 — Pedestrian criteria** — Head Impact Criterion for headform impactors, lower leg bending, upper leg force. Required for Euro NCAP pedestrian rating.
- [ ] **P2 — Abdominal Peak Force (APF)** — Abdomen criterion for side impact.
- [ ] **P2 — Acetabular force** — Pelvis criterion for SID-IIs / WorldSID side impact.
- [ ] **P2 — OLC (Occupant Load Criterion)** — Structural criterion used in Euro NCAP.

### Protocol enhancements

- [ ] **P1 — Protocol version management UI** — Visual diff between protocol versions. Show what thresholds changed between e.g. Euro NCAP 2023 vs 2025. The YAML threshold files already version this data.
- [ ] **P1 — Regulatory compliance check** — Given a test, automatically check all applicable FMVSS / ECE regulation limits. Flag exceedances with severity indicators.
- [ ] **P2 — Custom protocol builder** — Let users define pass/fail criteria with custom thresholds. Useful for internal OEM targets stricter than regulation.
- [ ] **P2 — Sensitivity analysis** — "What if" sliders: how would the score change if HIC was 50 points lower? Interactive exploration for design optimization.
- [ ] **P2 — Additional NCAP programs** — J-NCAP (Japan), C-NCAP (China), K-NCAP (Korea), ANCAP (Australia), Latin NCAP. Each as a protocol plugin.

---

## Data Quality & Validation

No commercial competitor has strong automated data quality features. This is an opportunity to differentiate.

- [ ] **P1 — Channel polarity check** — Verify SAE sign convention compliance. Detect inverted polarity (e.g., positive compression forces that should be negative per J211).
- [ ] **P1 — Sensor sanity checks** — Flag physically impossible values (head acceleration > 500g, negative femur tension in frontal impact, displacement > 1m).
- [ ] **P1 — Missing channel detection** — For a given protocol, check which required channels are missing from the test data. Show a completeness score before the user starts analysis.
- [ ] **P2 — Inter-channel consistency** — Verify that resultant acceleration equals sqrt(sum of squares) of components. Detect disagreement between redundant sensors.
- [ ] **P2 — Time sync verification** — Check that all channels have consistent timing (same trigger point, no drift between DAQ systems).
- [ ] **P2 — Data quality dashboard** — Single-page overview showing pass/fail for each quality check across all channels. Color-coded. Exportable.

---

## Templates & Workflow

The template system is one of Impakt's differentiators. Commercial tools (DIAdem, HyperGraph, Simcenter Testlab) all have template-driven workflows. Impakt should go further.

- [ ] **P1 — Template inheritance** — A template can extend another. "My NCAP template" extends "Euro NCAP 2024" but adds custom corridors and extra plots.
- [ ] **P1 — Channel auto-mapping** — When applying a template to a new test, auto-map channel patterns to actual available channels. Handle naming variations across test facilities (BASt vs. Calspan vs. Volkswagen conventions).
- [ ] **P1 — Template validation** — When a template references channel patterns, validate that the current test data has matching channels. Show warnings for missing channels with suggested alternatives.
- [ ] **P1 — Session history / undo** — Track a history of actions with undo/redo. Store in `.impakt/` session folder.
- [ ] **P2 — Template sharing** — Git-based version control for template libraries. Team templates synced via shared directory or Git repo.
- [ ] **P2 — Corridor management UI** — Visual editor for creating and editing tolerance corridors. Draw the envelope on a plot, export to CSV. Currently corridors are CSV-upload only.
- [ ] **P2 — Structured corridor format** — Metadata-rich corridor files: source protocol, year, applicable dummy type, confidence level. Bundle official protocol corridors with the tool.

---

## Reports & Export

Report generation is the final deliverable. This is where Impakt replaces hours of manual Excel/PowerPoint work.

- [ ] **P0 — Multi-page reports** — Combine multiple plots + injury summary + protocol rating into a single PDF with automatic table of contents. Currently each report type is standalone.
- [ ] **P1 — Excel export** — Export criteria results and cursor values to Excel, not just PDF/CSV. Engineers live in spreadsheets. Use openpyxl or xlsxwriter.
- [ ] **P1 — PowerPoint export** — One plot per slide with metadata. Common request in OEM environments. pyisomme generates PowerPoint — confirms the demand. `[ref: pyisomme uses python-pptx]`
- [ ] **P1 — Configurable report branding** — Company logo, header/footer, color scheme. Stored in `~/.impakt/brand.yaml`.
- [ ] **P1 — Static HTML export** — Bundle all data and Plotly.js into a single self-contained HTML file. Opens in any browser without a Python server. Solves the "share with stakeholders" problem. Plotly's `write_html(include_plotlyjs=True)` does most of the work.
- [ ] **P2 — Report templates gallery** — Pre-built templates for NHTSA compliance, Euro NCAP submission, IIHS test report formats.
- [ ] **P2 — Comparison reports** — Automatically generate a report comparing two or more tests. Highlight differences in criteria and ratings.
- [ ] **P2 — Automated narration** — Generate natural-language summary: "The head acceleration exceeded the Euro NCAP green threshold at t=0.032s, resulting in a yellow rating for the head region." Could leverage an LLM for nuanced interpretation.

---

## Video Synchronization

Every major commercial competitor (measX, DIAdem, Kistler, FalCon) has video-signal sync. It's the most visible gap in Impakt vs. commercial tools. Engineers watch high-speed camera footage frame-by-frame alongside the data.

- [ ] **P0 — Video playback linked to time axis** — Load an MP4/AVI alongside test data. Scrubbing the video moves the cursor on plots, and moving the cursor on plots seeks the video. The time offset between video start and DAQ trigger is configurable.
- [ ] **P1 — Multiple camera views** — Crash tests typically have 4-8 high-speed cameras (frontal, side, overhead, onboard). Support tiled video views synced to the same timeline.
- [ ] **P2 — Frame annotation** — Mark specific frames with notes (e.g., "airbag deployment", "head contact with steering wheel"). Export annotated frames.

Implementation notes: Foxglove and Rerun both demonstrate web-native signal+video sync. Dash can embed HTML5 `<video>` elements. The main challenge is sub-millisecond sync at high-speed camera frame rates (1000-10000 fps). A lightweight approach: decode video server-side with OpenCV, serve frames as images synced to the Dash callback timestamp. A heavier approach: WebCodecs API for client-side decoding.

---

## Integration & Automation

- [ ] **P0 — Jupyter notebook integration** — `Session`, `Channel`, and `ProtocolResult` objects should display rich output in Jupyter (`_repr_html_` with interactive Plotly plots, HTML tables). This makes Impakt a first-class citizen in the data science workflow.
- [ ] **P1 — CI/CD integration** — `impakt evaluate --protocol euro_ncap --exit-code` returns non-zero if any criterion fails. Useful for automated test validation in manufacturing pipelines.
- [ ] **P1 — Watch mode** — Monitor a directory for new test data. When a new test appears (DAQ export complete), auto-apply a template and generate a report. Valuable for high-throughput sled test labs.
- [ ] **P1 — REST API mode** — Run Impakt as a server with a REST API. Enables integration with PLM systems, CAE workflows, and custom dashboards.
- [ ] **P2 — Pre/post-processing hooks** — User-defined Python functions that run before/after template application, criteria computation, or report generation.
- [ ] **P2 — Real-time collaboration** — WebSocket-based sync of cursor positions, channel selections, and annotations. "Presenter mode" for post-test review sessions where one engineer drives.

---

## User Experience

- [ ] **P1 — Keyboard shortcuts** — `Ctrl+1..9` for channel groups. `Space` for play/pause animation. `R` to reset zoom. `F` for fullscreen plot. `/` for channel search focus. These are expected in professional tools.
- [ ] **P1 — Drag-and-drop** — Drag channels from the grid onto the plot area. Drag a test directory onto the app to open it.
- [ ] **P1 — Right-click context menus** — Right-click on a channel to apply transforms, compute criteria, or export.
- [ ] **P1 — Recent files** — Remember recently opened tests for quick access from the landing page.
- [ ] **P1 — Tooltip glossary** — Hover over "HIC15", "CFC 180", "Nij" to see a brief explanation. Aids learning for junior engineers and non-specialists reviewing results.
- [ ] **P2 — Guided analysis wizards** — Step-by-step workflows: "Run frontal NCAP analysis" walks through channel selection, filtering, criteria computation, and report generation.
- [ ] **P2 — Bookmarks** — Save specific views (channel selection + zoom + cursors) as named bookmarks within a session.
- [ ] **P2 — Multi-window** — Open multiple test sessions in separate browser tabs, optionally synchronized.
- [ ] **P2 — Synthetic data generator API** — Expose `tests/fixtures/generate_mme.py` as `impakt.synth` for users prototyping templates without real test data.

---

## Architecture Notes

### Transform pipeline

Currently transforms are a flat chain. Consider a DAG-based pipeline where a channel can be both filtered and unfiltered, with the resultant computed from filtered components but cursor values shown on unfiltered data. This matters when engineers want to see the effect of filtering without losing the original signal context.

### Static HTML export as a distribution format

Learned from FalCon's CustomerView model: OEMs need to share test results with recipients who don't have the analysis software installed. A self-contained HTML file with embedded Plotly.js, data, and interactive plots solves this without requiring a Python server or license.

### CFC filter implementation verification

PyAvia's author notes that for CFC 180 and 60, the SAE J211 Appendix C digital Butterworth algorithm should be used rather than scipy's generic `sosfiltfilt`. Impakt's current implementation uses scipy. This should be verified by comparing output against PyAvia's `J211_2pole` and NHTSA-Tools' `BwFilt` Fortran implementation for the same input signals.

### Multi-rate data architecture

Rerun's time-aware database handles channels sampled at different rates natively. Crash tests mix channels at 10kHz (accelerometers), 1kHz (displacement), and 100Hz (vehicle bus). Currently Impakt resamples to a common rate. A multi-rate architecture would be more accurate and memory-efficient.

### Corridor standardization

Corridors currently use simple CSV (time, lower, upper). Consider a structured format with metadata: source protocol, year, applicable dummy type, confidence level, units. Bundle official corridors from published protocol documents. NHTSA and Euro NCAP both publish reference corridors.

### Test-vs-simulation correlation

With lasso-python enabling LS-DYNA data import, the natural workflow becomes: load physical test + simulation, overlay the same channels, compute correlation metrics (CORA, ISO/TS 18571 rating). This is a premium feature in commercial tools (Altair HyperGraph, Siemens Simcenter) and a strong differentiator for an open-source tool.

---

## Plugin Ideas

- [ ] **impakt-lsdyna** — LS-DYNA binout/D3plot import `[lib: lasso-python]`
- [ ] **impakt-mdf** — ASAM MDF v2/v3/v4 import `[lib: asammdf]`
- [ ] **impakt-uds** — NHTSA UDS format reader `[ref: NHTSA-Tools]`
- [ ] **impakt-abaqus** — Abaqus ODB import
- [ ] **impakt-madymo** — MADYMO occupant simulation results
- [ ] **impakt-dicom** — DICOM medical imaging for injury correlation
- [ ] **impakt-jncap** — Japanese NCAP scoring
- [ ] **impakt-cncap** — Chinese NCAP scoring
- [ ] **impakt-kncap** — Korean NCAP scoring
- [ ] **impakt-ancap** — Australian NCAP scoring
- [ ] **impakt-latinncap** — Latin NCAP scoring
- [ ] **impakt-cora** — ISO/TS 18571 cross-correlation for test-vs-simulation rating
