Metadata-Version: 2.4
Name: pyisomme
Version: 1.0.0
Summary: Tools for ISO-MME file format (merge, report, calculate, CFC-filter, ...)
Author-email: Jonas Keller <jonaskeller14@googlemail.com>
License: MIT License
        
        Copyright (c) 2024 Jonas Keller
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/jonaskeller14/pyisomme
Keywords: pyisomme,isomme,iso-mme,iso
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib~=3.7.4
Requires-Dist: astropy~=6.0.0
Requires-Dist: pandas~=2.2.0
Requires-Dist: tqdm~=4.66.1
Requires-Dist: numpy~=1.26.3
Requires-Dist: scipy~=1.12.0
Requires-Dist: python-pptx~=0.6.23
Requires-Dist: dtwalign~=0.1.1
Requires-Dist: requests>=2.32.5
Requires-Dist: objective-rating-metrics~=1.3
Dynamic: license-file

# pyisomme

[![CI](https://github.com/jonaskeller14/pyisomme/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/jonaskeller14/pyisomme/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/jonaskeller14/pyisomme/branch/master/graph/badge.svg)](https://app.codecov.io/gh/jonaskeller14/pyisomme)
[![PyPI](https://img.shields.io/pypi/v/pyisomme.svg)](https://pypi.org/project/pyisomme/)
[![Python](https://img.shields.io/badge/python-%E2%89%A53.9-blue.svg)](https://pypi.org/project/pyisomme/)
[![License](https://img.shields.io/pypi/l/pyisomme.svg)](https://github.com/jonaskeller14/pyisomme/blob/master/LICENSE)

## Installation

```
pip install pyisomme
```

## Features
- Read/write ISO-MME (compressed/uncompressed)
- Modify Channel and calculate Injury Risk Values (HIC, a3ms, DAMAGE, OLC, BrIC, NIJ, ...)
- Plot Curves and compare multiple ISO-MMEs
- Create PowerPoint Reports (Euro-NCAP, UN-R137, UN-R94)
- Display Limit bars in plots
- Compare performance of left-hand-drive vehicle with right-hand-drive vehicle
- Command-line tools for listing, merging, editing, converting, plotting, and reporting ISO-MME data

## Command Line Interface (CLI)

Installing the package provides the `pyisomme` command. The equivalent
`python -m pyisomme` form is also supported.

```bash
pyisomme --help
pyisomme <command> --help
```

| Command | Purpose |
| --- | --- |
| `list` | List channels, optionally selected by code patterns |
| `code` | Decode a 16-character channel code and show its default unit |
| `merge` | Merge and transform one or more ISO-MME containers |
| `set` | Set one or more metadata fields on selected channels in place |
| `convert` | Numerically convert selected channel data to another unit in place |
| `plot` | Plot selected or calculated channels |
| `report` | Calculate and export an assessment report |


Describe a channel code:

```bash
pyisomme code 11HEADCG00H3ACXD
```

```text
Code: 11HEADCG00H3ACXD
Test Object: Vehicle 1
Position: Front left
Main Location: Head
Fine Location 1: Center of Gravity
Fine Location 2: Not defined
Fine Location 3: Hybrid III Mid-Sized Adult Male Dummy
Physical Dimension: Acceleration
Direction: Longitudinal
Filter Class: CFC 60
Default unit: m / s2
```

Edit channel codes

```bash
pyisomme set TEST1.mme TEST2.zip --fine-location-3 H3 -c '11HEAD000000ACXP' '13CHST000000DSXP'
```

Convert channel values and units (e.g. `0.04 m` becomes `40 mm`)

```bash
pyisomme convert TEST1.mme TEST2.zip --unit mm -c '13CHST0000H3DSXP'
```

Merge multiple ISO-MME containers:

```bash
pyisomme merge ./iso_merged.zip ./iso_1/v1.mme ./iso_2.zip ./iso_3.tar.gz
```

Resample from 0 to 100 ms with a 1 ms step and linear interpolation:

```bash
pyisomme merge ./resampled.mme ./iso_1/v1.mme --resample 0 0.001 0.1
```

Plot a calculated resultant head acceleration with filter class A / 1000 Hz:

```bash
pyisomme plot ./iso_1/v1.mme --codes '24HEAD??????ACRA' --xlim 0 100 --calculate
```

Create a report using only data from 0 to 200 ms:

```bash
pyisomme report EuroNCAP_Frontal_MPDB report.pptx data/nhtsa/09203 --crop 0 0.2
```

## Python Examples
- [Read ISO-MME](docs/isomme_read.ipynb)
- [Write ISO-MME](docs/isomme_write.ipynb)


- [Signal deriviation/integration](docs/channel_diff_int.ipynb)
- [Add/Subtract/Multiply/Divide Signals](docs/channel_operators.ipynb)
- [Apply cfc-filter](docs/channel_filter.ipynb)


- [Plotting](docs/plotting.ipynb)

- [Report](docs/report.ipynb)

## Example Report

Animated preview of a Euro NCAP PowerPoint report generated with pyisomme (using synthetic data):

<p align="center">
  <img src="docs/EuroNCAP_Frontal_50kmh.gif" alt="Animated preview of a Euro NCAP PowerPoint report" width="600" height="450">
</p>

## Limitations
- Only test-info (.mme), channel-info (.chn) and channel data files (.001/.002/...) are supported. All other files (videos, photos, txt-files) will be ignored when reading and writing.
- Writing methods do not ask before overwriting. In particular, `set` and `convert` rewrite every
  supplied ISO-MME container in place after validating all inputs and selections.
