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 --mtime, --no-mtime
67 Defines whether to set the file's mtime, using DateTimeOriginal tag
68 value. Use --no-mtime to set it to current time stamp after
69 processing.
70 --no-renrot or --nochg
72 Do not rename, rotate, tag and mtime images. It saves files from
73 any changes while allows to do aggregation, contact sheet
74 generation e.t.c.
75 --use-color, --no-use-color
77 Colorize output. This does NOT work under Windows.
78 --dry-run
80 Do not do anything, only print would have been done.
81 -g or --generate-thumb
83 Generation and writing ThumbnailImage tag. The original value of
84 the ThumbnailImage tag remains intact. To rewrite it you need to
85 delete it first (look exiftool examples).
86 --use-ipc, --no-use-ipc
88 Rotate thumbnails using pipe, rather than files. This does NOT work
89 under Windows.
90 -v Increase debugging level by 1. Debugging levels from 1 to 4 are
92 internal levels, the levels from 5 till 9 are equivalent to levels
93 1-5 levels ExifTool with the maximum verbosity for renrot.
94 -? or --help
96 Display short usage summary and exit.
97 --version
99 Output version information and exit.
100
102 --aggr-mode MODE
103 Run aggregation process in given MODE. Possible values are: none,
104 delta or template.
105 --aggr-delta NUMBER
107 Aggregation time delta, in seconds. Files with DateTimeOriginal and
108 ones of the previous file delta, greater than --aggr-delta are
109 placed in the directories, with the names are constructed by
110 concatenating the value of the --aggr-directory option and the
111 directory name counter.
112 --aggr-directory DIR
114 Aggregation directory name prefix (default is Images), have to be
115 on the same file system (or on the file system which supports
116 symbolic links in case of virtual aggregation), relative to the
117 current working directory or an absolute path.
118 -a or --aggr-template TEMPLATE
120 File name template to use for file aggregation. Images are
121 aggregated by date/time patterns. You may use combination of %d,
122 %H, %M, %m, %S, %Y, and %y meta-characters. The template can also
123 be defined in the configuration file (see Aggregation Template
124 variable). The default is %Y%m%d. For the detailed description,
125 refer to --name-template option. For practical uses, see "TEMPLATE
126 EXAMPLES" section.
127 --aggr-virtual, --no-aggr-virtual
129 Defines virtualization for existent aggregation modes. The main
130 effect of --aggr-virtual is that any files to be aggregated remain
131 untouched in their places, and relative symbolic links pointing to
132 them are stored in the directory tree created. Use
133 --no-aggr-virtual to prevent virtualization.
134
136 --contact-sheet, --no-contact-sheet or --cs, --no-cs
137 Create the contact sheet. Currently it works with ThumbnailImage
138 EXIFs and the files defined as thumbnails (see the option
139 --contact-sheet-thm, below)
140 --contact-sheet-file or --cs-file FILE
142 Base file name for montage files.
143 --contact-sheet-dir or --cs-dir DIR
145 Temporary directory for montage (created in the begining and
146 deleted at the end of the process)
147 --contact-sheet-thm or --cs-thm
149 Files for the montage are already thumbnails
150 Options bellow are native ImageMagic montage options look ImageMagick
152 documentation for montage options: montage --help and
153 http://www.imagemagick.org/
154 Note please, for COLOR use RGB triplets only like 000 for the black or
156 F00 for the red.
157 --contact-sheet-tile or --cs-tile GEOMETRY
159 Tile MxN (IM: -tile)
160 --contact-sheet-title or --cs-title STRING
162 Set the title of the contact sheet (IM: -title).
163 --contact-sheet-bg or --cs-bg COLOR
165 Background color (IM: -background).
166 --contact-sheet-bd or --cs-bd COLOR
168 Border color (IM: -bordercolor).
169 --contact-sheet-mt or --cs-mt COLOR
171 Frame color (IM: -mattecolor).
172 --contact-sheet-fn or --cs-fn STRING
174 Render text with this font (IM: -font).
175 --contact-sheet-fl or --cs-fl COLOR
177 Color to fill the text (IM: -fill).
178 --contact-sheet-lb or --cs-lb STRING
180 Assign a label to an image (IM: -label).
181 --contact-sheet-fr or --cs-fr GEOMETRY
183 Surround image with an ornamental border in N pixels (IM: -frame).
184 --contact-sheet-pntsz or --cs-pntsz NUMBER
186 Font point size (IM: -pointsize).
187 --contact-sheet-shadow or --cs-shadow
189 Set the shadow beneath a tile to simulate depth (IM: -shadow).
190 --contact-sheet-thm-fl or --cs-thm-fl COLOR
192 Color to fill the text in generated thumbnail.
193 --contact-sheet-thm-fn or --cs-thm-fn STRING
195 Render the generated thumbnail text with this font (IM: -font).
196 --contact-sheet-thm-grfr or --cs-thm-grfr COLOR
198 Generated thumbnail background gradient COLOR-from
199 --contact-sheet-thm-grto or --cs-thm-grto COLOR
201 Generated thumbnail background gradient COLOR-to
202 --contact-sheet-thm-text or --cs-thm-text STRING
204 Generated thumbnail text
205 --contact-sheet-rank or --cs-rank
207 Run ranking process according to the ranks defined with
208 --contact-sheet-rank-file The result is the colored frames of the
209 thumbnails of contact sheets.
210 --contact-sheet-rank-file or --cs-rank-file
212 Path to the file with ranks. Its format is a "file rankcolor" per
213 line. Filename separated from the color by space or tabulation.
214 01.file.jpg red
216 02.JPG CornflowerBlue
218 03.jpg aquamarine
220 04.file.JPG green
222 Only the files found in the file will be ranked.
224
226 --keywords, --no-keywords
227 Whether to fill Keywords tag. Default is to not. Be careful, since
228 with this option enabled, the existing keywords are rewriten. The
229 keywords are taken from .keywords file or file specified with
230 option --keywords-file.
231 -k or --keywords-file FILE
233 Path to the file with keywords. Its format is a keyword per line.
234 The CR and LF symbols are removed. Empty (only whitespace) lines
235 are ignored. Any leading and trailing whitespace is removed. For
236 example, the line " _Test_ CRLF" is read as "_Test_".
237 --keywords-replace, --no-keywords-replace
239 Replace existing Keywords tag list rather than add new values to
240 it. Default is not to replace.
241
243 -n or --name-template TEMPLATE
244 A template to use for creating new file names while renaming. It
245 can also be defined in the configuration file (variable Name
246 Template). The default is %Y%m%d%H%M%S. For practical uses, see
247 "TEMPLATE EXAMPLES" section.
248 Interpreted sequences are:
250 %% a literal %
252 %# a literal #
254 %C Numeric part of the original file name. Implemented for
256 the sake of cameras, that do not supply FileNumber EXIF tag
257 (currently all makes, except Canon). Such cameras generate file
258 names starting with letters and ended with digits. No other
259 symbols are allowed in file names, except "-", "." and "_".
260 %c Ordinal number of file in the processed file set (see also
262 --counter-fixed-field option).
263 %d Day of month (01-31).
265 %E The value of ExposureTime tag, if defined.
267 %e Old file extension
269 %F The value of FNumber tag, if defined.
271 %H Hour (00-23).
273 %I The value of ISO tag, if defined.
275 %i FileNumber tag if exists (otherwise, it is replaced by
277 string "NA").
278 %M Minute (00-59).
280 %m Month (01-12).
282 %n Previous filename (the one before renrot started
284 processing).
285 %O Base part of the original filename (see %o). In other
287 words, the first part from the beginning to the last dot
288 character.
289 %o The name file had before it was processed by renrot for
291 the first time. If the file was processed only once, the tag
292 RenRotFileNameOriginal is set to the original file name.
293 %S Second (00-59)
295 %W The value of WhiteBalance tag, if defined.
297 %Y Year with the century (1900, 1901, and so on)
299 %y Year without a century (00..99)
301 You can use value of any EXIF tag to be included as name part.
303 To do that you need to embrace tag name with sign "#", while
304 building name template (see "TEMPLATE EXAMPLES").
305 Be careful, since any binary EXIF (like ThumbnaiImage) can
307 produce totally unexpected results.
308 --no-rename
310 Do not rename files (default is to rename them to
311 YYYYmmddHHMMSS.ext)
312 --counter-fixed-field, --no-counter-fixed-field
314 Set fixed length for file counter, used in file name templates (see
315 %c). It is enabled by default. Use --no-counter-fixed-field to
316 undo its effect.
317 --counter-start NUMBER
319 Initial value for the file counter (default is 1)
320 --counter-step NUMBER
322 Step to increment file counter with (default is 1)
323
325 -r or --rotate-angle ANGLE
326 Define the angle to rotate files and thumbnails. Allowed values for
327 ANGLE are 90, 180 or 270. It is useful for files not having
328 Orientation tag.
329 --rotate-thumb ANGLE
331 Rotate only thumbnails. Allowed values for ANGLE are 90, 180 or 270
332 degrees. Use if the files which were already rotated, but their
333 thumbnails were not.
334 --only-orientation
336 Rotate by changing the value of Orientation tag, no real rotation
337 will be made. The sequence of values to rotate an image from normal
338 (0 degrees) by 90 degrees clockwise is: 0 -> 90 -> 180 -> 270 -> 0.
339 It means. set Orientation tag to 90cw after the first rotation, and
340 increase that value by 90 each time the rotation is applied. For
341 270cw the rotation algorithm uses the reverted sequence. Rotation
342 by 180cw triggers values in two pairs: 0 <-> 180 and 90 <-> 270.
343 This option cannot be applied to mirror values of Orientation tag.
344 --trim, --no-trim
346 Pass the "-trim" option to jpegtran(1), to trim if needed. By
347 default, trimming is enabled. Use --no-trim to disable it.
348 --no-rotate
350 Do not rotate images (default is to rotate according to EXIF data).
351
353 --comment-file FILE
354 File with commentaries. It is a low priority alias to TagFile =
355 Comment: FILE.
356 --user-comment STRING
358 A low priority alias to --tag UserComment: STRING
359 -t or --tag TAG
361 See the section "TAGS", for the detailed description
362 --no-tags
364 No user's defined tags will be written.
365
367 The name template "01.%c.%Y%m%d%H%M%S.%i.shtr-%E.f-%F.wb-%W.iso-%I"
368 (where F stays for FNumber, E for ExposureTime, I for ISO and W for
369 WhiteBalance) can produce the following names:
370 01.0021.20030414103656.NA.shtr-1by40.f-2.8.wb-Auto.iso-160.jpg
372 01.0024.20040131230857.100-0078.shtr-1by320.f-2.8.wb-Auto.iso-50.jpg
374 01.0022.20000820222108.NA.jpg
376 The name template
378 "01.%c.%Y%m%d%H%M%S.%i.shtr-#ExposureTime#.f-#FNumber#.wb-#WhiteBalance#.iso-#ISO#"
379 can produce the following names:
380 01.0021.20030414103656.NA.shtr-1_40.f-2.8.wb-Auto.iso-160.jpg
382 01.0024.20040131230857.100-0078.shtr-1_320.f-2.8.wb-Auto.iso-50.jpg
384 01.0022.20000820222108.NA.jpg
386 The aggregation template "%Y%m%d" produces the following aggregation:
388 these three files
390 01.11.20030414103656.NA.jpg
392 01.12.20030414103813.NA.jpg
394 01.13.20030414103959.NA.jpg
396 will be stored in the directory 20030414, and
398 01.14.20040131130857.100-0078.jpg
400 01.15.20040131131857.100-0079.jpg
402 01.16.20040131133019.100-0080.jpg
404 will be stored in the directory 20040131.
406
408 A configuration file can be used to set some variables. Renrot looks
409 for its configuration file, named renrot.conf, in system configuration
410 directories /etc/renrot and /usr/local/etc/renrot, and in subdirectory
411 .renrot. of the current user home directory. An alternate configuration
412 file can also be explicitly given using the --config-file option.
413 The configuration file consists of a set of case-insensive keywords and
415 their values separated by equal sign. Each such keyword/value pair
416 occupies a separate line. Boolean variables can have one of the
417 following values: 0, No, False, Off, Disable for false, and 1, Yes,
418 True, On, Enable for true.
419 The variables defined for use in the configuration file are, for
421 example:
422 mtime
424 Set to "Yes" for synchronize mtime with tags, otherwise set it to
425 "No".
426 name template
428 File name template (see --name-template, for the description).
429 trim
431 Set to "Yes" to trim rotated images when using jpegtran(1).
432 aggregation mode
434 Aggregation mode, possible values are: none, delta or template.
435 aggregation template
437 Aggregation template, which defines the file aggregation (see
438 --aggr-template, for the description).
439 aggregation virtual
441 Defines virtualization for the existing aggregation modes (see the
442 --aggr-virtual option).
443 Tag, TagFile
445 Refer to the section "TAGS", for the detailed description
446 include
448 Include the named file.
449
451 A TAG is defined by the following combination: TagName [Group]:
452 'value'. The defined tags are selected to be set and writen to the
453 EXIF tree using the command line option --tag and/or configuration file
454 options Tag.
455 The syntax of the command line option --tag is:
457 --tag TagName [Group]: 'value'
459 The syntax of the configuration file option Tag:
461 Tag = TagName [Group]: 'value'
463 The parameters TagName and Group are passed to ExifTool as is. The name
465 of the group must be enclosed in square brackets. Its value (after the
466 semicolon) can be enclosed in single quotes.
467 The TagFile keyword allows to set multi-line tags from a file. Its
469 syntax is:
470 TagFile = TagName [Group]: FILE
472 The following table summarizes the tags that can be used with the --tag
474 option and Tag keyword:
475 Copyright
477 Copyright notes.
478 Comment
480 General comment.
481 UserComment
483 Anything you would like to put as a comment.
484 CreatorContactInfoCiAdrCity
486 A city tag.
487 CreatorContactInfoCiAdrCtry
489 A country tag.
490 CreatorContactInfoCiAdrExtadr
492 Extended address (usually includes street and apartment number).
493 CreatorContactInfoCiAdrPcode
495 Zip code.
496 CreatorContactInfoCiAdrRegion
498 Region.
499 CreatorContactInfoCiEmailWork
501 Email.
502 CreatorContactInfoCiTelWork
504 Phone number.
505 CreatorContactInfoCiUrlWork
507 URL.
508 Additionally, you can add any known tag here, using Tag or TagFile
510 options as described above.
511
513 • The main configuration file renrot.conf is searched in the
514 following locations (in the order of their appearance):
515 ~/.renrot/
517 directory under user's home place
518 /usr/local/etc/renrot/
520 system directory
521 /etc/renrot/
523 system directory
524 Take into consideration, the files which are found will be loaded
526 and parsed in the order when user's configuration has maximal
527 priority.
528 • Other configuration files with additional options could be included
530 into main file:
531 colors.conf
533 colors setup for different output facilities
534 tags.conf
536 different tags setup
537 • The following files could be placed locally in the working
539 directory:
540 .keywords
542 file with keywords (see --keywords-file)
543 .rank
545 file with ranks (see --contact-sheet-rank-file)
546
548 If you found some bug or have some nice propositions, you are welcome.
549 Additionally, please, read the section RESTRICTIONS in file README.
550 1. It seems that on FreeBSD 6, Perl versions 5.8.x exhibits a bug that
552 causes renrot to crash. The overal amount of memory for the perl
553 process increasing up to the user datasize limit (in FreeBSD
554 default is 512M).
555 It seems to be a bug in perl's own malloc implementation. The bug
557 should not occur in any perl which uses the system malloc (unless
558 the system malloc has the same bug).
559 renrot aborts with the error message:
561 Out of memory during "large" request for XXXX bytes ...
563 This, however, does not happen with Perl v.5.6.x
565 2. Some versions of ImageMagick render contact sheets incorrectly. it
567 seems it is the question to ImageMagick.
568
570 Copyright 2005-2012, Zeus Panchenko, Andy Shevchenko.
571 This program is free software; you can redistribute it and/or modify it
573 under the same terms as Perl itself.
574
576 Image::ExifTool(3pm), exiftool(1), jpegtran(1), Image::Magick(3pm)
577perl v5.36.0 2023-01-20 RENROT(1)