Metadata-Version: 2.4
Name: baglab
Version: 0.2.0
Summary: ROS2 rosbag data analysis library
Author: Kotakku
Author-email: Kotakku <kotakkucu@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Kotakku/baglab
Project-URL: Repository, https://github.com/Kotakku/baglab
Project-URL: Documentation, https://kotakku.github.io/baglab/
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: pyarrow
Requires-Dist: pyyaml
Requires-Dist: rosbags>=0.9.20
Requires-Dist: rosbags-dataframe
Requires-Dist: scipy
Requires-Dist: control
Requires-Dist: matplotlib
Requires-Dist: plotly
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Dynamic: license-file

# baglab

ROS2 rosbag data analysis library. Load, explore, and visualize rosbag data with MATLAB-like simplicity using pandas DataFrames.

## Features

- **Lazy loading** — open a bag and read only the topics you need
- **Dot-access** — navigate message fields like `msg.twist.linear.x`
- **Geometry** — quaternion/euler conversion, distance, pose interpolation
- **Signal processing** — lowpass filter, FFT, differentiation, integration
- **Diagnostics** — topic rate, message gaps, latency chain analysis
- **Plotting** — time-series, trajectory, step response, error band

## Installation

### Prerequisites

- Python 3.10+
- ROS2 (Humble / Jazzy)

### baglab (Python only)

```bash
pip install baglab
```

For development:

```bash
git clone https://github.com/Kotakku/baglab.git
cd baglab
pip install -e ".[dev]"
```

### C++ acceleration backend (optional)

Installing `baglab_cpp_backend` enables near I/O-bound rosbag loading via rosbag2_cpp.
Requires a sourced ROS2 environment.

```bash
source /opt/ros/humble/setup.bash  # or jazzy

# Option 1: pip install
cd baglab
pip install scikit-build-core pybind11 numpy
pip install --no-build-isolation ./baglab_cpp_backend

# Option 2: colcon build
colcon build --packages-select baglab_cpp_backend
source install/setup.bash
```

Check whether the backend is available:

```python
import baglab
print(baglab.has_cpp_backend())  # True / False
```

baglab works without the backend — it falls back to rosbags (pure Python).

## Usage

```python
import baglab

# Load a rosbag (lazy loading)
bag = baglab.load("path/to/rosbag")

# List topics
print(bag.topics)
# {"/motor/angle": "sensor_msgs/msg/JointState", ...}

# Access topic data (loaded on first access)
twist_df = bag["/cmd_vel"]

# Dot-access for message fields
twist_df.msg.twist.linear.x         # Series
twist_df.msg.twist.linear.df        # DataFrame (columns: [x, y, z])

# Timestamps
t = baglab.stamp_to_sec(twist_df)                  # absolute [s]
t = baglab.stamp_to_sec(twist_df, relative=True)   # relative (starts at 0)

# Reindex by publication timestamp
twist_df = baglab.reindex_by_stamp(twist_df)
```

### Plot example

```python
import baglab
import matplotlib.pyplot as plt

bag = baglab.load("path/to/rosbag")
twist_df = bag["/cmd_vel"]

t = baglab.stamp_to_sec(twist_df, relative=True)
vel = twist_df.msg.twist.linear.df

fig, axes = plt.subplots(3, 1, sharex=True)
for ax, axis_name in zip(axes, ["x", "y", "z"]):
    ax.plot(t, vel[axis_name])
    ax.set_ylabel(axis_name)
axes[-1].set_xlabel("time [s]")
plt.show()
```

## Documentation

[https://kotakku.github.io/baglab/](https://kotakku.github.io/baglab/)

## License

Apache-2.0
