terbium / Guides
Pulling out images
Extract product photos from a PDF with terbium.export_images, named after the product beneath each one, with a manifest of image qualities.
On this page
Text is only half a catalogue. terbium.export_images extracts the product photos from a Portable Document Format (PDF) file and, for lookbooks, names each file after the product it sits under. It needs no artificial intelligence (AI) key.
import terbium
manifest = terbium.export_images("lookbook.pdf", "out/")
# out/Kyoto_Bedside_Table.jpeg, out/Meadow_Bedside_Table.jpeg, ...
export_images reads PDF files. For PowerPoint (PPTX) decks, use build_catalog(path, images_dir=...), which extracts slide pictures as part of building the catalog table.
From the shell
There is no separate image-export command. --images DIR sets where the catalog command writes the photos it extracts:
terbium lookbook.pdf --images out/ # catalog table, with the photos written to out/
The command writes image files only. It does not write a manifest file; to get the manifest, call export_images from Python and save it yourself. Worked examples shows how with the csv module.
What you get
Files land in the output folder named after the product (Kyoto_Bedside_Table.jpeg) when a caption label is found, or by page (page060.jpeg) when there is none. Names are made file-safe, and a repeated name gets a numeric suffix (Kyoto_Bedside_Table_2.jpeg).
The returned manifest is a list of dicts, one per image:
product: the caption label associated with the photo, orNonecollection: the group title the label belongs to, when there is a productpage: source page, 1-basedfile: the written filenameformat: the embedded encoding, such asjpegorpng, extracted losslesslywidth_px,height_px: true pixel dimensionscolorspace:RGB,CMYKorGraybytes: file sizedpi: effective resolution in dots per inch (DPI) at the placed size on the pagedominant_color: the average colour as hex, a cheap read on the finishbbox: position on the page in points, rounded to one decimal, used to bind a photo to its label
How it decides what to keep
A catalogue PDF holds three kinds of images, and terbium tells them apart by pixel size alone. An image whose longer side is under 64 pixels is an icon (care and certification marks), under 300 pixels a swatch (finishes), and anything larger a photo. Products are photos, so that is what it keeps by default.
- Only photos. With
only_photos=True(the default), icons and swatches are skipped, and so are thin banners and slivers: images whose shorter side is undermin_sidepixels (default 180) or whose aspect ratio is overmax_aspect(default 4.0). Withonly_photos=False, every image is kept whatever its kind or size, though repeated logos are still dropped whilededupe_repeatsis on. - Thumbnail sheets. If that pass keeps nothing, terbium retries once and accepts swatch-sized images with a shorter side down to 64 pixels.
- No repeated logos. With
dedupe_repeats=True(default), an image that appears on at least 3 pages and on at least 20% of the pages is treated as a logo or watermark and dropped, so you do not get the logo 80 times. - Association. With
associate=True(default), each photo binds to the nearest caption label: below the photo first (up to 140 points), then to its right (up to 180 points), then above it (up to 120 points).
Tune it with:
terbium.export_images(path, out_dir, only_photos=True, associate=True,
dedupe_repeats=True, min_side=180, max_aspect=4.0)
Bytes come from PyMuPDF
terbium extracts image bytes with PyMuPDF, which is already a dependency and returns a ready-to-save JPEG or PNG. pdfplumber is good for image position, metadata and cropping a region to a PNG, but pulling raw bytes through it means decoding PDF filters yourself, so terbium does not depend on it.
Reading what is inside an image
Extracting a photo needs no model. Reading material icons or finish swatches inside the imagery does; see the vision section of AI lane and routing.