larvaworld.lib.util.combining

Methods for detecting and combining files

Functions

files_in_dir(→ list[str])	Select files from directory matching filename conditions.
combine_images(, figsize, int] | None = None) → None)	Merge multiple image files into a single combined image file.
combine_videos(→ None)	Merge multiple video files into a single side-by-side video.
combine_pdfs(→ None)	Merge multiple PDF files into a single combined PDF.

Module Contents

larvaworld.lib.util.combining.files_in_dir(dir: str, sort: bool = True, include_subdirs: bool = False, suf: str = '', pref: str = '') → list[str]

Select files from directory matching filename conditions.

Scans a directory for files matching optional prefix and suffix filters. Can optionally include subdirectories and sort results.

Args:

dir: Absolute path to directory to search sort: If True, sort filenames alphabetically (default: True) include_subdirs: If True, search subdirectories recursively (default: False) suf: Required suffix to include file, e.g., ‘.txt’ (default: ‘’) pref: Required prefix to include file (default: ‘’)

Returns:

List of absolute file paths matching the criteria

Example:

>>> files = files_in_dir('/path/to/dir', suf='.py')
>>> files = files_in_dir('/path/to/dir', pref='test_', suf='.txt', include_subdirs=True)

larvaworld.lib.util.combining.combine_images(files: list[str] | None = None, file_dir: str = '.', save_as: str = 'combined_image.pdf', save_to: str | None = None, size: tuple[int, int] = (1000, 1000), figsize: tuple[int, int] | None = None) → None

Merge multiple image files into a single combined image file.

Creates a grid layout of images and saves as PDF or image. Images are thumbnailed to fit the grid based on total count. Uses PIL for processing.

Args:

files: List of image file paths. If None, scans file_dir file_dir: Directory to search for images if files not provided (default: ‘.’) save_as: Output filename (default: ‘combined_image.pdf’) save_to: Directory to save output. If None, uses file_dir size: Output image dimensions in pixels (default: (1000, 1000)) figsize: Override thumbnail size as (width, height) pixels

Example:

>>> combine_images(files=['img1.jpg', 'img2.jpg'], save_as='grid.pdf')
>>> combine_images(file_dir='/path/to/images', size=(2000, 2000))

larvaworld.lib.util.combining.combine_videos(files: list[str] | None = None, file_dir: str = '.', save_to: str | None = None, save_as: str = 'combined_videos.mp4') → None

Merge multiple video files into a single side-by-side video.

Uses ffmpeg to horizontally stack videos. All videos must have identical duration. Requires ffmpeg and ffprobe installed on system.

Args:

files: List of video file paths (.mp4). If None, scans file_dir for .mp4 files file_dir: Directory to search for videos if files not provided (default: ‘.’) save_to: Directory to save output. If None, uses file_dir save_as: Output filename (default: ‘combined_videos.mp4’)

Raises:

ValueError: If fewer than 2 videos provided or durations don’t match

Example:

>>> combine_videos(files=['vid1.mp4', 'vid2.mp4'], save_as='stacked.mp4')
>>> combine_videos(file_dir='/path/to/videos')

larvaworld.lib.util.combining.combine_pdfs(files: list[str] | None = None, file_dir: str = '.', pref: str = '', save_to: str | None = None, save_as: str = 'final.pdf', include_subdirs: bool = True) → None

Merge multiple PDF files into a single combined PDF.

Concatenates PDFs in order, preserving all pages. Uses pypdf library for merging. Can filter by filename prefix.

Args:

files: List of PDF file paths. If None, scans file_dir for .pdf files file_dir: Directory to search for PDFs if files not provided (default: ‘.’) pref: Required filename prefix to include (default: ‘’ for all) save_to: Directory to save output. If None, uses file_dir save_as: Output filename (default: ‘final.pdf’) include_subdirs: If True, search subdirectories recursively (default: True)

Example:

>>> combine_pdfs(files=['doc1.pdf', 'doc2.pdf'], save_as='merged.pdf')
>>> combine_pdfs(file_dir='/reports', pref='2024_', save_as='all_2024.pdf')