### FastAPI OCR API for Text Extraction

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

Example of a FastAPI application integrating OCR and OpenAI for text extraction from uploaded files. It handles file validation, preprocessing, raw text extraction, and AI-formatted output. Requires OpenAI API key and Tesseract OCR.

```python
from fastapi import FastAPI, File, UploadFile, HTTPException
from app.services.preprocessing import preprocess_image
from app.models.text_extraction import extract_text
from utils.file_utils import save_uploaded_file
from openai import OpenAI
import os

app = FastAPI(title="OCR API")
client = OpenAI()

@app.post("/extract-text")
async def extract_text_from_file(file: UploadFile = File(...)):
    # Validate file format
    if not file.filename.endswith(('.png', '.jpg', '.jpeg', '.pdf')):
        raise HTTPException(status_code=400, detail="Invalid file format")

    # Save uploaded file
    filepath = save_uploaded_file(file)

    # Preprocess the image
    preprocessed_path = preprocess_image(filepath)

    # Extract text using OCR
    raw_text = extract_text(preprocessed_path)

    # Format with OpenAI
    completion = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {
                "role": "system",
                "content": "You are an advanced text extraction assistant. Extract only key-value pairs from the given text."
            },
            {
                "role": "user",
                "content": f"Extract key-value pairs from:\n\n{raw_text}"
            }
        ]
    )

    formatted_text = completion.choices[0].message.content

    return {
        "raw_text": raw_text,
        "formatted_data": {"text": formatted_text}
    }

# Run the application
# uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

--------------------------------

### Text Extraction from Documents

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

Details the text extraction process using pytesseract for images and PyMuPDF for PDFs.

```APIDOC
## Text Extraction from Documents

### Description
This function handles the core text extraction from both image files and multi-page PDF documents. It intelligently selects the appropriate library (pytesseract for images, PyMuPDF for PDFs) based on the file type.

### Functionality
- **Image Text Extraction**: Utilizes `pytesseract` with the English language model to extract text from image files, especially after preprocessing.
- **PDF Text Extraction**: Employs `PyMuPDF` to efficiently extract text content from all pages of a PDF document.

### Code Example
```python
from app.models.text_extraction import extract_text

# Extract text from a preprocessed image
image_text = extract_text("uploads/preprocessed_image.jpg")
print(f"Extracted text: {image_text}")
# Expected output: "STUDENT ID\nName: John Smith\nClass: 10-A\nRoll No: 12345"

# Extract text from a multi-page PDF
pdf_text = extract_text("uploads/report.pdf")
print(f"PDF content: {pdf_text}")
# Expected output: "Page 1 content...\nPage 2 content...\nPage 3 content..."
```
```

--------------------------------

### Image Preprocessing Pipeline

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

Details the image preprocessing steps applied to enhance OCR accuracy, including deskewing, denoising, and thresholding.

```APIDOC
## Image Preprocessing Pipeline

### Description
This section outlines the core image preprocessing techniques used to prepare images for accurate text extraction. These steps are crucial for handling challenging document qualities such as skew, noise, and low contrast.

### Operations
1. **Deskew**: Corrects skewed or rotated images using Hough Line Transformation to align text horizontally.
2. **Grayscale Conversion**: Converts the image to grayscale.
3. **Denoising**: Applies median blur (3x3) and Gaussian blur (5x5) to reduce image noise.
4. **Adaptive Thresholding**: Uses adaptive thresholding (Gaussian method with block size 11) to binarize the image, adapting to varying lighting conditions.
5. **Morphological Operations**: Applies dilation followed by erosion to refine image shapes and remove small artifacts.
6. **Otsu Thresholding**: Performs Otsu's thresholding as a final adjustment for optimal contrast.

### Code Example
```python
from app.services.preprocessing import preprocess_image

try:
    input_path = "uploads/scanned_document.jpg"
    preprocessed_path = preprocess_image(input_path)
    print(f"Preprocessed image saved to: {preprocessed_path}")
    # Expected output: "uploads/scanned_document_preprocessed.jpg"
except ValueError as e:
    print(f"Error: {e}")
    # Expected output: "Invalid image file or file does not exist."
```
```

--------------------------------

### Image Preprocessing Pipeline - Python

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

Enhances image quality for OCR using a series of computer vision techniques including deskewing, denoising, and thresholding. Handles potential errors during image processing.

```python
from app.services.preprocessing import preprocess_image

# Preprocess an image for optimal OCR results
try:
    input_path = "uploads/scanned_document.jpg"
    preprocessed_path = preprocess_image(input_path)

    # The function performs the following operations:
    # 1. Deskew using Hough Line Transformation
    # 2. Convert to grayscale
    # 3. Apply median blur (3x3) and Gaussian blur (5x5)
    # 4. Adaptive thresholding (Gaussian, block size 11)
    # 5. Morphological operations (dilation + erosion)
    # 6. Otsu thresholding for final adjustment

    print(f"Preprocessed image saved to: {preprocessed_path}")
    # Output: "uploads/scanned_document_preprocessed.jpg"

except ValueError as e:
    print(f"Error: {e}")
    # Output: "Invalid image file or file does not exist."
```

--------------------------------

### Image Preprocessing for OCR Accuracy

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

Internal methods for image preprocessing to enhance OCR accuracy. Includes grayscale conversion, contrast enhancement, binary conversion, edge detection, and document alignment.

```python
from PIL import Image
from app.services.ocr_service import OCRService

ocr_service = OCRService()

# Preprocess an image for better OCR results
async def preprocess_example():
    image = Image.open("uploads/noisy_document.jpg")

    # Apply grayscale conversion and contrast enhancement
    processed = await ocr_service.preprocess_image(image)

    # The function:
    # - Converts to grayscale
    # - Applies contrast enhancement (threshold at 128)
    # - Converts to binary (1-bit pixels)

    processed.save("uploads/preprocessed_output.jpg")
    print("Image preprocessed successfully")

# Edge detection and document alignment
async def align_document():
    image = Image.open("uploads/skewed_card.jpg")

    # Detect edges and align the document
    aligned = await OCRService.detect_edges_and_align(image)

    # The function:
    # - Converts to grayscale
    # - Applies Canny edge detection
    # - Finds contours and identifies rectangular shapes
    # - Performs perspective transformation
    # - Returns aligned document image

    aligned.save("uploads/aligned_card.jpg")
```

--------------------------------

### Format OCR Text with OpenAI GPT-4

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

Transforms raw OCR text into structured key-value pairs using the OpenAI GPT-4 model. It takes raw text as input and returns formatted text, handling potential API errors.

```python
from app.services.openai_formatter import format_text_with_openai

raw_text = """
IDENTITY CARD
Nationality: United Arab Emirates
ID Number: 784-1990-1234567-8
Name: Ahmed Hassan
Date of Birth: 20/03/1990
Occupation: Software Engineer
"""

try:
    formatted_result = format_text_with_openai(raw_text)
    print(formatted_result)
    # Output:
    # nationality: United Arab Emirates
    # id_number: 784-1990-1234567-8
    # name: Ahmed Hassan
    # date_of_birth: 20/03/1990
    # occupation: Software Engineer

except ValueError as e:
    print(f"API Error: {e}")
    # Output: "OpenAI API Error: Invalid API key provided"
```

--------------------------------

### Deskew Image Correction

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

Details the automatic image deskewing process using Hough Line Transformation to correct skewed documents.

```APIDOC
## Deskew Image Correction

### Description
This function automatically corrects the orientation of skewed or rotated images by detecting the dominant text alignment using the Hough Line Transform. This ensures that extracted text is read in the correct horizontal orientation.

### Method
Internal function call within preprocessing pipeline.

### Process
1. **Edge Detection**: Applies Canny edge detection to identify significant edges in the image.
2. **Line Detection**: Uses the Hough Line Transform to detect lines within the edge map.
3. **Angle Calculation**: Computes the median angle of the detected lines to determine the skew angle.
4. **Image Rotation**: Rotates the image by the calculated skew angle to correct its orientation.
5. **Angle Filtering**: Filters out extreme angles outside the range of -45° to 45° to prevent incorrect rotations.

### Code Example
```python
import cv2
from app.services.preprocessing import deskew_image

image = cv2.imread("uploads/rotated_document.jpg")

if image is not None:
    deskewed = deskew_image(image)
    cv2.imwrite("uploads/corrected_document.jpg", deskewed)
    print("Image successfully deskewed")
else:
    print("Failed to load image")
```
```

--------------------------------

### File Upload Handler Utility

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

A utility function to save uploaded files to the server's designated upload directory. It automatically creates the directory if it doesn't exist and returns the full path of the saved file.

```python
from fastapi import UploadFile
from utils.file_utils import save_uploaded_file
import io

# Save an uploaded file
def handle_upload():
    # Simulate file upload
    file_content = b"fake image content"
    upload_file = UploadFile(
        filename="document.jpg",
        file=io.BytesIO(file_content)
    )

    # Save to uploads directory
    saved_path = save_uploaded_file(upload_file)
    print(f"File saved to: {saved_path}")
    # Output: "uploads/document.jpg"

    # The function automatically:
    # - Creates 'uploads' directory if it doesn't exist
    # - Saves file with original filename
    # - Returns the full file path
```

--------------------------------

### Text Extraction from Documents - Python

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

Extracts text from both image files and multi-page PDF documents. Uses pytesseract for images and PyMuPDF for PDFs, automatically handling file type detection.

```python
from app.models.text_extraction import extract_text

# Extract text from a preprocessed image
image_text = extract_text("uploads/preprocessed_image.jpg")
print(f"Extracted text: {image_text}")
# Output: "STUDENT ID\nName: John Smith\nClass: 10-A\nRoll No: 12345"

# Extract text from a multi-page PDF
pdf_text = extract_text("uploads/report.pdf")
print(f"PDF content: {pdf_text}")
# Output: "Page 1 content...\nPage 2 content...\nPage 3 content..."

# The function automatically detects file type and:
# - For PDFs: Extracts text from all pages using PyMuPDF
# - For images: Uses pytesseract with English language model
```

--------------------------------

### OCR Service for Document Processing

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

A complete document processing service that supports preprocessing and multi-language OCR. It can process uploaded image files and PDF documents, extracting text and returning the results.

```python
from fastapi import UploadFile
from app.services.ocr_service import OCRService
import io

# Initialize the OCR service
ocr_service = OCRService()

# Process an uploaded file
async def process_document_example():
    # Simulate an uploaded file
    with open("uploads/student_id.jpg", "rb") as f:
        file_content = f.read()

    upload_file = UploadFile(
        filename="student_id.jpg",
        file=io.BytesIO(file_content)
    )

    # Extract text with automatic preprocessing
    extracted_text = await ocr_service.process_document(upload_file)

    print(f"Extracted: {extracted_text}")
    # Output: "SCHOOL NAME\nStudent Name: Sarah Ahmed\nClass: 8-B\n..."

# Process a PDF document
async def process_pdf_example():
    with open("uploads/invoice.pdf", "rb") as f:
        pdf_content = f.read()

    pdf_file = UploadFile(
        filename="invoice.pdf",
        file=io.BytesIO(pdf_content)
    )

    # PDF pages are converted to images and processed individually
    result = await ocr_service.process_document(pdf_file)
    print(result)
```

--------------------------------

### POST /extract-text

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

Extracts text from an uploaded image file using OCR and formats it with OpenAI.

```APIDOC
## POST /extract-text

### Description
This endpoint accepts an image file (PNG, JPG, JPEG, PDF) and performs OCR to extract raw text. It then uses OpenAI's GPT-4o model to format the extracted text into key-value pairs.

### Method
POST

### Endpoint
/extract-text

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **file** (UploadFile) - Required - The image file to process.

### Request Example
```
(Binary upload of an image file)
```

### Response
#### Success Response (200)
- **raw_text** (str) - The raw text extracted from the image.
- **formatted_data** (dict) - A dictionary containing the AI-formatted text, typically as key-value pairs.

#### Response Example
```json
{
  "raw_text": "Name: John Doe\nID: 12345",
  "formatted_data": {
    "text": "name: John Doe\nid: 12345"
  }
}
```

#### Error Response (400)
- **detail** (str) - Error message indicating an invalid file format.

#### Error Response Example
```json
{
  "detail": "Invalid file format"
}
```
```

--------------------------------

### Extract Text from Document using cURL

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

API endpoint for extracting text from uploaded image or PDF files. It accepts multipart/form-data and returns raw text and AI-formatted data. Handles invalid file formats with a 400 Bad Request response.

```bash
# Upload an image file for text extraction
curl -X POST "http://localhost:8000/extract-text" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/identity_card.jpg"

# Example response
{
  "raw_text": "NATIONALITY\nSyrian Arab Republic\nID NUMBER\n784-1985-3965869-4\nNAME\nMtanious Naief Al Saiegh\nDATE OF BIRTH\n15/06/1985\nOCCUPATION\nAdministrative Director",
  "formatted_data": {
    "text": "nationality: Syrian Arab Republic\nid_number: 784-1985-3965869-4\nname: Mtanious Naief Al Saiegh\ndate_of_birth: 15/06/1985\noccupation: Administrative Director"
  }
}

# Upload a PDF document
curl -X POST "http://localhost:8000/extract-text" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/scanned_document.pdf"

# Error handling example - invalid file format
curl -X POST "http://localhost:8000/extract-text" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/document.txt"

# Response (400 Bad Request)
{
  "detail": "Invalid file format"
}
```

--------------------------------

### Pydantic Models for OCR API Data Validation

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

Defines Pydantic models for request and response validation in the OCR API. Includes models for API responses, document structures, and OCR service results, ensuring data integrity.

```python
from pydantic import BaseModel
from typing import Optional

# Response model for OCR endpoint
class OCRResponse(BaseModel):
    raw_text: str
    formatted_data: dict

# Example usage
response_data = OCRResponse(
    raw_text="Name: John Doe\nID: 12345",
    formatted_data={
        "text": "name: John Doe\nid: 12345"
    }
)

print(response_data.model_dump())
# Output: {'raw_text': 'Name: John Doe\nID: 12345', 'formatted_data': {'text': 'name: John Doe\nid: 12345'}}

# Document model
class Document(BaseModel):
    content: str
    document_type: str
    language: Optional[str] = None

doc = Document(
    content="Extracted text content",
    document_type="identity_card",
    language="eng"
)

# OCR service response model
class OCRServiceResponse(BaseModel):
    success: bool
    text: str
    document_type: str
    error_message: Optional[str] = None

result = OCRServiceResponse(
    success=True,
    text="Extracted document text",
    document_type="passport",
    error_message=None
)
```

--------------------------------

### POST /extract-text

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

Extract text from uploaded images or PDFs with automatic preprocessing and AI-powered formatting. Supports various image and PDF formats.

```APIDOC
## POST /extract-text

### Description
This endpoint extracts text from an uploaded file (image or PDF). It applies automatic preprocessing to enhance OCR accuracy and uses AI to format the extracted text into structured key-value pairs.

### Method
POST

### Endpoint
/extract-text

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **file** (file) - Required - The image or PDF file to process.

### Request Example
```bash
curl -X POST "http://localhost:8000/extract-text" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/identity_card.jpg"
```

### Response
#### Success Response (200 OK)
- **raw_text** (string) - The raw text extracted directly from the document.
- **formatted_data** (object) - An object containing AI-processed and structured text.
  - **text** (string) - Formatted key-value pairs extracted from the document.

#### Response Example
```json
{
  "raw_text": "NATIONALITY\nSyrian Arab Republic\nID NUMBER\n784-1985-3965869-4\nNAME\nMtanious Naief Al Saiegh\nDATE OF BIRTH\n15/06/1985\nOCCUPATION\nAdministrative Director",
  "formatted_data": {
    "text": "nationality: Syrian Arab Republic\nid_number: 784-1985-3965869-4\nname: Mtanious Naief Al Saiegh\ndate_of_birth: 15/06/1985\noccupation: Administrative Director"
  }
}
```

#### Error Response (400 Bad Request)
- **detail** (string) - Description of the error, e.g., "Invalid file format."

#### Error Response Example
```json
{
  "detail": "Invalid file format"
}
```
```

--------------------------------

### Deskew Image Correction - Python

Source: https://context7.com/livewithcodeankit/ai-ocr/llms.txt

Corrects the orientation of skewed or rotated images using OpenCV and Hough Line Transformation. Saves the deskewed image to a specified path.

```python
import cv2
from app.services.preprocessing import deskew_image

# Load and deskew a rotated or skewed image
image = cv2.imread("uploads/rotated_document.jpg")

if image is not None:
    deskewed = deskew_image(image)

    # Save the corrected image
    cv2.imwrite("uploads/corrected_document.jpg", deskewed)

    # The function:
    # - Detects edges using Canny edge detection
    # - Identifies lines using Hough Line Transform
    # - Calculates median angle from detected lines
    # - Rotates image to correct orientation
    # - Filters extreme angles (-45° to 45°)

    print("Image successfully deskewed")
else:
    print("Failed to load image")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.