RENROT(1p)

📦
version 1.2.0 · 3 versions
, in debian bookworm, ubuntu jammy, ubuntu noble

🌸 renrot(1p) — rename + rotate ur pics by their EXIF, no cap 💅

okay bestie, welcome to renrot(1p), straight out of the User Contributed Perl Documentation. it renames and rotates images according to EXIF data, and honestly? it's giving main character energy for ur whole photo library. 🎀

✨ NAME ✨

renrot — rename and rotate images according EXIF data 🦋

✨ SYNOPSIS ✨

renrot [OPTIONS] [[--] FILE1 FILE2 ...]

✨ DESCRIPTION ✨

so like, Renrot is built to work with a set of files that contain EXIF data, and it does two things to them — rename and rotate. periodt.

u can hand it a set of files two ways: explicitly, or with the --extension option, which grabs all the files with the suffix u gave it. and where does it operate? in the current working directory, unless u pass --work-directory and change that default. easy.

Renrot renames ur input files using a flexible name template (which, among other things, uses the DateTimeOriginal and FileModifyDate EXIF tags if they exist — and if they don't, it just names the file according to the current timestamp, nbd). and further? it can aggregate files according to the shooting time period, or according to a template u give it.

on top of that, it rotates files and their thumbnails, as per the Orientation EXIF tag. if that tag isn't there, the program lets u set rotation params with the --rotate-angle and --rotate-thumb command line options. heads up tho: this is currently implemented only for JPEG format. 😭

the program can also drop commentaries into these locations:

  • Commentary tag from file (see the --comment-file option)
  • UserComment tag from configuration variable (see the "TAGS" section)

personal details can be specified via XMP tags defined in a configuration file — again, see the "TAGS" section. iykyk. 💖

and one more thing: renrot can aggregate all files in different directories according to a given date/time pattern template, set with --aggr-template. slay.

✨ OPTIONS ✨

  • -c, --config-file FILE — path to the configuration file. 🗂️
  • -d, --work-directory DIR — define the working directory.
  • --exclude FILE — specify files to exclude. ⚠️ wildcards are not allowed. if u give a set of files, there has to be as many occurrences of this option as there are files in the set.
  • --sub-fileset FILE — get the names of the files to operate upon from FILE. that file needs one file name per line. this one's a lifesaver when u only need to process a set of X out of Y files in the directory. if u specify it, the rest of the files given on the command line are ignored.
  • -e, --extension EXTENSION — process the files with the given EXTENSION (JPG, jpeg, CRW, crw, etc). depending on the operating system, the extension search might or might not be case-sensitive. 🙈
  • --mtime, --no-mtime — defines whether to set the file's mtime using the DateTimeOriginal tag value. use --no-mtime to set it to the current time stamp after processing.
  • --no-renrot, --nochg — do not rename, rotate, tag and mtime images. it saves files from any changes while still allowing u to do aggregation, contact sheet generation, e.t.c. so useful, so iconic.
  • --use-color, --no-use-color — colorize output. 💅 this does NOT work under Windows.
  • --dry-run — do nothing, only print what would have been done. the vibe check before the real thing.
  • -g, --generate-thumb — generation and writing of the ThumbnailImage tag. the original value of the ThumbnailImage tag stays intact — to rewrite it u need to delete it first (look at exiftool examples).
  • --use-ipc, --no-use-ipc — rotate thumbnails using a pipe, rather than files. this does NOT work under Windows either.
  • -v — increase debugging level by 1. debugging levels from 1 to 4 are internal levels, and the levels from 5 till 9 are equivalent to levels 1-5 levels ExifTool, with the maximum verbosity for renrot.
  • -?, --help — display a short usage summary and exit. 🫶
  • --version — output version information and exit.

✨ AGGREGATION ✨

  • --aggr-mode MODE — run the aggregation process in the given MODE. possible values are: none, delta or template.
  • --aggr-delta NUMBER — aggregation time delta, in seconds. files with DateTimeOriginal and ones of the previous file delta, greater than --aggr-delta, are placed in the directories, with the names constructed by concatenating the value of the --aggr-directory option and the directory name counter.
  • --aggr-directory DIR — aggregation directory name prefix (default is Images), has to be on the same file system (or on the file system which supports symbolic links in case of virtual aggregation), relative to the current working directory, or an absolute path.
  • -a, --aggr-template TEMPLATE — file name template to use for file aggregation. images are aggregated by date/time patterns. u may use a combination of the %d, %H, %M, %m, %S, %Y, and %y meta-characters. the template can also be defined in the configuration file (see the Aggregation Template variable). the default is %Y%m%d. for the detailed description, refer to the --name-template option. for practical uses, see the "TEMPLATE EXAMPLES" section. 🌈
  • --aggr-virtual, --no-aggr-virtual — defines virtualization for existent aggregation modes. the main effect of --aggr-virtual is that any files to be aggregated remain untouched in their places, and relative symbolic links pointing to them are stored in the directory tree created. use --no-aggr-virtual to prevent virtualization.

✨ CONTACT SHEET GENERATOR ✨

  • --contact-sheet, --no-contact-sheet, --cs, --no-cs — create the contact sheet. currently it works with ThumbnailImage EXIFs and the files defined as thumbnails (see the option --contact-sheet-thm, below).
  • --contact-sheet-file, --cs-file FILE — base file name for montage files.
  • --contact-sheet-dir, --cs-dir DIR — temporary directory for montage (created in the begining and deleted at the end of the process).
  • --contact-sheet-thm, --cs-thm — files for the montage are already thumbnails.

the options below are native ImageMagic montage options — look at the ImageMagick documentation for montage options: montage --help and http://www.imagemagick.org/ 📸

note please, for COLOR use RGB triplets only, like 000 for the black or F00 for the red. don't get cute with it, bestie.
  • --contact-sheet-tile, --cs-tile GEOMETRY — tile MxN (IM: -tile).
  • --contact-sheet-title, --cs-title STRING — set the title of the contact sheet (IM: -title).
  • --contact-sheet-bg, --cs-bg COLOR — background color (IM: -background).
  • --contact-sheet-bd, --cs-bd COLOR — border color (IM: -bordercolor).
  • --contact-sheet-mt, --cs-mt COLOR — frame color (IM: -mattecolor).
  • --contact-sheet-fn, --cs-fn STRING — render text with this font (IM: -font).
  • --contact-sheet-fl, --cs-fl COLOR — color to fill the text (IM: -fill).
  • --contact-sheet-lb, --cs-lb STRING — assign a label to an image (IM: -label).
  • --contact-sheet-fr, --cs-fr GEOMETRY — surround image with an ornamental border in N pixels (IM: -frame).
  • --contact-sheet-pntsz, --cs-pntsz NUMBER — font point size (IM: -pointsize).
  • --contact-sheet-shadow, --cs-shadow — set the shadow beneath a tile to simulate depth (IM: -shadow).
  • --contact-sheet-thm-fl, --cs-thm-fl COLOR — color to fill the text in generated thumbnail.
  • --contact-sheet-thm-fn, --cs-thm-fn STRING — render the generated thumbnail text with this font (IM: -font).
  • --contact-sheet-thm-grfr, --cs-thm-grfr COLOR — generated thumbnail background gradient COLOR-from.
  • --contact-sheet-thm-grto, --cs-thm-grto COLOR — generated thumbnail background gradient COLOR-to.
  • --contact-sheet-thm-text, --cs-thm-text STRING — generated thumbnail text.
  • --contact-sheet-rank, --cs-rank — run the ranking process according to the ranks defined with --contact-sheet-rank-file. the result is the colored frames of the thumbnails of contact sheets. 🔥
  • --contact-sheet-rank-file, --cs-rank-file — path to the file with ranks. its format is a "file rankcolor" per line. filename separated from the color by space or tabulation.
01.file.jpg        red

02.JPG             CornflowerBlue

03.jpg             aquamarine

04.file.JPG        green

only the files found in the file will be ranked.

✨ KEYWORDIZER ✨

  • --keywords, --no-keywords — whether to fill the Keywords tag. default is to not. be careful, since with this option enabled, the existing keywords are rewriten. the keywords are taken from the .keywords file, or from the file specified with the option --keywords-file.
  • -k, --keywords-file FILE — path to the file with keywords. its format is a keyword per line. the CR and LF symbols are removed. empty (only whitespace) lines are ignored. any leading and trailing whitespace is removed. for example, the line " _Test_ CRLF" is read as "_Test_". 🍓
  • --keywords-replace, --no-keywords-replace — replace the existing Keywords tag list rather than add new values to it. default is not to replace.

💅 RENAMING (the glow-up section)

  • -n or --name-template TEMPLATE — the template renrot uses to build your new file names. You can also stash it in the config file (the variable is Name Template). Default is %Y%m%d%H%M%S. For real-world glow-ups, peek at the "TEMPLATE EXAMPLES" section below. ✨

Here's every interpreted sequence, bestie, memorize them like your fave lyrics:

  • %% — a literal %
  • %# — a literal #
  • %C — the numeric part of the original file name. This one exists for cameras that don't hand over a FileNumber EXIF tag (currently literally every make except Canon). Those cameras spit out file names that start with letters and end with digits. No other symbols are allowed in file names except -, . and _.
  • %c — the ordinal number of the file in the processed file set (also see the --counter-fixed-field option).
  • %d — day of month (01-31).
  • %E — the value of the ExposureTime tag, if it's defined.
  • %e — old file extension.
  • %F — the value of the FNumber tag, if it's defined.
  • %H — hour (00-23).
  • %I — the value of the ISO tag, if it's defined.
  • %i — the FileNumber tag if it exists (otherwise it gets swapped out for the string "NA").
  • %M — minute (00-59).
  • %m — month (01-12).
  • %n — previous filename (the one from before renrot started processing).
  • %O — base part of the original filename (see %o). In other words, the first part from the beginning up to the last dot character.
  • %o — the name the file had before it was processed by renrot for the first time. If the file was processed only once, the tag RenRotFileNameOriginal is set to the original file name.
  • %S — second (00-59)
  • %W — the value of the WhiteBalance tag, if it's defined.
  • %Y — year with the century (1900, 1901, and so on)
  • %y — year without a century (00..99)

You can use the value of any EXIF tag as a name part. To do that you wrap the tag name in # signs while you're building the name template (see "TEMPLATE EXAMPLES").

⚠️ Be careful, okay? Any binary EXIF (like ThumbnaiImage) can produce totally unexpected results. Not the cute kind of surprise. 😭
  • --no-rename — do not rename files (default is to rename them to YYYYmmddHHMMSS.ext)
  • --counter-fixed-field, --no-counter-fixed-field — set a fixed length for the file counter used in file name templates (see %c). It's enabled by default. Use --no-counter-fixed-field to undo its effect.
  • --counter-start NUMBER — initial value for the file counter (default is 1)
  • --counter-step NUMBER — the step you increment the file counter by (default is 1)

🔄 ROTATING

  • -r or --rotate-angle ANGLE — define the angle to rotate files and thumbnails. Allowed values for ANGLE are 90, 180 or 270. Super useful for files that have no Orientation tag.
  • --rotate-thumb ANGLE — rotate only thumbnails. Allowed values for ANGLE are 90, 180 or 270 degrees. Use this when the files were already rotated but their thumbnails were not (the betrayal 😤).
  • --only-orientation — rotate by changing the value of the Orientation tag; no real rotation gets made. The sequence of values to rotate an image from normal (0 degrees) by 90 degrees clockwise is: 0 -> 90 -> 180 -> 270 -> 0. Which means: set the Orientation tag to 90cw after the first rotation, and bump that value by 90 every time the rotation is applied. For 270cw the rotation algorithm uses the reverted sequence. Rotation by 180cw triggers values in two pairs: 0 <-> 180 and 90 <-> 270. This option cannot be applied to mirror values of the Orientation tag.
🚫 Mirror values? Not today. This option cannot be applied to mirror values of the Orientation tag.
  • --trim, --no-trim — pass the -trim option to jpegtran(1), to trim if needed. By default, trimming is enabled. Use --no-trim to disable it.
  • --no-rotate — do not rotate images (default is to rotate according to EXIF data).

🏷️ TAG WRITER

  • --comment-file FILE — a file with commentaries. It's a low priority alias to TagFile = Comment: FILE.
  • --user-comment STRING — a low priority alias to --tag UserComment: STRING
  • -t or --tag TAG — see the section "TAGS" for the detailed description
  • --no-tags — no user's defined tags will be written.

🌈 TEMPLATE EXAMPLES

The name template

01.%c.%Y%m%d%H%M%S.%i.shtr-%E.f-%F.wb-%W.iso-%I

(where F stays for FNumber, E for ExposureTime, I for ISO and W for WhiteBalance) can produce the following names:

01.0021.20030414103656.NA.shtr-1by40.f-2.8.wb-Auto.iso-160.jpg

01.0024.20040131230857.100-0078.shtr-1by320.f-2.8.wb-Auto.iso-50.jpg

01.0022.20000820222108.NA.jpg

The name template

01.%c.%Y%m%d%H%M%S.%i.shtr-#ExposureTime#.f-#FNumber#.wb-#WhiteBalance#.iso-#ISO#

can produce the following names:

01.0021.20030414103656.NA.shtr-1_40.f-2.8.wb-Auto.iso-160.jpg

01.0024.20040131230857.100-0078.shtr-1_320.f-2.8.wb-Auto.iso-50.jpg

01.0022.20000820222108.NA.jpg

The aggregation template %Y%m%d produces the following aggregation: these three files

01.11.20030414103656.NA.jpg

01.12.20030414103813.NA.jpg

01.13.20030414103959.NA.jpg

will be stored in the directory 20030414, and

01.14.20040131130857.100-0078.jpg

01.15.20040131131857.100-0079.jpg

01.16.20040131133019.100-0080.jpg

will be stored in the directory 20040131.

⚙️ CONFIG

A configuration file can be used to set some variables. Renrot looks for its configuration file, named renrot.conf, in the system configuration directories /etc/renrot and /usr/local/etc/renrot, and in the .renrot. subdirectory of the current user home directory. An alternate configuration file can also be explicitly given using the --config-file option.

The configuration file consists of a set of case-insensitive keywords and their values separated by an equal sign. Each such keyword/value pair occupies a separate line. Boolean variables can have one of the following values: 0, No, False, Off, Disable for false, and 1, Yes, True, On, Enable for true.

The variables defined for use in the configuration file are, for example:

  • mtime — set to "Yes" for synchronize mtime with tags, otherwise set it to "No".
  • name template — file name template (see --name-template for the description).
  • trim — set to "Yes" to trim rotated images when using jpegtran(1).
  • aggregation mode — aggregation mode, possible values are: none, delta or template.
  • aggregation template — aggregation template, which defines the file aggregation (see --aggr-template for the description).
  • aggregation virtual — defines virtualization for the existing aggregation modes (see the --aggr-virtual option).
  • Tag, TagFile — refer to the section "TAGS" for the detailed description
  • include — include the named file.

🏷️ TAGS

A TAG is defined by the following combination: TagName [Group]: 'value'. The defined tags are selected to be set and writen to the EXIF tree using the command line option --tag and/or configuration file options Tag.

The syntax of the command line option --tag is:

--tag TagName [Group]: 'value'

The syntax of the configuration file option Tag:

Tag = TagName [Group]: 'value'

The parameters TagName and Group are passed to ExifTool as is. The name of the group must be enclosed in square brackets. Its value (after the semicolon) can be enclosed in single quotes.

The TagFile keyword allows to set multi-line tags from a file. Its syntax is:

TagFile = TagName [Group]: FILE

Here's the rundown of every tag you can use with the --tag option and the Tag keyword:

  • Copyright — copyright notes.
  • Comment — general comment.
  • UserComment — anything you would like to put as a comment.
  • CreatorContactInfoCiAdrCity — a city tag.
  • CreatorContactInfoCiAdrCtry — a country tag.
  • CreatorContactInfoCiAdrExtadr — extended address (usually includes street and apartment number).
  • CreatorContactInfoCiAdrPcode — zip code.
  • CreatorContactInfoCiAdrRegion — region.
  • CreatorContactInfoCiEmailWork — email.
  • CreatorContactInfoCiTelWork — phone number.
  • CreatorContactInfoCiUrlWork — URL.

Additionally, you can add any known tag here, using Tag or TagFile options as described above. Go off, bestie 💅

📁 FILES

  • The main configuration file renrot.conf is searched in the following locations (in the order of their appearance):
    • ~/.renrot/ — directory under user's home place
    • /usr/local/etc/renrot/ — system directory
    • /etc/renrot/ — system directory

Take into consideration, the files which are found will be loaded and parsed in the order when user's configuration has maximal priority.

  • Other configuration files with additional options could be included into main file:
    • colors.conf — colors setup for different output facilities
    • tags.conf — different tags setup
  • The following files could be placed locally in the working directory:
    • .keywords — file with keywords (see --keywords-file)
    • .rank — file with ranks (see --contact-sheet-rank-file)

🐛 BUGS

If you found some bug or have some nice propositions, you are welcome. Additionally, please, read the section RESTRICTIONS in file README.

  1. It seems that on FreeBSD 6, Perl versions 5.8.x exhibits a bug that causes renrot to crash. The overal amount of memory for the perl process increasing up to the user datasize limit (in FreeBSD default is 512M).

It seems to be a bug in perl's own malloc implementation. The bug should not occur in any perl which uses the system malloc (unless the system malloc has the same bug).

renrot aborts with the error message:

Out of memory during "large" request for XXXX bytes ...

This, however, does not happen with Perl v.5.6.x

  1. Some versions of ImageMagick render contact sheets incorrectly. it seems it is the question to ImageMagick.

👑 AUTHORS

Copyright 2005-2012, Zeus Panchenko, Andy Shevchenko.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

🦋 SEE ALSO

Image::ExifTool(3pm), exiftool(1), jpegtran(1), Image::Magick(3pm)

And that's a wrap, gorgeous 🫶 this page is perl v5.32.0, dated 2021-01-25, filed under RENROT(1p) — now go forth and rename, rotate and tag like the icon you are 💖

📦 where this page comes from