summaryrefslogtreecommitdiffabout
path: root/README
blob: 8ae679ac6a315e6ca104eaec112b21c6f63c2470 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
WHAT IT IS
---- -- --

RenRot is a program to rename and lossless rotate (for now only JPEG format)
files according to their EXIF tags values.

To prevent incorrect associations, some explanation is needed here. The name
of project is short form of 'REName and ROTate' and no other interpretation
will be used.

RenRot is intended to work  with files of --extension extension containing
EXIF date and can do two things with them - rename and rotate. It runs in
batch mode in current or set with --work-directory directory as well as
selective mode for separate files given as arguments in command line.

New template ideology was implemented. It includes flexibility in file name
construction. In version 0.16 and later the previous behaviour still present
with default NameTemplate. The template can contain different data, from
direct name to EXIF data (the date, id or shooting details such as
WhiteBalance, ISO, e.t.c.). For further information, please, see applied
manual.

RenRot rotates file and its thumbnail, according to EXIF tag Orientation. If
the tag is absent or miss set, than the script allows to rotate the file as
well as it's thumbnail "by hands".

Furthermore, the script put a comment to:
    - Comment tag from comment file;
    - UserComment tag from configuration variable or command line option.

Personal data could be specified via XMP tags defined in configuration file.

In addition RenRot can aggregate all files in directories according the given
date/time pattern template, set with --aggr-template.

WHY RenRot?
--- -------

Several projects like RenRot are available in the net, but why to choose
namely RenRot? Because:
    - it does just what it would do - renames and rotates, nothing more than
      that;
    - it is pure CLI with all it's advantage (no need KDE or any other monster
      to run);
    - it uses Image::ExifTool (the best open tool to work with EXIF data) and
      libjpeg6 (the best open tool to operate JPEG format files, to correctly
      rotate both, the entire file and the thumbnail inside it);
    - it has very much flex file naming and aggregation template engines;
    - it uses original algorithm of smart Orientation tag rotation;
    - it works in batch mode.


GETTING
-------

RenRot home page is an ftp site for now. You can download script package from
the following sites:
 ftp://ftp.dn.farlep.net/pub/misc/renrot/ (home)
 ftp://andriy.asplinux.com.ua/pub/people/andy/renrot/ (mirror)
 ftp://ftp.asplinux.ru/ (looking for renrot package in RPM)
 Fedora Extras repository on any mirror (use yum or yumex utility to install
 package)


RUNNING
-------

After installation process was done renrot is being running by typing its name
in console as usual. The next several examples provide general applications of
the script:
    rename each file according to the given template
	renrot --name-template="01.%c.%Y%m%d%H%M%S.%E%F%W%I" --extension JPG

    rename each file according to the given template and aggregate according
    the date
	renrot --name-template="%y%m%d%H%M%S.%i" --aggr-mode="template" --aggr-template="%Y%m%d" *.JPG

    aggregate files by yymmddHHMM
	renrot --aggr-mode="template" --aggr-template="%y%m%d%H%M" --extension jpg

    rotate each file and their thumbnail by 90CW in specified directory
	renrot --rotate-angle 90 --work-directory="/tmp/images" --extension jpg

    rotate thumbnails, included to EXIF, for each file by 270CW (same as
    90CCW)
	renrot --rotate-thumb 270 --extension jpg

    rotate given files by Orientation tag (no real rotation will be done)
	renrot --no-rename --mtime --rotate-angle=90 --only-orientation *.JPEG

    fix file mtime according to its EXIF tags or current time stamp, when tags
    are invalid
	renrot --no-rotate --no-rename --mtime --extension jpeg

    leave mtime untouched for couple of files
	renrot --no-mtime *.jpg


RESTRICTIONS AND BUGS
------------ --- ----

RenRot has some restrictions and known bugs at runtime.

1. Script handles a whole directory without recursion and only with one
extension of files.

2. Algorithm treat each file with given extension as the image. Otherwise,
file will be renamed to the current time stamp when --no-rename option is
omitted.

3. Rename operation is not permited between different partitions due to hard
link technology used (this will be avoided in future).

4. Rotation process is available only on JPEG files.

5. It seems that for Perl v.5.8.7 and 5.8.8, at least on FreeBSD 6 the bug,
which cause crash of the renrot, exists. In case when total amount of the
files size to process is bigger than RAM amount, the renrot falls with error:

	Out of memory during "large" request for XXXX bytes ...

This doesn't occure for Perl v.5.6.1.

6. Still no way to set the tags with the same name but located in the
different groups.

7. The colorization is started after the configuration files were parsed.
While that is not happened the messages will be colorized by default color
scheme.

8. The colorization is not working under Windows platform.


DEBUGGING
---------

For advanced users and developers renrot provides debug interface. Amount of
-v options in a command line defines level of verbosity. So script differs the
nine levels of debugging such as:
    from 1 till 4 - internal levels
    from 5 till 9 - equal to 1-5 levels for ExifTool plus maximum verbosity for
                    renrot


INSTALLATION
------------

You can install RenRot to make it available for use by other users by typing
the following:
    perl Makefile.PL PREFIX=/usr/local
    make
    make install PREFIX=/usr/local

Notes:
   i) You need root access for the last step above.
  ii) Some Perl installations (like the standard OSX installation) may not
      contain the necessary files to complete the first step above. But no
      worries: You can install script manually by moving 'renrot' to any
      directory in your current PATH.
 iii) You may choose any desired PREFIX by changing /usr/local at above
      sample.

RenRot is shipped with the built-in spec file and rpm package. In RPM-based
distribution you may install package by next way:
    rpmbuild -tb renrot-<version>.tar.gz
    rpm -ivh /usr/src/redhat/RPMS/noarch/renrot-<version>-<release>.noarch.rpm


DEPENDENCIES
------------

Requires Perl version 5.6.0 or later. No other special libraries are required,
except:
    Image::ExifTool		http://www.sno.phy.queensu.ca/~phil/exiftool/
    Getopt::Long 		cpan:Getopt::Long (usually, it's included in
    				perl distribution)
    jpegtran (libjpeg6)		http://www.ijg.org/


LICENSING
---------

RenRot is an Open Source project distributed under GPL or Artistic license.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

For more information, please, consult with the full license text.


THANKS
------

Phil Harvey (http://www.sno.phy.queensu.ca/~phil/exiftool/) for his valued
comments and suggestions.

ASPLinux company (http://www.asplinux.ru) has included renrot to their
distribution.

Alex Zasypkin for his help with documentation writing.

Fedora Extras Team for including RenRot to its repository.

Vyacheslav Garonin for his idea concerning the virtual aggregation.


ARE YOU WANT SOMETHING TO SAY?
--- --- ---- --------- -- ----

If you have notes, propositions, found bugs or something else do not hesitate
to contact us!

Return to:

Send suggestions and report system problems to the System administrator.