1RENROT(1) User Contributed Perl Documentation RENROT(1)
2
6 renrot - rename and rotate images according EXIF data
7
9 renrot [OPTIONS] [[--] FILE1 FILE2 ...]
10
12 Renrot is intended to work with a set of files containing EXIF data and
13 can do two things to them -- rename and rotate. A set of files can be
14 given either explicitly or using the --extension option, which select
15 the files with the given suffix. Renrot operates on files in current
16 working directory, unless given the --work-directory option, which
17 changes this default.
18 Renrot renames input files using a flexible name template (which, among
20 others, uses DateTimeOriginal and FileModifyDate EXIF tags, if they
21 exist, otherwise names the file according to the current timestamp).
22 Further, renrot can aggregate files according to the shooting time
23 period or to a given template.
24 Additionally, it rotates files and their thumbnails, as per Orientation
26 EXIF tag. If that tag is absent, the program allows to set rotation
27 parameters using --rotate-angle and --rotate-thumb command line
28 options. This is currently implemented only for JPEG format.
29 The program can also place commentaries into the following locations:
31 - Commentary tag from file (see --comment-file option)
33 - UserComment tag from configuration variable (see "TAGS" section)
35 Personal details may be specified via XMP tags defined in a
37 configuration file, see "TAGS" section.
38 In addition, renrot can aggregate all files in different directories,
40 according to a given date/time pattern template, set with
41 --aggr-template.
42
44 -c or --config-file FILE
45 Path to the configuration file.
46 -d or --work-directory DIR
48 Define the working directory.
49 --exclude FILE
51 Specify files to exclude. Wildcards are not allowed. If a set of
52 files is given, there must be as many occurrences of this option as
53 there are files in the set.
54 --sub-fileset FILE
56 Get names of files to operate upon from FILE. The file must contain
57 a file name per line. This option is useful when you need to
58 process only a set of X from Y files in the directory. If
59 specified, the rest of files given in the command line is ignored.
60 -e or --extension EXTENSION
62 Process the files with given EXTENSION (JPG, jpeg, CRW, crw, etc).
63 Depending on the operating system, the extension search might or
64 might not be case-sensitive.
65 -n or --name-template TEMPLATE
67 A template to use for creating new file names while renaming. It
68 can also be defined in the configuration file (variable Name
69 Template). The default is %Y%m%d%H%M%S. For practical uses, see
70 "TEMPLATE EXAMPLES" section.
71 Interpreted sequences are:
73 %% a literal %
75 %# a literal #
77 %C Numeric part of the original file name. Implemented for
79 the sake of cameras, that do not supply FileNumber EXIF tag
80 (currently all makes, except Canon). Such cameras generate file
81 names starting with letters and ended with digits. No other
82 symbols are allowed in file names, except "-", "." and "_".
83 %c Ordinal number of file in the processed file set (see also
85 --counter-fixed-field option).
86 %d Day of month (01-31).
88 %E The value of ExposureTime tag, if defined.
90 %e Old file extension
92 %F The value of FNumber tag, if defined.
94 %H Hour (00-23).
96 %I The value of ISO tag, if defined.
98 %i FileNumber tag if exists (otherwise, it is replaced by
100 string "NA").
101 %M Minute (00-59).
103 %m Month (01-12).
105 %n Previous filename (the one before renrot started
107 processing).
108 %O Base part of the original filename (see %o). In other
110 words, the first part from the beginning to the last dot
111 character.
112 %o The name file had before it was processed by renrot for
114 the first time. If the file was processed only once, the tag
115 RenRotFileNameOriginal is set to the original file name.
116 %S Second (00-59)
118 %W The value of WhiteBalance tag, if defined.
120 %Y Year with the century (1900, 1901, and so on)
122 %y Year without a century (00..99)
124 You can use value of any EXIF tag to be included as name part.
126 To do that you need to embrace tag name with sign "#", while
127 building name template (see "TEMPLATE EXAMPLES").
128 Be careful, since any binary EXIF (like ThumbnaiImage) can
130 produce totally unexpected results.
131 --no-rename
133 Do not rename files (default is to rename them to
134 YYYYmmddHHMMSS.ext)
135 --counter-fixed-field, --no-counter-fixed-field
137 Set fixed length for file counter, used in file name templates (see
138 %c). It is enabled by default. Use --no-counter-fixed-field to
139 undo its effect.
140 --counter-start NUMBER
142 Initial value for the file counter (default is 1)
143 --counter-step NUMBER
145 Step to increment file counter with (default is 1)
146 -r or --rotate-angle ANGLE
148 Define the angle to rotate files and thumbnails. Allowed values for
149 ANGLE are 90, 180 or 270. It is useful for files not having
150 Orientation tag.
151 --rotate-thumb ANGLE
153 Rotate only thumbnails. Allowed values for ANGLE are 90, 180 or 270
154 degrees. Use if the files which were already rotated, but their
155 thumbnails were not.
156 --only-orientation
158 Rotate by changing the value of Orientation tag, no real rotation
159 will be made. The sequence of values to rotate an image from normal
160 (0 degrees) by 90 degrees clockwise is: 0 -> 90 -> 180 -> 270 -> 0.
161 It means. set Orientation tag to 90cw after the first rotation, and
162 increase that value by 90 each time the rotation is applied. For
163 270cw the rotation algorithm uses the reverted sequence. Rotation
164 by 180cw triggers values in two pairs: 0 <-> 180 and 90 <-> 270.
165 This option cannot be applied to mirror values of Orientation tag.
166 --trim, --no-trim
168 Pass the "-trim" option to jpegtran(1), to trim if needed. By
169 default, trimming is enabled. Use --no-trim to disable it.
170 --no-rotate
172 Do not rotate images (default is to rotate according to EXIF data).
173 --mtime, --no-mtime
175 Defines whether to set the file's mtime, using DateTimeOriginal tag
176 value. Use --no-mtime to set it to current time stamp after
177 processing.
178 --no-renrot or --nochg
180 Do not rename, rotate, tag and mtime images. It saves files from
181 any changes while allows to do aggregation, contact sheet
182 generation e.t.c.
183 --keywordize, --no-keywordize
185 Whether to keywordize. Default is to not. Be careful, since with
186 this option enabled, the existing keywords are rewriten. The
187 keywords are taken from .keywords file or file specified with
188 option --keywords-file.
189 -k or --keywords-file FILE
191 Path to the file with keywords. Its format is a keyword per line.
192 The CR and LF symbols are removed. Empty (only whitespace) lines
193 are ignored. Any leading and trailing whitespace is removed. For
194 example, the line " _Test_ CRLF" is read as "_Test_".
195 --keywords-replace, --no-keywords-replace
197 Replace existing Keywords tag list rather than add new values to
198 it. Default is not to replace.
199 --aggr-mode MODE
201 Run aggregation process in given MODE. Possible values are: none,
202 delta or template.
203 --aggr-delta NUMBER
205 Aggregation time delta, in seconds. Files with DateTimeOriginal and
206 ones of the previous file delta, greater than --aggr-delta are
207 placed in the directories, with the names are constructed by
208 concatenating the value of the --aggr-directory option and the
209 directory name counter.
210 --aggr-directory DIR
212 Aggregation directory name prefix (default is Images), have to be
213 on the same file system (or on the file system which supports
214 symbolic links in case of virtual aggregation), relative to the
215 current working directory or an absolute path.
216 -a or --aggr-template TEMPLATE
218 File name template to use for file aggregation. Images are
219 aggregated by date/time patterns. You may use combination of %d,
220 %H, %M, %m, %S, %Y, and %y meta-characters. The template can also
221 be defined in the configuration file (see Aggregation Template
222 variable). The default is %Y%m%d. For the detailed description,
223 refer to --name-template option. For practical uses, see "TEMPLATE
224 EXAMPLES" section.
225 --aggr-virtual, --no-aggr-virtual
227 Defines virtualization for existent aggregation modes. The main
228 effect of --aggr-virtual is that any files to be aggregated remain
229 untouched in their places, and relative symbolic links pointing to
230 them are stored in the directory tree created. Use
231 --no-aggr-virtual to prevent virtualization.
232 --comment-file FILE
234 File with commentaries. It is a low priority alias to TagFile =
235 Comment: FILE.
236 --user-comment STRING
238 A low priority alias to --tag UserComment: STRING
239 -t or --tag TAG
241 See the section "TAGS", for the detailed description
242 --no-tags
244 No user's defined tags will be written.
245 --use-color, --no-use-color
247 Colorize output. This does NOT work under Windows.
248 --dry-run
250 Do not do anything, only print would have been done.
251 -g or --generate-thumb
253 Generation and writing ThumbnailImage tag. The original value of
254 the ThumbnailImage tag remains intact. To rewrite it you need to
255 delete it first (look exiftool examples).
256 --use-ipc, --no-use-ipc
258 Rotate thumbnails using pipe, rather than files. This does NOT work
259 under Windows.
260 -v Increase debugging level by 1. Debugging levels from 1 to 4 are
262 internal levels, the levels from 5 till 9 are equivalent to levels
263 1-5 levels ExifTool with the maximum verbosity for renrot.
264 -? or --help
266 Display short usage summary and exit.
267 --version
269 Output version information and exit.
270
272 --contact-sheet, --no-contact-sheet or --cs, --no-cs
273 Create the contact sheet. Currently it works with ThumbnailImage
274 EXIFs and the files defined as thumbnails (see the option
275 --contact-sheet-thm, below)
276 --contact-sheet-file or --cs-file FILE
278 Base file name for montage files.
279 --contact-sheet-dir or --cs-dir DIR
281 Temporary directory for montage (created in the begining and
282 deleted at the end of the process)
283 --contact-sheet-thm or --cs-thm
285 Files for the montage are already thumbnails
286 Options bellow are native ImageMagic montage options look
288 ImageMagick documentation for montage options: montage --help
289 and http://www.imagemagick.org/
290 Note please, for COLOR use RGB triplets only like 000 for the
292 black or F00 for the red.
293 --contact-sheet-tile or --cs-tile GEOMETRY
295 Tile MxN (IM: -tile)
296 --contact-sheet-title or --cs-title STRING
298 Set the title of the contact sheet (IM: -title).
299 --contact-sheet-bg or --cs-bg COLOR
301 Background color (IM: -background).
302 --contact-sheet-bd or --cs-bd COLOR
304 Border color (IM: -bordercolor).
305 --contact-sheet-mt or --cs-mt COLOR
307 Frame color (IM: -mattecolor).
308 --contact-sheet-fn or --cs-fn STRING
310 Render text with this font (IM: -font).
311 --contact-sheet-fl or --cs-fl COLOR
313 Color to fill the text (IM: -fill).
314 --contact-sheet-lb or --cs-lb STRING
316 Assign a label to an image (IM: -label).
317 --contact-sheet-fr or --cs-fr GEOMETRY
319 Surround image with an ornamental border in N pixels (IM: -frame).
320 --contact-sheet-pntsz or --cs-pntsz NUMBER
322 Font point size (IM: -pointsize).
323 --contact-sheet-shadow or --cs-shadow
325 Set the shadow beneath a tile to simulate depth (IM: -shadow).
326 --contact-sheet-thm-fl or --cs-thm-fl COLOR
328 Color to fill the text in generated thumbnail.
329 --contact-sheet-thm-fn or --cs-thm-fn STRING
331 Render the generated thumbnail text with this font (IM: -font).
332 --contact-sheet-thm-grfr or --cs-thm-grfr COLOR
334 Generated thumbnail background gradient COLOR-from
335 --contact-sheet-thm-grto or --cs-thm-grto COLOR
337 Generated thumbnail background gradient COLOR-to
338 --contact-sheet-thm-text or --cs-thm-text STRING
340 Generated thumbnail text
341 --contact-sheet-rank or --cs-rank
343 Run ranking process according to the ranks defined with
344 --contact-sheet-rank-file The result is the colored frames of the
345 thumbnails of contact sheets.
346 --contact-sheet-rank-file or --cs-rank-file
348 Path to the file with ranks. Its format is a "file rankcolor" per
349 line. Filename separated from the color by space or tabulation.
350 01.file.jpg red
352 02.JPG CornflowerBlue
354 03.jpg aquamarine
356 04.file.JPG green
358 Only the files found in the file will be ranked.
360
362 The name template "01.%c.%Y%m%d%H%M%S.%i.shtr-%E.f-%F.wb-%W.iso-%I"
363 (where F stays for FNumber, E for ExposureTime, I for ISO and W for
364 WhiteBalance) can produce the following names:
365 01.0021.20030414103656.NA.shtr-1by40.f-2.8.wb-Auto.iso-160.jpg
367 01.0024.20040131230857.100-0078.shtr-1by320.f-2.8.wb-Auto.iso-50.jpg
369 01.0022.20000820222108.NA.jpg
371 The name template
373 "01.%c.%Y%m%d%H%M%S.%i.shtr-#ExposureTime#.f-#FNumber#.wb-#WhiteBalance#.iso-#ISO#"
374 can produce the following names:
375 01.0021.20030414103656.NA.shtr-1_40.f-2.8.wb-Auto.iso-160.jpg
377 01.0024.20040131230857.100-0078.shtr-1_320.f-2.8.wb-Auto.iso-50.jpg
379 01.0022.20000820222108.NA.jpg
381 The aggregation template "%Y%m%d" produces the following aggregation:
383 these three files
385 01.11.20030414103656.NA.jpg
387 01.12.20030414103813.NA.jpg
389 01.13.20030414103959.NA.jpg
391 will be stored in the directory 20030414, and
393 01.14.20040131130857.100-0078.jpg
395 01.15.20040131131857.100-0079.jpg
397 01.16.20040131133019.100-0080.jpg
399 will be stored in the directory 20040131.
401
403 A configuration file can be used to set some variables. Renrot looks
404 for its configuration file, named renrot.conf, in system configuration
405 directories /etc/renrot and </usr/local/etc/renrot>, and in
406 subdirectory .renrot. of the current user home directory. An alternate
407 configuration file can also be explicitly given using the --config-file
408 option.
409 The configuration file consists of a set of case-insensive keywords and
411 their values separated by equal sign. Each such keyword/value pair
412 occupies a separate line. Boolean variables can have one of the
413 following values: 0, No, False, Off for false, and 1, Yes, True, On for
414 true.
415 The variables defined for use in configuration file are:
417 mtime
419 Set to "Yes" for synchronize mtime with tags, otherwise set it to
420 "No".
421 name template
423 File name template (see --name-template, for the description).
424 trim
426 Set to "Yes" to trim rotated images when using jpegtran(1).
427 aggregation mode
429 Aggregation mode, possible values are: none, delta or template.
430 aggregation template
432 Aggregation template, which defines the file aggregation (see
433 --aggr-template, for the description).
434 aggregation virtual
436 Defines virtualization for the existing aggregation modes (see the
437 --aggr-virtual option).
438 Tag, TagFile
440 Refer to the section "TAGS", for the detailed description
441 include
443 Include the named file.
444
446 A TAG is defined by the following combination: TagName [Group]:
447 'value'. The defined tags are selected to be set and writen to the
448 EXIF tree using the command line option --tag and/or configuration file
449 options Tag.
450 The syntax of the command line option --tag is:
452 --tag TagName [Group]: 'value'
454 The syntax of the configuration file option Tag:
456 Tag = TagName [Group]: 'value'
458 The parameters TagName and Group are passed to ExifTool as is. The name
460 of the group must be enclosed in square brackets. Its value (after the
461 semicolon) can be enclosed in single quotes.
462 The TagFile keyword allows to set multi-line tags from a file. Its
464 syntax is:
465 TagFile = TagName [Group]: FILE
467 The following table summarizes the tags that can be used with the --tag
469 option and Tag keyword:
470 Copyright
472 Copyright notes.
473 Comment
475 General comment.
476 UserComment
478 Anything you would like to put as a comment.
479 CreatorContactInfoCiAdrCity
481 A city tag.
482 CreatorContactInfoCiAdrCtry
484 A country tag.
485 CreatorContactInfoCiAdrExtadr
487 Extended address (usually includes street and apartment number).
488 CreatorContactInfoCiAdrPcode
490 Zip code.
491 CreatorContactInfoCiAdrRegion
493 Region.
494 CreatorContactInfoCiEmailWork
496 Email.
497 CreatorContactInfoCiTelWork
499 Phone number.
500 CreatorContactInfoCiUrlWork
502 URL.
503 Additionally, you can add any known tag here, using Tag or TagFile
505 options as described above.
506
508 · The main configuration file renrot.conf is searched in the
509 following locations (in the order of their appearence):
510 ~/.renrot/
512 directory under user's home place
513 /usr/local/etc/renrot/
515 system directory
516 /etc/renrot/
518 system directory
519 · Other configuration files with additional options could be included
521 into main file:
522 colors.conf
524 colors setup for different output facilities
525 tags.conf
527 different tags setup
528 · The following files could be placed locally in the working
530 directory:
531 .keywords
533 file with keywords (see --keywords-file)
534 .rank
536 file with ranks (see --contact-sheet-rank-file)
537
539 If you found some bug or have some nice propositions, you are welcome.
540 Additionally, please, read the section RESTRICTIONS in file README.
541 1. It seems that on FreeBSD 6, Perl versions 5.8.x exhibits a bug that
543 causes renrot to crash. The overal amount of memory for the perl
544 process increasing up to the user datasize limit (in FreeBSD default is
545 512M).
546 It seems to be a bug in perl's own malloc implementation. The bug
548 should not occur in any perl which uses the system malloc (unless the
549 system malloc has the same bug).
550 2. Some versions of ImageMagick render contact sheets incorrectly. it
552 seems it is the question to ImageMagick.
553 renrot aborts with the error message:
555 Out of memory during "large" request for XXXX bytes ...
557 This, however, does not happen with Perl v.5.6.x
559
561 Copyright 2005-2008, Zeus Panchenko, Andy Shevchenko.
562 This program is free software; you can redistribute it and/or modify it
564 under the same terms as Perl itself.
565
567 Image::ExifTool(3pm), exiftool(1), jpegtran(1), Image::Magick(3pm)
568
570 Hey! The above document had some coding errors, which are explained
571 below:
572 Around line 2612:
574 '=item' outside of any '=over'
575 Around line 2732:
577 You forgot a '=back' before '=head1'
578 You forgot a '=back' before '=head1'
580perl v5.12.1 2008-10-06 RENROT(1)