Skip to content
terbium

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
  1. From the shell
  2. What you get
  3. How it decides what to keep
  4. Bytes come from PyMuPDF
  5. Reading what is inside an image

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, or None
  • collection: the group title the label belongs to, when there is a product
  • page: source page, 1-based
  • file: the written filename
  • format: the embedded encoding, such as jpeg or png, extracted losslessly
  • width_px, height_px: true pixel dimensions
  • colorspace: RGB, CMYK or Gray
  • bytes: file size
  • dpi: effective resolution in dots per inch (DPI) at the placed size on the page
  • dominant_color: the average colour as hex, a cheap read on the finish
  • bbox: 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 under min_side pixels (default 180) or whose aspect ratio is over max_aspect (default 4.0). With only_photos=False, every image is kept whatever its kind or size, though repeated logos are still dropped while dedupe_repeats is 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.