Pro Edition

Converter — Ausführliche Referenz

Auf einen Blick

NextPDF\Pro\Converter exportiert ein vorhandenes PDF nach positioniertem HTML, vereinfachtem SVG oder reinem Text und segmentiert Dokumentinhalte in typisierte strukturelle Regionen. Diese ausführliche Referenz führt die öffentliche API-Oberfläche, die Matrix der Operatorabdeckung, den Verhaltensvertrag und die Fehlermodi auf. Es handelt sich um einen Exporter zur Inhaltsextraktion, nicht um einen pixelgenauen Renderer.

Verfügbarkeit & Lizenzierung

Diese Funktion ist Bestandteil von NextPDF Pro (nextpdf/pro) und wird mit einem Lizenz-Envelope der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und eine Lizenz erwerben.

Kein Laufzeit-Capability-Flag steuert den Zugriff auf dieses Modul. Die Converter-Klassen werden aufgelöst, sobald das Pro-Paket installiert und lizenziert ist.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Löst aus oder scheitert mit	Hinweise
`PdfToHtmlConverter::convert()`	`string $pdfData`, `?ConversionConfig $config = null`	Exportiert jede textführende Seite in ein einziges eigenständiges HTML5-Dokument	`ConversionResult` (Ziel `Html5`)	`InvalidArgumentException`, wenn `$pdfData` leer ist	Eine Null-Konfiguration verwendet standardmäßig `ConversionTarget::Html5`
`PdfToSvgConverter::convert()`	`string $pdfData`, `int $pageIndex = 0`, `?ConversionConfig $config = null`	Exportiert eine Seite in ein eigenständiges SVG-Dokument	`ConversionResult` (Ziel `Svg`; `pageCount` ist immer 1)	`InvalidArgumentException`, wenn `$pdfData` leer ist	Ein `$pageIndex` außerhalb des Bereichs ergibt ein SVG, das nur den Hintergrund enthält
`PdfToTextConverter::convert()`	`string $pdfData`	Extrahiert dekodierten Text aus allen Seiten, getrennt durch einen Seitenumbruch-Marker	`ConversionResult` (Ziel `PlainText`)	`InvalidArgumentException`, wenn `$pdfData` leer ist	Nur dieses Ziel dekodiert Literal-String-Escapes
`PdfToTextConverter::extractPage()`	`string $pdfData`, `int $pageIndex`	Extrahiert dekodierten Text für eine nullbasierte Seite	`string`	Löst nicht aus; gibt `''` für eine fehlende Seite oder leere Eingabe zurück	Im Gegensatz zu `convert()` keine Absicherung gegen leere Eingaben
`DocumentSegmentationEngine::segment()`	`string $pdfData`	Klassifiziert Seiteninhalte anhand räumlicher und schriftbezogener Heuristiken in typisierte strukturelle Segmente	`NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation`	`InvalidArgumentException`, wenn die Eingabe leer ist oder die PDF-Struktur nicht geparst werden kann	Regelbasiert; führt keine KI-Inferenz durch
`ConversionConfig::__construct()`	`ConversionTarget $target`, `bool $embedFonts = false`, `bool $embedImages = true`, `float $scaleFactor = 1.0`, `string $cssClass = 'pdf-page'`	Unveränderliche Konvertierungseinstellungen	`ConversionConfig`	—	`embedFonts` und `embedImages` werden akzeptiert, aber in 3.1.0 nicht verwendet
`ConversionResult::size()`	—	Bytelänge der erzeugten Ausgabe	`int`	—	Öffentliche readonly-Felder: `output`, `target`, `pageCount`, `processingTimeMs`
`ConversionResult::isValid()`	—	Meldet, ob die Ausgabe nicht leer ist	`bool`	—	HTML- und SVG-Dokumentrümpfe sind nie leer; prüfen Sie stattdessen `pageCount`
`ConversionTarget`	String-basierte Fälle `Html5`, `Svg`, `PlainText`	Wählt das Exportziel aus	`mimeType(): string`, `fileExtension(): string`	—	`fileExtension()` verweist auf `html`, `svg`, `txt`

Signaturen der Einstiegspunkte:

public function convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult

public function convert(
    string $pdfData,
    int $pageIndex = 0,
    ?ConversionConfig $config = null,
): ConversionResult

public function convert(string $pdfData): ConversionResult
public function extractPage(string $pdfData, int $pageIndex): string

public function segment(string $pdfData): DocumentSegmentation

Verhaltensvertrag

Eingaben sind rohe PDF-Bytes; Ausgaben sind ein ConversionResult-Wertobjekt. Die drei Export-Converter teilen sich ein Scan-Modell: stream/endstream-Grenzen lokalisieren, BT/ET-Textblöcke isolieren und textzeigende Operatoren parsen. Sie parsen nicht die Querverweistabelle und dekomprimieren keine komprimierten Streams. DocumentSegmentationEngine unterscheidet sich: Es löst Trailer, Katalog und Seitenbaum auf und dekomprimiert FlateDecode-Seiteninhalte vor der Klassifizierung.

Operatorabdeckung:

PDF-Operator	HTML	SVG	Text
`Tj` (Zeichenkette zeigen)	ja	ja	ja
`TJ` (Array zeigen)	ja	ja	ja
`'` (bewegen + zeigen)	nein	nein	ja
`Td` / `Tm` (Position)	ja	ja	n. z.
`Tf` (Schriftgröße)	ja	ja	n. z.
`re` (Rechteck)	nein	ja	nein
`m` / `l` (Linie)	nein	ja	nein
`RG` (RGB-Kontur)	nein	ja (auf Rechteck-/Linienkontur angewandt)	nein
Kurven, Schattierung, Clipping, Bilder	nein	nein	nein

Positionierung. Jeder BT/ET-Block ermittelt eine Position aus seiner ersten Td- oder Tm-Übereinstimmung; Tm hat Vorrang, wenn beide auftreten. Die Y-Achse wird vom PDF-Benutzerraum in den Ausgaberaum oben links gespiegelt. Die Schriftgröße beträgt standardmäßig 12 pt, wenn kein Tf vorhanden ist.
Seitengeometrie. HTML und SVG gehen von einer A4-Seitenbox (595 x 842 pt) multipliziert mit scaleFactor aus. Das SVG-Wurzelelement trägt passende viewBox-, Breiten- und Höhenattribute über einem weißen Hintergrundrechteck.
Konturfarbe. RG-Operatoren werden positionsabhängig aufgelöst, sodass ein Stream, der die Konturfarbe mehr als einmal ändert, jedes Rechteck und jede Linie anhand des zuletzt vorangehenden Operators einfärbt. Die Komponenten werden vor der Hex-Umwandlung auf den Bereich 0..1 begrenzt. Die Rechteckfüllung ist immer schwarz; der Füll-Operator rg wird nicht ausgewertet.
String-Dekodierung. Das Textziel dekodiert Literal-String-Escapes gemäß ISO 32000-2:2020 §7.3.4.2: benannte Escapes, oktale \ddd-Codes maskiert auf ein Byte, Backslash-Zeilenfortsetzungen und Entfernung einzelner Backslashes. HTML- und SVG-Ziele geben die rohen Bytes zwischen den Klammern nach HTML- bzw. XML-Escaping aus; sie dekodieren keine Escapes.
Ausgabezusammenstellung. Das Textziel verbindet Blocktexte mit einem Leerzeichen und Seiten mit --- Page Break ---, umrahmt von Leerzeilen. Das HTML-Ziel gibt pro Textblock ein absolut positioniertes <div> innerhalb eines Seitencontainers aus, der die konfigurierte CSS-Klasse und ein data-page-Attribut trägt.
Determinismus. Bei identischer Eingabe und Konfiguration sind die erzeugten HTML-, SVG- oder Text-Bytes stabil. processingTimeMs ist eine Wanduhrmessung und wird von der deterministischen Oberfläche ausgenommen.

Randfälle & Fehlermodi

Leere Eingabe: Jeder convert()- und segment()-Einstiegspunkt löst InvalidArgumentException aus (“PDF data must not be empty”). Es wird keine Teilausgabe erzeugt. extractPage() ist die Ausnahme: Es gibt '' zurück, ohne auszulösen.
Streams ohne BT/ET werden von den HTML- und Text-Convertern übersprungen. Ein PDF, das nur solche Streams enthält, ergibt einen pageCount von null mit einer leeren Textausgabe oder einem seitenlosen HTML-Rumpf.
isValid() prüft nur auf nicht leere Ausgabe. HTML- und SVG-Converter geben stets einen Dokumentrumpf aus, sodass isValid() auch dann true bleibt, wenn kein Text gefunden wurde; verwenden Sie pageCount (HTML, Text), um eine leere Extraktion zu erkennen.
FlateDecode-Inhalte werden von den drei Export-Convertern nicht dekomprimiert. Ausschließlich komprimierte PDFs exportieren über sie wenig oder keinen Inhalt. segment() dekomprimiert FlateDecode-Seitenstreams.
segment() begrenzt die Dekomprimierung durch die Größe pro Stream, das Kompressionsverhältnis und ein kumulatives Budget. Ein Stream, der eine Obergrenze überschreitet, verschlechtert sich zu leerem Seiteninhalt, anstatt den Speicher zu erschöpfen; er löst nicht aus.
segment() löst InvalidArgumentException aus, wenn Trailer, Querverweis-Offset, Dokumentkatalog oder Seitenbaum nicht aufgelöst werden können.
Die Seitenindizierung unterscheidet sich je Converter. HTML- und Text-Converter zählen nur textführende Streams; der SVG-Converter zählt Streams, die einen beliebigen erkannten Grafik- oder Textoperator enthalten. Derselbe $pageIndex kann daher unterschiedliche Streams adressieren.
Numerische TJ-Kerning-Anpassungen werden verworfen; Array-Zeichenketten werden ohne Abstände zwischen den Glyphen aneinandergefügt.
Glyph-zu-Unicode-Zuordnung wird nicht angewandt. Text, der in Schriften mit benutzerdefinierten Kodierungen gesetzt ist, wird als rohe Bytefolge exportiert.
Gedrehter Text, nichttextuelle Transformationen und Spaltenfluss werden durch Positionierung nach erster Übereinstimmung angenähert und geben das ursprüngliche Layout möglicherweise nicht wieder.
In diesem Modul findet keine kryptografische Operation statt, sodass der FIPS-Modus kein modulspezifisches Verhalten aufweist.

Konformität

NextPDF dokumentiert die Funktion anhand der zitierten Klauseln. Support-Aussagen beschreiben implementiertes Verhalten; sie sind keine Ergebnisse von Konformitätstests und keine Zertifizierungen, und NextPDF besitzt keine Zertifizierung.

Aussage	Spezifikationsklausel	Status
`Tj` textzeigender Operator geparst	ISO 32000-2:2020 §9.4	Verifiziert (Unit-Suite)
`TJ` textzeigender Array-Operator geparst	ISO 32000-2:2020 §9.4	Verifiziert (Unit-Suite)
`'` Bewegen-und-zeigen-Operator geparst (nur Textziel)	ISO 32000-2:2020 §9.4	Verifiziert (Unit-Suite)
Literal-String-Escapes dekodiert (nur Textziel)	ISO 32000-2:2020 §7.3.4.2	Implementiert; Bytes werden unverändert zurückgegeben, die Zeichensatzinterpretation erfolgt nachgelagert
`re`, `m`, `l` Pfadkonstruktion erkannt (SVG-Ziel)	ISO 32000-2:2020 §8.5.2	Teilweise: Teilmenge ohne Kurven, Schließen oder Auswertung des Painting-Modus
Vollständiger Textzustandsautomat und Seitenrendering	—	Nicht unterstützt (außerhalb des Geltungsbereichs)

Der Converter parst textzeigende Operatoren, um Inhalte wiederherzustellen; er implementiert nicht den vollständigen Textzustandsautomaten, sodass die Glyphenpositionierung eher näherungsweise als spezifikationsgenau ist.

Entwicklungshinweise

Das Parsen ist linear zur PDF-Bytelänge. Der Speicher folgt der Eingabe plus der erzeugten Ausgabezeichenkette. Das Frontmatter performance_budget ist der Referenzwert pro Aufruf für ein typisches Büro-Dokument.
Die Converter parsen nicht vertrauenswürdige PDF-Bytes mit begrenztem strpos/substr-Scannen. Sie führen kein eingebettetes JavaScript aus und folgen keinen externen Referenzen. Behandeln Sie exportiertes HTML als nicht vertrauenswürdigen Inhalt und escapen Sie es für sein Ziel.
Die HTML-Ausgabe wird mit htmlspecialchars (ENT_QUOTES, HTML5) escaped; SVG-Text wird XML-escaped. Die konfigurierte cssClass wird vor der Ausgabe escaped.
Konfigurationsnutzung: scaleFactor gilt für die Ziele HTML und SVG; cssClass gilt nur für HTML; embedFonts und embedImages sind reserviert und derzeit ungenutzt; das Feld target überschreibt nicht das eigene Ausgabeformat eines Converters.
Die Export-Converter sind seit 1.9.0 enthalten; DocumentSegmentationEngine ist seit 2.1.0 enthalten und untermauert das Pro-MCP-Tool segment_document sowie den Interop-Segmentierungsvertrag.
PdfPageExtractor und PdfPageData im selben Namespace sind intern für die Segmentierungs-Engine und keine öffentliche API.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Geltungsbereichs.