DragonFly On-Line Manual Pages

RENROT(1) User Contributed Perl Documentation RENROT(1)

NAME
renrot - rename and rotate images according EXIF data

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

DESCRIPTION
Renrot is intended to work with a set of files containing EXIF data and
can do two things to them -- rename and rotate. A set of files can be
given either explicitly or using the --extension option, which select
the files with the given suffix. Renrot operates on files in current
working directory, unless given the --work-directory option, which
changes this default.

Renrot renames input files using a flexible name template (which, among
others, uses DateTimeOriginal and FileModifyDate EXIF tags, if they
exist, otherwise names the file according to the current timestamp).
Further, renrot can aggregate files according to the shooting time
period or to a given template.

Additionally, it rotates files and their thumbnails, as per Orientation
EXIF tag. If that tag is absent, the program allows to set rotation
parameters using --rotate-angle and --rotate-thumb command line
options. This is currently implemented only for JPEG format.

The program can also place commentaries into the following locations:

- Commentary tag from file (see --comment-file option)

- UserComment tag from configuration variable (see "TAGS" section)

Personal details may be specified via XMP tags defined in a
configuration file, see "TAGS" section.

In addition, renrot can aggregate all files in different directories,
according to a given date/time pattern template, set with
--aggr-template.

OPTIONS
-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. Wildcards are not allowed. If a set of
files is given, there must be as many occurrences of this option as
there are files in the set.

--sub-fileset FILE
Get names of files to operate upon from FILE. The file must contain
a file name per line. This option is useful when you need to
process only a set of X from Y files in the directory. If
specified, the rest of files given in the command line is ignored.

-e or --extension EXTENSION
Process the files with 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 DateTimeOriginal tag
value. Use --no-mtime to set it to current time stamp after
processing.

--no-renrot or --nochg
Do not rename, rotate, tag and mtime images. It saves files from
any changes while allows to do aggregation, contact sheet
generation e.t.c.

--use-color, --no-use-color
Colorize output. This does NOT work under Windows.

--dry-run
Do not do anything, only print would have been done.

-g or --generate-thumb
Generation and writing ThumbnailImage tag. The original value of
the ThumbnailImage tag remains intact. To rewrite it you need to
delete it first (look exiftool examples).

--use-ipc, --no-use-ipc
Rotate thumbnails using pipe, rather than files. This does NOT work
under Windows.

-v Increase debugging level by 1. Debugging levels from 1 to 4 are
internal levels, the levels from 5 till 9 are equivalent to levels
1-5 levels ExifTool with the maximum verbosity for renrot.

-? or --help
Display short usage summary and exit.

--version
Output version information and exit.

AGGREGATION
--aggr-mode MODE
Run aggregation process in 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 are 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), have 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 or --aggr-template TEMPLATE
File name template to use for file aggregation. Images are
aggregated by date/time patterns. You may use combination of %d,
%H, %M, %m, %S, %Y, and %y meta-characters. The template can also
be defined in the configuration file (see Aggregation Template
variable). The default is %Y%m%d. For the detailed description,
refer to --name-template option. For practical uses, see "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 or --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 or --cs-file FILE
Base file name for montage files.

--contact-sheet-dir or --cs-dir DIR
Temporary directory for montage (created in the begining and
deleted at the end of the process)

--contact-sheet-thm or --cs-thm
Files for the montage are already thumbnails

Options bellow are native ImageMagic montage options look 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.

--contact-sheet-tile or --cs-tile GEOMETRY
Tile MxN (IM: -tile)

--contact-sheet-title or --cs-title STRING
Set the title of the contact sheet (IM: -title).

--contact-sheet-bg or --cs-bg COLOR
Background color (IM: -background).

--contact-sheet-bd or --cs-bd COLOR
Border color (IM: -bordercolor).

--contact-sheet-mt or --cs-mt COLOR
Frame color (IM: -mattecolor).

--contact-sheet-fn or --cs-fn STRING
Render text with this font (IM: -font).

--contact-sheet-fl or --cs-fl COLOR
Color to fill the text (IM: -fill).

--contact-sheet-lb or --cs-lb STRING
Assign a label to an image (IM: -label).

--contact-sheet-fr or --cs-fr GEOMETRY
Surround image with an ornamental border in N pixels (IM: -frame).

--contact-sheet-pntsz or --cs-pntsz NUMBER
Font point size (IM: -pointsize).

--contact-sheet-shadow or --cs-shadow
Set the shadow beneath a tile to simulate depth (IM: -shadow).

--contact-sheet-thm-fl or --cs-thm-fl COLOR
Color to fill the text in generated thumbnail.

--contact-sheet-thm-fn or --cs-thm-fn STRING
Render the generated thumbnail text with this font (IM: -font).

--contact-sheet-thm-grfr or --cs-thm-grfr COLOR
Generated thumbnail background gradient COLOR-from

--contact-sheet-thm-grto or --cs-thm-grto COLOR
Generated thumbnail background gradient COLOR-to

--contact-sheet-thm-text or --cs-thm-text STRING
Generated thumbnail text

--contact-sheet-rank or --cs-rank
Run 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 or --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 Keywords tag. Default is to not. Be careful, since
with this option enabled, the existing keywords are rewriten. 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. 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 existing Keywords tag list rather than add new values to
it. Default is not to replace.

RENAMING
-n or --name-template TEMPLATE
A template to use for creating new file names while renaming. It
can also be defined in the configuration file (variable Name
Template). The default is %Y%m%d%H%M%S. For practical uses, see
"TEMPLATE EXAMPLES" section.

Interpreted sequences are:

%% a literal %

%# a literal #

%C Numeric part of the original file name. Implemented for
the sake of cameras, that do not supply FileNumber EXIF tag
(currently all makes, except Canon). Such cameras generate file
names starting with letters and ended with digits. No other
symbols are allowed in file names, except "-", "." and "_".

%c Ordinal number of file in the processed file set (see also
--counter-fixed-field option).

%d Day of month (01-31).

%E The value of ExposureTime tag, if defined.

%e Old file extension

%F The value of FNumber tag, if defined.

%H Hour (00-23).

%I The value of ISO tag, if defined.

%i FileNumber tag if exists (otherwise, it is replaced by
string "NA").

%M Minute (00-59).

%m Month (01-12).

%n Previous filename (the one before renrot started
processing).

%O Base part of the original filename (see %o). In other
words, the first part from the beginning to the last dot
character.

%o The name 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 WhiteBalance tag, if defined.

%Y Year with the century (1900, 1901, and so on)

%y Year without a century (00..99)

You can use value of any EXIF tag to be included as name part.
To do that you need to embrace tag name with sign "#", while
building name template (see "TEMPLATE EXAMPLES").

Be careful, since any binary EXIF (like ThumbnaiImage) can
produce totally unexpected results.

--no-rename
Do not rename files (default is to rename them to
YYYYmmddHHMMSS.ext)

--counter-fixed-field, --no-counter-fixed-field
Set fixed length for file counter, used in file name templates (see
%c). It is 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
Step to increment file counter with (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. It is useful for files not having
Orientation tag.

--rotate-thumb ANGLE
Rotate only thumbnails. Allowed values for ANGLE are 90, 180 or 270
degrees. Use if the files which were already rotated, but their
thumbnails were not.

--only-orientation
Rotate by changing the value of Orientation tag, no real rotation
will be made. The sequence of values to rotate an image from normal
(0 degrees) by 90 degrees clockwise is: 0 -> 90 -> 180 -> 270 -> 0.
It means. set Orientation tag to 90cw after the first rotation, and
increase that value by 90 each 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 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
File with commentaries. It is 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 system configuration
directories /etc/renrot and /usr/local/etc/renrot, and in subdirectory
.renrot. 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-insensive keywords and
their values separated by 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

The following table summarizes the tags that can be used with the --tag
option and Tag keyword:

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.

FILES
o 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.

o 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

o 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

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

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)

perl v5.20.2 2013-06-08 RENROT(1)

DragonFly On-Line Manual Pages

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

AGGREGATION

CONTACT SHEET GENERATOR

KEYWORDIZER

RENAMING

ROTATING

TAG WRITER

TEMPLATE EXAMPLES

CONFIG

TAGS

FILES

BUGS

AUTHORS

SEE ALSO