콘텐츠로 이동
NextPDF
getnextpdf.com

Pro 에디션

Converter — 심층 참조

한눈에 보기

섹션 제목: “한눈에 보기”

NextPDF\Pro\Converter는 기존 PDF를 위치 지정된 HTML, 단순화된 SVG, 또는 일반 텍스트로 내보내고, 문서 콘텐츠를 유형화된 구조 영역으로 세그먼트화합니다. 이 심층 참조는 공개 API 표면, 연산자 커버리지 매트릭스, 동작 계약, 실패 모드를 열거합니다. 이는 픽셀 단위로 정확한 렌더러가 아니라 콘텐츠 추출 내보내기 도구입니다.

제공 여부 및 라이선스

섹션 제목: “제공 여부 및 라이선스”

이 기능은 NextPDF Pro(nextpdf/pro)로 제공되며, Pro 티어 라이선스 봉투로 활성화됩니다. 해당 자격이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션을 비교하고 라이선스를 받으세요.

이 모듈을 게이트하는 런타임 기능 플래그는 없습니다. Converter 클래스는 Pro 패키지가 설치되고 라이선스가 부여되면 언제든지 해석됩니다.

공개 API 표면

섹션 제목: “공개 API 표면”
심볼매개변수기본 동작반환값예외 또는 실패 조건비고
PdfToHtmlConverter::convert()string $pdfData, ?ConversionConfig $config = null텍스트를 포함한 모든 페이지를 하나의 자체 완결형 HTML5 문서로 내보냅니다ConversionResult (대상 Html5)$pdfData가 비어 있으면 InvalidArgumentExceptionNull 구성은 ConversionTarget::Html5로 기본 설정됩니다
PdfToSvgConverter::convert()string $pdfData, int $pageIndex = 0, ?ConversionConfig $config = null한 페이지를 독립형 SVG 문서로 내보냅니다ConversionResult (대상 Svg; pageCount는 항상 1)$pdfData가 비어 있으면 InvalidArgumentException범위를 벗어난 $pageIndex는 배경만 있는 SVG를 산출합니다
PdfToTextConverter::convert()string $pdfData모든 페이지에서 디코딩된 텍스트를 추출하며, 페이지 나눔 마커로 구분합니다ConversionResult (대상 PlainText)$pdfData가 비어 있으면 InvalidArgumentException이 대상만 리터럴 문자열 이스케이프를 디코딩합니다
PdfToTextConverter::extractPage()string $pdfData, int $pageIndex0부터 시작하는 인덱스의 한 페이지에서 디코딩된 텍스트를 추출합니다string예외를 발생시키지 않으며, 없는 페이지나 빈 입력에는 ''를 반환합니다convert()와 달리 빈 입력 가드가 없습니다
DocumentSegmentationEngine::segment()string $pdfData공간 및 폰트 휴리스틱을 사용하여 페이지 콘텐츠를 유형화된 구조 세그먼트로 분류합니다NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation입력이 비어 있거나 PDF 구조를 파싱할 수 없으면 InvalidArgumentException규칙 기반이며, AI 추론을 수행하지 않습니다
ConversionConfig::__construct()ConversionTarget $target, bool $embedFonts = false, bool $embedImages = true, float $scaleFactor = 1.0, string $cssClass = 'pdf-page'불변 변환 설정ConversionConfig—embedFonts와 embedImages는 허용되지만 3.1.0에서는 사용되지 않습니다
ConversionResult::size()—생성된 출력의 바이트 길이int—공개 읽기 전용 필드: output, target, pageCount, processingTimeMs
ConversionResult::isValid()—출력이 비어 있지 않은지 보고합니다bool—HTML과 SVG 문서 셸은 절대 비어 있지 않으므로, 대신 pageCount를 확인하십시오
ConversionTarget문자열 기반 케이스 Html5, Svg, PlainText내보내기 대상을 선택합니다mimeType(): string, fileExtension(): string—fileExtension()은 html, svg, txt로 매핑됩니다

진입점 시그니처:

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

동작 계약

섹션 제목: “동작 계약”

입력은 원시 PDF 바이트이고, 출력은 ConversionResult 값 객체입니다. 세 가지 내보내기 컨버터는 동일한 스캐닝 모델을 공유합니다. stream/endstream 경계를 찾고, BT/ET 텍스트 블록을 분리하며, 텍스트 표시 연산자를 파싱합니다. 이들은 상호 참조 테이블을 파싱하지 않으며 압축된 스트림을 해제하지 않습니다. DocumentSegmentationEngine은 다릅니다. 이는 트레일러, 카탈로그, 페이지 트리를 해석하고, 분류 전에 FlateDecode 페이지 콘텐츠를 해제합니다.

연산자 커버리지:

PDF operatorHTMLSVGText
Tj (show string)예예예
TJ (show array)예예예
' (move + show)아니요아니요예
Td / Tm (position)예예해당 없음
Tf (font size)예예해당 없음
re (rectangle)아니요예아니요
m / l (line)아니요예아니요
RG (RGB stroke)아니요예 (사각형/선 스트로크에 적용)아니요
curves, shading, clipping, images아니요아니요아니요
  • 위치 지정. 각 BT/ET 블록은 첫 번째 Td 또는 Tm 일치로부터 하나의 위치를 해석합니다. 둘 다 나타나면 Tm이 우선합니다. Y축은 PDF 사용자 공간에서 좌측 상단 출력 공간으로 뒤집힙니다. Tf가 없으면 폰트 크기는 12 pt로 기본 설정됩니다.
  • 페이지 기하. HTML과 SVG는 A4 페이지 박스(595 x 842 pt)에 scaleFactor를 곱한 값을 가정합니다. SVG 루트는 흰색 배경 사각형 위에 일치하는 viewBox, width, height 속성을 갖습니다.
  • 스트로크 색상. RG 연산자는 위치 기반으로 해석되므로, 스트로크 색상을 두 번 이상 변경하는 스트림은 가장 최근의 선행 연산자로 각 사각형과 선을 채색합니다. 구성 요소는 16진수 변환 전에 0..1 범위로 클램핑됩니다. 사각형 채우기는 항상 검정색이며, rg 채우기 연산자는 평가되지 않습니다.
  • 문자열 디코딩. 텍스트 대상은 ISO 32000-2:2020 §7.3.4.2에 따라 리터럴 문자열 이스케이프를 디코딩합니다. 명명된 이스케이프, 1바이트로 마스킹된 8진 \ddd 코드, 백슬래시 줄 연속, 단독 백슬래시 제거가 포함됩니다. HTML과 SVG 대상은 HTML 또는 XML 이스케이프 후 괄호 사이의 원시 바이트를 방출하며, 이스케이프를 디코딩하지 않습니다.
  • 출력 조립. 텍스트 대상은 블록 텍스트를 공백으로 연결하고, 페이지를 빈 줄로 감싼 --- Page Break ---로 연결합니다. HTML 대상은 구성된 CSS 클래스와 data-page 속성을 갖는 페이지별 컨테이너 안에 텍스트 블록마다 절대 위치 지정된 <div> 하나를 방출합니다.
  • 결정성. 동일한 입력과 구성에 대해 생성된 HTML, SVG, 또는 텍스트 바이트는 안정적입니다. processingTimeMs는 벽시계 측정값이며 결정적 표면에서 제외됩니다.

엣지 케이스 및 실패 모드

섹션 제목: “엣지 케이스 및 실패 모드”
  • 빈 입력: 모든 convert() 및 segment() 진입점은 InvalidArgumentException(“PDF data must not be empty”)을 발생시킵니다. 부분 출력은 생성되지 않습니다. extractPage()는 예외입니다. 이는 예외를 발생시키지 않고 ''를 반환합니다.
  • BT/ET가 없는 스트림은 HTML과 텍스트 컨버터에서 건너뜁니다. 그런 스트림으로만 이루어진 PDF는 빈 텍스트 출력 또는 페이지 없는 HTML 셸과 함께 pageCount 0을 산출합니다.
  • isValid()는 출력이 비어 있지 않은지만 확인합니다. HTML과 SVG 컨버터는 항상 문서 셸을 방출하므로, 텍스트를 찾지 못한 경우에도 isValid()는 true로 유지됩니다. 빈 추출을 감지하려면 pageCount(HTML, 텍스트)를 사용하십시오.
  • FlateDecode 콘텐츠는 세 가지 내보내기 컨버터에서 해제되지 않습니다. 압축만 되어 있는 PDF는 이들을 통해 콘텐츠를 거의 또는 전혀 내보내지 못합니다. segment()는 FlateDecode 페이지 스트림을 해제합니다.
  • segment()는 스트림별 크기, 압축 비율, 누적 예산으로 압축 해제를 제한합니다. 한계를 초과하는 스트림은 메모리를 소진하는 대신 빈 페이지 콘텐츠로 저하되며, 예외를 발생시키지 않습니다.
  • segment()는 트레일러, 상호 참조 오프셋, 문서 카탈로그, 또는 페이지 트리를 해석할 수 없으면 InvalidArgumentException을 발생시킵니다.
  • 페이지 인덱싱은 컨버터마다 다릅니다. HTML과 텍스트 컨버터는 텍스트를 포함한 스트림만 계산하고, SVG 컨버터는 인식되는 그래픽 또는 텍스트 연산자를 포함하는 스트림을 계산합니다. 따라서 동일한 $pageIndex가 서로 다른 스트림을 가리킬 수 있습니다.
  • TJ 숫자 커닝 조정은 폐기되며, 배열 문자열은 글리프 간 간격 없이 연결됩니다.
  • 글리프-유니코드 매핑은 적용되지 않습니다. 사용자 지정 인코딩 폰트로 설정된 텍스트는 원시 바이트 시퀀스로 내보내집니다.
  • 회전된 텍스트, 비텍스트 변환, 컬럼 흐름은 첫 일치 위치 지정으로 근사되며 원본 레이아웃을 재현하지 못할 수 있습니다.
  • 이 모듈에서는 어떠한 암호화 연산도 발생하지 않으므로, FIPS 모드에는 모듈별 동작이 없습니다.

적합성

섹션 제목: “적합성”

NextPDF는 인용된 절에 대해 기능을 문서화합니다. 지원 진술은 구현된 동작을 설명하며, 적합성 테스트 결과나 인증이 아니고, NextPDF는 어떠한 인증도 보유하지 않습니다.

주장사양 절상태
Tj 텍스트 표시 연산자 파싱됨ISO 32000-2:2020 §9.4검증됨 (단위 테스트 스위트)
TJ 배열 텍스트 표시 연산자 파싱됨ISO 32000-2:2020 §9.4검증됨 (단위 테스트 스위트)
' 이동 후 표시 연산자 파싱됨 (텍스트 대상만)ISO 32000-2:2020 §9.4검증됨 (단위 테스트 스위트)
리터럴 문자열 이스케이프 디코딩됨 (텍스트 대상만)ISO 32000-2:2020 §7.3.4.2구현됨; 바이트는 그대로 반환되며, 문자셋 해석은 다운스트림 처리입니다
re, m, l 경로 구성 인식됨 (SVG 대상)ISO 32000-2:2020 §8.5.2부분적: 곡선, 닫기, 페인팅 모드 평가가 없는 하위 집합
전체 텍스트 상태 머신 및 페이지 렌더링—지원되지 않음 (범위 외)

Converter는 콘텐츠를 복원하기 위해 텍스트 표시 연산자를 파싱합니다. 전체 텍스트 상태 머신을 구현하지는 않으므로, 글리프 위치 지정은 사양 그대로 정확하기보다는 근사적입니다.

개발 노트

섹션 제목: “개발 노트”
  • 파싱은 PDF 바이트 길이에 선형적입니다. 메모리는 입력과 생성된 출력 문자열을 추적합니다. performance_budget 프런트 매터는 일반적인 오피스 문서에 대한 호출당 참조입니다.
  • 컨버터는 제한된 strpos/substr 스캐닝으로 신뢰할 수 없는 PDF 바이트를 파싱합니다. 임베디드 JavaScript를 실행하지 않고 외부 참조를 따르지 않습니다. 내보낸 HTML을 신뢰할 수 없는 콘텐츠로 취급하고 대상에 맞게 이스케이프하십시오.
  • HTML 출력은 htmlspecialchars(ENT_QUOTES, HTML5)로 이스케이프되고, SVG 텍스트는 XML 이스케이프됩니다. 구성된 cssClass는 방출 전에 이스케이프됩니다.
  • 구성 소비: scaleFactor는 HTML과 SVG 대상에 적용되고, cssClass는 HTML에만 적용되며, embedFonts와 embedImages는 예약되어 있으며 현재 사용되지 않고, target 필드는 컨버터 자체의 출력 형식을 재정의하지 않습니다.
  • 내보내기 컨버터는 1.9.0부터 제공되고, DocumentSegmentationEngine은 2.1.0부터 제공되며 Pro MCP segment_document 도구와 Interop 세그먼트화 계약을 뒷받침합니다.
  • 동일한 네임스페이스의 PdfPageExtractor와 PdfPageData는 세그먼트화 엔진 내부용이며 공개 API가 아닙니다.

게시 경계

섹션 제목: “게시 경계”

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 테이블, 런북 파일명, 티켓 접두사는 범위 외입니다.

함께 보기

섹션 제목: “함께 보기”