1RENROT(1)             User Contributed Perl Documentation            RENROT(1)
2
3
4

NAME

6       renrot - rename and rotate images according EXIF data
7

SYNOPSIS

9       renrot [OPTIONS] [[--] FILE1 FILE2 ...]
10

DESCRIPTION

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
19       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
25       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
30       The program can also place commentaries into the following locations:
31
32           - Commentary tag from file (see --comment-file option)
33
34           - UserComment tag from configuration variable (see "TAGS" section)
35
36       Personal details may be specified via XMP tags defined in a
37       configuration file, see "TAGS" section.
38
39       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

OPTIONS

44       -c or --config-file FILE
45           Path to the configuration file.
46
47       -d or --work-directory DIR
48           Define the working directory.
49
50       --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
55       --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
61       -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
66       --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
71       --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
76       --use-color, --no-use-color
77           Colorize output. This does NOT work under Windows.
78
79       --dry-run
80           Do not do anything, only print would have been done.
81
82       -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
87       --use-ipc, --no-use-ipc
88           Rotate thumbnails using pipe, rather than files. This does NOT work
89           under Windows.
90
91       -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
95       -? or --help
96           Display short usage summary and exit.
97
98       --version
99           Output version information and exit.
100

AGGREGATION

102       --aggr-mode MODE
103           Run aggregation process in given MODE. Possible values are: none,
104           delta or template.
105
106       --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
113       --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
119       -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
128       --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

CONTACT SHEET GENERATOR

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
141       --contact-sheet-file or --cs-file FILE
142           Base file name for montage files.
143
144       --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
148       --contact-sheet-thm or --cs-thm
149           Files for the montage are already thumbnails
150
151       Options bellow are native ImageMagic montage options look ImageMagick
152       documentation for montage options: montage --help and
153       http://www.imagemagick.org/
154
155       Note please, for COLOR use RGB triplets only like 000 for the black or
156       F00 for the red.
157
158       --contact-sheet-tile or --cs-tile GEOMETRY
159           Tile MxN (IM: -tile)
160
161       --contact-sheet-title or --cs-title STRING
162           Set the title of the contact sheet (IM: -title).
163
164       --contact-sheet-bg or --cs-bg COLOR
165           Background color (IM: -background).
166
167       --contact-sheet-bd or --cs-bd COLOR
168           Border color (IM: -bordercolor).
169
170       --contact-sheet-mt or --cs-mt COLOR
171           Frame color (IM: -mattecolor).
172
173       --contact-sheet-fn or --cs-fn STRING
174           Render text with this font (IM: -font).
175
176       --contact-sheet-fl or --cs-fl COLOR
177           Color to fill the text (IM: -fill).
178
179       --contact-sheet-lb or --cs-lb STRING
180           Assign a label to an image (IM: -label).
181
182       --contact-sheet-fr or --cs-fr GEOMETRY
183           Surround image with an ornamental border in N pixels (IM: -frame).
184
185       --contact-sheet-pntsz or --cs-pntsz NUMBER
186           Font point size (IM: -pointsize).
187
188       --contact-sheet-shadow or --cs-shadow
189           Set the shadow beneath a tile to simulate depth (IM: -shadow).
190
191       --contact-sheet-thm-fl or --cs-thm-fl COLOR
192           Color to fill the text in generated thumbnail.
193
194       --contact-sheet-thm-fn or --cs-thm-fn STRING
195           Render the generated thumbnail text with this font (IM: -font).
196
197       --contact-sheet-thm-grfr or --cs-thm-grfr COLOR
198           Generated thumbnail background gradient COLOR-from
199
200       --contact-sheet-thm-grto or --cs-thm-grto COLOR
201           Generated thumbnail background gradient COLOR-to
202
203       --contact-sheet-thm-text or --cs-thm-text STRING
204           Generated thumbnail text
205
206       --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
211       --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
215               01.file.jpg        red
216
217               02.JPG             CornflowerBlue
218
219               03.jpg             aquamarine
220
221               04.file.JPG        green
222
223           Only the files found in the file will be ranked.
224

KEYWORDIZER

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
232       -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
238       --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

RENAMING

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
249           Interpreted sequences are:
250
251               %%   a literal %
252
253               %#   a literal #
254
255               %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
261               %c   Ordinal number of file in the processed file set (see also
262               --counter-fixed-field option).
263
264               %d   Day of month (01-31).
265
266               %E   The value of ExposureTime tag, if defined.
267
268               %e   Old file extension
269
270               %F   The value of FNumber tag, if defined.
271
272               %H   Hour (00-23).
273
274               %I   The value of ISO tag, if defined.
275
276               %i   FileNumber tag if exists (otherwise, it is replaced by
277               string "NA").
278
279               %M   Minute (00-59).
280
281               %m   Month (01-12).
282
283               %n   Previous filename (the one before renrot started
284               processing).
285
286               %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
290               %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
294               %S   Second (00-59)
295
296               %W   The value of WhiteBalance tag, if defined.
297
298               %Y   Year with the century (1900, 1901, and so on)
299
300               %y   Year without a century (00..99)
301
302               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
306               Be careful, since any binary EXIF (like ThumbnaiImage) can
307               produce totally unexpected results.
308
309       --no-rename
310           Do not rename files (default is to rename them to
311           YYYYmmddHHMMSS.ext)
312
313       --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
318       --counter-start NUMBER
319           Initial value for the file counter (default is 1)
320
321       --counter-step NUMBER
322           Step to increment file counter with (default is 1)
323

ROTATING

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
330       --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
335       --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
345       --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
349       --no-rotate
350           Do not rotate images (default is to rotate according to EXIF data).
351

TAG WRITER

353       --comment-file FILE
354           File with commentaries. It is a low priority alias to TagFile =
355           Comment: FILE.
356
357       --user-comment STRING
358           A low priority alias to --tag UserComment: STRING
359
360       -t or --tag TAG
361           See the section "TAGS", for the detailed description
362
363       --no-tags
364           No user's defined tags will be written.
365

TEMPLATE EXAMPLES

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
371           01.0021.20030414103656.NA.shtr-1by40.f-2.8.wb-Auto.iso-160.jpg
372
373           01.0024.20040131230857.100-0078.shtr-1by320.f-2.8.wb-Auto.iso-50.jpg
374
375           01.0022.20000820222108.NA.jpg
376
377       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
381           01.0021.20030414103656.NA.shtr-1_40.f-2.8.wb-Auto.iso-160.jpg
382
383           01.0024.20040131230857.100-0078.shtr-1_320.f-2.8.wb-Auto.iso-50.jpg
384
385           01.0022.20000820222108.NA.jpg
386
387       The aggregation template "%Y%m%d" produces the following aggregation:
388
389       these three files
390
391           01.11.20030414103656.NA.jpg
392
393           01.12.20030414103813.NA.jpg
394
395           01.13.20030414103959.NA.jpg
396
397       will be stored in the directory 20030414, and
398
399           01.14.20040131130857.100-0078.jpg
400
401           01.15.20040131131857.100-0079.jpg
402
403           01.16.20040131133019.100-0080.jpg
404
405       will be stored in the directory 20040131.
406

CONFIG

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
414       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
420       The variables defined for use in the configuration file are, for
421       example:
422
423       mtime
424           Set to "Yes" for synchronize mtime with tags, otherwise set it to
425           "No".
426
427       name template
428           File name template (see --name-template, for the description).
429
430       trim
431           Set to "Yes" to trim rotated images when using jpegtran(1).
432
433       aggregation mode
434           Aggregation mode, possible values are: none, delta or template.
435
436       aggregation template
437           Aggregation template, which defines the file aggregation (see
438           --aggr-template, for the description).
439
440       aggregation virtual
441           Defines virtualization for the existing aggregation modes (see the
442           --aggr-virtual option).
443
444       Tag, TagFile
445           Refer to the section "TAGS", for the detailed description
446
447       include
448           Include the named file.
449

TAGS

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
456       The syntax of the command line option --tag is:
457
458           --tag TagName [Group]: 'value'
459
460       The syntax of the configuration file option Tag:
461
462           Tag = TagName [Group]: 'value'
463
464       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
468       The TagFile keyword allows to set multi-line tags from a file. Its
469       syntax is:
470
471           TagFile = TagName [Group]: FILE
472
473       The following table summarizes the tags that can be used with the --tag
474       option and Tag keyword:
475
476       Copyright
477           Copyright notes.
478
479       Comment
480           General comment.
481
482       UserComment
483           Anything you would like to put as a comment.
484
485       CreatorContactInfoCiAdrCity
486           A city tag.
487
488       CreatorContactInfoCiAdrCtry
489           A country tag.
490
491       CreatorContactInfoCiAdrExtadr
492           Extended address (usually includes street and apartment number).
493
494       CreatorContactInfoCiAdrPcode
495           Zip code.
496
497       CreatorContactInfoCiAdrRegion
498           Region.
499
500       CreatorContactInfoCiEmailWork
501           Email.
502
503       CreatorContactInfoCiTelWork
504           Phone number.
505
506       CreatorContactInfoCiUrlWork
507           URL.
508
509       Additionally, you can add any known tag here, using Tag or TagFile
510       options as described above.
511

FILES

513       •   The main configuration file renrot.conf is searched in the
514           following locations (in the order of their appearance):
515
516           ~/.renrot/
517               directory under user's home place
518
519           /usr/local/etc/renrot/
520               system directory
521
522           /etc/renrot/
523               system directory
524
525           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
529       •   Other configuration files with additional options could be included
530           into main file:
531
532           colors.conf
533               colors setup for different output facilities
534
535           tags.conf
536               different tags setup
537
538       •   The following files could be placed locally in the working
539           directory:
540
541           .keywords
542               file with keywords (see --keywords-file)
543
544           .rank
545               file with ranks (see --contact-sheet-rank-file)
546

BUGS

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
551       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
556           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
560           renrot aborts with the error message:
561
562               Out of memory during "large" request for XXXX bytes ...
563
564           This, however, does not happen with Perl v.5.6.x
565
566       2.  Some versions of ImageMagick render contact sheets incorrectly. it
567           seems it is the question to ImageMagick.
568

AUTHORS

570       Copyright 2005-2012, Zeus Panchenko, Andy Shevchenko.
571
572       This program is free software; you can redistribute it and/or modify it
573       under the same terms as Perl itself.
574

SEE ALSO

576       Image::ExifTool(3pm), exiftool(1), jpegtran(1), Image::Magick(3pm)
577
578
579
580perl v5.36.0                      2023-01-20                         RENROT(1)
Impressum