udataframe_rs

udataframe_rs 是一个专为处理结构化文档数据（如 PDF 解析结果、OCR 识别结果）设计的纯 Rust 轻量级数据框（DataFrame）库。

与通用的 DataFrame 库（如 Polars 或 Pandas）不同，udataframe_rs 针对文档布局特征进行了深度优化，内置了坐标过滤（Spatial Filtering）、页面管理、文本合并（Line Merging）等特化功能，并利用 Rust 的编译时特性提供高效、类型安全的字段访问。

核心特性

• 特化数据模型：内置 DataItem 结构，完美适配 PDF/OCR 的坐标（x0, y0, x1, y1）、页面、文本及标志位。
• 空间查询优化：支持基于坐标范围（如 x0y0x1y1 矩形区域）的快速数据筛选。
• 类型安全：通过编译时泛型特化（Field Traits）实现对不同字段（i32, String）的快速访问，避免运行时类型转换开销。
• 文本处理：集成正则表达式支持，提供正则筛选、提取、替换及基于长度的过滤。
• OCR 友好：内置对 OCR JSON 结果的解析支持。
• 格式化输出：支持将数据框直接打印为美观的 ASCII 表格，方便调试。

安装

在你的 Cargo.toml 中添加：

[dependencies]
udataframe_rs = "0.1.2"
regex = "1.12.1"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

快速上手

use udataframe_rs::{DataItem, UDataFrame, FieldText, FieldX0, Greater_};

fn main() {
    // 1. 创建数据框
    let mut df = UDataFrame::from_items([
        DataItem::new(0, 10, 20, 30, 40, 20, 20, 1, 0, "Hello", ""),
        DataItem::new(1, 50, 25, 80, 45, 30, 20, 1, 0, "Rust", ""),
        DataItem::new(2, 15, 60, 45, 80, 30, 20, 2, 0, "World", ""),
    ]);

    // 2. 基于坐标筛选 (x0 > 12)
    let filtered = df.df_x0_grate(12);

    // 3. 排序 (按 X0 字段升序)
    df.sort_by_field::<FieldX0>(false);

    // 4. 正则筛选文本长度 > 4 的行
    let regex_df = df.df_strlen_grate::<FieldText>(4);

    // 5. 打印结果表格
    df.format_print();
}

主要功能模块

1. 字段访问系统

库使用单态化技术定义了一系列字段类型，如 FieldX0, FieldY1, FieldText 等。这使得你可以编写高度泛型的代码：

use udataframe_rs::{DataItem, FieldText, FieldX0};

let item = DataItem::new(0, 10, 20, 30, 40, 20, 20, 1, 0, "Hello", "");
let val = item.field_const::<FieldText>(); // 获取 String 引用
let x = item.field_const::<FieldX0>();     // 获取 i32 引用

2. 空间/坐标过滤 (Spatial Query)

在处理文档数据时，经常需要获取页面某个区域内的文字：

• df_x0x1_in(x0, x1): 筛选处于指定水平范围内的项。
• df_x0y0x1y1(x0, y0, x1, y1): 筛选位于指定矩形框内的项。
• df_y1_less(val): 筛选 y1 坐标小于某值的项（通常用于获取"页眉"下方的数据）。

3. 正则表达式集成

深度集成 regex 库：

• df_regex::<FieldText>(&re): 筛选匹配正则的行。
• regex_replace::<FieldText, FieldTextSep>(&re, "replacement"): 正则替换并保存到新字段。
• regex_extract::<FieldText>(&re): 从文本中提取捕获组内容。

4. 文本长度过滤

支持根据文本长度进行过滤：

• df_strlen_grate::<FieldText>(len): 筛选文本长度大于指定值的项。
• df_strlen_less::<FieldText>(len): 筛选文本长度小于指定值的项。
• df_strlen_equal::<FieldText>(len): 筛选文本长度等于指定值的项。

5. 数据清洗与转换

• 行合并 (merge_line)：根据指定的横向和纵向阈值，将物理上断开但逻辑上属于一行的文本块进行合并。
• 数学运算：对坐标列进行批量加减（add, sub），常用于坐标系偏移校正。
• 统计：快速计算某一列的均值 (mean_col)、最大值 (max_col) 或最小值 (min_col)。
• 替换：支持字符串替换 (replace) 和多字符替换 (multi_replace)。

6. 多样化的返回类型

根据需求选择不同的返回形式：

• df_xxx: 返回一个新的 UDataFrame（拥有所有权，深拷贝）。
• idx_xxx: 返回符合条件的索引集合 Vec<usize>。
• ref_xxx: 返回符合条件的引用集合 Vec<&DataItem>（无拷贝，适合临时遍历）。

7. 特定索引操作

• df_from_idx(&[indices]): 根据指定索引获取数据项。
• df_drop_idx(&[indices]): 删除指定索引的数据项。

OCR 导入示例

你可以直接将 OCR 识别的 JSON 字符串导入为 DataFrame：

use udataframe_rs::UDataFrame;

let json_data = r#"{"description":"成功", "error_code":0,"recognize_time":123,"request_id":"12qer3", "result": [{"position": {"width": 604, "top": 74, "left": 434, "height": 39}, "score": 0.99235141, "type": "print", "words": "江苏省医疗门诊投费票据(电子)", "quad": "434,74,1038,74,1038,113,434,113"}], "rotation":90}"#;
let df = UDataFrame::from_ocr_str(json_data).expect("Parse error");

调试视图示例 (format_print)

+-----+-----+-----+-----+-----+-------+--------+------+-------+------------+----------+
| idx | x0  | y0  | x1  | y1  | width | height | page | flags | text       | text_sep |
+-----+-----+-----+-----+-----+-------+--------+------+-------+------------+----------+
| 0   | 434 | 74  | 1038| 113 | 604   | 39     | 0    | 0     | 医疗发票    |          |
| 1   | 95  | 193 | 185 | 213 | 90    | 20     | 0    | 0     | 票据代码:   |          |
+-----+-----+-----+-----+-----+-------+--------+------+-------+------------+----------+

完整使用示例

use udataframe_rs::{DataItem, UDataFrame, FieldText, FieldX0, Greater_};
use regex::Regex;

fn main() {
    // 1. 创建数据框
    let mut df = UDataFrame::from_items([
        DataItem::new(0, 10, 20, 30, 40, 20, 20, 1, 0, "Hello", ""),
        DataItem::new(1, 50, 25, 80, 45, 30, 20, 1, 0, "Rust", ""),
        DataItem::new(2, 15, 60, 45, 80, 30, 20, 2, 0, "World", ""),
    ]);

    // 2. 基于坐标筛选 (x0 > 12)
    let filtered = df.df_x0_grate(12);
    println!("Filtered by x0 > 12: {}", filtered.len());

    // 3. 排序 (按 X0 字段升序)
    df.sort_by_field::<FieldX0>(false);

    // 4. 正则筛选文本长度 > 4 的行
    let re = Regex::new(r"^[A-Z][a-z]*$").unwrap();
    let regex_filtered = df.df_regex_strlen_grate::<FieldText>(&re, 4);
    println!("Regex filtered: {}", regex_filtered.len());

    // 5. 基于文本长度过滤
    let length_filtered = df.df_strlen_grate::<FieldText>(4);
    println!("Length filtered: {}", length_filtered.len());

    // 6. 统计计算
    let mean_x0 = df.mean_col::<FieldX0>().unwrap();
    println!("Mean of X0: {}", mean_x0);

    // 7. 获取特定索引的数据
    let indices_df = df.df_from_idx(&[0, 2]);
    println!("Items at indices [0, 2]: {}", indices_df.len());

    // 8. 打印结果表格
    df.format_print();
}

开源协议

本项目采用 MIT 协议。

贡献

欢迎提交 Issue 或 Pull Request 来改进 udataframe_rs！特别是在处理复杂文档布局算法方面。