렌더링 파이프라인
문서에서 페이지 이미지까지
OpenDocumentAsync와 브라우저에 도달하는 PNG 사이에는 두 개의 뚜렷한 단계가 있습니다: viewer resolution(문서를 로드하는 엔진, 열 때 한 번 결정)과 page processing(각 요청마다 각 페이지 이미지에 대해 발생하는 일). 두 단계를 모두 알면 형식이 렌더링되는 이유와 DefaultRender가 실제로 전환하는 것이 무엇인지 설명됩니다.
단계 1 — 포맷 뷰어 해결
팩토리는 파일 확장자를 포맷 카탈로그를 통해 뷰어에 매핑하며, 세 가지 우선순위 레벨이 있습니다:
- 맞춤 뷰어 우선.
DoconutOptions.RegisterViewer(extension, factory, defaultConfig?)에 등록한 모든 항목이 내장 뷰어보다 우선합니다. - 내장 패밀리 뷰어. 카탈로그는 각 보기 가능한 확장자를 뷰어 패밀리(Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn)와 매핑하고, 각각 고유한 엔진 어댑터를 가집니다. 동일한 확장자에 대해 라이선스된 플러그인이 뷰어를 제공하면, 플러그인 뷰어가 내장 뷰어를 대체합니다.
AddDoconut()는 시작 시 등록된 플러그인 권한을 검증하며, 팩토리가 내장 뷰어로 폴백하는 것은 방어적인 런타임 규칙입니다. - 플러그인 전용 포맷. 일부 확장자는 내장 뷰어가 전혀 없으며 — DICOM (
.dcm)은 DICOM 플러그인을 통해서만 존재합니다. 필요한 기능 없이 열면 다음과 같은 예외가 발생합니다:
LicenseException: This document type requires the 'Dicom' plugin license.뷰어가 전혀 없는 확장자를 선언하면 다음과 같은 예외가 발생합니다:
FormatNotSupportedException: Document format '<extension>' is not supported.해결 후, 구성은 확정됩니다: 전달한 경우 명시적인 구성 객체, 그렇지 않으면 카탈로그에서 가져온 포맷의 기본 구성. 보호된 문서의 경우 DocOptions.Password가 구성에 복사됩니다.
단계 1b — 리다이렉트 모드 (DefaultRender = false)
대부분의 포맷별 구성은 DefaultRender 플래그를 노출합니다. 이 플래그는 두 가지 근본적으로 다른 경로 중 하나를 선택합니다:
DefaultRender = true— 문서는 네이티브하게 렌더링되어 바로 페이지 이미지로 출력됩니다.DefaultRender = false— 문서는 먼저 메모리 내에서 PDF로 변환되고, 원본 엔진은 해제되며 PDF 뷰어가 인계받습니다. 생성된 PDF는 실제 텍스트를 포함하므로 전체 텍스트 검색이 픽셀 정확도의 네이티브 하이라이트를 얻습니다; 변환이 사용자에게 보이지 않기 때문에 파이프라인은 리다이렉트된 PDF에 대해AllowSearch와AllowCopy를 강제로 활성화합니다.
XPS와 카탈로그의 기본값인 MHT는 리다이렉트 경로를 사용합니다. PDF 프로젝션은 HTML 및 Microsoft Project와 같은 포맷에 대해 네이티브 검색을 제공할 수 있습니다. 결과 PDF에 텍스트 레이어가 없는 이미지가 포함된 경우, 표준 뷰어는 해당 픽셀을 검색할 수 없습니다.
문서를 열 때 사전 변환 비용이 발생하지만 텍스트가 포함된 PDF 프로젝션이 필요할 경우 리다이렉트 모드를 사용하십시오.
단계 2 — 페이지-이미지 파이프라인
렌더링된 페이지는 고정된 순서를 통해 요청당 처리됩니다:
raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response- 워터마크 — 라이선스 상태(라이선스 누락, 임시 또는 구독 만료, 도메인 불일치, 버전 오류)와
DocOptions.Watermark를 통해 지정한 사용자 정의 텍스트가 적용됩니다. 적절히 라이선스된 앱—또는 활성 임시 라이선스—에 사용자 정의 워터마크가 없으면 이 단계가 건너뛰어집니다. - 회전/플립 — 사용자가 위젯에서 설정한 페이지별 상태(90°/180°/270°, 가로/세로 플립)는 세션에 저장되고 해당 페이지가 이후 렌더링될 때마다 적용됩니다.
- 스케일 — 썸네일 및 줌 레벨은 렌더링된 페이지를 요청된 목표 크기로 스케일링하여 생성됩니다;
0는 원본 크기로 제공한다는 의미입니다. - 주석 합성 — 저장된 주석이 비트맵에 그려져 내보내기 및 페이지 이미지에 표시됩니다.
- 인코딩 — 결과는 풀링된 메모리 스트림을 사용해 PNG로 인코딩되고 HTTP 응답에 직접 기록됩니다.
미들웨어 내부 오류는 HTTP 오류 페이지 대신 PNG 오류 이미지(흰 배경에 빨간 텍스트)로 반환되어 위젯이 페이지 영역에 표시할 수 있습니다.
페이지 캐싱
BaseConfig.CachePages(기본값 true)은 문서 세션 기간 동안 렌더링된 페이지 이미지를 메모리에 유지하여 페이지를 다시 방문해도 재렌더링되지 않게 합니다. BaseConfig.ImageResolution(25–300 DPI, 0 = 포맷 기본값)는 주요 품질/메모리 조정 옵션이며, 각 포맷의 기본값은 해당 구성 페이지에 문서화되어 있습니다.
단일 노드와 다중 노드 렌더링
위 내용은 문서를 연 세션에 대해 필요 시 단일 노드가 렌더링하는 방식을 설명합니다. 하나의 노드가 전체 아티팩트 세트를 렌더링하고 배포하며, 다른 노드가 공유 스토리지에서 해당 페이지를 제공하는 배포는 다른 읽기 경로를 사용합니다 — 분산 배포를 참고하십시오.
Linux에서의 폰트
페이지는 서버에 설치된 폰트로 그려집니다. Linux에서는 첫 문서를 열기 전에 폰트 구성 라이브러리를 설치해야 합니다(fontconfig on RHEL and Fedora):
apt-get update && apt-get install -y libfontconfig1이 라이브러리가 없으면 문서를 열 때 The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. 오류가 발생합니다. 이것은 Doconut이 필요로 하는 유일한 시스템 패키지이며, libgdiplus는 필요하지 않습니다.
그 의존성은 기본 폰트 세트(DejaVu)를 제공하므로 문서는 바로 렌더링됩니다. 서버에 없는 폰트를 요구하는 문서—예를 들어 일반 Linux 이미지에 없는 Calibri, Arial, Times New Roman—는 가장 가까운 설치된 폰트로 대체되며, 이로 인해 텍스트 너비와 줄 바꿈이 Windows와 다를 수 있습니다. Windows에 더 가깝게 출력하려면 메트릭 호환 대체 폰트인 fonts-liberation, fonts-crosextra-carlito, fonts-crosextra-caladea를 설치하십시오; 다른 스크립트를 위해 fonts-noto-core 또는 fonts-noto-cjk를 추가하거나, 자체 .ttf/.otf 파일을 /usr/share/fonts/에 복사하고 fc-cache -f를 실행하십시오.
Alpine 및 기타 musl 기반 배포판은 지원되지 않습니다.
무엇을 조정할지
| 원하는 항목 | 조정 방법 |
|---|---|
| 페이지를 더 선명하게 | 포맷 구성에서 ImageResolution |
| HTML/EPUB/이메일/MHT/MPP에서 정확한 텍스트 검색 | 포맷 구성에서 DefaultRender = false |
| 대용량 문서에서 메모리 사용량 감소 | CachePages = false, 세션을 명시적으로 종료 |
| 각 페이지에 자체 스탬프 추가 | DocOptions.Watermark |
이 페이지가 도움이 되었나요?