Obrazy SVG w fpdf2: zachowaj ścieżki w pliku PDF tworzonym w Pythonie

Użyj pdf.image("logo.svg", x=20, y=20, w=60), aby umieścić SVG w dokumencie fpdf2. Obsługiwana geometria SVG staje się ścieżkami rysunkowymi PDF. Nie musisz najpierw renderować logo do PNG. Oficjalna dokumentacja SVG opisuje tę bezpośrednią metodę i jej ograniczenia.

Jeśli ten format jest dla Ciebie nowy, przewodnik po plikach SVG wyjaśnia ścieżki i kontenery obrazów. Nawet udany import wymaga sprawdzenia. Plik może zawierać osadzone piksele, korzystać z funkcji, których importer nie odtwarza, albo mieć pustą przestrzeń wokół grafiki. W tym przewodniku tworzymy niewielkie autorskie logo, umieszczamy je w dokumencie w określonym rozmiarze i sprawdzamy wynikowy PDF. Jeśli masz oryginał wektorowy, zachowaj go; odzyskiwanie grafiki z PNG lub JPG to osobny, wcześniejszy etap.

Zacznij od znanego SVG i ustalonej wersji fpdf2

Uruchomiliśmy przykład z Pythonem 3.12 i fpdf2 2.8.8. To przetestowana wersja, a nie obietnica, że każde późniejsze wydanie będzie działać identycznie. Oficjalna strona pakietu w PyPI opisuje instalację pod nazwą dystrybucji fpdf2; import w Pythonie używa nazwy fpdf.

Użyj nowego środowiska, aby przykład był niezależny od pakietów innego projektu:

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

W Windows aktywuj środowisko za pomocą .venv\Scripts\activate. Zapisz ten autorski prostokątny emblemat jako 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>

Są tu dwie zamknięte podścieżki. Zewnętrzny prostokąt jest wypełniony, a wewnętrzny staje się otworem dzięki regule wypełnienia evenodd. Nie ma tu żadnego fontu, obrazu ani efektu, co ułatwia diagnozowanie pierwszego testu.

Zapisz poniższy kod jako place_logo.py obok pliku SVG:

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

Uruchom python place_logo.py. Otwórz logo.pdf i sprawdź, czy w pobliżu lewego górnego rogu znajduje się turkusowa prostokątna ramka, przez której środek widać stronę.

Odróżnij obszar SVG od narysowanego logo

Obszar źródłowy ma proporcje 3:2: 120 jednostek szerokości i 80 wysokości. Przy w=60 ten przykład zajmuje obszar 60 × 40 mm. Grafika zaczyna się 10 jednostek źródłowych od krawędzi tego obszaru, więc jej narysowany zewnętrzny prostokąt ma 50 × 30 mm i zaczyna się w punkcie 25, 25 mm na stronie. Te wartości wynikają z obliczeń na podstawie współrzędnych i skali tego przykładu testowego.

Ten margines wyjaśnia, dlaczego pomiar kolorowego kształtu daje inny wynik niż pomiar obszaru umieszczenia. Jeśli logo klienta wygląda na zbyt małe, sprawdź marginesy w pliku źródłowym, zanim zwiększysz jego szerokość w PDF.

Przewodnik po obrazach w fpdf2 wyjaśnia obsługę wymiarów i możliwość zachowania proporcji wewnątrz określonego prostokąta. W tym pierwszym przykładzie ustaw tylko szerokość. Jeśli później podasz oba wymiary, świadomie przetestuj oczekiwane dopasowanie, zamiast zakładać, że każdy plik źródłowy będzie miał takie same proporcje.

Sprawdź, czy zapisany PDF zawiera ścieżki

Podgląd PDF pokazuje wygląd, ale obraz może wyglądać ostro przy niewielkim powiększeniu. Sprawdź również sam plik. Zweryfikowaliśmy ten samodzielny przykład za pomocą 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"))

Wynik wskazywał zero obrazów na stronie. Zdekodowana zawartość zawierała kontury prostokątów zapisane za pomocą operacji ustawienia punktu bieżącego, rysowania linii i zamknięcia ścieżki, po których następowało f*, czyli operacja wypełnienia zgodnie z regułą parzystości. Wraz z otworem widocznym po renderowaniu przemawia to za wnioskiem, że ten przykład testowy bez obrazów zachował geometrię rysunkową w zapisanym PDF.

Nie przenoś tego wniosku na inny plik wejściowy bez sprawdzenia. Raport może zasadnie zawierać zdjęcia w innych miejscach; sam SVG też może zawierać obraz. Diagnostyka osadzonych obrazów rastrowych pomaga odróżnić logo zbudowane ze ścieżek od bitmapy opakowanej w kod SVG. Bardziej złożone pliki PDF mogą też umieszczać zawartość rysunkową wewnątrz obiektów, do których odwołuje się dokument, więc powyższy krótki skrypt jest punktem wyjścia dla tego samodzielnego przykładu testowego, a nie uniwersalnym audytem PDF.

Diagnozuj brakujące elementy grafiki w zainstalowanej wersji

Zacznij od uruchomienia przykładu z małym emblematem powyżej. Jeśli działa, a Twoje docelowe logo nie, zawęża to problem do grafiki źródłowej lub używanych przez nią funkcji. Zachowaj oryginał i upraszczaj kopię, zmieniając po jednej funkcji naraz.

Starsze odpowiedzi wymagają tu ostrożności. Nasz osobny test w wersji 2.8.8, zawierający prosty element <text>, dał tekst HELLO, który można było wyodrębnić, a prostokąt z prostym gradientem liniowym został poprawnie wyeksportowany. Te ograniczone testy nie potwierdzają pełnej zgodności z tekstem SVG, fontami, CSS ani gradientami. Pokazują jednak, dlaczego stare stwierdzenie, że żaden tekst SVG lub żadne gradienty nie są obsługiwane, może skłonić Cię do niepotrzebnej rasteryzacji.

Aktualna lista funkcji SVG nadal wymienia ograniczenia, takie jak znaczniki, wzory, tekst na ścieżce oraz złożony lub zewnętrzny CSS. Podczas diagnozowania pozostaw ostrzeżenia importera widoczne i porównuj zapisaną stronę ze źródłem. Sam brak ostrzeżeń w logu nie dowodzi, że każdy element wizualny został zachowany.

Użyj wersji rastrowej, gdy wynik tego wymaga

Jeśli efektu nie da się odtworzyć w wybranym procesie, zdecyduj, czy zachowanie jego wyglądu jest ważniejsze niż zachowanie geometrii. Wyrenderowany PNG może być odpowiedni dla tej części dokumentu. Sprawdź go w docelowym rozmiarze fizycznym i prawidłowo oznacz wynik; osadzenie wyrenderowanego obrazu rastrowego nie zachowuje oryginalnych ścieżek.

W przypadku logo marki lepszym wyborem może być zatwierdzony napis zamieniony na krzywe lub prostszy eksport wektorowy. W przypadku edytowalnego tekstu dokumentu pozostaw obsługę fontów i tekstu w procesie tworzenia dokumentu. Wektoryzacja zrzutu ekranu ze zdaniem nie odzyskuje jego typografii ani nie sprawia, że staje się ono tekstem, który można zaznaczyć.

Jeśli Twój istniejący kod PDF używa innej biblioteki Pythona, proces obsługi SVG w ReportLab ma własne kontrole importu i wymiarów. Zmiana biblioteki to osobna decyzja implementacyjna, więc przetestuj konkretną problematyczną funkcję, zanim przebudujesz dokument.

Przygotuj grafikę dostępną tylko w wersji rastrowej przed etapem PDF

Gdy pozostało tylko logo PNG lub JPG, wektoryzator logo PerfectVector może przygotować wersję SVG do sprawdzenia przed zaimportowaniem jej za pomocą fpdf2. Porównaj kontury, małe otwory i obszary kolorów ze źródłem, a następnie przeprowadź na tej wersji te same kontrole umieszczenia i pliku PDF.

Użyj oryginalnej grafiki wektorowej, jeśli jest dostępna. Wierne odtworzenie napisu marki może wymagać ponownego wpisania tekstu lub ręcznej korekty; przewodnik po wektoryzacji logo wyjaśnia ten wybór. Emblemat w tym artykule to autorski, ręcznie napisany SVG, a nie wynik konwersji w PerfectVector poddany pomiarom. PerfectVector przygotowuje grafikę, a fpdf2 kontroluje jej umieszczenie w PDF.

FAQ

Czy fpdf2 może bezpośrednio wstawić SVG? Tak. Przekaż plik SVG do metody image i ustaw jego położenie oraz rozmiar. Obsługiwana geometria może stać się ścieżkami PDF, ale sprawdź wyeksportowany plik i wygląd własnej grafiki.

Czy fpdf2 obsługuje tekst SVG? Nasz podstawowy test tekstu zadziałał w fpdf2 2.8.8. Nie gwarantuje to obsługi każdego fontu, funkcji układu ani konstrukcji tekstu na ścieżce. Sprawdź zainstalowaną wersję i przetestuj napis, którego faktycznie używa Twój dokument.

Dlaczego obraz o szerokości 60 mm wygląda na węższy niż 60 mm? Żądany rozmiar dotyczy obszaru umieszczenia. Puste marginesy wewnątrz SVG pozostają częścią tego obszaru, więc narysowany kształt może być węższy.

Czy przed dodaniem logo PNG należy przekonwertować je na SVG? Tylko jeśli potrzebujesz edytowalnych ścieżek, a grafika nadaje się do wektoryzacji. Zachowaj fotografie jako obrazy rastrowe i użyj oryginalnego logo wektorowego, jeśli istnieje. Sprawdź wersję uzyskaną przez wektoryzację przed jej wstawieniem.

Źródła

1. fpdf2 — SVG — Dokumentuje bezpośrednie wstawianie SVG, obsługę funkcji i logi ostrzeżeń.
2. fpdf2 — Images — Wyjaśnia umieszczanie obrazów, wymiary i dopasowanie z zachowaniem proporcji.
3. fpdf2 — PyPI package — Wskazuje dystrybucję do zainstalowania i konwencję jej importowania w Pythonie.

Masz tylko logo rastrowe? Przygotuj wersję SVG do sprawdzenia za pomocą PerfectVector, sprawdź jej kontury i otwory, a następnie umieść ją w wymaganym rozmiarze za pomocą fpdf2 i sprawdź zapisany PDF.