Image Manipulation Scripts

A collection of Python and shell scripts for:

• Adding titles or descriptions to images
• Fixing image aspect ratios for printing
• Generating title/subtitle cards for video editors like kdenlive
• Generating an image thumbnail gallery

⚠️ Make backup copies of your images before using these scripts. Many will overwrite files.

Installation

These tools use ImageMagick via its command-line interface (CLI). Make sure it’s installed and accessible via your system PATH.

To install the Python commands:

pip install .

Resize images to a fixed aspect ratio

This tool pads images to match a target aspect ratio (default: 4x6). It overwrites files by default.

Resize all .jpg images to 6×4 (or 4×6, depending on image orientation):

ima-resize *.jpg

Add a 20-pixel border before resizing:

ima-resize -b 20 *.jpg

You can also set a different target ratio using -r:

ima-resize -r 5x7 *.jpg

Supported ratios: 4x6, 5x7, 8x10, 11x14.

Create video title and subtitle cards

The shell scripts mksub.sh and mktitle.sh generate PNG title/subtitle cards for use in kdenlive or other video editors.

Usage is built into the scripts—open them for details.

Annotate images with text and metadata

Automatically generate ima-annotate commands based on image dates:

ima-mkpics -p prefix *.jpg > commands.sh

This will:

• Extract the image date from EXIF metadata or (for WhatsApp images) from the filename
• Generate shell commands to annotate each image and optionally create XML metadata
• Output a script t.sh that you can edit and run

To apply annotations:

sh commands.sh

Output files are named based on the image’s timestamp and prefixed with the -p argument (prefix).

Use -x to also generate .xml metadata files:

ima-mkpics -x -p myprefix *.jpg > commands.sh

See help for all options:

ima-mkpics -h
ima-annotate -h

Annotation Position Format (-d flag)

The -d (direction) flag controls text placement. It takes a hyphenated combination of:

• Vertical position: top, middle, bottom
• Horizontal position: left, middle, right
• Orientation: horizontal, vertical

Examples:

top-left-horizontal
top-left-vertical
top-right-horizontal
top-right-horizontal
top-middle-vertical
top-middle-vertical
bottom-left-horizontal
bottom-left-vertical
bottom-right-horizontal
bottom-right-vertical
bottom-middle-horizontal
bottom-middle-vertical
middle-left-horizontal
middle-left-vertical
middle-right-horizontal
middle-right-horizontal
middle-middle-vertical
middle-middle-vertical

You can abbreviate using first letters, e.g. t-l-h = top-left-horizontal.

Generate HTML thumbnail gallery

The ima-showth tool scans the current directory for .jpg images and generates a simple paginated HTML gallery with thumbnails.

Thumbnails are created using ImageMagick (convert) and stored in a th/ subdirectory. Each HTML page shows up to 12 images with navigation links between pages.

showth.py [linktoparent]

Arguments

• linktoparent: Optional. If nonzero, the “Up one level” link points to the parent folder’s index.html.

Behavior

• Processes all .jpg (case-insensitive) files in the current directory, skipping any that already end with .th.jpg.
• Generates thumbnails (th/filename.th.jpg) resized to 160×120 pixels. Thumbnail conversions run in parallel for speed.
• Creates paginated HTML files: index.html, index2.html, index3.html, etc.
• Each page links to previous and next pages for browsing.
• The navigation arrow images (ar_l.png and ar_r.png) are not created by the script — you’ll need to provide them yourself.

The HTML template is defined in a file tmpl.html, which uses Jinja2 syntax. You can modify the template’s CSS and layout as desired. An example template is included.

Place the tmpl.html in the same folder as your images.

Requirements

• Python 3.8+
• Jinja2
• ImageMagick CLI (convert must be in your PATH)

Install dependencies (if needed):

pip install jinja2

Example usage:

# Create a thumbnail gallery in the current folder
ima-showth

# Same, but with a parent directory link
ima-showth 1