Automatyczna rotacja PDF – API do wyrównywania stron PDF i obrazów

Zeskanowane lub sfotografowane dokumenty często trafiają do nas odwrócone lub obrócone bokiem. Ręczna rotacja nie sprawdza się przy przetwarzaniu setek dokumentów. Automatyczne API rotacji PDF, które wykrywa orientację na podstawie rzeczywistej treści – nie tylko z danych EXIF – i ją koryguje, wyeliminowałoby żmudny krok z procesu przetwarzania.

Kto przetwarza akta, skany lub zdjęcia w dużych ilościach, wie: nieprawidłowa orientacja kosztuje czas.

Dlaczego stworzenie własnego rozwiązania do automatycznego wyrównywania stron PDF i obrazów trwa tygodnie

Kto chce zbudować to samodzielnie, szybko odkrywa, że wykrywanie orientacji zazwyczaj oznacza: uruchomienie OCR, analizę kierunku tekstu, określenie rotacji. Tesseract, EasyOCR lub usługi OCR w chmurze mogą w tym pomóc – ale trzeba je zintegrować, uwzględnić różne języki i dopasować wyniki do rotacji 0°/90°/180°/270°. Pliki PDF wymagają przetwarzania strona po stronie. Zbudowanie niezawodnego API do wykrywania orientacji dokumentów kosztuje czas na integrację i dostrajanie.

Jak API MaraDocs do automatycznej rotacji PDF rozwiązuje to w minuty

API MaraDocs oferuje pdf.orientation i img.orientation. Oba wykorzystują analizę opartą na tekście do określenia prawidłowej orientacji – bardziej niezawodną niż EXIF, który często jest błędny lub nie istnieje. W przypadku plików PDF analizowana jest każda strona; w przypadku obrazów – cały obraz. API zwraca obrócony wynik wraz z kątami dla każdej strony z wartościami pewności. Nie trzeba utrzymywać potoku OCR, hostować modeli ani konfigurować języków. Jedno wywołanie API i otrzymujesz poprawiony uchwyt do kolejnego kroku.

Przepływ pracy wykrywania orientacji dokumentów: walidacja, wyrównanie, łączenie

Prześlij plik PDF lub obraz, zwaliduj pod kątem wirusów i formatu, następnie wywołaj orientation. API analizuje każdą stronę (lub cały obraz w przypadku danych jednostronicowych) i zwraca obrócony uchwyt. Ten uchwyt można bezpośrednio przekazać do OCR, kompozycji lub optymalizacji – orientacja wpisuje się jako jeden krok w każdy potok. Plik nie musi być ponownie przesyłany między krokami; obrócony wynik pozostaje w przestrzeni roboczej.

Co wyróżnia MaraDocs: przestrzenie robocze, webview i niemieckie prawo o ochronie danych

Większość API do dokumentów wymusza przesyłanie, przetwarzanie, pobieranie i ponowne przesyłanie dla następnego kroku. W MaraDocs pliki pozostają w przestrzeni roboczej. Po wykryciu orientacji obrócony uchwyt jest bezpośrednio przekazywany do OCR, kompozycji lub optymalizacji – bez ponownego przesyłania. Uchwyty przepływają; dane pozostają po stronie serwera.

Gdy wykrywanie orientacji jest niepewne – skany o niskim kontraście, odręczne notatki lub mieszane języki – można otworzyć app.maradocs.io do ręcznej weryfikacji i korekty. Użytkownicy otrzymują pełną ręczną kontrolę, gdy automatyzacja osiąga swoje granice.

Całe przetwarzanie odbywa się w Niemczech (Maramia GmbH), z szyfrowaniem w spoczynku i podczas transmisji. Przestrzenie robocze wygasają po 7 dniach. Żadne dane nie opuszczają UE. Dla przetwarzania dokumentów wrażliwych pod względem ochrony danych jest to istotne.

Kod TypeScript dla automatycznej rotacji PDF

Dokumentacja 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 });

// Przesyłanie i walidacja
const uploaded = await client.data.upload(pdfOrImageFile);
const pdfVal = await client.pdf.validate({ unvalidated_file_handle: uploaded.unvalidated_file_handle });
const pdfHandle = okPdf(pdfVal);

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

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

// Dla obrazów: użyj client.img.validate + client.img.orientation

Kod Python dla wykrywania orientacji dokumentów

Dokumentacja 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()

Podsumowanie i kolejne kroki

API do automatycznej rotacji PDF i wykrywania orientacji dokumentów jest dostępne. MaraDocs przetwarza obrazy i pliki PDF z analizą opartą na tekście. Dalsze powiązane przepływy pracy: Skaner dokumentów, Przetwarzanie PDF oraz Rozpoznawanie tekstu.

---

Wypróbuj teraz: API MaraDocs | SDK TypeScript

---