swswswswsw/rukopys

--- language: - uk license: cc-by-nc-sa-4.0 task_categories: - object-detection - image-to-text tags: - handwriting-recognition - htr - ocr - bounding-box - ukrainian - document-analysis - cyrillic size_categories: - 10K<n<100K pretty_name: "RUKOPYS: Ukrainian Handwritten Text Recognition Dataset" authors: - Dmytro Voitekh - Volodymyr Zmiivskyyi - Oleksii Molchanovskyi organizations: - Ukrainian Catholic University configs: - config_name: full default: true data_files: - split: train path: - "train/metadata.jsonl" - "train/images/**" - split: silver path: - "silver/metadata.jsonl" - "silver/images/**" - config_name: gt_only data_files: - split: train path: - "train/metadata.jsonl" - "train/images/**" - config_name: test data_files: - split: test path: - "test/metadata.jsonl" - "test/images/**" --- # RUKOPYS: Ukrainian Handwritten Text Recognition Dataset **RUKOPYS** (Ukrainian: *рукопис* — manuscript) is the first large-scale open dataset for Ukrainian handwritten text recognition (HTR). It spans over a century of Ukrainian handwriting — from 1920s archival documents to present-day school homework — and is designed for end-to-end document understanding: region detection, type classification, and text transcription. Ukrainian is among the largest Slavic languages (45M+ native speakers) yet had no dedicated open HTR dataset prior to RUKOPYS. > **Competition:** RUKOPYS powers the [Handwritten to Data](https://www.kaggle.com/competitions/handwritten-to-data) challenge on Kaggle (April 16 — June 15, 2026). Submit your HTR model predictions and compete for $7,000 in prizes. --- ## What Makes RUKOPYS Different Most HTR datasets are built from a single source — one archive, one corpus, one handwriting style. RUKOPYS is deliberately the opposite. It combines four sources that differ across every dimension that makes handwriting recognition hard: | Dimension | Range in RUKOPYS | |-----------|-----------------| | **Time period** | 1919–1935 (archival pen & ink) → 2020–2025 (modern ballpoint, pencil) | | **Writers** | School children (grades 5–11), university students, adult citizens | | **Document type** | Archival state documents, personal dictation sheets, exam papers, homework | | **Capture method** | Flatbed scanner (archive, university) vs phone camera (dictation, school) | | **Orthography** | Archaic pre-reform spelling (1920s) → contemporary Ukrainian | | **Content** | Prose, formulas, chemistry, tables, teacher annotations | This breadth is intentional. A model trained only on clean archival scans will fail on a phone photo of a student notebook — and vice versa. RUKOPYS is designed so that the models trained on it generalize across real-world variation, not just perform well on a narrow slice of it. --- ## Splits | Split | Images | GT Regions | `annotation_source` | Description | |-------|--------|-----------|---------------------|-------------| | **train** | 770 | 16,381 | `annotator` / `volunteer` | Human-annotated — full bboxes + verified transcription | | **silver** | 8,210 | 163,081 | `auto` | Auto-annotated by Qwen3-VL 8B + Gemini — for self-training | | **test** | 386 | — (hidden) | — | Images only — submit predictions to the [Kaggle competition](https://www.kaggle.com/competitions/handwritten-to-data) | | **private benchmark** | 21 | — (hidden until June 15) | — | Held-out set withheld during the competition; published after the online stage closes as a reusable community benchmark | Use `annotation_source` to distinguish human GT from auto-annotations when combining splits. --- ## Data Sources | Source | ID | Period | Images (train+test) | Description | |--------|----|--------|---------------------|-------------| | National Dictation | `dictation` | 2020–2025 | 456 | Phone photos of handwritten Ukrainian National Dictation. One canonical text per year, thousands of unique handwriting styles. | | State Archive | `archive` | 1919–1935 | 169 | Scanned documents from 12 archival funds of the Central State Archive of Ukraine (ЦДАВО). Pen & ink, archaic orthography. | | University (KNUTE) | `university` | 2024–2025 | 246 | Scanned student exam work from 5 faculties: text, math formulas, chemistry, tables. | | School Homework | `school` | 2024–2025 | 285 | Phone photos of school homework (grades 5–11, 20+ subjects) from Opornyi Lyceum s. Zymne (Опорний ліцей с. Зимне). | --- ## Dataset Structure ``` train/ # Human-annotated (770 images) images/{uuid}.jpg metadata.jsonl # bbox + type + language + legibility + text silver/ # Auto-annotated (8,210 images) images/{uuid}.jpg metadata.jsonl # same schema as train test/ # Test images, no annotations (386 images) images/{uuid}.jpg metadata.jsonl # file_name, image_width, image_height, source (regions: null) ``` `train` and `silver` share the same schema and can be combined freely with `concatenate_datasets`. --- ## Loading ### With `datasets` (recommended — loads images as PIL, regions as structured fields) ```python from datasets import load_dataset, concatenate_datasets ds = load_dataset("UkrainianCatholicUniversity/rukopys") # Human-annotated train gt_train = ds["train"] example = gt_train[0] print(example["image"]) # PIL Image print(example["source"]) # "dictation" print(example["annotation_source"]) # "annotator" print(example["regions"]) # [{bbox, type, language, legibility, text}, ...] # Combine GT + silver full_train = concatenate_datasets([gt_train, ds["silver"]]) # GT-only config (no silver): ds_gt = load_dataset("UkrainianCatholicUniversity/rukopys", "gt_only") ``` ### With `pandas` ```python import pandas as pd df_train = pd.read_json("hf://datasets/UkrainianCatholicUniversity/rukopys/train/metadata.jsonl", lines=True) ``` ### With `polars` ```python import polars as pl df_train = pl.read_ndjson("hf://datasets/UkrainianCatholicUniversity/rukopys/train/metadata.jsonl") ``` ### Direct download with `huggingface_hub` ```python from huggingface_hub import snapshot_download path = snapshot_download(repo_id="UkrainianCatholicUniversity/rukopys", repo_type="dataset") # All files under `path` in the original folder structure (train/, silver/, test/) ``` --- ## Annotation Schema Each record in `train` and `silver` has a `regions` field — a list of annotated content regions: ```json { "file_name": "images/abc123.jpg", "image_width": 3024, "image_height": 4032, "source": "dictation", "annotation_source": "annotator", "regions": [ { "bbox": [134, 766, 3754, 1197], "type": "handwritten", "language": "uk", "legibility": "legible", "text": "Спочатку був брехунець. У нього кожного дня: „Клац!"" } ] } ``` `bbox` format: `[x1, y1, x2, y2]` — pixel coordinates, top-left origin. ### Region Types | Type | Description | Transcription | |------|-------------|---------------| | `handwritten` | Handwritten text line | Exact text, 1 bbox = 1 line | | `printed` | Printed/typed text line | Exact text, 1 bbox = 1 line | | `formula` | Standalone math/chemistry expression | LaTeX | | `table` | Full table | Pipe-separated values | | `annotation` | Teacher marks, grades, numbering | Short text | | `image` | Stamps, seals, drawings | Empty | | `graph` | Charts, plots | Empty | ### Special Text Markers | Marker | Meaning | |--------|---------| | `~~word~~` | Strikethrough text | | `~~old~~{new}` | Strikethrough with correction | | `[illegible]` | Unreadable word within a legible line | ### Region Attributes | Attribute | Values | |-----------|--------| | `language` | `uk`, `other` | | `legibility` | `legible`, `illegible` | | `annotation_source` | `annotator`, `volunteer`, `auto` | `annotation_source` values: | Value | Meaning | |-------|---------| | `annotator` | Labeled by [Keymakr](https://keymakr.com/) — professional human annotation service | | `volunteer` | Labeled by community volunteers; spot-checked for quality | | `auto` | Auto-generated by the VLM pipeline (silver split only) | --- ## Anti-Leakage Design | Source | Train | Test | Guarantee | |--------|-------|------|-----------| | **Dictation** | Year 2024 | Years 2020, 2022, 2025 | Different canonical texts | | **Archive** | Archival file set A | Archival file set B | Non-overlapping archival document sets | | **University** | Exam PDF group A | Exam PDF group B | Different students' exam files | | **School** | Grades 5, 6, 7, 9, 11 | Grades 8, 10 | Different grade bands | --- ## Silver Split The `silver` split contains 8,210 auto-annotated images generated by a multi-stage VLM pipeline: ``` Stage 1: Qwen3-VL 8B block detection Stage 2: Gemini Flash block classification Stage 3: Qwen3-VL 8B line segmentation within text blocks Stage 4: Gemini Flash transcription ``` Known limitations: bbox sequence drift on dense text; axis-aligned boxes may clip skewed lines; ~440 archive files contain mixed Ukrainian/Russian text from the 1919–1935 period. --- ## Acknowledgements Professional annotation was provided by [Keymakr](https://keymakr.com/), a human-in-the-loop data annotation company. Additional annotations were contributed by volunteers. The full list of contributors will be published shortly. All volunteer annotations underwent spot-checking for quality assurance. All images were reviewed prior to publication to remove personally identifiable information (PII). --- ## Roadmap This is the first public release of RUKOPYS. The dataset will grow incrementally — both through additional sources and through expanded coverage of existing ones. We welcome collaboration from: - **Annotators** interested in contributing human-verified labels - **Researchers** working on better automatic annotation approaches (layout analysis, HTR pre-annotation, active learning) If you'd like to contribute, reach out via the [Kaggle competition forum](https://www.kaggle.com/competitions/handwritten-to-data/discussion) or open an issue on HuggingFace. --- ## Potential Uses - Fine-tune HTR models on `train`, evaluate on `test` via the [Kaggle competition](https://www.kaggle.com/competitions/handwritten-to-data) - Pseudo-labeling: GT text for each dictation year is publicly known — use it for text-line alignment - Self-training / semi-supervised learning with the `silver` split - Multi-source domain adaptation (modern handwriting → historical documents) --- ## License **CC BY-NC-SA 4.0** — Attribution, Non-Commercial, Share-Alike. - **National Dictation** images: provided under a data sharing agreement for academic research and publication - **State Archive** (ЦДАВО): provided under a data sharing agreement for academic research and publication - **KNUTE** and **Opornyi Lyceum s. Zymne (Опорний ліцей с. Зимне)**: provided under data sharing agreements for academic research and publication --- ## Citation ```bibtex @dataset{rukopys_2026, title = {{RUKOPYS}: Ukrainian Handwritten Text Recognition Dataset}, author = {Dmytro Voitekh and Volodymyr Zmiivskyyi and Oleksii Molchanovskyi}, organization = {Ukrainian Catholic University}, year = {2026}, license = {CC BY-NC-SA 4.0}, url = {https://huggingface.co/UkrainianCatholicUniversity/rukopys}, note = {First large-scale Ukrainian HTR dataset; from 1920s archival documents to 2025 school homework and exams} } ```language: - uk license: cc-by-nc-sa-4.0 task_categories: - 目标检测（object-detection） - 图像到文本（image-to-text） tags: - 手写识别（handwriting-recognition） - 手写文本识别（HTR, Handwritten Text Recognition） - 光学字符识别（OCR, Optical Character Recognition） - 边界框（bounding-box） - 乌克兰语（ukrainian） - 文档分析（document-analysis） - 西里尔文（cyrillic） size_categories: - 10K<n<100K pretty_name: "RUKOPYS：乌克兰手写文本识别数据集" authors: - 德米特罗·沃伊泰赫（Dmytro Voitekh） - 弗拉基米尔·兹米伊夫斯基（Volodymyr Zmiivskyyi） - 阿列克谢·莫尔恰诺夫斯基（Oleksii Molchanovskyi） organizations: - 乌克兰天主教大学（Ukrainian Catholic University） configs: - config_name: full default: true data_files: - split: train path: - "train/metadata.jsonl" - "train/images/**" - split: silver path: - "silver/metadata.jsonl" - "silver/images/**" - config_name: gt_only data_files: - split: train path: - "train/metadata.jsonl" - "train/images/**" - config_name: test data_files: - split: test path: - "test/metadata.jsonl" - "test/images/**" # RUKOPYS：乌克兰手写文本识别数据集 **RUKOPYS**（乌克兰语: *рукопис* — 手稿）是首个面向乌克兰语的大规模开源手写文本识别（HTR, Handwritten Text Recognition）数据集。其涵盖了一个多世纪的乌克兰手写文本——从1920年代的档案文献到当代的学校作业，旨在支持端到端文档理解任务：区域检测、类型分类与文本转录。 乌克兰语是全球使用人数最多的斯拉夫语言之一（母语使用者超4500万），但在RUKOPYS发布前，尚无专门的开源HTR数据集。 > **赛事信息**：RUKOPYS 为 Kaggle 平台上的「Handwritten to Data」竞赛（2026年4月16日至6月15日）提供支持。参赛者可提交HTR模型预测结果，角逐总计7000美元的奖金池。 --- ## RUKOPYS的独特之处 绝大多数HTR数据集仅源自单一数据源——单一档案馆、单一语料库、单一手写风格。而RUKOPYS刻意打破了这一局限。 它整合了四大数据源，这些数据源在手写识别难度的所有维度上均存在显著差异： | 维度 | RUKOPYS中的覆盖范围 | |-----|-------------------| | **时间跨度** | 1919–1935年（档案用钢笔墨水书写） → 2020–2025年（现代圆珠笔、铅笔书写） | | **书写者群体** | 中小学生（5至11年级）、大学生、成年市民 | | **文档类型** | 官方档案文件、个人听写答卷、考试试卷、课后作业 | | **采集方式** | 平板扫描仪（档案、大学场景） vs 手机拍摄（听写、学校场景） | | **正字法** | 旧正字法改革前的拼写（1920年代） → 当代乌克兰语正字法 | | **文本内容** | 散文、公式、化学内容、表格、教师批注 | 这种广度的设计是有意为之。仅在干净的档案扫描样本上训练的模型，无法有效识别学生笔记本的手机拍摄照片——反之亦然。RUKOPYS的设计目标是让基于其训练的模型能够泛化到真实世界的各类变体中，而非仅在狭窄的细分场景下取得优异性能。 --- ## 数据集划分 | 划分 | 图像数量 | 真值区域数 | `annotation_source` | 描述 | |------|---------|-----------|-------------------|------| | **train（训练集）** | 770 | 16,381 | `annotator` / `volunteer` | 人工标注：包含完整边界框与经校验的转录文本 | | **silver（银标集）** | 8,210 | 163,081 | `auto` | 由Qwen3-VL 8B与Gemini自动标注，用于自训练 | | **test（测试集）** | 386 | —（隐藏） | — | 仅提供图像，需向Kaggle竞赛提交预测结果 | | **private benchmark（私有基准集）** |21 | —（2026年6月15日前隐藏） | — | 竞赛期间预留的数据集；线上阶段结束后发布，作为可复用的社区基准数据集 | 可通过`annotation_source`字段区分人工标注与自动标注结果，以便灵活合并不同划分。 --- ## 数据源 | 数据源 | 标识符 | 时间跨度 | 图像数量（训练集+测试集） | 描述 | |--------|--------|---------|-----------------------|------| | 全国听写活动 | `dictation` | 2020–2025 | 456 | 乌克兰全国听写活动手写文本的手机拍摄照片。每年采用统一的标准文本，涵盖数千种独特手写风格。 | | 国家档案馆 | `archive` |1919–1935 |169 | 乌克兰中央国家档案馆（ЦДАВО）12个档案库的扫描文档。采用钢笔墨水书写，使用旧正字法。 | | 国立基辅理工大学（KNUTE） | `university` |2024–2025 |246 | 来自5个院系的学生考试答卷扫描件：包含文本、数学公式、化学内容与表格。 | | 学校作业 | `school` |2024–2025 |285 | 来自兹姆内村奥波尔内中学（Опорний ліцей с. Зимне）的5至11年级学生课后作业的手机拍摄照片，涵盖20余门学科。 | --- ## 数据集结构 train/ # 人工标注（770张图像） images/{uuid}.jpg metadata.jsonl # 包含边界框、文本类型、语言、可识别度与转录文本 silver/ # 自动标注（8,210张图像） images/{uuid}.jpg metadata.jsonl # 与训练集schema一致 test/ # 测试集图像，无标注（386张图像） images/{uuid}.jpg metadata.jsonl # 包含file_name、image_width、image_height、source（regions字段为null） 训练集与银标集采用相同的元数据schema，可通过`concatenate_datasets`函数自由合并。 --- ## 数据集加载 ### 使用`datasets`库（推荐：自动加载PIL格式图像，结构化字段读取区域标注） python from datasets import load_dataset, concatenate_datasets ds = load_dataset("UkrainianCatholicUniversity/rukopys") # 加载人工标注的训练集 gt_train = ds["train"] example = gt_train[0] print(example["image"]) # PIL图像对象 print(example["source"]) # 数据源标识，例如"dictation" print(example["annotation_source"]) # 标注来源，例如"annotator" print(example["regions"]) # 区域标注列表：[{bbox, type, language, legibility, text}, ...] # 合并人工标注训练集与银标集 full_train = concatenate_datasets([gt_train, ds["silver"]]) # 仅真值配置（不含银标集）： ds_gt = load_dataset("UkrainianCatholicUniversity/rukopys", "gt_only") ### 使用`pandas`库 python import pandas as pd df_train = pd.read_json("hf://datasets/UkrainianCatholicUniversity/rukopys/train/metadata.jsonl", lines=True) ### 使用`polars`库 python import polars as pl df_train = pl.read_ndjson("hf://datasets/UkrainianCatholicUniversity/rukopys/train/metadata.jsonl") ### 通过`huggingface_hub`直接下载 python from huggingface_hub import snapshot_download path = snapshot_download(repo_id="UkrainianCatholicUniversity/rukopys", repo_type="dataset") # 所有文件将按照原始目录结构（train/、silver/、test/）下载至`path`路径下 --- ## 标注元数据规范 训练集与银标集的每条数据均包含`regions`字段，为标注内容区域的列表： json { "file_name": "images/abc123.jpg", "image_width": 3024, "image_height": 4032, "source": "dictation", "annotation_source": "annotator", "regions": [ { "bbox": [134, 766, 3754, 1197], "type": "handwritten", "language": "uk", "legibility": "legible", "text": "Спочатку був брехунець. У нього кожного дня: „Клац!" } ] } `bbox`格式为`[x1, y1, x2, y2]`，采用像素坐标，原点为图像左上角。 ### 区域类型 | 类型 | 描述 | 转录要求 | |------|-----|---------| | `handwritten` | 手写文本行 | 精确转录文本，1个边界框对应1行文本 | | `printed` | 印刷/打印文本行 | 精确转录文本，1个边界框对应1行文本 | | `formula` | 独立数学/化学表达式 | 采用LaTeX格式转录 | | `table` | 完整表格 | 采用竖线分隔的文本格式 | | `annotation` | 教师批改标记、分数、编号 | 简短文本转录 | | `image` | 印章、印记、绘图 | 转录文本为空 | | `graph` | 图表、绘图 | 转录文本为空 | ### 特殊文本标记 | 标记 | 含义 | |------|-----| | `~~word~~` | 删除线文本 | | `~~old~~{new}` | 删除线修正文本 | | `[illegible]` | 可读行内的不可读单词 | ### 区域属性 | 属性 | 可选值 | |------|-------| | `language` | `uk`（乌克兰语）、`other`（其他语言） | | `legibility` | `legible`（可识别）、`illegible`（不可识别） | | `annotation_source` | `annotator`（专业标注）、`volunteer`（志愿者标注）、`auto`（自动标注） | 标注来源字段的具体含义： | 值 | 含义 | |----|------| | `annotator` | 由[Keymakr](https://keymakr.com/)提供的专业人工标注服务 | | `volunteer` | 由社区志愿者标注，经抽样质检 | | `auto` | 由视觉语言模型（VLM）流水线自动生成（仅银标集使用） | --- ## 防数据泄露设计 | 数据源 | 训练集 | 测试集 | 保障机制 | |--------|-------|-------|---------| | **全国听写活动** | 2024年数据 | 2020、2022、2025年数据 | 使用不同的标准听写文本 | | **国家档案馆** | 档案集合A | 档案集合B | 采用完全不重叠的档案文档集 | | **国立基辅理工大学** | 试卷组A | 试卷组B | 采用不同学生的考试答卷 | | **学校作业** | 5、6、7、9、11年级学生作业 | 8、10年级学生作业 | 采用不同年级段的学生样本 | --- ## 银标集说明 银标集包含8210张自动标注的图像，由多阶段视觉语言模型流水线生成： 阶段1：Qwen3-VL 8B 块检测 阶段2：Gemini Flash 块分类 阶段3：Qwen3-VL 8B 文本块内行分割 阶段4：Gemini Flash 文本转录 已知局限性：密集文本场景下的边界框序列偏移问题；轴对齐边界框可能裁剪倾斜的文本行；约440份1919–1935年的档案文件包含混合的乌克兰语/俄语文本。 --- ## 致谢 专业标注服务由人机循环数据标注公司[Keymakr](https://keymakr.com/)提供。 额外标注由社区志愿者贡献，完整贡献者名单将在近期公布。所有志愿者标注均经过抽样质检以保障质量。 所有图像在发布前均经过审核，已移除所有个人可识别信息（PII）。 --- ## 开发路线图 本次为RUKOPYS的首次公开发布。数据集将持续迭代扩展——既会新增数据源，也会扩充现有数据源的覆盖范围。 我们欢迎以下群体参与合作： - 愿意贡献人工校验标注的**标注人员** - 致力于优化自动标注方法的**研究人员**（包括布局分析、HTR预标注、主动学习等方向） 若有意参与，可通过[Kaggle竞赛论坛](https://www.kaggle.com/competitions/handwritten-to-data/discussion)或在HuggingFace平台提交Issue联系我们。 --- ## 潜在应用场景 - 在训练集上微调HTR模型，通过Kaggle竞赛在测试集上进行评估 - 伪标签生成：各年度全国听写活动的标准文本均已公开，可用于文本行对齐任务 - 基于银标集的自训练/半监督学习 - 多源域自适应（现代手写文本 → 历史手写文献） --- ## 许可证 **CC BY-NC-SA 4.0** — 署名-非商业性使用-相同方式共享。 - **全国听写活动**图像：根据数据共享协议，仅可用于学术研究与出版 - **国家档案馆（ЦДАВО）**图像：根据数据共享协议，仅可用于学术研究与出版 - **国立基辅理工大学**与**兹姆内村奥波尔内中学**图像：根据数据共享协议，仅可用于学术研究与出版 --- ## 引用格式 bibtex @dataset{rukopys_2026, title = {{RUKOPYS}: Ukrainian Handwritten Text Recognition Dataset}, author = {Dmytro Voitekh and Volodymyr Zmiivskyyi and Oleksii Molchanovskyi}, organization = {Ukrainian Catholic University}, year = {2026}, license = {CC BY-NC-SA 4.0}, url = {https://huggingface.co/UkrainianCatholicUniversity/rukopys}, note = {首个大规模乌克兰语HTR数据集；涵盖1920年代档案文献至2025年学校作业与考试答卷} }