Utilities¶

siglip2_toolkit.utils ¶

Shared, dependency-light helpers: filesystem scanning, image loading, metadata (EXIF) extraction, thumbnails and incremental-run planning.

setup_logging ¶

setup_logging(level='INFO')

Configure root logging with a compact, consistent format.

register_heif_support ¶

register_heif_support()

Register the Pillow HEIF opener once, supporting HEIC/HEIF images.

find_image_files ¶

find_image_files(directories)

Recursively yield the image files found in the given directories.

Non-existent or non-directory inputs are skipped with a warning. Yields absolute paths.

sanitize_filename ¶

sanitize_filename(filename)

Remove characters that are invalid in file names.

resolve_torch_device ¶

resolve_torch_device(
    torch, device_choice="auto", dtype_choice=None
)

Resolve (device, dtype) from a device choice string.

"auto" prefers CUDA, then MPS, then CPU. Half precision is selected automatically on accelerated devices unless dtype_choice overrides it.

load_image ¶

load_image(item)

Load an image from a path, bytes, a file-like object or a PIL image.

Returns an RGB PIL.Image.Image. Raises ValueError/OSError for unreadable input.

create_thumbnail ¶

create_thumbnail(
    image_path,
    image,
    thumbnail_dir,
    thumbnail_size=(128, 128),
)

Save a WEBP thumbnail next to the configured thumbnail directory.

Returns the absolute thumbnail path, or None when creation fails.

extract_metadata ¶

extract_metadata(
    image_path,
    *,
    create_thumbnails=False,
    thumbnail_dir="thumbnails",
    thumbnail_size=(128, 128),
)

Extract filesystem/EXIF metadata (and optionally a thumbnail) for an image.

Returns None when the image cannot be read. The metadata schema is stable and part of the index format: path, filename, size_bytes, creation_time, modification_time, width, height, exif and (optionally) thumbnail_path.

filter_files_for_update ¶

filter_files_for_update(all_files_on_disk, existing)

Plan an incremental run.

Files to process are the files on disk that are either new (not in the export) or whose modification time differs from the recorded one by more than one second. Records without metadata (metadata was not exported) cannot be compared, so only new files are detected for them. Missing or unparseable timestamps cause reprocessing.