# udataframe_rs

**Repository Path**: SongpingWang/udataframe_rs

## Basic Information

- **Project Name**: udataframe_rs
- **Description**: 自定义的静态数据处理库
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-28
- **Last Updated**: 2026-01-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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` 中添加：

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

## 快速上手

```rust
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` 等。这使得你可以编写高度泛型的代码：

```rust
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：

```rust
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`)

```text
+-----+-----+-----+-----+-----+-------+--------+------+-------+------------+----------+
| 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     | 票据代码:   |          |
+-----+-----+-----+-----+-----+-------+--------+------+-------+------------+----------+
```

## 完整使用示例

```rust
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`！特别是在处理复杂文档布局算法方面。