Provided by: renrot_1.1-2_all bug

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.

       -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)

       -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).

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

       --keywordize, --no-keywordize
           Whether to keywordize. 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.

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

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

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

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.

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 for false, and 1, Yes,
       True, On for true.

       The variables defined for use in configuration file are:

       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:

       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.

FILES

       •   The main configuration file renrot.conf is searched in the following locations (in the
           order of their appearence):

           ~/.renrot/
               directory under user's home place

           /usr/local/etc/renrot/
               system directory

           /etc/renrot/
               system directory

       •   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).

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

       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

AUTHORS

       Copyright 2005-2008, 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)

POD ERRORS

       Hey! The above document had some coding errors, which are explained below:

       Around line 2612:
           '=item' outside of any '=over'

       Around line 2732:
           You forgot a '=back' before '=head1'

           You forgot a '=back' before '=head1'