NAME

SYNOPSIS

DESCRIPTION

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:

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.

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:

--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-#ExposureTime#.f-#FNumber#.wb-#WhiteBalance#.iso-#ISO#" can produce the following names:

The aggregation template "%Y%m%d" produces the following aggregation:

these three files

will be stored in the directory 20030414, and

will be stored in the directory 20040131.

CONFIG

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

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

The syntax of the configuration file option Tag:

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:

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

•

Other configuration files with additional options could be included into main file:

•

The following files could be placed locally in the working directory:

BUGS

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:

2.

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

AUTHORS

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

SEE ALSO