Rotazione automatica PDF – API per orientare pagine PDF e immagini

I documenti scansionati o fotografati arrivano spesso capovolti o ruotati lateralmente. La rotazione manuale non scala quando si devono elaborare centinaia di documenti. Un'API di rotazione automatica PDF che rileva l'orientamento in base al contenuto effettivo – non solo dai dati EXIF – e lo corregge, eliminerebbe un passaggio laborioso dalla pipeline di elaborazione.

Chi elabora fascicoli, scansioni o foto in grandi quantità lo sa: l'orientamento errato fa perdere tempo.

Perché una soluzione propria per l'orientamento automatico di pagine PDF e immagini richiede settimane

Chi vuole svilupparla internamente scopre presto che il rilevamento dell'orientamento significa principalmente: eseguire OCR, analizzare la direzione del testo, dedurre la rotazione. Tesseract, EasyOCR o servizi OCR cloud possono aiutare – ma bisogna integrarli, considerare diverse lingue e mappare i risultati su rotazioni di 0°/90°/180°/270°. I PDF richiedono elaborazione pagina per pagina. Costruire un'API affidabile per il rilevamento dell'orientamento dei documenti costa tempo di integrazione e messa a punto.

Come l'API MaraDocs per la rotazione automatica PDF lo risolve in pochi minuti

L'API MaraDocs offre pdf.orientation e img.orientation. Entrambe utilizzano l'analisi basata su testo per determinare l'orientamento corretto – più affidabile dell'EXIF, che spesso è errato o assente. Per i PDF viene analizzata ogni pagina; per le immagini l'intera immagine. L'API restituisce il risultato ruotato insieme agli angoli per pagina con valori di confidenza. Nessuna pipeline OCR da mantenere, nessun hosting di modelli, nessuna configurazione linguistica. Una chiamata API e si ottiene un handle corretto per il passaggio successivo.

Workflow per l'orientamento documenti: Validare, Orientare, Concatenare

Caricare PDF o immagine, validare virus e formato, quindi chiamare orientation. L'API analizza ogni pagina (o l'intera immagine per input a pagina singola) e restituisce un handle ruotato. Questo handle può essere inoltrato direttamente a OCR, composizione o ottimizzazione – l'orientamento si inserisce come un passaggio in qualsiasi pipeline. Il file non deve essere ricaricato tra i passaggi; il risultato ruotato rimane nel workspace.

Cosa distingue MaraDocs: Workspace, Webview e normativa tedesca sulla privacy

La maggior parte delle API per documenti costringe a caricare, elaborare, scaricare e ricaricare per il passaggio successivo. Con MaraDocs i file rimangono nel workspace. Dopo il rilevamento dell'orientamento, l'handle ruotato viene passato direttamente a OCR, composizione o ottimizzazione – nessun nuovo caricamento. Gli handle fluiscono; i dati rimangono lato server.

Quando il rilevamento dell'orientamento è incerto – scansioni a basso contrasto, note manoscritte o lingue miste – è possibile aprire app.maradocs.io per verifica e correzione manuale. Gli utenti ottengono pieno controllo manuale quando l'automazione raggiunge i suoi limiti.

L'intera elaborazione avviene in Germania (Maramia GmbH), crittografata a riposo e durante il trasferimento. I workspace scadono dopo 7 giorni. Nessun dato lascia l'UE. Per l'elaborazione di documenti sensibili alla privacy questo è rilevante.

Codice TypeScript per la rotazione automatica PDF

Riferimento API: data/upload, pdf/validate, img/validate, pdf/orientation, img/orientation, data/download/pdf

import { MaraDocsClient } from "@maramia/maradocs-sdk-ts";
import { okPdf } from "@maramia/maradocs-sdk-ts/models/pdf";

const client = new MaraDocsClient({ workspaceSecret: workspace_secret });

// Caricare e validare
const uploaded = await client.data.upload(pdfOrImageFile);
const pdfVal = await client.pdf.validate({ unvalidated_file_handle: uploaded.unvalidated_file_handle });
const pdfHandle = okPdf(pdfVal);

// Orientamento PDF
const oriented = await client.pdf.orientation({ pdf_handle: pdfHandle });

// Scaricare risultato
const blob = await client.data.downloadPdf({ pdf_handle: oriented.rotated_pdf_handle });

// Per immagini: usare client.img.validate + client.img.orientation

Codice Python per il rilevamento orientamento documenti

Riferimento API: data/upload, pdf/validate, pdf/orientation, img/orientation, data/download/pdf

# pip install python-decouple requests
"""Fix PDF page orientation using MaraDocs. Set ACCOUNT_SECRET in .env or environment."""

import sys
import time
from pathlib import Path

import requests
from decouple import config

API_URL = "https://api.maradocs.io/v1"


def create_workspace() -> dict:
    """Create a workspace and return auth headers."""
    r = requests.post(
        f"{API_URL}/workspace",
        headers={"Authorization": f"Bearer {config('ACCOUNT_SECRET')}"},
        json={"subaccount": None},
    )
    ws = r.json()
    return {"Authorization": f"Bearer {ws['workspace_secret']}"}


def upload_file(path: Path, auth: dict) -> dict:
    """Upload a file via two-step flow (signed URL + S3 POST). Returns unvalidated_file_handle."""
    data = path.read_bytes()
    resp = requests.post(
        f"{API_URL}/data/upload",
        headers={**auth, "Content-Type": "application/json"},
        json={"name": path.name, "size": len(data)},
    ).json()
    requests.post(
        resp["post_url"],
        data=resp.get("post_header", {}),
        files={"file": (path.name, data, "application/pdf")},
    )
    return resp["unvalidated_file_handle"]


def run_job(path: str, payload: dict, auth: dict, timeout: int = 60) -> dict:
    """Run a job and poll until complete. Returns the result (unwraps response if present)."""
    url = f"{API_URL}/{path}"
    r = requests.post(url, headers=auth, json=payload).json()
    job_id = r["job_id"]
    start = time.time()
    while time.time() - start < timeout:
        poll_r = requests.get(f"{url}/{job_id}", headers=auth)
        if poll_r.status_code == 200:
            return poll_r.json()
    raise TimeoutError(f"Job {path} timed out")


def download_pdf(pdf_handle: str, auth: dict) -> bytes:
    """Request signed URL and fetch PDF bytes."""
    r = requests.post(
        f"{API_URL}/data/download/pdf",
        headers=auth,
        json={"pdf_handle": pdf_handle},
    )
    info = r.json()
    dl = requests.get(info["url"], headers=info.get("headers", {}))
    return dl.content


def main() -> None:
    pdf_path = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("input.pdf")
    auth = create_workspace()
    handle = upload_file(pdf_path, auth)
    validate = run_job("pdf/validate", {"unvalidated_file_handle": handle}, auth)
    pdf_handle = validate["response"]["pdf_handle"]
    oriented = run_job("pdf/orientation", {"pdf_handle": pdf_handle}, auth)
    rotated_handle = oriented["response"]["rotated_pdf_handle"]
    Path("rotated.pdf").write_bytes(download_pdf(rotated_handle, auth))
    print("rotated.pdf created")


if __name__ == "__main__":
    main()

Riepilogo e prossimi passi

È disponibile un'API per la rotazione automatica PDF e il rilevamento dell'orientamento documenti. MaraDocs elabora immagini e PDF con analisi basata su testo. Altri workflow correlati: Scanner documenti, Elaborazione PDF e Riconoscimento testo.

---

Prova ora: API MaraDocs | SDK TypeScript

---