penmimic 0.1.0__tar.gz

penmimic-0.1.0/HOW_IT_WORKS.md

@@ -0,0 +1,87 @@
+# How penmimic works
+
+Written for a smart student who has not seen the code.
+
+## The big idea
+1. You write every character five times on a printed sheet.
+2. We photograph the sheet, find each box, and cut out the ink. That gives a "font" made of your real letters.
+3. To write a sentence, we pick a letter image for every character, set them in a row, add small random
+   wobbles, and paste them onto paper.
+
+No machine learning is used in version 0.1; it is image processing and layout.
+
+## Block vs cursive
+There are two printable templates with the **same grid** (same box positions, same markers), so one reader handles both:
+- **Block**: plain boxes with a dotted baseline.
+- **Cursive**: same boxes, plus a solid black **style bar** in the header, an x-height line, and a filled start dot
+  and hollow end dot on each a-z row.
+
+How the program tells them apart: `detect_template_style` checks whether the style bar is black. Pick the style you
+want with `Writer.from_samples(folder, style="cursive")`. Pages of the other style in the same folder are skipped.
+
+Cursive extras:
+1. `remove_cursive_join_guides` erases the printed dots so they are not read as ink.
+2. `trim_cursive_connector_tails` trims long thin lead-in/exit strokes near the baseline, keeping the letter body, loops and descenders.
+3. In `layout.py`, two lowercase letters in the same word get a smaller gap (they overlap slightly so strokes meet), and cursive uses less tilt jitter so words stay on the line.
+
+## Files (in `src/penmimic/`)
+
+### `template.py` - the sheet
+Draws the printable sheet and defines where every box is (page size, box size, rows per page).
+**Both** the sheet and the photo reader import these numbers, so they always agree.
+Each page has:
+- four solid black squares in the corners (so we can straighten the photo),
+- small header squares: one square = page 1, two = page 2 ... (so we know which page a photo is),
+- a row per character with five boxes, each with a pale dotted baseline to write on.
+
+### `glyphs.py` - from photo to letters
+1. **`find_marker_centers`** turns the photo black-and-white (Otsu's method picks the cut-off automatically),
+   finds blobs, and keeps the four biggest solid squares. A solid square fills its bounding box; a letter does not.
+2. **`rectify`** uses a *perspective transform*: we know where the four squares should be on a flat page and where
+   they are in the photo, so OpenCV computes the warp that flattens the photo into a perfect A4 page.
+3. **`normalise_lighting`** estimates how bright the blank paper is in each place (a morphological *close* erases
+   the thin pen strokes, then we blur) and divides the photo by it. Shadows disappear and paper becomes white everywhere.
+4. **`read_page_number`** counts the header squares.
+5. **`cut_glyph`** looks inside one box (ignoring a margin so the printed border is not included), keeps dark pixels,
+   throws away tiny specks, crops tightly, and saves an **alpha mask** (how much ink at each pixel, with soft edges).
+   It also records the **baseline**: how many pixels down from the top of the crop the dotted line was.
+   This is why a comma hangs below the line and an apostrophe floats above it.
+6. **`save_glyphs` / `load_glyphs`** write one transparent PNG per letter (`U0041_v2.png` = "A", variant 2) plus `glyphs.json`.
+
+### `layout.py` - where everything goes (no drawing here)
+- Picks a random variant for each character, avoiding the same variant twice in a row.
+- **Jitter** multiplies small random numbers: size +-8%, tilt +-3 degrees, height +-6% of a letter, gap +-40%.
+  `jitter=0` turns it all off.
+- Measures words; if a word would cross the right margin it moves to the next line. A word too long for a line is broken by letter.
+- Fallbacks: curly quotes become straight ones; a missing character tries the other case, then `?`, then leaves a gap.
+- Uses a seeded random generator so `seed=42` gives the same page every time.
+
+### `render.py` - drawing
+Draws paper (plain or ruled), then for each letter: scale and tilt its mask, line its baseline up with the line,
+and paste a block of the ink colour through the mask. Because the glyph is only a mask, any ink colour works.
+For the GIF, we paste letters one by one and save a snapshot every few letters.
+
+### `writer.py` - the public API
+`Writer.from_samples(folder)` runs the extraction. `Writer.write(text, ...)` does layout and returns a `Page`;
+`Page.save()` writes a PNG and `Page.animate()` writes a GIF.
+
+### `cli.py`
+The `penmimic` command.
+
+### `demo/`
+A tiny Flask site. The server loads your letters once, and `/render` returns a PNG. Text length, size and
+colour are validated so the server can't be overloaded or sent bad input.
+
+### `tests/`
+We cannot ship someone's real handwriting, so tests make fake handwriting from a computer font, "photograph" it
+with perspective, shadows and noise, and check that all 365 boxes are recovered, baselines are right, text wraps
+inside the margins, and the same seed gives the same page.
+
+## Design choices
+- One file defines the page geometry, so the printer and the reader cannot drift apart.
+- Markers + perspective warp, instead of asking for a perfectly scanned page.
+- Masks instead of coloured images, so ink colour is free and edges stay smooth.
+- Layout is separate from drawing, so layout can be tested without images.
+- Clear errors (`corner squares`, `which template page`) instead of silent bad output.
+
+

penmimic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ezzah Najmal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

penmimic-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE README.md HOW_IT_WORKS.md
+recursive-include examples *.py
+recursive-include tests *.py
+global-exclude __pycache__ *.py[cod]

penmimic-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: penmimic
+Version: 0.1.0
+Summary: Write any text in your own handwriting, from photos of a filled-in template sheet.
+Author: Ezzah Najmal
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Ezzah-2k9/penmimic
+Project-URL: Issues, https://github.com/Ezzah-2k9/penmimic/issues
+Keywords: handwriting,opencv,pillow,image,text-to-handwriting
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: opencv-python-headless>=4.8
+Requires-Dist: Pillow>=10.1
+Provides-Extra: demo
+Requires-Dist: flask>=3.0; extra == "demo"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: flask>=3.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# penmimic
+
+Write any text in **your own handwriting** from Python. Fill in a printable template, photograph it, and
+`penmimic` cuts out your letters and uses them to write whatever you like, as a PNG or an animated GIF.
+
+## The problem
+Typed text feels impersonal. Existing handwriting tools are closed, limited, or hard to use from code.
+
+## The solution
+A small library with a short API:
+
+```python
+from penmimic import Writer
+
+w = Writer.from_samples("my_samples/")
+w.write("Hello world").save("note.png")
+w.write("Hello world").animate("note.gif")
+```
+
+Each letter is picked at random from five of your own versions, then given a tiny random change in size,
+tilt, height and spacing, so the page does not look copy-pasted.
+
+## Install
+
+```bash
+pip install penmimic
+```
+Python 3.10+. For the optional web demo: `pip install "penmimic[demo]"`.
+
+## Use it
+
+**1. Print the template(s)** (5 A4 pages each). There are two: **block** letters and **cursive**.
+```bash
+penmimic --make-templates templates/                 # makes both PDFs
+penmimic --make-template block.pdf                   # just block
+penmimic --make-template cursive.pdf --style cursive # just cursive
+```
+In the cursive sheet, every a-z box has a dotted baseline, an x-height line, a filled dot (start) and a hollow
+dot (end). Write one natural letter with a short lead-in at the filled dot and a short flick at the hollow dot.
+You do not have to fill in both sheets: fill the style(s) you want. Photos of both can sit in the same folder.
+**2. Fill it in** with a dark pen. Write every character in every box, sitting on the dotted line.
+
+**3. Photograph each page.** Whole page in view, flat, good light, plain surface, held upright (portrait).
+Put the photos in a folder, e.g. `my_samples/`. File names do not matter: each page is recognised from the
+small squares in its header.
+
+**4. Write.**
+```python
+from penmimic import Writer
+w = Writer.from_samples("my_samples/", style="cursive")   # or "block" (default); letters saved in my_samples/glyphs_cursive/
+w.write("Dear diary,\nToday was good.", size=1.2, ink="navy", paper="lined",
+        line_spacing=1.8, jitter=0.8, seed=42).save("diary.png")
+```
+
+Command line:
+```bash
+penmimic "Hello world" --samples my_samples --style cursive -o note.png
+penmimic "Hello world" --samples my_samples -o note.gif --paper lined --ink navy
+```
+
+### Options for `write()`
+| Option | Default | Meaning |
+|---|---|---|
+| `letter_spacing` | 1.0 | 0-3. Gap between letters (in cursive, above 1 opens the joins) |
+| `word_spacing` | 1.0 | 0-3. Gap between words |
+| `size` | 1.0 | Text size (1.0 = as written on the template) |
+| `ink` | `#1b1b3a` | Ink colour: name or hex |
+| `line_spacing` | 1.6 | Gap between lines, as a multiple of a typical letter height |
+| `jitter` | 1.0 | 0 = identical letters, 1 = natural, 2 = messy (max) |
+| `paper` | `plain` | `plain` or `lined` |
+| `width` / `margin` | 1600 / 80 | Page size in pixels |
+| `seed` | None | Same seed = same result every time |
+
+## Demo website
+```bash
+pip install -e ".[demo]"
+export PENMIMIC_SAMPLES=my_samples     # Windows PowerShell: $env:PENMIMIC_SAMPLES="my_samples"
+python demo/app.py                     # open http://127.0.0.1:5000
+```
+
+## Results
+- 44 automated tests pass (`pytest`). They use *synthetic* "handwriting" made from a computer font, photographed
+  with simulated perspective, shadow and noise. They prove the pipeline works, not that it looks good on every
+  real hand.
+- TODO: after trying it with your own handwriting, record here what you saw (e.g. which characters needed
+  re-writing, how long extraction takes on your machine). Report only what you measured.
+
+## Limitations
+- Needs a clean template: a pen that is too light, boxes crossed by ink, or a dark/uneven background can break extraction.
+- Cursive mode overlaps and tightens letters inside a word so they touch, but it still pastes separate letter images; it does not draw one continuous pen stroke.
+- Only the characters on the template (A-Z, a-z, 0-9, `.,!?'"-:;()`). Others fall back to the other case,
+  then `?`, then a blank gap.
+- Photos must show the whole page, roughly upright. Very strong shadows or extreme angles fail with a clear error.
+- It copies your letters; it does not learn how you write. A neural stroke model is planned for version 0.2.
+- Left-to-right scripts only.
+
+## Credits
+- Built by Ezzah Najmal.
+- Code drafted with help from Claude (Anthropic), then reviewed and tested by the author.
+- Libraries: OpenCV, Pillow, NumPy, Flask, pytest.
+
+## Licence
+MIT. See [LICENSE](LICENSE). Handwriting samples are personal data: only use your own or ones you have permission to use.

penmimic-0.1.0/README.md

@@ -0,0 +1,103 @@
+# penmimic
+
+Write any text in **your own handwriting** from Python. Fill in a printable template, photograph it, and
+`penmimic` cuts out your letters and uses them to write whatever you like, as a PNG or an animated GIF.
+
+## The problem
+Typed text feels impersonal. Existing handwriting tools are closed, limited, or hard to use from code.
+
+## The solution
+A small library with a short API:
+
+```python
+from penmimic import Writer
+
+w = Writer.from_samples("my_samples/")
+w.write("Hello world").save("note.png")
+w.write("Hello world").animate("note.gif")
+```
+
+Each letter is picked at random from five of your own versions, then given a tiny random change in size,
+tilt, height and spacing, so the page does not look copy-pasted.
+
+## Install
+
+```bash
+pip install penmimic
+```
+Python 3.10+. For the optional web demo: `pip install "penmimic[demo]"`.
+
+## Use it
+
+**1. Print the template(s)** (5 A4 pages each). There are two: **block** letters and **cursive**.
+```bash
+penmimic --make-templates templates/                 # makes both PDFs
+penmimic --make-template block.pdf                   # just block
+penmimic --make-template cursive.pdf --style cursive # just cursive
+```
+In the cursive sheet, every a-z box has a dotted baseline, an x-height line, a filled dot (start) and a hollow
+dot (end). Write one natural letter with a short lead-in at the filled dot and a short flick at the hollow dot.
+You do not have to fill in both sheets: fill the style(s) you want. Photos of both can sit in the same folder.
+**2. Fill it in** with a dark pen. Write every character in every box, sitting on the dotted line.
+
+**3. Photograph each page.** Whole page in view, flat, good light, plain surface, held upright (portrait).
+Put the photos in a folder, e.g. `my_samples/`. File names do not matter: each page is recognised from the
+small squares in its header.
+
+**4. Write.**
+```python
+from penmimic import Writer
+w = Writer.from_samples("my_samples/", style="cursive")   # or "block" (default); letters saved in my_samples/glyphs_cursive/
+w.write("Dear diary,\nToday was good.", size=1.2, ink="navy", paper="lined",
+        line_spacing=1.8, jitter=0.8, seed=42).save("diary.png")
+```
+
+Command line:
+```bash
+penmimic "Hello world" --samples my_samples --style cursive -o note.png
+penmimic "Hello world" --samples my_samples -o note.gif --paper lined --ink navy
+```
+
+### Options for `write()`
+| Option | Default | Meaning |
+|---|---|---|
+| `letter_spacing` | 1.0 | 0-3. Gap between letters (in cursive, above 1 opens the joins) |
+| `word_spacing` | 1.0 | 0-3. Gap between words |
+| `size` | 1.0 | Text size (1.0 = as written on the template) |
+| `ink` | `#1b1b3a` | Ink colour: name or hex |
+| `line_spacing` | 1.6 | Gap between lines, as a multiple of a typical letter height |
+| `jitter` | 1.0 | 0 = identical letters, 1 = natural, 2 = messy (max) |
+| `paper` | `plain` | `plain` or `lined` |
+| `width` / `margin` | 1600 / 80 | Page size in pixels |
+| `seed` | None | Same seed = same result every time |
+
+## Demo website
+```bash
+pip install -e ".[demo]"
+export PENMIMIC_SAMPLES=my_samples     # Windows PowerShell: $env:PENMIMIC_SAMPLES="my_samples"
+python demo/app.py                     # open http://127.0.0.1:5000
+```
+
+## Results
+- 44 automated tests pass (`pytest`). They use *synthetic* "handwriting" made from a computer font, photographed
+  with simulated perspective, shadow and noise. They prove the pipeline works, not that it looks good on every
+  real hand.
+- TODO: after trying it with your own handwriting, record here what you saw (e.g. which characters needed
+  re-writing, how long extraction takes on your machine). Report only what you measured.
+
+## Limitations
+- Needs a clean template: a pen that is too light, boxes crossed by ink, or a dark/uneven background can break extraction.
+- Cursive mode overlaps and tightens letters inside a word so they touch, but it still pastes separate letter images; it does not draw one continuous pen stroke.
+- Only the characters on the template (A-Z, a-z, 0-9, `.,!?'"-:;()`). Others fall back to the other case,
+  then `?`, then a blank gap.
+- Photos must show the whole page, roughly upright. Very strong shadows or extreme angles fail with a clear error.
+- It copies your letters; it does not learn how you write. A neural stroke model is planned for version 0.2.
+- Left-to-right scripts only.
+
+## Credits
+- Built by Ezzah Najmal.
+- Code drafted with help from Claude (Anthropic), then reviewed and tested by the author.
+- Libraries: OpenCV, Pillow, NumPy, Flask, pytest.
+
+## Licence
+MIT. See [LICENSE](LICENSE). Handwriting samples are personal data: only use your own or ones you have permission to use.

penmimic-0.1.0/examples/quickstart.py

@@ -0,0 +1,14 @@
+import argparse
+from penmimic import Writer
+
+parser = argparse.ArgumentParser(description="Render text from your handwriting samples.")
+parser.add_argument("--samples", default="my_samples", help="folder containing filled template page images")
+parser.add_argument("--style", choices=["block", "cursive"], default="block")
+parser.add_argument("--output", default="handwriting.png")
+args = parser.parse_args()
+
+writer = Writer.from_samples(args.samples, style=args.style)
+writer.write("Hello World.\nThis is PenMimic.", size=0.9, jitter=0.25, seed=42).save(args.output)
+print(f"Saved {args.output}")
+
+

penmimic-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "penmimic"
+version = "0.1.0"
+description = "Write any text in your own handwriting, from photos of a filled-in template sheet."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ezzah Najmal" }]
+keywords = ["handwriting", "opencv", "pillow", "image", "text-to-handwriting"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Multimedia :: Graphics",
+]
+dependencies = [
+    "numpy>=1.24",
+    "opencv-python-headless>=4.8",
+    "Pillow>=10.1",
+]
+
+[project.optional-dependencies]
+demo = ["flask>=3.0"]
+dev = ["pytest>=8.0", "flask>=3.0", "build", "twine"]
+
+[project.scripts]
+penmimic = "penmimic.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Ezzah-2k9/penmimic"
+Issues = "https://github.com/Ezzah-2k9/penmimic/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+penmimic = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+

penmimic-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

penmimic-0.1.0/src/penmimic/__init__.py

@@ -0,0 +1,9 @@
+"""penmimic - write any text in your own handwriting."""
+
+from .template import make_both_templates, make_template
+from .writer import Page, Writer
+
+__version__ = "0.1.0"
+__all__ = ["Writer", "Page", "make_template", "make_both_templates", "__version__"]
+
+

penmimic-0.1.0/src/penmimic/cli.py

@@ -0,0 +1,54 @@
+"""Command line:  penmimic "Hello world" --samples my_samples -o note.png"""
+
+import argparse
+import sys
+
+from .template import make_both_templates, make_template
+from .writer import Writer
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="penmimic", description="Write text in your own handwriting.")
+    p.add_argument("text", nargs="?", help="the text to write")
+    p.add_argument("--samples", help="folder with photos of your filled-in template (or extracted glyphs)")
+    p.add_argument("--style", choices=["block", "cursive"], default="block", help="handwriting template style")
+    p.add_argument("-o", "--output", default="out.png", help="output file (.png, or .gif to animate)")
+    p.add_argument("--make-template", metavar="PDF",
+                   help="create ONE printable template (use --style block|cursive) and exit")
+    p.add_argument("--make-templates", metavar="DIR",
+                   help="create BOTH templates (block + cursive PDFs) in DIR and exit")
+    p.add_argument("--size", type=float, default=1.0)
+    p.add_argument("--ink", default="#1b1b3a")
+    p.add_argument("--line-spacing", type=float, default=1.6)
+    p.add_argument("--jitter", type=float, default=1.0)
+    p.add_argument("--letter-spacing", type=float, default=1.0, help="0-3, 1 = natural")
+    p.add_argument("--word-spacing", type=float, default=1.0, help="0-3, 1 = natural")
+    p.add_argument("--paper", choices=["plain", "lined"], default="plain")
+    p.add_argument("--width", type=int, default=1600)
+    p.add_argument("--seed", type=int, default=None)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.make_templates:
+        for path in make_both_templates(args.make_templates):
+            print(f"Template written to {path}")
+        return 0
+    if args.make_template:
+        print(f"Template written to {make_template(args.make_template, args.style)}")
+        return 0
+    if not args.text or not args.samples:
+        print("error: give the text and --samples (or use --make-template)", file=sys.stderr)
+        return 2
+    writer = Writer.from_samples(args.samples, style=args.style)
+    page = writer.write(args.text, size=args.size, ink=args.ink, line_spacing=args.line_spacing,
+                        jitter=args.jitter, paper=args.paper,
+                        letter_spacing=args.letter_spacing, word_spacing=args.word_spacing, width=args.width, seed=args.seed)
+    out = page.animate(args.output) if args.output.lower().endswith(".gif") else page.save(args.output)
+    print(f"Saved {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())