Metadata-Version: 2.4
Name: anki-niobium
Version: 0.2.5
Summary: NIOBIUM: Nadia's Image Occlusion Booster Is UnManned - A CLI tool for extracting text and image-occlusion-style notes from images and PDFs for Anki
Project-URL: Homepage, https://github.com/agahkarakuzu/niobium
Project-URL: Repository, https://github.com/agahkarakuzu/niobium
Project-URL: Issues, https://github.com/agahkarakuzu/niobium/issues
Author-email: Agah Karakuzu <agahkarakuzu@gmail.com>
License: GPL-3.0
License-File: LICENSE
Keywords: anki,education,flashcards,image-occlusion,ocr,pdf
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.8
Requires-Dist: click
Requires-Dist: easyocr
Requires-Dist: numpy<2.0
Requires-Dist: pillow
Requires-Dist: pymupdf
Requires-Dist: requests
Requires-Dist: tqdm
Description-Content-Type: text/markdown

![PyPI - Version](https://img.shields.io/pypi/v/anki-niobium?style=flat&logo=python&logoColor=white&logoSize=8&labelColor=rgb(255%2C0%2C0)&color=white)

## NIOBIUM: Nadia's Image Occlusion Booster Is UnManned

NIOBIUM is a small CLI tool for extracting text and image-occlusion-style notes from images and PDFs, and for preparing Anki-compatible outputs (via AnkiConnect or by creating an .apkg). This README shows common usages and examples for the command-line interface.

### Trivia: What the actual heck is niobium?

Niobium is a stealthy gray metal that is absurdly strong, feather‑light and allergic to corrosion. Mostly mined in Brazil and Canada, it moonlights in super‑alloys for jet engines and superconducting MRI magnets. It even hides in the capacitors inside your phone and laptop.

So next time you're on a flight, fiddling with your phone on the way to an MRI conference, tip your hat to niobium, OR just give this repo a ⭐️.


## Installation

### Using pip

```bash
pip install anki-niobium
```

### Using uv (faster alternative)

```bash
uv pip install anki-niobium
```

### From source

```bash
git clone https://github.com/agahkarakuzu/niobium.git
cd niobium
pip install -e .
```

## Requirements

- Python 3.8 or higher
- All dependencies are automatically installed with the package

## Quick overview

The main entry point is the `niobium` command. It exposes a few mutually-exclusive input modes and a few mutually-exclusive output modes.

Inputs (one required):
- `-i, --image` — absolute path to a single image file
- `-dir, --directory` — directory containing multiple images
- `-pin, --single-pdf` — absolute path to a single PDF

Outputs (one required):
- `-deck, --deck-name` — name of the Anki deck where notes will be pushed (requires AnkiConnect)
- `-pout, --pdf-img-out` — output directory where images extracted from a PDF will be saved
- `-apkg, --apkg-out` — output directory where a generated `.apkg` will be saved

Other useful flags:
- `-ioid, --io-model-id` — ID of the built-in Image Occlusion model in Anki (optional, used with `--apkg-out`)
- `-m, --merge-rects` — whether to merge nearby detected rectangles (default: True)
- `-mx, --merge-lim-x` — horizontal merging threshold in pixels (default: 10)
- `-my, --merge-lim-y` — vertical merging threshold in pixels (default: 10)
- `-l, --langs` — comma-separated OCR languages (default: `en`)
- `-g, --gpu` — GPU index to use, or `-1` for CPU only (default: -1)
- `-hdr, --add-header` — add filename as a header (default: False)
- `-basic, --basic-type` — create basic Anki cards instead of image-occlusion notes (default: False)

Run `niobium -h` to see the help text with the current arguments.

## Examples

Below are some concrete example commands (assumes you're in the project root and using zsh/bash):

1) ⭐️ Run OCR and push image-occlusion notes to an Anki deck (via AnkiConnect)

This processes all images under a directory and pushes notes to the Anki deck named `MyStudyDeck`.

```bash
niobium --directory /absolute/path/to/images --deck-name MyStudyDeck
```

Notes:
- You may specify a deck name that doesn't yet exist; you'll be prompted to create it.
- Anki must be running with the AnkiConnect add-on enabled.
- The tool will detect text and create image-occlusion notes from detected regions.

2) Extract images from a single PDF

This extracts embedded images from `lecture.pdf` into `./out_images`.

```bash
niobium --single-pdf /absolute/path/to/lecture.pdf --pdf-img-out /absolute/path/to/out_images
```

Important: `--single-pdf` is required when using `--pdf-img-out`.


3) Produce an `.apkg` file (offline export, **NOT TESTED**)

This processes a directory and writes an `.apkg` bundle suitable for import into Anki without requiring AnkiConnect at runtime.

```bash
niobium --directory /absolute/path/to/images --apkg-out /absolute/path/to/output_dir
```

Optional: include the Image Occlusion model id if you want the built-in model referenced in the package:

```bash
niobium --directory /absolute/path/to/images --apkg-out /absolute/path/to/output_dir --io-model-id 12345
```

4) Create basic (front/back) Anki cards instead of image-occlusion notes

```bash
niobium --directory /absolute/path/to/images --deck-name MyStudyDeck --basic-type True
```

This comes in handy when you have a bunch of images in a folder (may be extracted from a PDF, see (2) above), and would like to create Q&A for each one of them. 

5) Tweak rectangle merging and OCR languages

If bounding boxes are too fragmented, increase the merge thresholds. To OCR multiple languages, provide a comma-separated list.

```bash
niobium --directory /absolute/path/to/images --deck-name MyStudyDeck --merge-lim-x 20 --merge-lim-y 20 --langs en,fr
```

Note: Rectangle merging and other heuristics are experimental. Nearby occlusion boxes may be merged unintentionally, or distinct boxes may remain separate. Adjust --merge-lim-x/--merge-lim-y or disable merging with --merge-rects to change the behavior.

If you come up with a more robust approach to this, feel free to send a PR!

6) GPU usage

Pass `--gpu 0` to attempt to use GPU 0. The default `-1` runs on CPU.

```bash
niobium --directory /abs/path/to/images --deck-name MyStudyDeck --gpu 0
```

## Common workflows

- Automatic creation of image-occlusion notes and push to Anki:
  - `--directory` + `--deck-name`  (Anki must be running with anki-connect installed)
  - `--single-pdf` + `--deck-name` (Anki must be running with anki-connect installed)
- Quick extraction from a PDF for manual review:
  - `--single-pdf` + `--pdf-img-out`

## Troubleshooting

- If AnkiConnect calls fail, confirm Anki is running and AnkiConnect is installed and enabled.
- If OCR quality is poor, try adding the proper language code with `--langs` (e.g., `en,es`) and ensure Tesseract language packs are installed.
- If many small boxes are produced, increase `--merge-lim-x`/`--merge-lim-y` or set `--merge-rects False` to disable merging.

## Development

### Setting up for development

```bash
git clone https://github.com/agahkarakuzu/niobium.git
cd niobium
pip install -e .
```

### Running tests

The package includes automated tests that run on each push via GitHub Actions. You can test locally:

```bash
# Test the CLI is available
niobium -h

# Test import
python -c "from niobium.cli import main; print('Import successful')"
```

### Project structure

- `niobium/cli.py` - Main CLI entry point with argument parsing
- `niobium/io.py` - Core I/O helpers and OCR functionality
- `pyproject.toml` - Package configuration and dependencies

## Contributing

If you'd like to contribute, open an issue or submit a pull request.