Metadata-Version: 2.4
Name: mib-extractor
Version: 0.2.0
Summary: CLI tool to archive Mission Information Bases (MIB), inspect SPIDs, and build serializable SPID parameter maps.
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: space-mission,spacecraft,mission-information-base,mib,telemetry,telecommand,packet-processing,spid,scet,ecss
Author: Romolo Politi
Author-email: romolo.politi@inaf.it
Requires-Python: >=3.13
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Provides-Extra: spice
Requires-Dist: bitstring (>=4.3.1,<5.0.0)
Requires-Dist: pandas (>=3.0.1,<4.0.0)
Requires-Dist: rich-click (>=1.9.7,<2.0.0)
Requires-Dist: spicepy (>=1.0.5,<2.0.0) ; extra == "spice"
Project-URL: Citation, https://doi.org/10.5281/zenodo.18798971
Project-URL: Documentation, https://github.com/RomoloPoliti-INAF/mib-extractor/tree/main/doc
Project-URL: Issues, https://github.com/RomoloPoliti-INAF/mib-extractor/issues
Project-URL: Repository, https://github.com/RomoloPoliti-INAF/mib-extractor
Description-Content-Type: text/markdown

# MIB Extractor

![Python Version](https://img.shields.io/badge/python-3.13%2B-blue?style=plastic&logo=python&logoColor=white)
![Version](https://img.shields.io/badge/version-0.2.0-blueviolet?style=plastic)
[![codecov](https://codecov.io/github/RomoloPoliti-INAF/mib-extractor/graph/badge.svg?token=C9FSBW02J5)](https://codecov.io/github/RomoloPoliti-INAF/mib-extractor)
![CI](https://github.com/RomoloPoliti-INAF/mib-extractor/actions/workflows/ci.yml/badge.svg)
[![License: GPL v3+](https://img.shields.io/badge/License-GPLv3%2B-blueviolet.svg?style=plastic)](LICENSE)
[![DOI](https://zenodo.org/badge/1167626806.svg)](https://doi.org/10.5281/zenodo.18798971)

`mib-extractor` is a CLI tool to archive Mission Information Bases (MIB), inspect SPIDs, and generate serializable SPID parameter maps (`pickle` or `parquet`).



## Quick Start

```bash
# 1) Add a MIB folder to the local archive
mib-extractor add /path/to/mib_folder --code mission-2-5

# 2) Inspect available SPIDs
mib-extractor spids mission-2-5

# 3) Build a serializable SPID map
mib-extractor build-spid-map mission-2-5 \
  --spid 1001,1002 \
  --output ./out/spid_map.pkl \
  --format pickle \
  --date-zero 2025-01-01T00:00:00Z
```

## Installation

### 1. Clone and enter the project

```bash
git clone <your-repo-url>
cd mib-extractor
```

### 2. Install dependencies

Using Poetry:

```bash
poetry install
```

Or using the local virtual environment:

```bash
python -m venv venv
source venv/bin/activate
pip install -e .
```

### Optional dependency: `spicepy`

`spicepy` is optional. If installed, SCET conversion uses SPICE.
If not installed, the tool falls back to CLI-provided `--date-zero`.

With Poetry (optional extra):

```bash
poetry add "spicepy>=1.0.5,<2.0.0" --optional
```

Or pip:

```bash
pip install "spicepy>=1.0.5,<2.0.0"
```

## CLI Overview

Check available commands:

```bash
mib-extractor --help
```

Main commands:

- `add <mib_path> [--code CODE]`
- `list`
- `remove <code>`
- `rename <code> <new_code>`
- `spids <code> [--filter WORD]...`
- `spid <code> <spid_number>`
- `build-spid-map <code> --spid ... --output <file> --format parquet|pickle --date-zero <ISO-UTC>`
- `build-command-map <code> --apid <tc_apid> --output <file> --format parquet|pickle`

### Examples

Add a MIB folder:

```bash
mib-extractor add /path/to/mib_folder
```

List archived MIBs:

```bash
mib-extractor list
```

List SPIDs (with filter):

```bash
mib-extractor spids mission-2-5 --filter science --filter housekeeping
```

Build SPID map as pickle:

```bash
mib-extractor build-spid-map mission-2-5 \
  --spid 1001 --spid 1002 \
  --output ./out/spid_map.pkl \
  --format pickle \
  --date-zero 2025-01-01T00:00:00Z
```

Build command map (CCF + CDF) as pickle:

```bash
mib-extractor build-command-map mission-2-5 \
  --apid 42 \
  --output ./out/command_map.pkl \
  --format pickle
```

Build SPID map as parquet:

```bash
mib-extractor build-spid-map mission-2-5 \
  --spid 1001,1002,1003 \
  --output ./out/spid_map.parquet \
  --format parquet \
  --date-zero 2025-01-01T00:00:00Z
```

## Output File Structure (`pickle` / `parquet`)

Both formats store the same tabular structure (`pandas.DataFrame`):

Core columns:

- `SPID`
- `DESCR`
- `NAME`
- `OFFBY`
- `OFFBI`
- `WIDTH`
- `UNIT`
- `CATEG`
- `CURTX`
- `NATUR`
- `PTC`
- `PFC`

SCET metadata columns (only for SCET-like rows, `PTC=9`, `PFC=17`):

- `SCET_MODE` (`spicepy` or `date_zero_fallback`)
- `SCET_ZERO_UTC`

For command maps (`build-command-map`), output rows come from `CCF + CDF` join and include command-level fields (`CNAME`, `APID`, `TYPE`, `STYPE`, ...), plus command-parameter fields (`ELTYPE`, `ELLEN`, `BIT`, `PNAME`, `INTER`, ...).

## Loading `pickle`/`parquet` and Building `ParamDef` Objects

Use `mib_extractor.paramdef_loader.dataframe_to_paramdefs` to convert a DataFrame into a `list[ParamDef]`.

### Example: from pickle

```python
import pandas as pd
from mib_extractor.paramdef_loader import dataframe_to_paramdefs

# Load full table
spid_table = pd.read_pickle("./out/spid_map.pkl")

# Select one SPID and convert to ParamDef list
spid_1002_df = spid_table.query("SPID == 1002")
params = dataframe_to_paramdefs(spid_1002_df)

print(type(params), len(params))
print(params[0])
```

### Example: from parquet

```python
import pandas as pd
from mib_extractor.paramdef_loader import dataframe_to_paramdefs

spid_table = pd.read_parquet("./out/spid_map.parquet")
spid_1001_df = spid_table[spid_table["SPID"] == 1001]
params = dataframe_to_paramdefs(spid_1001_df)

for p in params[:3]:
    print(p.mnemonic, p.byte_location, p.bit_location, p.build_unpack_format())
```

### Using `ParamDef` list at runtime

```python
# Example snippet
for param in params:
    fmt = param.build_unpack_format()
    # value = param.extract(bitstream, fmt)  # requires a BitStream-like object
    # param.calibrate()
```

  ## Telecommand Object Model

  The package now includes typed telecommand classes:

  - `Telecommand` (`src/mib_extractor/telecommand_definition.py`)
  - `TelecommandParameter` (`src/mib_extractor/telecommand_definition.py`)

  Both classes expose runtime fields:

  - `value`
  - `calibrated`

  and runtime methods equivalent to `ParamDef`:

  - `calibrate()`
  - `reset_runtime()`

  Build object graphs from command-map DataFrames:

  ```python
  import pandas as pd
  from mib_extractor.telecommand_loader import dataframe_to_telecommands

  command_table = pd.read_pickle("./out/command_map.pkl")
  commands = dataframe_to_telecommands(command_table)

  cmd = commands[0]
  print(cmd.command_name, cmd.apid, len(cmd.parameters))
  print(cmd.parameters[0].parameter_name)
  ```

  Or build objects directly from a MIB folder/APID:

  ```python
  from pathlib import Path
  from mib_extractor.build_command_map import build_telecommands_from_mib

  commands = build_telecommands_from_mib(
    mib_folder=Path("/path/to/mib"),
    apid=42,
  )
  ```

## Notes

- Code arguments in CLI commands support unique prefixes.
- If a code prefix is ambiguous, CLI returns an error with possible matches.
- Archive data is stored under `.mib_archive/` in the current working directory.

## License

This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).
See the [LICENSE](LICENSE) file for details.

## How to Cite

If you use this software in scientific work, please cite:

- **MIB Extractor** (v0.2.0), DOI: https://doi.org/10.5281/zenodo.18798971

Citation metadata is available in [CITATION.cff](CITATION.cff).

