---
license: mit
pipeline_tag: object-detection
tags:
- table-detection
- spreadsheets
- object-detection
- faster-rcnn
- pytorch
---

# ExcelTableCNN: VEnron2 table detector

A Faster R-CNN table-boundary detector for spreadsheets, from
[ExcelTableCNN](https://github.com/Flagro/ExcelTableCNN), a license-clean
reimplementation of the TableSense approach. Given a sheet's cell grid it
predicts a bounding box (cell range) for each table, with PBR boundary snapping
and a grid-context backbone.

- Input: 30 per-cell feature channels, built by the package from `.xls`/`.xlsx`.
- Output: table bounding boxes as cell ranges, each with a confidence score.
- Weights: `final.pt` (about 201 MB), trained 160 epochs on the full VEnron2 set.

## Metrics

Evaluated on the held-out VEnron2 test split (197 sheets, 342 tables) at score
threshold 0.5, using the strict Error-of-Boundary metric (EoB-0 = cell-exact,
EoB-2 = within 2 cells):

| Metric | Precision | Recall |
|---|---|---|
| EoB-0 (exact) | 47.7% | 48.2% |
| EoB-2 (within 2 cells) | 66.5% | 67.3% |

The reloaded checkpoint reproduces these numbers exactly (RoI pooling scale
pinned to 1.0, see PR #8). For reference, the TableSense paper reports EoB-2
precision 86.5% / recall 91.3%, trained on about 25x more hand-labeled sheets.

## Usage

Install the package (it handles featurization and decoding):

```bash
pip install git+https://github.com/Flagro/ExcelTableCNN.git
```

Download the weights and detect tables from the command line:

```bash
huggingface-cli download flagro/exceltablecnn-venron2 final.pt --local-dir .
excel-table-cnn-detect report.xls --weights final.pt
# Sheet1!B2:H45   score=0.973
```

Or from Python:

```python
from huggingface_hub import hf_hub_download
from excel_table_cnn import load_checkpoint

path = hf_hub_download("flagro/exceltablecnn-venron2", "final.pt")
model = load_checkpoint(path, device="cpu")  # or "cuda"
```

## Training

- Data: VEnron2, 1,288 training sheets, via the ExcelTableCNN pipeline.
- Schedule: 160 epochs, batch size 1, SGD (lr 0.005, momentum 0.9, weight decay
  5e-4), 100-step warmup, constant LR, mixed precision.
- Featurization caps: default 2,048 x 512 cells. Seed 42.
- Hardware: single NVIDIA T4 (Kaggle), about 4 hours.
- Architecture: 30-channel input, grid-context backbone (stride 1), Faster
  R-CNN detection head, PBR boundary-snapping head, 2 classes (table vs
  background).
- Code: excel-table-cnn 0.3.0, commit `0ed4205`.

## Limitations

- Trained only on VEnron2 (Enron-derived financial and operational
  spreadsheets); expect lower accuracy on very different domains or layouts.
- Cell-exact (EoB-0) detection is still under 50%; boundaries are often off by 1
  to 2 cells, which is why EoB-2 is much higher. Use EoB-2 for downstream
  extraction that tolerates small boundary error.
- Sheets larger than 2,048 x 512 cells are clipped during featurization.

## License and data

Code and weights are MIT-licensed (see the
[repository](https://github.com/Flagro/ExcelTableCNN)). The training data is the
public VEnron2 corpus, derived from the Enron email dataset; confirm its terms
permit your intended redistribution or use.

## Citation

Built on the method from TableSense (Dong et al., AAAI 2019). Please cite the
original paper for the approach and link this repository for the implementation.