fpdf2 SVG 이미지: Python PDF에 경로 유지하기

pdf.image("logo.svg", x=20, y=20, w=60)으로 fpdf2 문서에 SVG를 배치하세요. 지원되는 SVG 도형은 PDF 그리기 경로가 됩니다. 먼저 로고를 PNG로 렌더링할 필요는 없습니다. 공식 SVG 문서는 이 직접 처리 방식과 한계를 설명합니다.

형식 자체가 낯설다면 SVG 파일 가이드가 경로와 이미지 컨테이너를 설명합니다. 가져오기에 성공해도 확인이 필요합니다. 파일에 픽셀이 삽입되어 있거나 가져오기 도구가 재현하지 못하는 기능에 의존하거나 그림 주변에 여백이 있을 수 있습니다. 이 가이드는 직접 만든 작은 로고를 명시적 크기로 배치하고 결과 PDF를 검사합니다. 기존 벡터 원본이 있다면 유지하세요. PNG나 JPG에서 그림을 복원하는 것은 별도의 앞 단계입니다.

알려진 SVG와 고정된 fpdf2 버전으로 시작하기

Python 3.12와 fpdf2 2.8.8로 예제를 실행했습니다. 이는 테스트한 버전이며 모든 이후 릴리스가 똑같이 동작한다는 보장은 아닙니다. 패키지의 공식 PyPI 페이지는 fpdf2 배포 이름으로 설치한다고 설명하며 Python import는 fpdf입니다.

다른 프로젝트 패키지와 독립적인 예제가 되도록 새 환경을 사용하세요.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "fpdf2==2.8.8"

Windows에서는 대신 .venv\Scripts\activate로 환경을 활성화하세요. 이 직접 만든 직사각형 문양을 logo.svg로 저장하세요.

<svg xmlns="http://www.w3.org/2000/svg"
     width="120" height="80" viewBox="0 0 120 80">
  <path fill="#137d89" fill-rule="evenodd"
        d="M10 10H110V70H10Z M30 25H90V55H30Z"/>
</svg>

닫힌 하위 경로가 두 개 있습니다. 바깥 사각형은 채워지고 안쪽 사각형은 evenodd 채우기 규칙으로 구멍이 됩니다. 글꼴, 이미지나 효과가 없어 첫 테스트를 진단하기 쉽습니다.

다음을 SVG 옆에 place_logo.py로 저장하세요.

from pathlib import Path
from fpdf import FPDF
 
folder = Path(__file__).resolve().parent
pdf = FPDF(unit="mm")
pdf.add_page()
pdf.image(str(folder / "logo.svg"), x=20, y=20, w=60)
pdf.output(str(folder / "logo.pdf"))

python place_logo.py를 실행하세요. logo.pdf를 열고 왼쪽 위 가까이에 중앙으로 페이지가 비치는 청록색 직사각형 프레임이 있는지 확인하세요.

SVG 캔버스와 칠해진 로고 구분하기

원본 캔버스는 너비 120단위, 높이 80단위의 3:2 비율입니다. w=60에서 이 예제는 60 × 40 mm 캔버스를 차지합니다. 그림은 원본 좌표 기준으로 캔버스 가장자리에서 10단위 안쪽에 시작하므로 칠해진 바깥 사각형은 50 × 30 mm이며 페이지의 25, 25 mm에서 시작합니다. 이 예제의 좌표와 배율로 계산한 값입니다.

이 여백 때문에 색칠된 모양의 측정값과 배치 캔버스의 측정값이 다릅니다. 고객 로고가 너무 작아 보이면 PDF 너비를 늘리기 전에 원본 여백을 확인하세요.

fpdf2 이미지 가이드는 크기 처리와 지정한 상자 안에서 비율을 유지하는 옵션을 설명합니다. 첫 예제에서는 너비만 설정하세요. 나중에 두 크기를 모두 지정한다면 모든 원본이 같은 비율이라고 가정하지 말고 원하는 맞춤을 의도적으로 테스트하세요.

저장된 PDF에 경로가 있는지 검증하기

PDF 미리보기는 모양을 보여 주지만 이미지도 적당한 확대에서는 선명할 수 있습니다. 파일도 검사하세요. pypdf 6.1.1로 독립 예제를 검사했습니다.

python -m pip install "pypdf==6.1.1"

from pathlib import Path
from pypdf import PdfReader
 
folder = Path(__file__).resolve().parent
page = PdfReader(folder / "logo.pdf").pages[0]
print("Page images:", len(page.images))
print(page.get_contents().get_data().decode("latin-1"))

출력은 페이지 이미지 0개를 보고했습니다. 디코딩한 콘텐츠에는 이동, 직선, 경로 닫기 연산으로 표현한 사각형 윤곽선과 그 뒤의 even-odd 채우기 연산 f*가 있었습니다. 렌더링된 구멍과 함께 보면 이 이미지 없는 예제가 저장된 PDF에서도 그리기 도형으로 유지됐다는 결론을 뒷받침합니다.

확인하지 않고 다른 입력에 이 결론을 적용하지 마세요. 보고서의 다른 곳에는 사진이 있어도 되고 SVG 자체에도 이미지가 있을 수 있습니다. 삽입 래스터 진단은 경로 로고와 SVG 마크업으로 감싼 비트맵을 구분하는 데 도움이 됩니다. 더 복잡한 PDF는 참조 객체 안에 그리기 콘텐츠를 둘 수도 있으므로 위 짧은 스크립트는 독립 예제의 시작점이며 범용 PDF 감사 도구가 아닙니다.

설치한 릴리스로 누락된 그림 진단하기

먼저 위 작은 문양을 실행하세요. 예제는 작동하지만 운영 로고는 실패한다면 원본 그림이나 사용하는 기능으로 문제를 좁힌 것입니다. 원본을 보관하고 사본에서 기능 하나씩 단순화하세요.

여기서는 오래된 답변에 주의해야 합니다. 간단한 <text> 요소가 있는 별도 2.8.8 테스트는 추출 가능한 HELLO 텍스트를 만들었고, 기본 선형 그라디언트 사각형도 성공적으로 내보냈습니다. 이 좁은 검사가 SVG 텍스트, 글꼴, CSS나 그라디언트의 완전한 호환성을 입증하지는 않습니다. 다만 모든 SVG 텍스트나 모든 그라디언트가 지원되지 않는다는 오래된 설명이 불필요한 래스터화를 유도할 수 있음을 보여 줍니다.

현재 SVG 기능 목록에도 마커, 패턴, 경로 위 텍스트와 복잡한 또는 외부 CSS 같은 제한이 있습니다. 진단할 때 가져오기 경고를 보이게 유지하고 저장한 페이지를 원본과 비교하세요. 깨끗한 로그만으로 모든 시각 기능이 유지됐다는 증거가 되지는 않습니다.

결과에 맞게 래스터 대안 사용하기

선택한 처리 과정에서 효과를 재현할 수 없다면 모양 유지가 도형 유지보다 중요한지 결정하세요. 해당 문서 부분에는 렌더링한 PNG가 적합할 수 있습니다. 최종 실제 크기에서 확인하고 출력을 정확히 표시하세요. 래스터 렌더링을 삽입해도 원래 경로는 보존되지 않습니다.

브랜드 로고에는 승인된 윤곽선 글자나 더 단순한 벡터 내보내기가 더 나을 수 있습니다. 편집 가능한 문서 텍스트는 문서 작업 흐름에서 글꼴과 텍스트를 처리하세요. 문장 스크린샷을 추적해도 타이포그래피가 복원되거나 선택 가능한 텍스트가 되지는 않습니다.

기존 PDF 코드가 다른 Python 라이브러리를 쓴다면 ReportLab SVG 작업 흐름에는 고유한 가져오기·크기 검사가 있습니다. 라이브러리 전환은 별도의 구현 결정이므로 문서를 다시 만들기 전에 실제 문제 기능을 테스트하세요.

PDF 단계 전에 래스터 원본 그림 준비하기

PNG나 JPG 로고만 남았다면 PerfectVector의 로고 벡터화 도구로 fpdf2 가져오기 전 SVG 후보를 준비할 수 있습니다. 윤곽선, 작은 구멍과 색상 영역을 원본과 비교한 뒤 후보에 같은 배치·PDF 검사를 수행하세요.

벡터 원본이 있으면 사용하세요. 정확한 브랜드 글자는 재입력이나 수동 수정이 필요할 수 있습니다. 로고 벡터화 가이드가 그 선택을 설명합니다. 이 글의 문양은 직접 작성한 SVG이며 측정한 PerfectVector 변환 결과가 아닙니다. PerfectVector는 그림을 준비하고 fpdf2는 PDF 배치를 제어합니다.

FAQ

fpdf2가 SVG를 직접 삽입할 수 있나요? 네. image 메서드에 SVG 파일을 전달하고 위치와 크기를 설정하세요. 지원 도형은 PDF 경로가 될 수 있지만 자신의 그림에서는 내보낸 파일과 모양을 확인하세요.

fpdf2는 SVG 텍스트를 지원하나요? 기본 텍스트 테스트는 fpdf2 2.8.8에서 작동했습니다. 모든 글꼴, 레이아웃 기능이나 경로 위 텍스트를 보장하지는 않습니다. 설치 릴리스를 확인하고 실제 문서에서 쓰는 글자를 테스트하세요.

60 mm 이미지가 60 mm보다 좁아 보이는 이유는 무엇인가요? 요청한 크기는 배치 캔버스에 적용됩니다. SVG 내부 여백도 캔버스에 포함되므로 칠해진 모양은 더 좁을 수 있습니다.

PNG 로고를 추가하기 전에 SVG로 변환해야 하나요? 편집 가능한 경로가 필요하고 그림이 추적에 적합한 경우에만 하세요. 사진은 래스터로 유지하고 원본 벡터 로고가 있으면 사용하세요. 추적 후보를 확인한 뒤 삽입하세요.

Sources

1. fpdf2 — SVG — 직접 SVG 삽입, 기능 지원과 경고 로그를 설명합니다.
2. fpdf2 — 이미지 — 이미지 배치, 크기와 가로세로 비율 맞춤을 설명합니다.
3. fpdf2 — PyPI 패키지 — 설치 가능한 배포 이름과 Python import 규칙을 설명합니다.

래스터 로고만 있나요? PerfectVector로 SVG 후보를 준비하고 윤곽선과 구멍을 확인하세요. fpdf2로 필요한 크기에 배치한 뒤 저장된 PDF를 검사하세요.