noisedestroyers/impakt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1617ee94b90c5e0ff0f8b083feef064bdbc1a1f7
impakt/docs/STATUS.md

13 KiB
Raw Blame History

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

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:

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.
Reference in New Issue View Git Blame Copy Permalink