Metadata-Version: 2.4
Name: xbcar
Version: 1.0.1
Summary: 车载CAN信号解析与可视化工具，支持静态图、动态图、HTML报告生成（含ECharts交互式图表）
Project-URL: Homepage, https://gitee.com/xiaobaiOTS/xbcar
Project-URL: Issues, https://gitee.com/xiaobaiOTS/xbcar/issues
Project-URL: Documentation, https://gitee.com/xiaobaiOTS/xbcar/blob/main/README.md
Author-email: xiaobaiTser <807447312@qq.com>
License: MIT
License-File: LICENSE
Keywords: automotive,can,canoe,dbc,echarts,embedded,plot,signal,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Requires-Python: >=3.8
Requires-Dist: cantools>=39.0.0
Requires-Dist: loguru>=0.6.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: python-can>=4.0.0
Requires-Dist: scikit-learn>=1.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: flake8>=6.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-html>=3.1.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: black>=23.0.0; extra == 'full'
Requires-Dist: flake8>=6.0.0; extra == 'full'
Requires-Dist: flask-session>=0.4.0; extra == 'full'
Requires-Dist: flask>=2.0.0; extra == 'full'
Requires-Dist: isort>=5.12.0; extra == 'full'
Requires-Dist: mypy>=1.0.0; extra == 'full'
Requires-Dist: openpyxl>=3.0.0; extra == 'full'
Requires-Dist: pandas>=1.0.0; extra == 'full'
Requires-Dist: pytest-cov>=4.0.0; extra == 'full'
Requires-Dist: pytest-html>=3.1.0; extra == 'full'
Requires-Dist: pytest>=7.0.0; extra == 'full'
Provides-Extra: web
Requires-Dist: flask-session>=0.4.0; extra == 'web'
Requires-Dist: flask>=2.0.0; extra == 'web'
Requires-Dist: openpyxl>=3.0.0; extra == 'web'
Requires-Dist: pandas>=1.0.0; extra == 'web'
Description-Content-Type: text/markdown

# xbcar

车载CAN信号解析与可视化工具，支持静态图、动态图、HTML报告生成。

## ✨ 特性

- 📊 **静态图生成**：生成PNG格式的静态信号图
- 🎬 **动态GIF动画**：生成可交互的GIF动画
- 📈 **交互式ECharts图表**：HTML报告中使用ECharts实现真正的交互式图表
- 🔍 **DBC文件解析**：支持DBC数据库文件解码信号
- 📄 **HTML报告生成**：美观的HTML格式报告
- 🖥️ **Web管理界面**：基于Flask的可视化管理平台
- 📦 **灵活配置**：可指定信号、时间范围、值范围等
- 🐍 **Python 3.8+**：支持现代Python版本

## 📦 安装

### 使用pip

```bash
pip install xbcar
```

### 使用uv（推荐）

```bash
uv add xbcar
```

### 从源码安装

```bash
git clone https://gitee.com/xiaobaiOTS/xbcar.git
cd xbcar
pip install -e .
```

## 🚀 使用方式

xbcar 支持三种使用方式，推荐优先使用 Web 管理页面：

---

### 🖥️ 方式一：Web 管理页面（推荐）

**启动服务**：

```bash
# 直接运行（默认模式就是 serve）
xbcar

# 或者显式指定模式
xbcar --mode serve

# Linux环境下运行，禁止自动打开浏览器
xbcar --open-browser false
```

**访问地址**：http://localhost:5858

**默认登录**：
- 用户名：`xiaobai`
- 密码：`123456`

**Web管理页面功能**：

| 功能模块 | 说明 |
|----------|------|
| 📁 **文件加载** | 加载CAN日志文件（.asc/.blf）和DBC文件 |
| 📋 **信号列表** | 查看所有可用信号及其描述信息 |
| 📊 **统计分析** | 计算信号的统计特征（最小/最大/平均值、标准差等） |
| 🔍 **异常检测** | 检测信号中的异常值（超限、突变、超时） |
| ⚖️ **信号比较** | 设置多信号比较条件，分析事件触发时刻 |
| 📈 **趋势预测** | 基于线性回归预测信号未来趋势，查看R²系数评估拟合质量 |
| 💾 **数据导出** | 将信号数据导出为CSV或Excel格式 |
| 📋 **生成报告** | 生成包含统计信息和图表的HTML报告 |

**使用步骤**：

1. 启动 Web 服务
2. 访问 http://localhost:5858 并登录
3. 在"文件加载"页面选择日志文件（和可选的DBC文件）
4. 使用各个功能模块进行信号分析

---

### 🐍 方式二：API 调用

```python
from xbcar import CANSignalPlotter, PlotConfig

# 创建绘图器实例
plotter = CANSignalPlotter(
    log_file="path/to/log.asc",
    dbc_file="path/to/signals.dbc"  # 可选
)

# 查看可用信号
print(f"可用信号: {plotter.get_signal_names()}")

# 配置绘图参数
config = PlotConfig(
    signal_names=["ACC_AEBTargetRelSpeed", "ACC_AEBTargetLngRange"],
    time_range=(0.0, 60.0),  # 可选
    title="AEB信号分析",
    chart_type="echarts"  # 推荐使用ECharts
)

# 生成HTML报告（推荐）
plotter.generate_html_report(config, output_path="report.html")

# 或者生成静态图
plotter.plot_static(config, output_path="static_plot.png", is_show=False)

# 或者生成动态GIF
plotter.plot_interactive(config, output_path="animation.gif", is_show=False)
```

---

### 🖥️ 方式三：CMD 命令行

pip 安装后，可以直接使用 `xbcar` 命令，也可以使用 `python -m xbcar`：

```bash
# 直接使用 xbcar 命令（推荐）
# ECharts交互式HTML报告（推荐）
xbcar --log-file log.asc --dbc-file signals.dbc --mode report --chart-type echarts --output report.html

# 生成静态PNG图
xbcar --log-file log.asc --dbc-file signals.dbc --mode static --output static_plot.png

# 生成动态GIF动画
xbcar --log-file log.asc --dbc-file signals.dbc --mode interactive --output animation.gif --time-range 0 60

# 列出所有可用信号
xbcar --log-file log.asc --dbc-file signals.dbc --list-signals

# 启动Web管理页面（默认模式）
xbcar

# 或者显式指定模式
xbcar --mode serve

# 生成HTML报告
xbcar --log-file log.asc --mode report --output report.html
```

---

## 📚 API 文档

### CANSignalPlotter 类

```python
class CANSignalPlotter:
    def __init__(self, log_file: str, dbc_file: Optional[str] = None):
        """
        初始化CAN信号绘图器
        
        Args:
            log_file: CAN日志文件路径（支持.asc和.blf格式）
            dbc_file: DBC数据库文件路径（可选，用于信号解码）
        """
        
    def get_signal_names(self) -> List[str]:
        """获取所有可用的信号名称列表"""
        
    def get_time_range(self) -> Tuple[float, float]:
        """获取日志的时间范围（起始时间、结束时间）"""
        
    def compare_signals(self, trigger_signal: str, trigger_condition, 
                        target_signals: Dict[str, Any]) -> bool:
        """
        信号比较判断方法：基于触发信号的条件判断目标信号是否符合预期
        
        Args:
            trigger_signal: 触发信号名称
            trigger_condition: 触发条件，支持三种类型：
                - 精确值: 如 10, 20.5 等
                - 范围: 如 (10, 20) 表示 10 <= x <= 20
                - 操作符: 如 {"op": ">", "value": 10}，支持的操作符: >, <, >=, <=, ==, !=
            target_signals: 目标信号及其预期值或范围的字典
        
        Returns:
            bool: 所有目标信号都符合预期返回 True，否则返回 False
        
        Examples:
            # 精确值触发，精确值目标
            result = plotter.compare_signals("SignalA", 10, {"SignalB": 20})
            
            # 范围触发，范围目标
            result = plotter.compare_signals("SignalA", (10, 20), {"SignalB": (20, 30)})
            
            # 操作符触发
            result = plotter.compare_signals("SignalA", {"op": ">", "value": 20}, {"SignalB": 50})
            
            # 多个目标信号
            result = plotter.compare_signals("SignalA", 10, {
                "SignalB": 20,
                "SignalC": (15, 25),
                "SignalD": {"op": "<", "value": 30}
            })
        """
        
    def plot_static(self, config: PlotConfig, 
                    save_path: Optional[str] = None,
                    is_show: bool = False):
        """
        生成静态信号图
        
        Args:
            config: 绘图配置
            save_path: 保存路径（可选）
            is_show: 是否显示图片（默认False）
        """
        
    def plot_interactive(self, config: PlotConfig,
                        save_path: Optional[str] = None,
                        is_show: bool = False):
        """
        生成动态GIF动画
        
        Args:
            config: 绘图配置
            save_path: 保存路径（可选）
            is_show: 是否显示动画（默认False）
        """
        
    def plot_multi_axis(self, config: PlotConfig,
                        save_path: Optional[str] = None,
                        is_show: bool = False):
        """
        生成多Y轴信号图（适合值范围差异大的信号）
        
        Args:
            config: 绘图配置
            save_path: 保存路径（可选）
            is_show: 是否显示图片（默认False）
        """
        
    def generate_html_report(self, config: PlotConfig,
                            output_path: Optional[str] = None) -> Dict[str, Any]:
        """
        生成HTML格式报告（含ECharts或matplotlib图表）
        
        Args:
            config: 绘图配置
            output_path: 报告保存路径（可选，默认"signal_report.html"）
            
        Returns:
            包含报告信息的字典
        """
```

### PlotConfig 类

```python
from dataclasses import dataclass
from typing import List, Tuple, Optional

@dataclass
class PlotConfig:
    """绘图配置类"""
    signal_names: Optional[List[str]] = None  # 要显示的信号名称列表，不指定则显示所有
    time_range: Optional[Tuple[float, float]] = None  # 时间范围（起始时间、结束时间），单位：秒
    value_range: Optional[Tuple[float, float]] = None  # 值范围（最小值、最大值）
    figure_size: Tuple[int, int] = (16, 10)  # 图表尺寸（宽度、高度），单位：英寸
    animation_interval: int = 100  # 动画帧间隔，单位：毫秒
    show_grid: bool = True  # 是否显示网格
    title: Optional[str] = None  # 图表标题（不指定则使用日志文件名）
    image_format: str = "png"  # 报告中图片格式（仅在chart_type="matplotlib"时有效）
    chart_type: str = "echarts"  # 图表类型："echarts"（推荐）或"matplotlib"
```

## 📋 完整示例

### 示例1：ECharts交互式报告

```python
from xbcar import CANSignalPlotter, PlotConfig

plotter = CANSignalPlotter("log.asc", "signals.dbc")

config = PlotConfig(
    signal_names=["Signal1", "Signal2", "Signal3"],
    time_range=(0.0, 120.0),  # 只显示前2分钟
    title="完整信号分析",
    chart_type="echarts"
)

report_data = plotter.generate_html_report(config, output_path="complete_report.html")
print(f"报告已生成，包含 {report_data['total_signals']} 个信号")
```

### 示例2：matplotlib向后兼容模式

```python
from xbcar import CANSignalPlotter, PlotConfig

plotter = CANSignalPlotter("log.asc", "signals.dbc")

config = PlotConfig(
    signal_names=["Speed", "Brake"],
    time_range=(0.0, 60.0),
    title="matplotlib模式",
    chart_type="matplotlib",
    image_format="png"
)

plotter.generate_html_report(config, output_path="matplotlib_report.html")
```

### 示例3：多Y轴图

```python
from xbcar import CANSignalPlotter, PlotConfig

plotter = CANSignalPlotter("log.asc", "signals.dbc")

config = PlotConfig(
    signal_names=["Voltage", "Current", "Temperature"],  # 值范围差异大
    time_range=(0.0, 300.0)
)

plotter.plot_multi_axis(config, save_path="multi_axis.png", is_show=False)
```

### 示例4：完整工作流（批量处理）

```python
from xbcar import CANSignalPlotter, PlotConfig
import os

log_files = ["log1.asc", "log2.asc", "log3.asc"]
dbc_file = "signals.dbc"

for log_file in log_files:
    plotter = CANSignalPlotter(log_file, dbc_file)
    
    base_name = os.path.splitext(os.path.basename(log_file))[0]
    
    config = PlotConfig(
        signal_names=["Acceleration", "Speed"],
        chart_type="echarts"
    )
    
    plotter.generate_html_report(config, output_path=f"report_{base_name}.html")
    print(f"已处理: {log_file}")
```

## 🔧 日志配置

### 命令行日志参数

```bash
# 设置日志级别（DEBUG、INFO、WARNING、ERROR）
python -m xbcar --log-file log.asc --dbc-file signals.dbc --mode report --log-level INFO

# 将日志保存到文件
python -m xbcar --log-file log.asc --dbc-file signals.dbc --mode report --log-output app.log
```

### 代码中配置日志

```python
from loguru import logger
import sys

# 配置日志输出级别
logger.remove()
logger.add(sys.stderr, level="INFO")  # 可选：DEBUG、INFO、WARNING、ERROR
```

## 📊 输出格式对比

| 格式 | 类型 | 特点 | 推荐场景 |
|------|------|------|----------|
| ECharts (HTML) | 交互式动态图表 | 可缩放、悬停显示值、支持多Y轴 | **日常分析（推荐）** |
| PNG (matplotlib) | 静态图片 | 高质量静态图 | 文档插图 |
| GIF (matplotlib) | 动态动画 | 播放动画效果 | 演示用途 |
| PNG (matplotlib, 多Y轴) | 静态图片 | 适合值范围差异大的信号 | 特定分析场景 |

## 🔍 支持的文件格式

### 日志文件格式

- `.asc`：Vector CANoe格式
- `.blf`：Vector BLF（Binary Logging Format）

### 数据库文件格式

- `.dbc`：CAN Database文件（DBC v2.0+）

## 📝 命令行参数完整列表

```bash
python -m xbcar [OPTIONS]

必须参数:
--log-file FILE           CAN日志文件路径（支持.asc和.blf格式）
--dbc-file FILE           DBC数据库文件路径（可选）

模式选择:
--mode {static,interactive,multi-axis,report,list-signals}
                            输出模式（默认: report）
                            - static: 静态PNG图
                            - interactive: 动态GIF动画
                            - multi-axis: 多Y轴静态图
                            - report: HTML报告（默认）
                            - list-signals: 列出所有可用信号

输出配置:
--output FILE             输出文件路径（PNG、GIF或HTML）
--title TEXT              图表标题（不指定则使用日志文件名）

信号配置:
--signals [NAME ...]      要显示的信号名称列表，不指定则显示所有
--time-range START END    时间范围（起始时间 结束时间），单位：秒
--value-range MIN MAX     值范围（最小值 最大值）

图表配置:
--chart-type {echarts,matplotlib}
                            报告中图表类型（仅在report模式下有效，默认: echarts）
                            - echarts: 交互式ECharts图表（推荐）
                            - matplotlib: matplotlib静态图片
--image-format {png,gif}  报告中图片格式（仅在chart-type=matplotlib时有效，默认: png）
--figure-size WIDTH HEIGHT
                            图表尺寸（宽度 高度），单位：英寸（默认: 16 10）
--animation-interval MS   动画帧间隔，单位：毫秒（仅interactive模式有效，默认: 100）

Web服务配置（仅在serve模式下有效）:
--host HOST               Web服务主机地址（默认: 127.0.0.1）
--port PORT               Web服务端口（默认: 5858）
--username USERNAME       登录用户名（默认: xiaobai）
--password PASSWORD       登录密码（默认: 123456）
--open-browser            是否自动打开浏览器（默认: True）

其他选项:
--show                    是否在执行时显示图表（仅在interactive/static/multi-axis模式有效）
--log-level {DEBUG,INFO,WARNING,ERROR}
                            日志级别（默认: INFO）
--log-output FILE         日志输出文件路径（可选，设置后日志同时输出到文件）
-h, --help                显示帮助信息
```

## 🔧 开发

### 开发环境设置

```bash
# 克隆仓库
git clone https://gitee.com/xiaobaiOTS/xbcar.git
cd xbcar

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或
.\venv\Scripts\activate  # Windows

# 安装开发依赖
pip install -e ".[dev]"
```

### 运行测试

```bash
pytest tests/
```

## 🐛 常见问题

### Q: 加载DBC文件失败怎么办？

A: 工具会尝试以非严格模式加载，跳过有问题的消息。可以查看日志了解具体信息。

### Q: Windows终端中文乱码？

A: 工具已内置UTF-8编码支持，如果仍有问题，可以尝试设置终端编码为UTF-8。

### Q: ECharts图表加载慢？

A: ECharts使用CDN加载，确保网络连接正常。如果离线环境，需要下载echarts.min.js到本地并修改HTML。

### Q: 信号数量太多，图表太乱？

A: 建议使用`--signals`参数指定要分析的信号，或者手动调整HTML中ECharts配置。

### Q: Web管理页面登录失败？

A: 默认用户名是 `xiaobai`，密码是 `123456`。如果仍有问题，请检查服务是否正常启动。

## 📄 许可证

MIT License - 详见LICENSE文件。

## 🤝 贡献

欢迎贡献！请先阅读 CONTRIBUTING.md（如果有）。

## 📞 联系方式

如有问题或建议，请：
1. 提交 Gitee Issue
2. 发送邮件

---

🎉 **开始使用 xbcar，让CAN信号分析更简单！**