image#

mediautils.image.get_all_jpeg_files(root_dir: str | PathLike, exclude: list[str] | None = None) → list[Path][source]#

List all JPEG files under root_dir recursively.

Parameters:

  • root_dir (str | os.PathLike) – Root directory to search.

  • exclude (list[str] | None) – Substrings to exclude: any directory whose path contains one of these strings is skipped. If None, DEFAULT_EXCLUDE_PATTERNS is used. Pass an empty list to disable exclusions.

Return type:

list[Path]

mediautils.image.get_offset_image(path: str | PathLike) → str | None[source]#

Read the offset_time_original EXIF tag of an image.

Parameters:

path (str | os.PathLike) – Path to the image.

Returns:

The UTC offset stored in the offset_time_original EXIF tag (e.g. "+09:00"), or None if the tag is absent.

Return type:

str | None

mediautils.image.get_orientation(path: str | PathLike) → str[source]#

Detect whether an image is portrait or landscape.

Takes EXIF orientation into account (rotation 90° or 270°). Square images are reported as "landscape".

Parameters:

path (str | os.PathLike) – Path to a JPEG image.

Returns:

"portrait" or "landscape".

Return type:

str

mediautils.image.get_time_image(path: str | PathLike) → datetime[source]#

Read the datetime_original EXIF tag of an image.

Parameters:

path (str | os.PathLike) – Path to the image.

Returns:

The datetime stored in the datetime_original EXIF tag, naive (no timezone attached, regardless of whether an offset_time_original tag is present).

Return type:

datetime

mediautils.image.process_images(src_dir: str | PathLike, dest_portrait: str | PathLike, dest_landscape: str | PathLike, max_dim: int = 1024, exclude: list[str] | None = None) → list[Path][source]#

Dispatch JPEG images by orientation and resize them.

Collects all JPEG files under src_dir (recursively), detects each image’s orientation, copies it to dest_portrait or dest_landscape, and resizes it if its largest dimension exceeds max_dim.

Parameters:

  • src_dir (str | os.PathLike) – Source directory to scan for JPEG files.

  • dest_portrait (str | os.PathLike) – Output directory for portrait images.

  • dest_landscape (str | os.PathLike) – Output directory for landscape images.

  • max_dim (int) – Maximum size in pixels for the largest dimension.

  • exclude (list[str] | None) – Exclusion patterns passed to get_all_jpeg_files().

Returns:

Paths to the output files.

Return type:

list[Path]

mediautils.image.resize_image(path: str | PathLike, max_dim: int = 1024, out_dir: str | PathLike = 'out', out_name: str | None = None) → Path[source]#

Write a copy of an image, resized if its largest dimension exceeds max_dim.

Images with EXIF orientation 6 or 8 (rotated 90°/270°) are copied without resizing to avoid corrupting the orientation metadata.

Parameters:

  • path (str | os.PathLike) – Path to the source image.

  • max_dim (int) – Maximum size in pixels for the largest dimension.

  • out_dir (str | os.PathLike) – Directory where the output file is saved. Created if it does not exist.

  • out_name (str | None) – Output file name. If None, the original file name is kept.

Returns:

Path to the output file.

Return type:

Path

mediautils.image.set_file_creation_time(path: str | PathLike, dt: datetime) → None[source]#

Set a file’s Windows filesystem creation-time metadata.

Unlike EXIF timestamps, Windows filesystem timestamps carry no timezone: they are stored as an absolute instant and redisplayed converted to whatever timezone the machine currently uses. dt is interpreted as local wall-clock time on the current machine (exactly like datetime.timestamp()), so that a tool reading the creation time back on this same machine (e.g. Windows Explorer or FastStone Image Viewer) redisplays the same digits.

Parameters:

  • path (str | os.PathLike) – Path to the file.

  • dt (datetime) – The datetime to set as creation time, interpreted in the machine’s current local timezone.

Raises:

NotImplementedError – If not running on Windows.

mediautils.image.set_time_image(path: str | PathLike, dt: datetime, out_dir: str | PathLike = 'out', out_name: str | None = None, offset: str | None = None) → Path[source]#

Write a copy of an image with datetime_original set to dt.

Parameters:

  • path (str | os.PathLike) – Path to the source image.

  • dt (datetime) – The datetime to write into the EXIF metadata.

  • out_dir (str | os.PathLike) – Directory where the modified copy is saved. Created if it does not exist.

  • out_name (str | None) – Output file name. If None, the original file name is kept.

  • offset (str | None) – UTC offset to write to the offset_time_original EXIF tag, in "+HH:MM"/"-HH:MM" format (e.g. "+09:00"). If None, the tag is left untouched.

Returns:

Path to the output file.

Return type:

Path

mediautils.image.set_time_raw(path: str | PathLike, dt: datetime, out_dir: str | PathLike = 'out', out_name: str | None = None, offset: str | None = None) → Path[source]#

Write a copy of a RAW image with DateTimeOriginal set to dt.

Camera RAW formats (e.g. Panasonic .rw2) are TIFF-based, not JPEG-APP1-based, so the exif.Image interface used by set_time_image() cannot parse them. This uses the external exiftool command-line tool instead, which must be on PATH. Any other metadata tag is left untouched.

Parameters:

  • path (str | os.PathLike) – Path to the source RAW image.

  • dt (datetime) – The datetime to write into the DateTimeOriginal metadata tag.

  • out_dir (str | os.PathLike) – Directory where the modified copy is saved. Created if it does not exist.

  • out_name (str | None) – Output file name. If None, the original file name is kept.

  • offset (str | None) – UTC offset to write to the OffsetTimeOriginal metadata tag, in "+HH:MM"/"-HH:MM" format (e.g. "+09:00"). If None, the tag is left untouched.

Returns:

Path to the output file.

Return type:

Path