PDFKit SVG: 평면화 없이 벡터 로고 배치하기

Node로 생성한 PDF에 완전한 SVG 로고를 배치하려면 PDFKit과 svg-to-pdfkit을 사용하고 SVG 마크업을 SVGtoPDF(doc, svg, x, y, options)에 전달하세요. PDFKit 기본 doc.path()는 경로의 d 속성 값 같은 SVG 경로 데이터를 받습니다. 주변 SVG 문서, 다른 도형이나 스타일은 가져오지 않습니다.

여러 색과 중앙 구멍이 있는 로고에서는 이 차이가 중요합니다. 경로 하나만 복사하면 그림 일부가 빠질 수 있습니다. 전체 로고를 PNG로 만들면 래스터 렌더링은 유지하지만 원했던 경로 기반 PDF 출력은 포기합니다.

이 가이드는 직접 만든 문양, 완전한 Node 스크립트와 저장 PDF 검사를 사용합니다. 편집 가능한 벡터 로고가 이미 있다면 소스로 유지하세요. 래스터 복원은 이 가져오기 단계 전에 합니다.

전체 SVG 삽입과 단일 경로 중 선택하기

PDFKit의 벡터 문서는 경로 파서와 관련 그리기 메서드를 설명합니다. 별도 SVG-to-PDFKit 라이브러리는 전체 SVG 마크업을 처리합니다.

PDFKit 이미지 문서는 doc.image()용 PNG와 JPEG를 나열합니다. 이 호출을 전체 SVG 가져오기 도구로 취급하지 마세요.

예를 들어 다음은 유효한 경로 API 사용입니다.

doc.save();
doc.fillColor('#eeaa42');
doc.path('M125 100L175 20L225 100Z').fill();
doc.restore();

문양의 삼각형을 경로 좌표에 그립니다. 소스 파일 다른 부분의 청록색 고리나 막대는 복원하지 않습니다. 조각들이 함께 있어야 하면 아래 전체 문서 방식을 쓰세요.

브라우저에서 jsPDF로 PDF를 구성한다면 별도 jsPDF SVG 작업 흐름을 따르세요. React 컴포넌트 문서는 React-pdf SVG 로고 작업 흐름을 사용하세요. Python 문서는 ReportLab 가져오기·크기 검사와 fpdf2 직접 SVG 배치를 비교하세요.

고정 패키지로 작은 예제 실행하기

PDFKit 0.20.2와 SVG-to-PDFKit 0.1.8로 예제를 실행했습니다. 테스트한 의존성 쌍이며 어느 패키지든 업그레이드하면 자신의 출력을 확인하세요.

새 Node 프로젝트에 설치하세요.

npm install --save-exact pdfkit@0.20.2 svg-to-pdfkit@0.1.8

다음을 logo.svg로 저장하세요. 고리와 구멍은 fill-rule="evenodd"인 경로 하나를 공유하고 금색 삼각형과 청록색 막대는 별도 도형입니다. 파일에는 글꼴, 이미지나 효과가 없습니다.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 120">
  <path fill="#147d78" fill-rule="evenodd"
    d="M110 60A50 50 0 1 1 10 60A50 50 0 1 1 110 60Z
       M85 60A25 25 0 1 1 35 60A25 25 0 1 1 85 60Z"/>
  <path fill="#eeaa42" d="M125 100L175 20L225 100Z"/>
  <rect x="227" y="20" width="8" height="80" fill="#147d78"/>
</svg>

같은 디렉터리에 다음을 place-logo.cjs로 저장하고 node place-logo.cjs를 실행하세요.

const fs = require('node:fs');
const { finished } = require('node:stream/promises');
const PDFDocument = require('pdfkit');
const SVGtoPDF = require('svg-to-pdfkit');
 
async function main() {
  const svg = fs.readFileSync('logo.svg', 'utf8');
  const doc = new PDFDocument({ size: [800, 450], margin: 0 });
  const output = fs.createWriteStream('logo.pdf');
  doc.pipe(output);
  const warnings = [];
  SVGtoPDF(doc, svg, 72, 150, {
    width: 180, height: 90,
    preserveAspectRatio: 'xMinYMin meet',
    warningCallback: message => warnings.push(message),
  });
  SVGtoPDF(doc, svg, 432, 150, {
    width: 90, height: 45,
    preserveAspectRatio: 'xMinYMin meet',
    warningCallback: message => warnings.push(message),
  });
  doc.end();
  await finished(output);
  fs.writeFileSync('warnings.json', JSON.stringify(warnings, null, 2));
  if (warnings.length) process.stderr.write(warnings.join('\n') + '\n');
}
main().catch(error => {
  process.stderr.write(error.stack + '\n');
  process.exitCode = 1;
});

PDFKit은 스트림을 만듭니다. doc.end()는 문서를 마무리하고 스크립트는 출력 스트림 완료를 기다린 뒤 반환합니다. 시작하기 문서는 스트림 모델과 인치당 72포인트인 PDF 포인트 페이지 크기를 설명합니다.

여기의 두 배치 뷰포트는 180 × 90 pt와 90 × 45 pt, 즉 2.5 × 1.25인치와 1.25 × 0.625인치입니다. 모두 원본 viewBox의 2:1 비율과 맞습니다. 도형에는 viewBox 내부 여백이 있어 보이는 경계가 뷰포트보다 작습니다. 주변 텍스트와 로고를 정렬할 때 캔버스와 칠해진 그림을 따로 측정하세요.

가져오기 도구는 width와 height를 초기 뷰포트로 설명합니다. preserveAspectRatio 옵션은 그 안의 맞춤을 제어합니다. 이 예제는 페이지 크기 기본값에 의존하지 않도록 일치하는 비율과 명시적 크기를 사용합니다. 예상보다 작은 로고에 assumePt를 일반 해결책으로 쓰지 말고 원본 크기, viewBox와 대상 뷰포트부터 확인하세요.

PDF를 검사하고 모양도 확인하기

최소 logo.pdf는 800 × 450 pt 페이지 하나였습니다. pypdf 6.10.0으로 3차 곡선 연산 24개, even-odd 채우기 연산 두 개, 페이지 이미지 0개를 찾았습니다. 페이지 리소스에 글꼴이나 XObject는 없었습니다. 이 예제에서 가져오기 도구는 경고를 내지 않았습니다.

이는 좁은 결론을 뒷받침합니다. 직접 만든 이미지 없는 문양이 테스트 버전에서 PDF 도형으로 그려졌습니다. 임의의 SVG가 완전히 벡터 PDF가 된다는 뜻은 아닙니다. 사진을 삽입한 로고는 별도 검사가 필요합니다.

Poppler로 레이블 버전도 렌더링했습니다. 같은 SVG와 두 뷰포트 크기를 사용하고 비교 패널에 배치를 옮겼습니다. 두 고리를 통해 옅은 패널 배경이 보이고 삼각형과 좁은 막대는 고리와 분리되어 있습니다.

선명한 확대만으로는 증거가 약합니다. 충분히 큰 비트맵도 선명할 수 있습니다. 반대로 보고서 어딘가의 곡선 연산은 로고의 래스터화 여부를 알려 주지 않습니다. 사진과 차트도 있는 문서 검사 전에 작은 테스트 PDF에서 그림을 분리하세요.

자신의 로고에서는 둘 다 확인하세요.

1. PDF 검사 도구로 페이지 콘텐츠와 참조 객체를 검사하세요. 로고가 칠해지는 곳의 그리기 명령을 찾고 이미지 객체도 확인하세요. 복잡한 PDF는 Form XObject 내부에 콘텐츠를 둘 수 있어 최상위 개수만으로 부족할 수 있습니다.
2. 실제 뷰어에서 저장 PDF를 열고 원본과 비교하세요. 실제 전달 크기에서 구멍, 별도 색상, 클리핑, 여백과 작은 세부를 확인하세요.

PDF 생성 코드 옆에 원본 SVG를 보관하세요. 소스가 픽셀을 감싸기만 한다면 SVG 확장자가 도형을 증명한다고 가정하기 전에 삽입 이미지 진단을 쓰세요.

테스트한 작업 흐름 안에서 글꼴·효과 처리하기

SVG-to-PDFKit은 지원하지 않는 기능에 필터와 foreignObject를 나열합니다. 글꼴 등록과 콜백 요구도 설명합니다. 서버에서 처리하는 작은 로고에는 명시적 SVG 표현 속성을 쓰고 렌더링 결과와 경고를 함께 검토하세요. 브라우저 계산 CSS는 제공된 SVG 요소에 쓰는 별도 옵션이며 이 Node 스크립트에 마크업을 전달하는 것과 같지 않습니다. 라이브러리의 기능·글꼴 문서를 참고하세요.

문양은 의도적으로 텍스트를 피합니다. 실제 글자는 의도한 글꼴을 제공해 테스트하거나 벡터 원본에 승인된 윤곽선 글자를 유지하세요. PDFKit의 글꼴 문서는 글꼴 삽입·등록을 설명합니다. 문서 텍스트와 로고 윤곽선은 편집 요구가 다릅니다. 글자 스크린샷을 추적해도 원래 글꼴을 알아내지 못합니다.

브랜드 표식이 이 가져오기 도구가 재현하지 못하는 효과에 의존하면 적합한 도형으로 재구성하거나 다른 내보내기 방식을 선택해 검증하세요. 경로 유지보다 모양이 중요하면 래스터 삽입도 유효한 선택입니다. 그 선택을 벡터 보존 내보내기라고 설명하지 마세요.

예제는 RGB 색상을 씁니다. 경로 유지만으로 인쇄 업체의 색상, PDF/X나 인쇄 전 요구를 충족했다고 할 수 없습니다. 수신자와 확인하세요. 로고 형식 가이드는 편집 원본과 전달 파일을 구분하는 데 도움이 됩니다.

삽입 전에 래스터 로고 복원하기

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

벡터 원본이 있으면 항상 사용하세요. 손상된 글자나 정확한 브랜드 도형은 편집기에서 해당 부분을 재입력하거나 다시 그리세요. 로고 벡터화 가이드는 소스 결정을 설명합니다. PerfectVector는 그림 경로를 준비하고 PDFKit과 가져오기 도구는 문서 배치를 처리합니다. 테스트 문양은 수동 작성 벡터이며 측정 변환 결과가 아닙니다.

FAQ

PDFKit이 doc.path()로 전체 SVG를 가져올 수 있나요? 아닙니다. path 메서드는 SVG 경로 데이터를 읽습니다. 이 작업에서 전체 문서에는 SVG-to-PDFKit을 쓰거나 각 도형을 직접 그리고 스타일을 지정하세요.

SVG-to-PDFKit이 래스터 이미지 없는 PDF를 보장하나요? 아닙니다. 테스트한 이미지 없는 문양은 그리기 연산과 페이지 이미지 0개를 만들었습니다. 특히 삽입 이미지나 가져오기 지원 밖 기능이 있으면 자신의 입력과 내보낸 PDF를 검사하세요.

보이는 로고가 지정한 너비·높이보다 작은 이유는 무엇인가요? 옵션은 가져오기 뷰포트를 정의합니다. 원본 viewBox 안의 여백도 레이아웃에 남고 비율 맞춤이 추가 공간을 만들 수 있습니다. 요청 PDF 크기를 바꾸기 전에 그림 경계를 확인하세요.

Sources

1. PDFKit — 벡터 그래픽 — SVG 경로 파싱, 페인트 연산과 그래픽 상태를 설명합니다.
2. SVG-to-PDFKit — 사용과 제한 — 전체 SVG 삽입, 뷰포트 옵션, 경고, 글꼴과 지원 기능을 정의합니다.
3. PDFKit — 이미지 — 이미지 API가 받는 비트맵 형식을 나열합니다.
4. PDFKit — 시작하기 — 문서 스트림, 마무리와 PDF 포인트 페이지 크기를 설명합니다.
5. PDFKit — 글꼴 — 글꼴 삽입과 이름별 등록을 설명합니다.

문서 로고가 래스터로 시작하면 PerfectVector로 SVG 후보를 준비하고 구멍·윤곽선을 확인하세요. 필요한 PDF 크기에 배치하고 저장 파일을 검사하세요.