CairoSVG: Ekspor SVG ke PDF dan PNG pada Ukuran Tepat

Gunakan cairosvg.svg2png() untuk ekspor raster dan cairosvg.svg2pdf() untuk PDF. Untuk lebar PNG tertentu, tetapkan output_width; untuk pembesaran proporsional, gunakan scale. parent_width menyediakan wadah yang dipakai untuk menghitung dimensi berdasarkan persentase. dpi mengendalikan hubungan piksel dan satuan fisik, sehingga mengubahnya dapat memengaruhi ukuran PNG dan PDF secara berbeda.

Contoh di bawah dimulai dengan lambang SVG kecil dan memeriksa file yang dihasilkan setiap pengaturan. Contoh sesuai bagi desainer yang mengotomatiskan ekspor logo dan pengembang yang menyiapkan karya untuk dokumen. CairoSVG merender konten SVG yang ada. CairoSVG tidak men-trace logo PNG menjadi path yang bisa diedit.

Mulai dengan SVG mandiri

Kami menjalankan contoh ini dengan Python 3.12.11 dan CairoSVG 2.9.1. Instal konverter dengan versi tetap dalam lingkungan proyek:

python -m pip install "CairoSVG==2.9.1"

CairoSVG juga memerlukan pustaka Cairo native. Jika instalasi atau impor gagal, ikuti catatan sistem operasi dalam dokumentasi instalasinya.

Simpan lambang asli tiga path ini sebagai emblem.svg. Bukaan persegi membuat aturan isian yang hilang mudah diperhatikan, dan bilah sempit menyediakan titik pemeriksaan detail kecil. Ini karya demonstrasi buatan tangan, bukan konversi PerfectVector.

<svg xmlns="http://www.w3.org/2000/svg"
     width="240" height="120" viewBox="0 0 240 120">
  <path fill="#176b63" fill-rule="evenodd"
        d="M20 100 V20 H100 V100 Z M40 40 V80 H80 V40 Z"/>
  <path fill="#e5a43a" d="M110 100 L160 20 L210 100 Z"/>
  <path fill="#24435d" d="M220 20 H230 V100 H220 Z"/>
</svg>

Dimensi akar menjelaskan viewport keluaran. viewBox menjelaskan persegi panjang koordinat internal karya. Di sini keduanya memiliki rasio 2:1 yang sama. Pertahankan hubungan itu secara sengaja ketika mengadaptasi contoh untuk logo Anda.

Ekspor satu master pada ukuran yang diperlukan

Simpan sebagai export_emblem.py di samping SVG, lalu jalankan python export_emblem.py:

import cairosvg
 
cairosvg.svg2png(
    url="emblem.svg",
    write_to="emblem-480.png",
    output_width=480,
)
cairosvg.svg2pdf(
    url="emblem.svg",
    write_to="emblem.pdf",
)

PNG kami berukuran 480 × 240 piksel. Halaman PDF berukuran 180 × 90 point, setara dengan 2.5 × 1.25 inci. Ini adalah pengukuran dari contoh yang disediakan, bukan dimensi yang harus diharapkan dari setiap SVG.

Padanan command line-nya:

cairosvg emblem.svg --output-width 480 -o emblem-480.png
cairosvg emblem.svg -o emblem.pdf

Referensi API dan command line CairoSVG mendokumentasikan nama file masukan melalui url, byte SVG melalui bytestring, dan keluaran file melalui write_to. Dalam CLI, ekstensi nama file keluaran memilih format.

Pilih kontrol yang sesuai masalah

Opsi yang namanya mirip menjawab pertanyaan berbeda. Referensi ukuran CairoSVG memisahkan wadah induk dari dimensi keluaran yang diminta.

Untuk sumber berukuran piksel kami, setiap opsi dijalankan secara independen:

Baris terakhir adalah jebakannya: menggandakan DPI tidak memberikan lebih banyak piksel PNG untuk SVG berukuran piksel ini. Itu membuat dimensi piksel yang sama menempati ruang fisik lebih kecil dalam PDF. Gunakan dimensi keluaran ketika kebutuhan penyerahan Anda berupa jumlah piksel.

Memberikan kedua dimensi keluaran menetapkan persegi panjang kanvas; tidak menjamin kotak logo terisi rapat. Aturan rasio aspek SVG dan area kosong di dalam viewBox tetap berpengaruh. Mulai dengan satu dimensi keluaran ketika ingin proporsi asli, lalu periksa hasil.

Dimensi persentase membutuhkan induk

Untuk salinan contoh yang akarnya memakai width="50%" height="50%", pemanggilan ini menyediakan induk 960 × 480 piksel:

cairosvg.svg2png(
    url="emblem-percent.svg",
    parent_width=960,
    parent_height=480,
    write_to="emblem-percent.png",
)

Keluaran kami 480 × 240 piksel: setengah lebar induk dan setengah tingginya. Ini menjelaskan mengapa parent_width=480 tidak dapat dipertukarkan dengan output_width=480.

Jika CairoSVG melaporkan ukuran SVG tidak terdefinisi, periksa dimensi akar terlebih dahulu. Berikan dimensi positif yang sesuai penggunaannya, atau sediakan dimensi induk ketika persentase bergantung padanya. Jangan menyimpulkan ukuran halaman yang dimaksud dari seberapa besar browser kebetulan menampilkan karya.

Dimensi fisik berperilaku berbeda

Ubah akar asli menjadi width="2.5in" height="1.25in", sambil mempertahankan viewBox. Dalam pengujian kami, dpi=96 menghasilkan PNG 240 × 120 dan dpi=192 menghasilkan PNG 480 × 240. Kedua PDF tetap 180 × 90 point.

Di sini sumber mendefinisikan ukuran fisik, sehingga lebih banyak piksel per inci menaikkan resolusi raster sambil mempertahankan ukuran halaman fisik PDF. Prinsip yang sama memungkinkan halaman yang dibuat sengaja memakai milimeter atau inci. Periksa kotak halaman PDF ekspor alih-alih menganggap jumlah piksel besar berarti halaman A4 atau letter.

Jika logo harus berada dalam laporan dengan teks, margin, dan beberapa elemen, gunakan tahap tata letak dokumen. Panduan penempatan SVG ReportLab kami membahas pembuatan PDF langsung; pemeriksaan sumber daya dan ukuran WeasyPrint membahas dokumen HTML.

Verifikasi ekspor, termasuk bagian yang tetap vektor

Kami membaca header PNG dengan Pillow serta kotak halaman dan stream konten PDF dengan pypdf 6.10.0. Keempat PDF dari sumber piksel berisi operasi menggambar path dan nol image pada halaman. Itu mengonfirmasi geometri vektor untuk contoh sederhana tanpa image ini. Hasil tidak membuktikan kesetiaan penuh untuk sembarang SVG.

Untuk memeriksa dimensi keluaran sendiri, instal pillow dan pypdf dalam lingkungan yang sama dan jalankan:

from PIL import Image
from pypdf import PdfReader
 
with Image.open("emblem-480.png") as image:
    print("PNG pixels:", image.size)
 
page = PdfReader("emblem.pdf").pages[0]
print("PDF points:", float(page.mediabox.width),
      float(page.mediabox.height))
print("Page images:", len(page.images))

Referensi PageObject menjelaskan mediabox dan images. Jumlah image adalah diagnostik berguna, tetapi tidak dapat membuktikan setiap bentuk, font, atau efek bertahan dengan benar.

Sebelum penyerahan:

1. Buka PNG dan PDF lalu bandingkan lambang dengan SVG. Periksa bukaan, segitiga, bilah, dan margin.
2. Verifikasi dimensi piksel PNG dan dimensi fisik PDF secara independen.
3. Periksa karya pada ukuran penggunaan yang dimaksud, termasuk celah sempit dan detail kecil.
4. Simpan SVG asli dan ulangi pemeriksaan setelah mengubahnya atau meningkatkan versi konverter.

Halaman dukungan SVG CairoSVG menyatakan keluaran vektor dipertahankan jika memungkinkan. Gambar raster tertanam tetap berupa konten raster. Jika file Anda berisi PNG dalam pembungkus SVG, diagnosis image tertanam membantu mengidentifikasinya sebelum ekspor.

CairoSVG adalah renderer statis. Animasi, scripting, tata letak teks lanjutan, dan banyak filter berada di luar alur yang didukung. Dokumentasinya mencantumkan hanya feOffset, feBlend, dan feFlood sebagai filter yang didukung. Untuk karya yang bergantung pada efek lain, bandingkan hasil dengan hati-hati atau ekspor melalui aplikasi yang mendukung fitur itu. Pemanggilan konversi yang berhasil saja tidak cukup.

Rekonstruksikan master vektor hanya ketika sumber memerlukannya

Jika logo Anda hanya tersisa sebagai PNG atau JPG, PerfectVector dapat menyediakan tahap raster ke SVG sebelum CairoSVG mengekspornya. Periksa bentuk, bukaan kecil, dan tulisan merek hasil rekonstruksi dalam editor; lalu simpan master SVG mandiri. Alur vektorisasi logo kami menjelaskan pemeriksaan itu.

SVG yang sudah bisa diedit dapat langsung masuk tahap ekspor. Mengonversinya ke PNG dan men-trace ulang akan membuang geometri sumber yang berguna. Foto dapat tetap sebagai gambar raster ketika itulah konten yang dimaksud.

Untuk logo yang hanya raster, coba gambar Anda sendiri dalam PerfectVector, periksa kontur dan bukaan SVG, lalu verifikasi dimensi piksel maupun ukuran halaman fisik ekspor CairoSVG Anda.

FAQ

Mengapa perubahan DPI tidak mengubah ukuran PNG saya? Jika akar SVG memakai dimensi piksel, mengubah DPI belum tentu mengubah jumlah piksel PNG. Dalam contoh ini, SVG 240 kali 120 piksel tetap pada ukuran itu di 192 DPI. Gunakan output_width atau scale ketika memerlukan lebih banyak piksel keluaran.

Apakah parent width sama dengan output width? Tidak. parent_width menyediakan wadah yang dipakai untuk menghitung dimensi berdasarkan persentase. output_width meminta lebar keluaran akhir. Lebar akar 50% dengan parent_width 960 dihitung menjadi 480 piksel dalam contoh.

Apakah CairoSVG selalu membuat PDF yang seluruhnya vektor? Tidak. CairoSVG mempertahankan keluaran vektor jika memungkinkan, tetapi SVG dapat menyertakan gambar raster dan fitur yang tidak didukung. Periksa isi serta tampilan PDF alih-alih memperlakukan ekstensi file sebagai bukti.

Sources

1. Dokumentasi CairoSVG — Menjelaskan instalasi, API konversi, kontrol ukuran, dan batasan rendering.
2. Dukungan SVG 1.1 CairoSVG — Menjelaskan pemeliharaan vektor, image tertanam, dan fitur yang tidak didukung.
3. Referensi PageObject pypdf — Mendokumentasikan antarmuka kotak halaman dan image yang dipakai untuk memeriksa PDF.