PDF의 목차 페이지를 클릭할 수 있는데 추출 후 레벨이 손실되면 어떻게 해야 하나요?

PDF의 목차 페이지는 리더에서 정상적으로 리디렉션될 수 있지만, 스크립트를 사용하여 추출한 후에는 계층 구조가 단순해지거나 페이지 번호가 잘못 배치되거나 심지어 색인이 비정상일 수도 있습니다. 이러한 유형의 문제는 스캔한 파일이나 책갈피 구조가 불규칙한 파일을 병합할 때 흔히 발생합니다. 추출 결과가 하위 사용자에게 직접 전달될 경우 번역 분할 및 연결 오류가 발생할 수 있습니다.

이 문서는 PDF 카탈로그를 일괄 처리해야 하는 개발자 및 문서화 팀을 위한 것입니다. 읽은 후에는 get_toc() 반환 값의 의미를 이해하고, 레벨 및 페이지 번호에 대한 확인 규칙을 숙지하고, 어떤 상황을 수동 확인으로 전환해야 하는지 알 수 있습니다. 본 글은 처리방법을 설명하기 위해 합성 샘플을 사용하였으며, 코드는 격리된 환경에서 샘플을 통해 확인되었으나, 이것이 모든 실제 파일이나 제품 효과를 보장하는 것은 아닙니다. 중요한 서류를 처리하기 전, 원본을 보관하시고, 본문에 기재된 경계 및 허용 항목에 따라 검토하시기 바랍니다.

PDF 목차 페이지를 클릭할 수 있지만 추출 후 계층 구조가 손실되면 어떻게 해야 하나요? 한 문장 결론

먼저 확인한 후 쓰기: 북마크 수준을 먼저 확인해야 하며, 첫 번째 항목이 첫 번째 수준으로 간주되고, 이후 수준은 이전 항목에 1을 더한 값을 초과할 수 없으며, 페이지 번호를 벗어난 항목은 기록되지 않습니다.

추출 결과가 왜 레벨이 떨어지나요?

get_toc()는 기본적으로 [level, title, page] 트리플 목록을 출력합니다. 그 중 page는 1부터 시작하는 물리적 페이지 번호이며, level는 중첩 깊이만을 나타낼 뿐 연속성이나 적법성을 보장하지 않습니다.

원본 PDF가 스캔 병합 도구로 생성된 경우 일반적인 문제는 다음과 같습니다.

• 레벨 점프: 예를 들어 1에서 3으로 직접 점프합니다.
• 페이지 번호 예외: 페이지 번호가 0이거나 전체 페이지 수를 초과합니다.
• 제목 예외: 제목에 제어 문자가 포함되어 있습니다.

다운스트림 작업에 직접 사용하면 번역 세그먼트에 혼란이 발생하거나 링크 오류가 발생합니다. 더 은밀하게도 일부 PDF에는 시각적 목차 페이지가 있지만 책갈피 메타데이터가 내장되어 있지 않습니다. 이때 get_toc()가 빈 목록을 반환하는 것은 정상이며 대신 텍스트 레이아웃 분석을 사용해야 합니다.

독립형 구성 예

종속성 예는 가져오기 목록을 참조하세요. 코드는 메모리에 입력을 구성하며 실행 기록은 별도로 제공되며 모든 실제 파일을 보장하지는 않습니다.

import pymupdf
def validate(rows, pages):
    previous = 0
    for level, title, page in rows:
        if type(level) is not int or level < 1 or level > previous + 1:
            raise ValueError("invalid hierarchy")
        if type(page) is not int or not 1 <= page <= pages:
            raise ValueError("invalid destination")
        if not isinstance(title, str) or not title.strip():
            raise ValueError("empty title")
        previous = level
    return rows
with pymupdf.open() as doc:
    for _ in range(3):
        doc.new_page()
    rows = [[1, "Chapter", 1], [2, "Section", 2], [1, "Appendix", 3]]
    doc.set_toc(validate(rows, doc.page_count))
    assert doc.get_toc() == rows
    assert len(doc.get_toc()) == 3
    for bad in [[[2, "Bad", 1]], [[1, "Bad", 99]], [[1, "", 1]]]:
        try:
            validate(bad, doc.page_count)
        except ValueError:
            pass
        else:
            raise AssertionError("invalid outline accepted")

합법 입력과 불법 입력에 대한 처리 규칙

올바른 입력은 다음을 충족해야 합니다. [1, doc.page_count] 범위의 연속 레벨과 페이지 번호가 있는 트리플 목록. 예를 들어, [[1, "引言", 1], [2, "背景", 2], [1, "方法", 5]]는 유효하고 두 번째 수준은 첫 번째 수준 다음에 나타나며 PDF 개요 구문을 따릅니다.

일반적인 잘못된 입력은 다음과 같습니다.

• 레벨이 0이거나 음수입니다.
• 페이지 번호는 0입니다.
• 페이지 수가 전체 페이지 수를 초과합니다.
• 제목이 빈 문자열이거나 공백 문자만 포함합니다.

이러한 상황에서 기사에 제공된 방법은 다음과 같습니다.

1. 잘못된 페이지 번호가 있는 항목을 건너뛰고 경고를 기록합니다.
2. 구조적 무결성을 유지하려면 빈 제목에 대해 [untitled]와 같은 자리 표시자를 유지하세요.
3. 단일 오류로 인해 전체 디렉토리의 구문 분석을 중단하지 마십시오.

레벨이 1 미만인 경우에는 두 가지 전략을 알아야 합니다. 예제의 요약 부분은 불법 레벨을 거부하고 자동으로 수정하지 않는 것을 옹호하는 반면, 기사의 규칙 설명은 이를 1로 강제하는 것입니다. 둘 중 하나를 프로세스에 따라 결정하십시오. 또한 이러한 규칙은 다운스트림 프로세스의 견고성을 보장하도록 설계되었으며 PDF 표준의 필수 요구 사항은 아닙니다. 실제 테스트에서는 페이지 번호가 경계를 넘을 때 PyMuPDF가 경고를 인쇄하지만 예외를 발생시키지 않는 것으로 나타났습니다. 따라서 검증 기능은 적극적으로 필터링해야 하며 라이브러리의 동작에 의존할 수 없습니다.

📊 핵심 비교

문서 상황에 따라 get_toc()의 결과와 제안된 처리 방법이 다릅니다.

수제 기준과 수동 검토 경계

아래 표는 PDF 카탈로그 메타데이터의 추출 단계에만 초점을 맞추고 있습니다:

코드 시연은 구조적 합법성만 검사하며, 점프의 정확성을 검증하기 위해 엔드투엔드 효과도 렌더링과 결합해야 합니다.

🎯 어떤 방법이 당신에게 맞나요?

디렉터리를 일괄 추출해야 할 경우

먼저 get_toc() 결과에 대해 구조적 검증을 수행한 후 후속 워크플로우에 기록하고, 검증을 위해 로그를 보관합니다.

PDF가 시각적으로 목차가 있지만 추출된 것은 비어 있다면요

get_toc()를 반복해서 시도하지 말고, 텍스트 레이아웃 분석 및 처리로 전환하세요.

디렉토리 항목이 같은 이름이지만 페이지가 다르다면요

이 항목들을 수동으로 검증하세요; 페이지 번호 중 하나를 자동으로 선택하지 마세요.

만약 문서를 번역 과정에 넘기고 싶다면,

먼저, 번역 전에 올바른 목차 구조와 페이지 번호를 확인하여 단락 혼동을 피하세요.

❓ 자주 묻는 질문 (FAQ)

1. 왜 페이지 번호는 1에서 시작하는데, 페이지 색인은 보통 0부터 시작하나요?

북마크 페이지 번호는 1부터 시작하는 물리적 페이지 번호이며, PyMuPDF와 같은 라이브러리의 페이지 인덱스는 보통 0부터 시작합니다. 이 차이는 변환 시 중요하며, 그렇지 않으면 페이지 번호가 어긋날 수 있습니다.

2. get_toc(): 빈 목록을 반환하는 것이 반드시 파일 문제를 의미하나요?

꼭 그런 건 아니에요. 일부 PDF는 시각적으로는 목차 페이지가 있지만 북마크 메타데이터가 없기 때문에 빈 목록을 반환하는 것이 일반적입니다. 이 경우 텍스트 레이아웃 분석을 사용해야 합니다.

3. 페이지 번호가 경계를 넘으면 도서관에서 즉시 오류를 보고하나요?

아니. 이 글의 테스트 결과, PyMuPDF는 페이지 번호가 경계를 벗어날 때 경고를 출력하지만 예외는 던지지 않으므로 검증 함수가 적극적으로 필터링해야 합니다.

4. 계층적 점프(예: 1에서 3로 바로 넘어가는 것)는 중간 레이어를 채워야 하나요?

기사에서 제안하는 것은 원래 계층 구조를 유지하고 중간 계층을 채우지 말라는 것인데, 이 구조는 여전히 유효합니다.

📝 요약

PDF 디렉터리의 계층 구조와 페이지 번호는 사용 전에 반드시 확인해야 하므로, get_toc()의 원본 출력물을 직접적으로 신뢰할 수 있는 구조로 간주할 수 없습니다. 모호함이나 북마크 부족이 발생하면 즉시 수작업 작업으로 전환하거나 다른 방법으로 전환하여 후속 프로세스 오류를 피하세요.

지금 경험해보세요: 원본 형식을 유지하면서 번역을 시작하려면 문서를 업로드하세요

참고문헌 및 다음 단계

• PyMuPDF Document.get_toc 공식 문서

다음 단계는 알려진 디렉터리 문제를 담은 테스트 PDF를 준비하고, 위의 검증 스크립트를 실행하여 다양한 이상 현상의 비율을 계산하는 것입니다. 빈번한 계층적 건너뛰기나 페이지 번호 오프셋이 발생한다면, 번역 전에 목차 재구성 단계를 추가하는 것을 고려해 보세요.

문서 번역을 위해 이 체크리스트를 사용하세요

먼저 페이지 순서, 출처 위치, 텍스트 무결성을 꼼꼼히 확인한 후, 동일한 둔감화 샘플을 번역 과정에 제출하세요. 번역 후에도 제목, 본문, 캡션이 정확히 일치하는지 확인하는 것이 필요합니다; 텍스트의 부드러움만으로 판단하는 것만으로는 충분하지 않습니다.

OmniDoc는 다중 형식의 문서 번역 포털을 제공하며, 공식 웹사이트에서는 OCR, 용어집, 이중언어 참고 기능을 소개합니다. 파일을 직접 시작하고자 하는 팀에게는 실제 샘플을 활용해 평가할 가치가 있는 경로입니다. 업로드를 승인한 익명 파일을 사용해 이 기사의 체크리스트와 결과를 확인해 주시기 바랍니다. 이는 OmniDoc이 이 기사의 오픈소스 라이브러리나 내부 알고리즘을 사용한다는 주장도 아니며, 제품 성능 테스트를 예시로 대체하지도 않습니다.