# Contributing

## Installation

Install [pixi](https://pixi.sh/latest/) for pulling conda/pip packages:

```bash
curl -fsSL https://pixi.sh/install.sh | sh
```

Create pixi environment and enter activated shell:

```bash
pixi s
```

Create a virtualenv and install nemotron-ocr into it via `uv`:

```bash
uv venv \
&& uv pip install -e ./nemotron-ocr -v
```

Assert that OCR inference libraries can now be imported successfully:

```bash
uv run python -c "import nemotron_ocr; import nemotron_ocr_cpp"
```

## Usage

`NemotronOCRV2` is the recommended entry point for OCR inference:

```python
from nemotron_ocr.inference.pipeline_v2 import NemotronOCRV2

ocr = NemotronOCRV2()
predictions = ocr("ocr-example-input-1.png")

for pred in predictions:
    print(f"  - Text: '{pred['text']}', Confidence: {pred['confidence']:.2f}")
```

The level of detection merging can be adjusted with `merge_level`:

```python
ocr(image_path, merge_level="word")       # individual words
ocr(image_path, merge_level="sentence")   # merged into sentences
ocr(image_path, merge_level="paragraph")  # merged into paragraphs (default)
```

### Inference modes

```python
# Detector only — bounding boxes, no text (fastest, lowest memory)
ocr_det = NemotronOCRV2(detector_only=True)

# Skip relational — per-word text, no reading-order grouping
ocr_fast = NemotronOCRV2(skip_relational=True)

# Profiling — per-phase CUDA-synced timing in logs
ocr_profile = NemotronOCRV2(verbose_post=True)
```

### Example script

```bash
uv run python example.py ocr-example-input-1.png
uv run python example.py ocr-example-input-1.png --merge-level word
uv run python example.py ocr-example-input-1.png --detector-only
uv run python example.py ocr-example-input-1.png --skip-relational
```