xbcar 1.0.1

车载CAN信号解析与可视化工具，支持静态图、动态图、HTML报告生成（含ECharts交互式图表）

xbcar

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

✨ 特性

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

📦 安装

使用pip

pip install xbcar

使用uv（推荐）

uv add xbcar

从源码安装

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

🚀 使用方式

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

---

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

启动服务：

# 直接运行（默认模式就是 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 调用

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：

# 直接使用 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 类

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 类

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交互式报告

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向后兼容模式

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轴图

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：完整工作流（批量处理）

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}")

🔧 日志配置

命令行日志参数

# 设置日志级别（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

代码中配置日志

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+）

📝 命令行参数完整列表

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                显示帮助信息

🔧 开发

开发环境设置

# 克隆仓库
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]"

运行测试

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信号分析更简单！