CairoSVG: Xuất SVG sang PDF và PNG đúng kích thước

Dùng cairosvg.svg2png() để xuất raster và cairosvg.svg2pdf() để tạo PDF. Với chiều rộng PNG cụ thể, đặt output_width; để phóng to theo tỷ lệ, dùng scale. parent_width cung cấp vùng chứa dùng để tính kích thước phần trăm. dpi điều khiển quan hệ giữa pixel và đơn vị vật lý, nên thay đổi nó có thể tác động khác nhau đến kích thước PNG và PDF.

Ví dụ dưới đây bắt đầu với biểu tượng SVG nhỏ và kiểm tra tệp được tạo bởi từng thiết lập. Nó phù hợp với nhà thiết kế tự động hóa xuất logo và lập trình viên chuẩn bị hình cho tài liệu. CairoSVG kết xuất nội dung SVG hiện có. Nó không đồ lại logo PNG thành đường dẫn chỉnh sửa được.

Bắt đầu với SVG tự chứa

Chúng tôi chạy các ví dụ này bằng Python 3.12.11 và CairoSVG 2.9.1. Cài công cụ chuyển đổi với phiên bản cố định trong môi trường dự án:

python -m pip install "CairoSVG==2.9.1"

CairoSVG cũng cần thư viện Cairo của hệ thống. Nếu cài đặt hoặc nhập thư viện thất bại, làm theo ghi chú hệ điều hành trong tài liệu cài đặt.

Lưu biểu tượng gốc ba đường dẫn này thành emblem.svg. Lỗ vuông giúp dễ nhận ra quy tắc tô màu bị thiếu, và thanh hẹp cung cấp điểm kiểm tra chi tiết nhỏ. Đây là hình minh họa viết thủ công, không phải chuyển đổi 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>

Kích thước phần tử gốc mô tả khung nhìn đầu ra. viewBox mô tả hình chữ nhật tọa độ bên trong của hình. Ở đây cả hai có cùng tỷ lệ 2:1. Giữ quan hệ đó có chủ đích khi điều chỉnh ví dụ cho logo của bạn.

Xuất một bản gốc theo kích thước cần thiết

Lưu đoạn này thành export_emblem.py cạnh SVG rồi chạy 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 của chúng tôi có kích thước 480 × 240 pixel. Trang PDF là 180 × 90 point, tương đương 2.5 × 1.25 inch. Đây là số đo từ mẫu được cung cấp, không phải kích thước mong đợi từ mọi SVG.

Các lệnh dòng lệnh tương đương là:

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

Tài liệu API và dòng lệnh của CairoSVG mô tả tên tệp đầu vào qua url, dữ liệu byte SVG qua bytestring và đầu ra tệp qua write_to. Trong CLI, phần mở rộng tên tệp đầu ra chọn định dạng.

Chọn tùy chọn phù hợp vấn đề

Các tùy chọn có tên tương tự trả lời những câu hỏi khác nhau. Tài liệu kích thước CairoSVG phân biệt vùng chứa cha với kích thước đầu ra được yêu cầu.

Với nguồn định kích thước bằng pixel, chúng tôi chạy từng tùy chọn độc lập:

Hàng cuối là điểm dễ nhầm: tăng gấp đôi DPI không cho SVG định kích thước pixel này thêm pixel PNG. Nó làm cùng kích thước pixel chiếm không gian vật lý nhỏ hơn trong PDF. Dùng kích thước đầu ra khi yêu cầu bàn giao là số pixel.

Cung cấp cả hai kích thước đầu ra đặt hình chữ nhật khung vẽ; không bảo đảm logo lấp đầy khung sát mép. Quy tắc tỷ lệ khung hình SVG và khoảng trống bên trong viewBox vẫn quan trọng. Bắt đầu với một chiều đầu ra khi muốn tỷ lệ gốc, rồi kiểm tra kết quả.

Kích thước phần trăm cần vùng chứa cha

Với bản sao mẫu có phần tử gốc dùng width="50%" height="50%", lệnh này cung cấp vùng chứa cha 960 × 480 pixel:

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

Đầu ra của chúng tôi là 480 × 240 pixel: một nửa chiều rộng cha và một nửa chiều cao. Điều này giải thích vì sao parent_width=480 không thể dùng thay output_width=480.

Nếu CairoSVG báo kích thước SVG chưa xác định, kiểm tra kích thước gốc trước. Đặt kích thước dương phù hợp cách dùng cho tài liệu, hoặc cung cấp kích thước cha khi phần trăm phụ thuộc chúng. Đừng suy ra kích thước trang dự định từ việc trình duyệt tình cờ hiển thị hình lớn đến đâu.

Kích thước vật lý hoạt động khác

Đổi phần tử gốc ban đầu thành width="2.5in" height="1.25in", giữ nguyên viewBox. Trong phép thử của chúng tôi, dpi=96 tạo PNG 240 × 120 và dpi=192 tạo PNG 480 × 240. Cả hai PDF vẫn là 180 × 90 point.

Ở đây nguồn xác định kích thước vật lý, nên nhiều pixel mỗi inch hơn tăng độ phân giải raster và giữ kích thước trang PDF vật lý. Cùng nguyên tắc cho phép trang được tạo có chủ đích dùng milimét hoặc inch. Kiểm tra khung trang PDF xuất ra thay vì cho rằng số pixel lớn đồng nghĩa trang A4 hay letter.

Nếu logo cần nằm trong báo cáo có chữ, lề và nhiều thành phần, dùng một bước dàn trang tài liệu. Hướng dẫn đặt SVG bằng ReportLab của chúng tôi trình bày dựng PDF trực tiếp; kiểm tra tài nguyên và kích thước WeasyPrint trình bày tài liệu HTML.

Xác minh bản xuất, gồm những gì vẫn là vector

Chúng tôi đọc phần đầu PNG bằng Pillow và các khung trang cùng luồng nội dung PDF bằng pypdf 6.10.0. Mỗi PDF trong bốn bản từ nguồn pixel chứa các thao tác vẽ đường dẫn và không có ảnh trang. Điều đó xác nhận hình học vector cho mẫu đơn giản không có ảnh này. Nó không chứng minh rằng mọi chi tiết của SVG bất kỳ đều được tái hiện chính xác.

Để kiểm tra kích thước đầu ra của bạn, cài pillow và pypdf trong cùng môi trường rồi chạy:

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))

Tài liệu PageObject mô tả mediabox và images. Số ảnh là chỉ dấu chẩn đoán hữu ích, nhưng không thể chứng minh mọi hình, phông hay hiệu ứng còn nguyên đúng cách.

Trước khi bàn giao:

1. Mở PNG và PDF rồi so sánh biểu tượng với SVG. Kiểm tra lỗ, tam giác, thanh và lề.
2. Xác minh độc lập kích thước pixel PNG và kích thước vật lý PDF.
3. Kiểm tra hình ở kích thước sử dụng dự định, gồm khe hẹp và chi tiết nhỏ.
4. Giữ SVG gốc và chạy lại những kiểm tra này sau khi thay đổi nó hoặc nâng cấp công cụ chuyển đổi.

Trang hỗ trợ SVG của CairoSVG cho biết đầu ra vector được giữ khi có thể. Ảnh raster nhúng vẫn là nội dung raster. Nếu tệp chứa PNG trong lớp bọc SVG, chẩn đoán ảnh nhúng giúp bạn nhận diện trước khi xuất.

CairoSVG là trình kết xuất tĩnh. Hoạt ảnh, mã kịch bản, dàn chữ nâng cao và nhiều bộ lọc nằm ngoài quy trình được hỗ trợ. Tài liệu chỉ liệt kê feOffset, feBlend và feFlood là bộ lọc được hỗ trợ. Với hình phụ thuộc hiệu ứng khác, so sánh kết quả cẩn thận hoặc xuất qua ứng dụng hỗ trợ các tính năng đó. Chỉ lệnh chuyển đổi thành công là chưa đủ.

Chỉ khôi phục bản vector gốc khi nguồn cần

Nếu logo chỉ còn PNG hoặc JPG, PerfectVector có thể cung cấp bước raster sang SVG ở trước khi CairoSVG xuất. Kiểm tra hình khôi phục, lỗ nhỏ và chữ thương hiệu trong trình chỉnh sửa; rồi lưu bản SVG gốc tự chứa. Quy trình vector hóa logo của chúng tôi giải thích bước kiểm tra đó.

SVG chỉnh sửa được hiện có có thể chuyển thẳng sang xuất. Chuyển nó sang PNG rồi đồ lại sẽ bỏ đi hình học nguồn hữu ích. Ảnh chụp có thể giữ là ảnh raster khi đó là nội dung dự định.

Với logo chỉ có raster, hãy thử ảnh của bạn trong PerfectVector, kiểm tra đường bao và các lỗ SVG, rồi xác minh cả kích thước pixel lẫn kích thước trang vật lý của các bản xuất CairoSVG.

Câu hỏi thường gặp

Vì sao đổi DPI mà PNG vẫn cùng kích thước? Nếu phần tử gốc SVG dùng kích thước pixel, thay DPI không nhất thiết đổi số pixel PNG. Trong ví dụ này, SVG 240 × 120 pixel giữ kích thước đó ở 192 DPI. Dùng output_width hoặc scale khi cần thêm pixel đầu ra.

Chiều rộng cha có giống chiều rộng đầu ra không? Không. parent_width cung cấp vùng chứa dùng để tính kích thước phần trăm. output_width yêu cầu chiều rộng đầu ra cuối. Chiều rộng gốc 50% với parent_width 960 được tính thành 480 pixel trong ví dụ.

CairoSVG luôn tạo PDF hoàn toàn vector phải không? Không. CairoSVG giữ đầu ra vector khi có thể, nhưng SVG có thể chứa ảnh raster và tính năng không được hỗ trợ. Kiểm tra nội dung và diện mạo PDF thay vì coi phần mở rộng tệp là bằng chứng.

Nguồn tham khảo

1. Tài liệu CairoSVG — Mô tả cài đặt, API chuyển đổi, tùy chọn kích thước và giới hạn kết xuất.
2. Hỗ trợ SVG 1.1 của CairoSVG — Giải thích giữ vector, ảnh nhúng và tính năng không được hỗ trợ.
3. Tài liệu PageObject của pypdf — Mô tả giao diện khung trang và ảnh được dùng để kiểm tra PDF.