synthocr 2.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- synthocr-2.1.0/LICENSE-APACHE +202 -0
- synthocr-2.1.0/LICENSE-MIT +21 -0
- synthocr-2.1.0/NOTICE +25 -0
- synthocr-2.1.0/PKG-INFO +261 -0
- synthocr-2.1.0/README.md +230 -0
- synthocr-2.1.0/pyproject.toml +95 -0
- synthocr-2.1.0/pyproject.toml.orig +72 -0
- synthocr-2.1.0/synthocr/__init__.py +3 -0
- synthocr-2.1.0/synthocr/__main__.py +3 -0
- synthocr-2.1.0/synthocr/cli.py +540 -0
- synthocr-2.1.0/synthocr/config.py +589 -0
- synthocr-2.1.0/synthocr/corpora.py +160 -0
- synthocr-2.1.0/synthocr/corpus_store.py +222 -0
- synthocr-2.1.0/synthocr/downloads.py +77 -0
- synthocr-2.1.0/synthocr/experiments.py +399 -0
- synthocr-2.1.0/synthocr/font_catalog.json +579 -0
- synthocr-2.1.0/synthocr/font_profiles.json +18 -0
- synthocr-2.1.0/synthocr/fonts.py +225 -0
- synthocr-2.1.0/synthocr/home.py +150 -0
- synthocr-2.1.0/synthocr/kurdish_characters.json +442 -0
- synthocr-2.1.0/synthocr/kurdish_spelling.json +45 -0
- synthocr-2.1.0/synthocr/lexicons.json +82 -0
- synthocr-2.1.0/synthocr/pipeline.py +512 -0
- synthocr-2.1.0/synthocr/preview.py +112 -0
- synthocr-2.1.0/synthocr/render.py +555 -0
- synthocr-2.1.0/synthocr/spelling.py +111 -0
- synthocr-2.1.0/synthocr/static/app.css +1111 -0
- synthocr-2.1.0/synthocr/static/app.js +1759 -0
- synthocr-2.1.0/synthocr/static/brand.svg +5 -0
- synthocr-2.1.0/synthocr/static/index.html +773 -0
- synthocr-2.1.0/synthocr/static/theme.js +28 -0
- synthocr-2.1.0/synthocr/text.py +437 -0
- synthocr-2.1.0/synthocr/verify.py +307 -0
- synthocr-2.1.0/synthocr/web.py +2259 -0
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ardalan Jalal
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
synthocr-2.1.0/NOTICE
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
SynthOCR
|
|
2
|
+
Copyright (c) 2026 Ardalan Jalal
|
|
3
|
+
|
|
4
|
+
The SynthOCR source code is licensed under either of the MIT License
|
|
5
|
+
(LICENSE-MIT) or the Apache License, Version 2.0 (LICENSE-APACHE), at your
|
|
6
|
+
option.
|
|
7
|
+
|
|
8
|
+
The code license does not cover the following, which keep their own terms:
|
|
9
|
+
|
|
10
|
+
- Fonts in fonts/open/: SIL Open Font License 1.1. Each family includes its
|
|
11
|
+
OFL.txt; synthocr/font_catalog.json pins the upstream commit and checksums.
|
|
12
|
+
- Tatoeba sentences in data/raw/tatoeba/: CC BY 2.0 France. Contributor
|
|
13
|
+
attribution is kept with every record and in each dataset's origins.jsonl.
|
|
14
|
+
- Synthetic template text in data/raw/synthetic-v2/ and the Kurdish spelling
|
|
15
|
+
cases in data/raw/kurdish-spelling-v1/: CC0 1.0, as recorded per record.
|
|
16
|
+
- data/raw/examples.jsonl: example text written for this project, licensed
|
|
17
|
+
with the code.
|
|
18
|
+
- data/raw/kurdish_corpus.txt, data/raw/legacy_text.txt, data/raw/symbols.txt
|
|
19
|
+
and data/raw/char_map.json: original inputs whose upstream source and
|
|
20
|
+
redistribution terms were not recorded. No license is granted for them.
|
|
21
|
+
- The Kurdish reference characters in synthocr/kurdish_characters.json come
|
|
22
|
+
from https://github.com/ardalan-jalal/font-checking.
|
|
23
|
+
|
|
24
|
+
Datasets you generate inherit the terms of the text and fonts used to make them.
|
|
25
|
+
See data/SOURCES.md and fonts/README.md for details.
|
synthocr-2.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: synthocr
|
|
3
|
+
Version: 2.1.0
|
|
4
|
+
Summary: OCR training data for Kurdish and other languages: text images with exact labels
|
|
5
|
+
Keywords: ocr,synthetic-data,kurdish,sorani,kurmanji,text-recognition,dataset
|
|
6
|
+
Author: Ardalan Jalal
|
|
7
|
+
License-Expression: MIT OR Apache-2.0
|
|
8
|
+
License-File: LICENSE-APACHE
|
|
9
|
+
License-File: LICENSE-MIT
|
|
10
|
+
License-File: NOTICE
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Natural Language :: Arabic
|
|
15
|
+
Classifier: Natural Language :: English
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Classifier: Topic :: Scientific/Engineering :: Image Recognition
|
|
18
|
+
Classifier: Topic :: Text Processing :: Linguistic
|
|
19
|
+
Requires-Dist: pillow>=13.0.0
|
|
20
|
+
Requires-Dist: fonttools>=4.67.0
|
|
21
|
+
Requires-Dist: regex>=2026.9.29
|
|
22
|
+
Requires-Dist: fastapi>=0.162.0 ; extra == 'web'
|
|
23
|
+
Requires-Dist: uvicorn>=0.53.0 ; extra == 'web'
|
|
24
|
+
Requires-Python: >=3.14
|
|
25
|
+
Project-URL: Homepage, https://github.com/ardalan-jalal/SynthOCR
|
|
26
|
+
Project-URL: Documentation, https://github.com/ardalan-jalal/SynthOCR/blob/main/docs/ui.md
|
|
27
|
+
Project-URL: Repository, https://github.com/ardalan-jalal/SynthOCR
|
|
28
|
+
Project-URL: Issues, https://github.com/ardalan-jalal/SynthOCR/issues
|
|
29
|
+
Provides-Extra: web
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
<p align="center">
|
|
33
|
+
<img src="https://raw.githubusercontent.com/ardalan-jalal/SynthOCR/main/docs/readme-banner.svg" width="100%" alt="SynthOCR — OCR training data for Kurdish. Text images with exact labels, made on your computer.">
|
|
34
|
+
</p>
|
|
35
|
+
|
|
36
|
+
<p align="center">
|
|
37
|
+
<a href="https://pypi.org/project/synthocr/"><img alt="PyPI" src="https://img.shields.io/pypi/v/synthocr?color=a99aff"></a>
|
|
38
|
+
<img alt="Python 3.14+" src="https://img.shields.io/badge/Python-3.14%2B-3776ab?logo=python&logoColor=white">
|
|
39
|
+
<a href="https://github.com/ardalan-jalal/SynthOCR/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/ardalan-jalal/SynthOCR/actions/workflows/ci.yml/badge.svg"></a>
|
|
40
|
+
<a href="#license-and-credits"><img alt="License: MIT OR Apache-2.0" src="https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-2f9e6e"></a>
|
|
41
|
+
</p>
|
|
42
|
+
|
|
43
|
+
<p align="center">
|
|
44
|
+
<a href="#quickstart">Quickstart</a> /
|
|
45
|
+
<a href="#common-use-cases">Use cases</a> /
|
|
46
|
+
<a href="#what-you-get">Output</a> /
|
|
47
|
+
<a href="#command-line">Command line</a> /
|
|
48
|
+
<a href="#how-it-works">How it works</a> /
|
|
49
|
+
<a href="#documentation">Documentation</a>
|
|
50
|
+
</p>
|
|
51
|
+
|
|
52
|
+
**SynthOCR makes OCR training data for Kurdish.** Choose your text and a look; it
|
|
53
|
+
renders text images, each with its exact text label (ground truth), and saves them
|
|
54
|
+
to a folder on your computer.
|
|
55
|
+
|
|
56
|
+
It is built for Sorani and Kurmanji, with Arabic and English, and handles what makes
|
|
57
|
+
Kurdish hard: joining letters, right-to-left text mixed with numbers and Latin
|
|
58
|
+
words, and fonts that silently miss letters. One Python package powers the web app
|
|
59
|
+
and the command line. Everything runs locally.
|
|
60
|
+
|
|
61
|
+
## Quickstart
|
|
62
|
+
|
|
63
|
+
Install the package with [uv](https://docs.astral.sh/uv/getting-started/installation/)
|
|
64
|
+
(or `pip install "synthocr[web]"`) and start the app:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
uv tool install "synthocr[web]"
|
|
68
|
+
synthocr ui
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The app opens at **[127.0.0.1:8000](http://127.0.0.1:8000)**. Stop it with
|
|
72
|
+
**Ctrl+C**. On first start it downloads open fonts and Kurdish, Arabic and English
|
|
73
|
+
text (about 80 MB, under a minute) into your SynthOCR folder; run `synthocr setup`
|
|
74
|
+
to do this ahead of time, or `synthocr setup --offline` without the Tatoeba text.
|
|
75
|
+
|
|
76
|
+
<details>
|
|
77
|
+
<summary><strong>Where are my files?</strong> And how to run from source.</summary>
|
|
78
|
+
|
|
79
|
+
Fonts, text and the app's own copy of each dataset live in your SynthOCR folder:
|
|
80
|
+
`~/Library/Application Support/SynthOCR` on macOS, `%LOCALAPPDATA%\SynthOCR` on
|
|
81
|
+
Windows and `~/.local/share/synthocr` on Linux. Set `SYNTHOCR_HOME` to use another
|
|
82
|
+
folder. Datasets you save go wherever you choose.
|
|
83
|
+
|
|
84
|
+
To work on SynthOCR itself, run it from a clone; it then uses the repository's
|
|
85
|
+
`config.toml`, fonts and text:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
git clone https://github.com/ardalan-jalal/SynthOCR.git
|
|
89
|
+
cd SynthOCR
|
|
90
|
+
uv sync --locked --extra web
|
|
91
|
+
uv run --extra web synthocr ui
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
</details>
|
|
95
|
+
|
|
96
|
+
<details>
|
|
97
|
+
<summary><strong>macOS or Windows?</strong> Install the text-shaping libraries first.</summary>
|
|
98
|
+
|
|
99
|
+
On **macOS**:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
brew install freetype harfbuzz fribidi libraqm jpeg-turbo libtiff webp
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
On **Windows**, install [MSYS2](https://www.msys2.org/), run
|
|
106
|
+
`pacman -S mingw-w64-ucrt-x86_64-fribidi` in its terminal and add
|
|
107
|
+
`C:\msys64\ucrt64\bin` to your `PATH`. On **Debian/Ubuntu**, you may need
|
|
108
|
+
`sudo apt-get install libfribidi0`.
|
|
109
|
+
|
|
110
|
+
Check that shaping works; this must print `True`:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
uv run python -c 'from PIL import features; print(features.check_feature("raqm"))'
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
</details>
|
|
117
|
+
|
|
118
|
+
## Make a dataset
|
|
119
|
+
|
|
120
|
+
1. **Text:** pick languages (Sorani, Kurmanji, Arabic, English) and, with several,
|
|
121
|
+
each one's share. Use the built-in text or upload a TXT, CSV or JSONL file.
|
|
122
|
+
2. **Look:** choose **Clean**, **Balanced** or **Varied**. **Customize** sets
|
|
123
|
+
backgrounds, effects, tilt, blur and text size; **Fonts** picks fonts or adds
|
|
124
|
+
your own.
|
|
125
|
+
3. **Generate:** choose a folder and a label format, then click
|
|
126
|
+
**Generate dataset**. Every image is checked against its label before it is saved.
|
|
127
|
+
|
|
128
|
+
<details>
|
|
129
|
+
<summary><strong>See the app</strong> — one Sorani sentence, clean and in three Balanced styles.</summary>
|
|
130
|
+
|
|
131
|
+
<p align="center">
|
|
132
|
+
<img src="https://raw.githubusercontent.com/ardalan-jalal/SynthOCR/main/docs/readme-app.png" width="520" alt="The Look step of SynthOCR: Clean, Balanced and Varied styles, and a preview of one Sorani sentence on a clean background, an office scan, aged paper and a phone photo, with its exact text label.">
|
|
133
|
+
</p>
|
|
134
|
+
|
|
135
|
+
</details>
|
|
136
|
+
|
|
137
|
+
Saving into a folder needs Chrome or Edge; other browsers download a ZIP.
|
|
138
|
+
|
|
139
|
+
## Common use cases
|
|
140
|
+
|
|
141
|
+
| Use case | Example |
|
|
142
|
+
| --- | --- |
|
|
143
|
+
| Fine-tune an OCR model | Make line images with exact labels for Tesseract, TrOCR, PaddleOCR, docTR or your own model. |
|
|
144
|
+
| Fill gaps in real data | Add scanned, aged and photographed looks, or rare letters and numbers, that a small real dataset lacks. |
|
|
145
|
+
| Test fonts for Kurdish | See which fonts draw every Sorani or Kurmanji letter correctly before you use them. |
|
|
146
|
+
| Check an OCR pipeline | Feed known text through your OCR and compare its output with the exact labels. |
|
|
147
|
+
| Teaching and research | Show how shaping, direction and image quality affect recognition, with reproducible settings. |
|
|
148
|
+
|
|
149
|
+
Synthetic images help, but they are not a substitute for real documents. Measure
|
|
150
|
+
your model on real, hand-checked text before trusting it.
|
|
151
|
+
|
|
152
|
+
## What you get
|
|
153
|
+
|
|
154
|
+
```text
|
|
155
|
+
my-dataset/
|
|
156
|
+
images/00000000.png … the text images
|
|
157
|
+
labels.csv or manifest.jsonl, metadata.jsonl, *.gt.txt (your format)
|
|
158
|
+
origins.jsonl where each text came from, with its license
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
| Format | Contents |
|
|
162
|
+
| --- | --- |
|
|
163
|
+
| Images + labels.jsonl | One JSON line per image: text, language, font, text position, source and checksum. |
|
|
164
|
+
| Images + labels.csv | Image file name and text, one row per image. |
|
|
165
|
+
| Images + .gt.txt | A text file next to each image, for Tesseract training. |
|
|
166
|
+
| Hugging Face ImageFolder | Images and `metadata.jsonl` for `datasets.load_dataset("imagefolder")`. |
|
|
167
|
+
|
|
168
|
+
Labels keep the original logical character order, including right-to-left and
|
|
169
|
+
mixed-script text. They are never changed to fit a font: each label is drawn only
|
|
170
|
+
in a font that has every one of its characters.
|
|
171
|
+
|
|
172
|
+
## Command line
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
synthocr kurdish # 1,000 Sorani images, verified
|
|
176
|
+
synthocr kurdish --language both --samples 10000 # Sorani and Kurmanji
|
|
177
|
+
synthocr generate --language ckb --language en \
|
|
178
|
+
--language-weight ckb=70 --language-weight en=30 --samples 5000 --output dataset/mixed
|
|
179
|
+
synthocr export --dataset dataset/mixed --format csv --output dataset/mixed-csv
|
|
180
|
+
synthocr kurdish --check --language both # all 274 Kurdish spelling cases
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
<details>
|
|
184
|
+
<summary><strong>Common options</strong></summary>
|
|
185
|
+
|
|
186
|
+
| Option | What it does |
|
|
187
|
+
| --- | --- |
|
|
188
|
+
| `--samples N` | Number of images. |
|
|
189
|
+
| `--language TAG` | Use text tagged with this language (`ckb`, `kmr`, `ar`, `en`, …); repeat to combine. |
|
|
190
|
+
| `--language-weight TAG=N` | Share of images per language; omitted languages weigh 1, 0 excludes one. |
|
|
191
|
+
| `--font FILE` | Use only this font (name or ID from `synthocr fonts list`); repeat. |
|
|
192
|
+
| `--augmentation 0..1` | Share of images with backgrounds and effects. |
|
|
193
|
+
| `--background-preset NAME` | Document background, e.g. `office-scan`, `aged-paper`; repeat to mix. |
|
|
194
|
+
| `--rotation`, `--blur`, `--contrast` | Upper limits for tilt (degrees), blur (pixels) and contrast change. |
|
|
195
|
+
| `--format png\|jpg\|webp\|tif` | Image format. |
|
|
196
|
+
| `--seed N`, `--workers N` | Reproducibility and parallel workers. |
|
|
197
|
+
| `--output PATH` | A new, empty folder; existing data is never overwritten. |
|
|
198
|
+
|
|
199
|
+
See `synthocr generate --help` and [augmentation settings](https://github.com/ardalan-jalal/SynthOCR/blob/main/docs/augmentation.md).
|
|
200
|
+
|
|
201
|
+
</details>
|
|
202
|
+
|
|
203
|
+
## How it works
|
|
204
|
+
|
|
205
|
+
SynthOCR takes text from the bundled corpus or your file, picks for each label a
|
|
206
|
+
font that can draw all of it, and renders it with Pillow and RAQM (HarfBuzz and
|
|
207
|
+
FriBiDi) for correct shaping and direction. Backgrounds and effects (paper texture,
|
|
208
|
+
grain, shadows, stains, folds, scan bands, tilt, blur) are generated procedurally;
|
|
209
|
+
no images are downloaded. Every image is then decoded and checked against its
|
|
210
|
+
label, checksum and bounds before the dataset is offered to you.
|
|
211
|
+
|
|
212
|
+
Text is streamed from a SQLite index and images are written as they are made, so
|
|
213
|
+
large datasets fit on an ordinary laptop. The web app is FastAPI with plain HTML,
|
|
214
|
+
CSS and JavaScript; it never sends folder paths to the server, and the browser
|
|
215
|
+
writes the finished files into the folder you choose.
|
|
216
|
+
|
|
217
|
+
## Speed
|
|
218
|
+
|
|
219
|
+
On an Apple M4 Pro with one worker, the app generated and verified **1,000 mixed
|
|
220
|
+
Sorani, Kurmanji and English images in 9 seconds** (Balanced style), and saved all
|
|
221
|
+
files to a folder 5 seconds later. Speed depends on fonts, image size, effects and
|
|
222
|
+
hardware; measure yours with `synthocr benchmark --samples 1000`.
|
|
223
|
+
|
|
224
|
+
## Privacy
|
|
225
|
+
|
|
226
|
+
Everything runs on your computer. The app listens only on `127.0.0.1`, uploads
|
|
227
|
+
and fonts you add stay in its local workspace, and nothing is sent to any service.
|
|
228
|
+
|
|
229
|
+
## Development
|
|
230
|
+
|
|
231
|
+
```bash
|
|
232
|
+
uv sync --locked --extra web --group dev
|
|
233
|
+
uv run --group dev ruff check . && uv run --group dev ruff format --check .
|
|
234
|
+
uv run --extra web --group dev pytest
|
|
235
|
+
node --test tests/ui.test.cjs
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
See [CONTRIBUTING.md](https://github.com/ardalan-jalal/SynthOCR/blob/main/CONTRIBUTING.md) to get started and the
|
|
239
|
+
[development guide](https://github.com/ardalan-jalal/SynthOCR/blob/main/docs/development.md) for architecture, checks and CI.
|
|
240
|
+
|
|
241
|
+
## Documentation
|
|
242
|
+
|
|
243
|
+
- [App guide](https://github.com/ardalan-jalal/SynthOCR/blob/main/docs/ui.md): every option in the app
|
|
244
|
+
- [Kurdish guide](https://github.com/ardalan-jalal/SynthOCR/blob/main/docs/kurdish.md): Kurdish text, spelling cases and font checks
|
|
245
|
+
- [Augmentation](https://github.com/ardalan-jalal/SynthOCR/blob/main/docs/augmentation.md): backgrounds and effects in detail
|
|
246
|
+
- [Development](https://github.com/ardalan-jalal/SynthOCR/blob/main/docs/development.md): adding text and fonts, tests, architecture
|
|
247
|
+
- [Hosting](https://github.com/ardalan-jalal/SynthOCR/blob/main/docs/hosting.md): running it on a server
|
|
248
|
+
- [Data sources](https://github.com/ardalan-jalal/SynthOCR/blob/main/data/SOURCES.md) and [fonts](https://github.com/ardalan-jalal/SynthOCR/blob/main/fonts/README.md): provenance and licenses
|
|
249
|
+
|
|
250
|
+
## License and credits
|
|
251
|
+
|
|
252
|
+
Licensed under either of the [MIT License](https://github.com/ardalan-jalal/SynthOCR/blob/main/LICENSE-MIT) or the
|
|
253
|
+
[Apache License, Version 2.0](https://github.com/ardalan-jalal/SynthOCR/blob/main/LICENSE-APACHE), at your option. Copyright © 2026
|
|
254
|
+
**Ardalan Jalal**. Unless you state otherwise, any contribution you submit is
|
|
255
|
+
dual-licensed in the same way, without additional terms.
|
|
256
|
+
|
|
257
|
+
Bundled fonts (SIL Open Font License) and texts (Tatoeba, CC BY 2.0 France;
|
|
258
|
+
templates, CC0) keep their own licenses, and generated datasets inherit them. See
|
|
259
|
+
[NOTICE](https://github.com/ardalan-jalal/SynthOCR/blob/main/NOTICE) for details.
|
|
260
|
+
|
|
261
|
+
Maintained by [@ardalan-jalal](https://github.com/ardalan-jalal).
|