Metadata-Version: 2.1
Name: cfastblf
Version: 0.1.2
Summary: Cython-accelerated BLF file reading/writing and signal query library.
Author-email: rockswang <rockswang@foxmail.com>
License: # End User License Agreement (EULA)
        ## cfastblf Freeware License
        
        **IMPORTANT - READ CAREFULLY:** This End User License Agreement ("EULA") is a legal agreement between you (either an individual or a single entity) and the author of cfastblf for the software product identified above, which includes computer software and may include associated media, printed materials, and "online" or electronic documentation ("SOFTWARE PRODUCT"). By installing, copying, or otherwise using the SOFTWARE PRODUCT, you agree to be bound by the terms of this EULA. If you do not agree to the terms of this EULA, do not install or use the SOFTWARE PRODUCT.
        
        ## 1. GRANT OF LICENSE
        
        The SOFTWARE PRODUCT is licensed as follows:
        
        ### 1.1 Installation and Use
        The author grants you a non-exclusive, non-transferable, limited license to install and use the SOFTWARE PRODUCT for personal, educational, or commercial purposes.
        
        ### 1.2 Backup Copies
        You may make copies of the SOFTWARE PRODUCT as may be necessary for backup and archival purposes.
        
        ## 2. DESCRIPTION OF OTHER RIGHTS AND LIMITATIONS
        
        ### 2.1 Maintenance of Copyright Notices
        You must not remove or alter any copyright notices on any copies of the SOFTWARE PRODUCT.
        
        ### 2.2 Distribution
        You may redistribute the SOFTWARE PRODUCT in its original, unmodified form, provided that:
        - The original copyright notices are maintained
        - No fees are charged for the redistribution
        - The SOFTWARE PRODUCT is distributed with this EULA
        - The redistribution is not part of a commercial product or service
        
        ### 2.3 Prohibition on Reverse Engineering
        You may not reverse engineer, decompile, or disassemble the SOFTWARE PRODUCT, except and only to the extent that such activity is expressly permitted by applicable law notwithstanding this limitation.
        
        ### 2.4 Commercial Use
        The SOFTWARE PRODUCT may be used for commercial purposes without additional fees.
        
        ### 2.5 Technical Limitations
        The free version of the SOFTWARE PRODUCT has the following technical limitations:
        - Only supports Windows operating systems
        - Limited to processing 2 million CAN/CANFD frames
        - Data exceeding the frame limit will be truncated
        
        ## 3. COPYRIGHT
        
        All title and copyrights in and to the SOFTWARE PRODUCT (including but not limited to any images, photographs, animations, video, audio, music, text, and "applets" incorporated into the SOFTWARE PRODUCT), and any copies of the SOFTWARE PRODUCT are owned by the author. The SOFTWARE PRODUCT is protected by copyright laws and international treaty provisions. Therefore, you must treat the SOFTWARE PRODUCT like any other copyrighted material.
        
        ## 4. NO WARRANTIES
        
        The author expressly disclaims any warranty for the SOFTWARE PRODUCT. The SOFTWARE PRODUCT and any related documentation is provided "as is" without warranty of any kind, either express or implied, including, without limitation, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. The entire risk arising out of use or performance of the SOFTWARE PRODUCT remains with you.
        
        ## 5. LIMITATION OF LIABILITY
        
        In no event shall the author be liable for any special, consequential, incidental or indirect damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or any other pecuniary loss) arising out of the use of or inability to use the SOFTWARE PRODUCT, even if the author has been advised of the possibility of such damages.
        
        ## 6. TERMINATION
        
        Without prejudice to any other rights, the author may terminate this EULA if you fail to comply with the terms and conditions of this EULA. In such event, you must destroy all copies of the SOFTWARE PRODUCT and all of its component parts.
        
        ## 7. GOVERNING LAW
        
        This EULA shall be governed by and construed in accordance with the laws of the People's Republic of China.
        
        ## 8. CONTACT INFORMATION
        
        For questions about this EULA or to obtain a commercial license without the limitations of the free version, please contact:
        
        **Email:** rockswang@foxmail.com
        **GitHub:** https://github.com/rockswang/cfastblf
        
        ## 9. ENTIRE AGREEMENT
        
        This EULA constitutes the entire agreement between you and the author concerning the SOFTWARE PRODUCT and supersedes any prior verbal or written communications, proposals, or representations.
        
        ---
        
        **By installing or using the SOFTWARE PRODUCT, you acknowledge that you have read this agreement, understand it, and agree to be bound by its terms and conditions.**
Project-URL: Homepage, https://github.com/rockswang/cfastblf
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy >=1.16.0
Provides-Extra: dev
Requires-Dist: Cython >=3.1.0 ; extra == 'dev'

# cfastblf

Cython-accelerated BLF file reading/writing and signal query library.

## Project Introduction

`cfastblf` is a high-performance BLF (Binary Logging Format) file reading/writing library written in Cython, specifically designed for processing automotive bus data. By compiling critical performance paths into native code using Cython, it provides faster file parsing and processing speed compared to python-can.

This library supports reading, filtering, signal decoding, and exporting of CAN/CAN FD messages, offering both low-level direct access and high-level query usage patterns, suitable for automotive data analysis and test validation scenarios.

## Features

- **High-performance parsing**: Core logic compiled with Cython, significantly improving BLF file parsing speed
- **NumPy integration**: Uses NumPy structured arrays as memory data structures for high-speed data analysis and processing
- **Memory efficient**: Optimized index-data block storage structure effectively reduces memory usage, supports loading hundreds of millions of frame data at once
- **Complete protocol support**: Supports multiple message types including CAN, CAN FD, error frames, etc.
- **Flexible signal decoding**: Supports high-speed signal extraction and conversion based on DBC files
- **Advanced query functionality**: Provides expression-based message filtering and signal mapping
- **Platform compatibility**: Free version supports Windows, contact author for other system versions

## Installation

```bash
pip install cfastblf
```

## Usage

```python
from cfastblf import read, write, signal_decoder, Query

with open(r'myblf.blf', 'rb') as blf:  # Note: use binary read mode
    # Read all CAN/CANFD frames from BLF file, returns a tuple
    # The tuple contains: index array (numpy structured array) and compact data block (numpy byte array)
    # The dtype structure of index structured array: np.dtype([('timestamp', 'i8'), ('can_id', 'u4'), ('is64', 'u1'), ('channel', 'u1'), ('len', 'u1'), ('flags', 'u1'), ('loc', 'u8')])
    # Where:
    # * timestamp: timestamp in nanoseconds
    # * len: message payload length (bytes)
    # * flags: flag bits, from high to low: reserved, is_extended_id, is_remote_frame, is_error_frame, is_fd, is_rx, bitrate_switch, error_state_indicator
    # * loc: offset in data block (bytes)
    frames = read(blf)

# Low-level usage: directly read message frames
index, chunk = frames  # Destructure tuple, chunk can be reused by frame subsets
msg = index[5]  # The 5th CAN message (frame)
can_id = msg['can_id']  # Read CAN ID
payload = chunk[msg['loc']:msg['loc'] + msg['len']]  # Get message payload

# Low-level usage: filter frames with specific CAN_ID
sub = frames[0][frames[0]['can_id'] == 0x150]  # Pure numpy computation

# High-level usage: using query
from cantools import database as db
dbc = db.load_file(r'mybus.dbc', encoding='gbk')  # Load DBC file
qry = Query()  # Create query
qry.addDatabase(dbc)  # Add signal database
# Filter frames with CAN ID 0x150, note: must use 'frames' in query string to represent actual frame array
sub = qry.filter(frames, "frames['can_id'] == 0x150")  # Note: sub is still a tuple
# Decode ECU_150_CheckSum signal from all frames in subset sub
sig = qry.map(sub, 'signals.ECU_150_CheckSum(frames)')  # Returns float array

# Save frame subset as BLF file
with open('output.blf', 'wb') as f:  # Must use binary write mode
    write(f, sub)
```

## Free Version Limitations

This module is freeware, not open source software. Free version has the following limitations:
1. Only provides binary installation packages for Windows systems.
2. Only supports processing up to 2M CAN/CANFD frames, data exceeding this limit will be truncated.

## Contact Author

**Email:** rockswang@foxmail.com
**GitHub:** https://github.com/rockswang/cfastblf
