A macOS command line tool to batch-process image files

Latest Release: 7.0.0

 

 

How to Use imageprep

imageprep is a macOS command line tool to help you batch-process JPEG, PNG and TIFF image files.

In Terminal, run:

imageprep [--source path] [--destination path] \
          [--action s scale_height scale_width] \
          [--action p pad_height pad_width] \
          [--action c crop_height crop_width] \
          [--cropfrom anchor_point] \
          [--offset y-coord x-coord] \
          [--colour pad_colour] \
          [--resolution dpi_value] \
          [--format format_type] \
          [-x] [--overwrite] \
          [--info] [--createdirs] \
          [--help] [--version]

Options

Switch	Argument(s)	Description
-s or --source	{path}	The path to an image or a directory of images. Default: current working directory
-d or --destination	{path}	The path to the images. Default: source directory
-a or --action	{type} {width} {height}	The crop/pad dimensions. Type is s (scale), c (crop) or p (pad), eg. -a s 200 200
-c or --colour	{colour}	The padding colour in Hex, eg. A1B2C3. Numbers may be prefixed #, $ or 0x, or have no prefix. Default: FFFFFF
--cropfrom	{anchor point}	Set an anchor point for crop actions. See Anchor Points below
--offset	{x} {y}	Set an anchor point for crop actions. See Anchor Points below
-r or --resolution	{dpi}	Set the image dpi, eg. 300
-f or --format	{format}	Set the image format: JPG/JPEG, PNG, GIF, BMP or TIF/TIFF
-j or --jpeg	{level}	Set the compression level of any saved JPEG images as a percentage. Default: 80
--createdirs		Create intermediate directories to the destination, if needed. Default: do not create
-o or --overwrite		Overwrite an existing file. Without this, existing files will be kept
--info		Output image information in machine-readable form: path, width, height, resolution and alpha state
-x		Delete the source file(s). Without this, the source will be retained.
-q or --quiet		Silence output messages (errors excepted)
-h or --help		Show help information
--version		Show version information

 
You can add any number of actions: they will be applied in the order they appear at the command line.

If you omit either the --source or --destination flags, their default values will be the directory from which you ran the tool. From version 7.0.0, you may include a list of one or more files at the command line. These will be processed in place of any files included in the source directory (if included; or the default source directory otherwise). This allows you to process specific files rather than all of those in the source. Files processed this way will be written to the --destination directory.

You may specify a single image as your source using the --source flag. If you do this, you may also specify a specific name for the processed file, or a directory in which the processed file will be placed — it will use the same name as the source. You can’t output a directory of images to a named file.

Adding the --createdirs switch will cause imageprep to create any intermediate directories required to write the destination file(s).

Actions

imageprep has three basic actions, or action types:

• crop — trim the image to the specified dimensions.
• pad — expand the image’s canvas to the specified dimensions, leaving the image itself at its current size.
• scale — grow or shrink the image to the specified dimensions.

The actions are selected with the --action flag followed by a single character code: c, p or
s.

Padding an image to a size below its current dimensions is a de facto crop. Cropping an image to a size above its current dimensions is a pad.

To set the colour of a padded file’s canvas, use --colour and include an RGB integer in hex format, eg. --colour FF0000 for red. The default pad colour is white. You can specify the hex value in upper or lower case, and with no prefix or any of the following prefixes: 0x, $, #, x.

You can include multiple actions; they will be processed in the order they were included at the command line. Take care, though: imageprep will not guard against unwanted values — though it will ignore actions that result in image dimensions that are zero or negative.

Image Format

You can choose a new image format by using the --format flag and providing the new format: jpeg, jpg, tiff or png. For example, --format jpeg converts all of the batch images to JPEG format. The file extension will be changed accordingly. Any change applies to all of the images in the batch.

From version 7.0.0, if you are working with JPEG images, you can set the target files’ compression level with the --jpeg switch. Pass a percentage quality level (the higher the quality, the lower the compression applied).

Image Resolution

You can choose a new print resolution by using the --resolution flag and providing a new value in dots per inch (DPI). For example, --resolution 300 will set images to 300dpi. If you do not include --resolution, no change is made to images’ resolutions. Any change applies to all of the images in the batch.

File Protection

By default, imageprep deletes source files once it has processed them unless source and destination images are the same. To prevent source files from being deleted, include the --keep switch.

If a file exists at the destination with the name and extension of a generated file, imageprep will not process the file. Include the --overwrite switch to replace the file at the destination.

Crop Anchor Points

You can specify an anchor point for crop operations. Use the --cropfrom switch and a value to indicate the anchor point: text markers, eg. tr for top-right, bl for bottom-left or
cr for centre-right, etc., or a numerical value:

	Left	Centre	Right
Top	TL	TC	TR
Centre	CL	N/A	CR
Bottom	BL	BC	BR

 

	Left	Centre	Right
Top	0	1	2
Centre	3	N/A	5
Bottom	6	7	8

 

From version 6.3.0, you can specify crop anchors as x and y co-ordinates: this is the co-ordinate of the top left point of the retained area. For example, with a 1920 x 1080 image, to crop out all but a 500 by 500 area in the centre of the top left of the image, you would specify 500 and 500 as your width and height values, and 230 and 20 as your offset co-ordinates (x and y, respectively). Offset values cannot be negative, and values beyond the dimensions of the source image will be ignored.

Please note that if you also specify a crop anchor point using --cropfrom, it will override any --offset value you specify.

Examples

This will take all of the images files in ~/Documents/Source Images, crop them to 1536 x 2048, set the resolution at 300dpi, convert them to JPEGs and save the resulting files in ~/Documents/Processed Images. The source files will not be deleted.

$ imageprep --source ~/Documents/'Source Images' \
            --destination ~/Documents/'Processed Images' \
            --action c 1536 2048 \
            --format jpg \
            --resolution 300

This will convert ~/Documents/Source Images/cover.png to ~/Documents/Processed Images/cover.tiff without deleting the source file.

$ imageprep --source ~/Documents/'Source Images'/cover.png \
            --destination ~/Documents/'Processed Images' \
            --format tiff

This will reduce the image ~/Documents/Source Images/cover.jpg and then pad the image out to the original size with a yellow border. The source files will be deleted.

$ imageprep --source ~/Documents/'Source Images'/cover.jpg \
            --destination ~/Documents/'Source Images'/cover.jpg \
            --colour FFD709
            --action s 1024 1366
            --action p 1536 2048
            -x

This will crop the image ~/Documents/Source Images/cover.jpg, anchoring the crop to the top-centre of the source image. The source files will not be deleted.

$ imageprep --source ~/Documents/'Source Images'/cover.jpg \
            --destination ~/Documents/'Processed Images' \
            --action c 1024 1024
            --cropfrom tc

This will crop the image ~/Documents/Source Images/cover.jpg at a specified offset. The source files will not be deleted.

$ imageprep --source ~/Documents/'Source Images'/cover.jpg \
            --destination ~/Documents/'Processed Images' \
            --action c 1024 1024
            --offset 29 39

Back to the Top

---

Source Code

You can view Imageprep’s source code at GitHub.

Back to the Top

---

Release Notes

• 7.0.0 10 August 2023
  • Support the loading of individual files, not just a directory.
  • Deleting source files after processing is no longer the default.
  • Allow the compression level of JPEG output to be specified by the user.
• 6.3.4 24 May 2022
  • Add man page.
  • Under-the-hood code improvements.
• 6.3.3 23 July 2021
  • Replace async signal unsafe ctrl-c trapper with safe one.
• 6.3.2 16 June 2021
  • Fix a regular expression bug.
• 6.3.1 16 June 2021
  • Add better, broader fix for sips `no zero offsets, please’ issue.
• 6.3.0 2 June 2021
  • Add --offset flag to set an alternative crop anchor point.
  • Better checking for missing value arguments.
• 6.2.1 13 January 2021
  • No code changes — packaging update only.
• 6.2.0 28 December 2020
  • Add --cropfrom flag to select a crop anchor point.
  • Add the ability to crop/scale/pad to the width or height of the source image.
  • Add the ability to crop/scale/pad to a specified width or height using the aspect ratio of the source image.
  • Add --info argument.
• 6.1.0 21 December 2020
  • Add optional destination intermediate directory creation.
  • Ignore sub-directories in the source directory for file-safety reasons.
  • Colourise output for greater visibility.
  • Sort source file list before processing.
  • Write all messages to user via stderr (click here to see why).
  • Correctly trap SIGINT.
  • Correctly keep source file when no target file is named.
  • Add examples to help text.
  • Add test suite.
• 6.0.0 2 December 2020
  • Initial public release.

Back to the Top

---

Related Software

• Depot
• pdfmaker
• utitool
• Hex
• Shell Scripts

Back to the Top

---