Section: User Contributed Perl Documentation (1p)
Return to Main Contents
renrot - rename and rotate images according EXIF data
renrot [OPTIONS] [[--] FILE1 FILE2 ...]
RenRot is intended to work with files of --extension extension,
containing EXIF data and can do two things with them - rename and rotate. It
runs in batch mode in current or set with --work-directory directory, as
well as selective mode for separate files given as arguments in command line.
RenRot renames files according the DateTimeOriginal and FileModifyDate EXIF
tags, if they exists. Otherwise, the name will be set according to the current
time stamp and will look as YYYYmmddHHMMSS.XXXX.ext, where XXXX is whether
file ID, if exists in EXIF (as for Canon) or incremental suffix to the name
Additionally, it rotates files and their thumbnails, accordingly Orientation
EXIF tag. When the tag is absent or miss set, the program allows to rotate the
file as well as it's thumbnail via --rotate-angle and --rotate-thumb
options. Now implemented only for JPEG format.
The script, also, can place the commentary into:
- Commentary tag from file (see --comment-file option)
- UserComment tag from configuration variable (see ``TAGS'' section)
Personal details could be specified via XMP tags defined in a configuration
file, see ``TAGS'' section.
In addition, RenRot can aggregate all files in directories according the given
date/time pattern template, set with --aggr-template.
- -c or --config-file FILE
path to the configuration file
- -d or --work-directory DIR
define the working directory
- --exclude FILE
specify files to exclude. No wildcards are available. For set of files option
must be occured same times as files given.
- -e or --extension EXTENSION
extension of files to be processed, JPG, jpeg, CRW, crw, or any other you need.
The given extension is case-sensivity in related filesystems.
- -n or --name-template TEMPLATE
template, which is used for file name building while renaming. It could be
defined in configuration file (the variable Name Template). The default is
%Y%m%d%H%M%S. For practical results see ``TEMPLATE EXAMPLES'' section.
Interpreted sequences are:
%% a literal %
%C the numeric part of the original file name. Implemented for the sake
of the cameras, where no FileNumber EXIF tag is present (currently all except
Canon). Filename would started by letters and ended by digits. No other
symbols are not allowed, except "-", "." and "_".
%c file order number in the processed file set (also see
%d day of the month (01-31)
%E ExposureTime tag value if defined
%e old file extension
%F FNumber tag value if defined
%H hour (00-23)
%I ISO tag value if defined
%i FileNumber tag if exists (otherwise, it'll be replaced by string
%M minute (00-59)
%m month (01-12)
%n previous filename (the one before the current processing with renrot)
%O base part of the original filename (see %o). In other words the
first part from the begin to the last dot symbol.
%o the name, file had before first processing with renrot. If the file
was processed with renrot if only once, the tag RenRotFileNameOriginal written
with the file name.
%S second (00-59)
%W WhiteBalance tag value if defined
%Y year (1900, 1901, and so on)
%y last two digits of year (00..99)
no rename needed, default is to rename to the YYYYmmddHHMMSS.ext
- --counter-fixed-field, --no-counter-fixed-field
set fixed length for file counter (corresponding to %c), where it is used
in templates. It's enabled by default. Use --no-counter-fixed-field to set
dynamic width of field.
- --counter-start NUMBER
the number to start count the files, to be renamed, from (default is 1)
- --counter-step NUMBER
the step for the counter of the files to be renamed (default is 1)
- -r or --rotate-angle ANGLE
define the angle to rotate file and the thumbnail on 90, 180 or 270. It's for
the files where no Orientation tag is set right way.
- --rotate-thumb ANGLE
rotate only thumbnail by 90, 180 or 270 degree. It's for the files which were
rotated, but thumbnail wasn't.
rotate by changing Orientation tag, no real rotation will be made. The
sequence of values when rotating image from normal (0 degrees) by 90cw is: 0
-> 90 -> 180 -> 270 -> 0. It means set Orientation tag to 90cw after first
usage of rotation by 90cw and so on. For 270cw rotation algorithm uses
reversed sequence. Rotation by 180cw triggers values in two pairs: 0 <-> 180
and 90 <-> 270. This option can't be applied to mirror values of Orientation
- --trim, --no-trim
pass option "-trim" to jpegtran(1) to trim if needed. By default trimming
is on. Use --no-trim to negate described behaviour.
no rotation needed, default is to rotate according EXIF data
- --mtime, --no-mtime
defines, whether to set mtime of the file, using DateTimeOriginal tag value.
Use --no-mtime to set it to current time stamp after processing.
- --keywordize, --no-keywordize
whether to keywordize. Default is to not. Be careful, since this option when
on, rewrites existing keywords, not adds. The keywords are taken from
.keywords file or file specified with option --keywords-file.
- -k or --keywords-file FILE
path to the file with keywords (format is each keyword per line). The CR and
LF symbols are removed. The empty (only whitespace) lines are skiped. The lead
and tail whitespaces are also removed. For example, line " _Test_ CRLF"
will be transformed to "_Test_".
- --keywords-replace, --no-keywords-replace
Replace existing tag Keywords list rather than add the values to it. Default
is to not replace.
- --aggr-mode MODE
run aggregation process in given MODE. Possible values are: none, delta or
- --aggr-delta NUMBER
aggregation time delta in seconds (file with DateTimeOriginal and the one of
the previous file delta, greater than --aggr-delta is placed to the
--aggr-directory followed by directory name counter).
- --aggr-directory DIR
counterless aggregation directory name (default is Images)
- -a or --aggr-template TEMPLATE
template, which is used for file aggregation. Aggregation fulfils according
date/time patterns. You may use combination of %d, %H, %M, %m,
%S, %Y, and/or %y keys. It could be defined in configuration file
(the variable Aggregation Template). The default is %Y%m%d. For detailed
description, please, turn to --name-template option. For practical results
see ``TEMPLATE EXAMPLES'' section.
- --aggr-virtual, --no-aggr-virtual
defines virtualization for existent aggregation modes. If set, than results of
the aggregation are placed into the directory defined with command line option
--aggr-virtual-directory or configuration file option aggregation virtual
directory and further occures the things, which have to occure with the
choosen aggregation mode but without this option. The difference is that the
files to be aggregated are remains untouched in their places, and symlinks are
placed to the directory tree created instead. Use --no-aggr-virtual to
- --aggr-virtual-directory DIR
defines the directory, the results of the virtual aggregation to be placed to
- --comment-file FILE
file with commentary. The low priority alias to TagFile = Comment: FILE.
- --user-comment STRING
low priority alias to --tag UserComment: STRING
- -t or --tag TAG
look ``TAGS'' section for the detailed description
no tags will be written. Default is to write tags.
- --use-color, --no-use-color
colorized output. This NOT works under Win32.
show what would have been happened (no real actions)
- --use-ipc, --no-use-ipc
thumbnail rotation via pipe, rather than via file. This NOT works under Win32.
one or more "-v" sets debug level. From 1 to 4 - internal levels, 5 till 9 -
equal to 1-5 levels for ExifTool plus maximum verbosity for renrot.
- -? or --help
display quick help and exit
output version information and exit
The name template "01.%c.%Y%m%d%H%M%S.%i.%E%F%W%I" may produces following
where F stays for FNumber, E for ExposureTime, I for ISO and
W for WhiteBalance.
The aggregation template "%Y%m%d" produces following aggregation:
these three files
will be put to the directory 20030414, and
will be put to the directory 20040131.
Configuration file could be used to set some variables. Configuration file is
just set of case-insensivity keys and its values separated by equal sign.
Boolean variables can be defined via following keywords: 0, No, False, Off for
false, and 1, Yes, True, On for true. RenRot looks for file named
renrot.conf in system directories such as /etc/renrot and
/usr/local/etc/renrot, and in home directory of the user in subdirectory
.renrot. User defined configuration file can be given via --config-file
option. In the last case the given file is used only.
These variables could be set via configuration file:
set to "Yes" for synchronize mtime with tags, otherwise set it to "No"
- name template
name template, which defines the file name look (see --name-template)
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
- aggregation virtual
defines virtualization for existent aggregation modes (see --aggr-virtual option)
- aggregation virtual directory
defines the directory for virtual aggregation (see --aggr-virtual-directory option>
- Tag, TagFile
look ``TAGS'' section for the detailed description
defines the file that would be included in place as part of configuration
TAG is defined by the next combination: TagName [Group]: 'value'.
Using command line option --tag and/or configuration file options Tag
it's possible to choose defined tags to be set and writen to the EXIF tree.
The syntax of the command line option --tag:
--tag TagName [Group]: 'value'
The syntax of the configuration file option Tag:
Tag = TagName [Group]: 'value'
Parameters TagName and Group are passed to ExifTool as is. Name of the
group have to be enclosed in square brackets. The value (after semicolon)
of the tag could be enclosed in tics.
Also the option TagFile was defined to give posibility to fill value of some
tags with multi line content from the file. The syntax as follows:
TagFile = TagName [Group]: FILE
Bellow are the tags to make sense to use with the options --tag and Tag:
anything you'd wanna put as commentary
extended address (usually street and apartments)
Additionally you can add any known tag here to be passed by Tag or
TagFile options in the format described above.
Configuration file placement (with high priority first):
If you found some bug or have nice proposition, you are welcome. Additionally,
please, read RESTRICTIONS section in README.
It seems that for Perl v.5.8.7 and 5.8.8, at least on FreeBSD 6 the bug, which
cause crash of the renrot, exists.
In case when total amount of the files size to process is bigger than RAM
amount, the renrot falls with error:
Out of memory during ``large'' request for XXXX bytes ...
This doesn't occure for Perl v.5.6.1.
Copyright 2005-2006, Zeus Panchenko, Andy Shevchenko.
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
Image::ExifTool (3pm), exiftool (1), jpegtran (1)
- TEMPLATE EXAMPLES
- SEE ALSO
This document was created by
using the manual pages.
Time: 13:58:51 GMT, February 15, 2008