/ [renrot] / trunk / README
To checkout: svn checkout http://svn.gnu.org.ua/sources/renrot/trunk/README
Puszcza

Contents of /trunk/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 542 - (show annotations)
Wed Aug 13 19:29:47 2008 UTC (13 years, 2 months ago) by andy_shev
File size: 9413 byte(s)
Reorganization 'Thanks and Credits' in the documentation. Update 'Getting'
1 WHAT IT IS
2 ---- -- --
3
4 RenRot is a program to rename and lossless rotate (for now only JPEG format)
5 files according to their EXIF tags values.
6
7 To prevent incorrect associations, some explanation is needed here. The name
8 of project is short form of 'REName and ROTate' and no other interpretation
9 will be used.
10
11 RenRot is intended to work with files of --extension extension containing
12 EXIF date and can do two things with them - rename and rotate. It runs in
13 batch mode in current or set with --work-directory directory as well as
14 selective mode for separate files given as arguments in command line.
15
16 New template ideology was implemented. It includes flexibility in file name
17 construction. In version 0.16 and later the previous behaviour still present
18 with default NameTemplate. The template can contain different data, from
19 direct name to EXIF data (the date, id or shooting details such as
20 WhiteBalance, ISO, e.t.c.). For further information, please, see applied
21 manual.
22
23 RenRot rotates file and its thumbnail, according to EXIF tag Orientation. If
24 the tag is absent or miss set, than the script allows to rotate the file as
25 well as its thumbnail "by hands".
26
27 Furthermore, the script put a comment to:
28 - Comment tag from comment file;
29 - UserComment tag from configuration variable or command line option.
30
31 Personal data could be specified via XMP tags defined in configuration file.
32
33 Starting from the version 0.21rc1 RenRot can write any EXIF tag given by
34 command line option or configuration file.
35
36 In addition RenRot can aggregate all files in directories according the given
37 date/time pattern template, set with --aggr-template.
38
39
40 WHY RenRot
41 --- ------
42
43 Several projects like RenRot are available in the net, but why to choose
44 namely RenRot? Because:
45 - it does just what it would do - renames and rotates, nothing more than
46 that;
47 - it is pure CLI with all it's advantage (no need KDE or any other monster
48 to run);
49 - it uses Image::ExifTool (the best open tool to work with EXIF data) and
50 libjpeg6 (the best open tool to operate JPEG format files, to correctly
51 rotate both, the entire file and the thumbnail inside it);
52 - it has very much flex file naming and aggregation template engines;
53 - it uses original algorithm of smart Orientation tag rotation;
54 - it works in batch mode.
55
56 Although not all of these 100% truth now due to implementation of the Contact
57 Sheet Generator framework RenRot is worth to try.
58
59
60 GETTING
61 -------
62
63 RenRot's home page is the https://puszcza.gnu.org.ua/projects/renrot/. You can
64 download script package from the following sites:
65 ftp://download.gnu.org.ua/pub/release/renrot/ (home)
66 ftp://ftp.dn.farlep.net/pub/misc/renrot/ (mirror)
67 http://www.smile.org.ua/~andy/prj/renrot/ (mirror)
68
69 Repositories:
70 Fedora and any of its mirrors (use yum install renrot)
71 Debian and any of its mirrors (use apt-get install renrot)
72 Ubuntu (the same as for Debian)
73
74 To get notifications about new releases you could subscribe on the Freshmeat
75 page:
76 http://freshmeat.net/projects/renrot/
77
78
79 RUNNING
80 -------
81
82 After installation process was done renrot is being running by typing its name
83 in console as usual. The next several examples provide general applications of
84 the script:
85 rename each file according to the given template
86 renrot --name-template="01.%c.%Y%m%d%H%M%S.%E%F%W%I" --extension JPG
87
88 rename each file according to the given template and aggregate according
89 the date
90 renrot --name-template="%y%m%d%H%M%S.%i" --aggr-mode="template" --aggr-template="%Y%m%d" *.JPG
91
92 aggregate files by yymmddHHMM
93 renrot --aggr-mode="template" --aggr-template="%y%m%d%H%M" --extension jpg
94
95 rotate each file and their thumbnail by 90CW in specified directory
96 renrot --rotate-angle 90 --work-directory="/tmp/images" --extension jpg
97
98 rotate thumbnails, included to EXIF, for each file by 270CW (same as
99 90CCW)
100 renrot --rotate-thumb 270 --extension jpg
101
102 rotate given files by Orientation tag (no real rotation will be done)
103 renrot --no-rename --mtime --rotate-angle=90 --only-orientation *.JPEG
104
105 fix file mtime according to its EXIF tags or current time stamp, when tags
106 are invalid
107 renrot --no-rotate --no-rename --mtime --extension jpeg
108
109 leave mtime untouched for couple of files
110 renrot --no-mtime *.jpg
111
112
113 RESTRICTIONS AND BUGS
114 ------------ --- ----
115
116 RenRot has some restrictions and known bugs at runtime.
117
118 1. Script handles a whole directory without recursion and only with one
119 extension of files.
120
121 2. Algorithm treats each file with given extension as the image. Otherwise,
122 file will be renamed to the current time stamp when --no-rename option is
123 omitted.
124
125 3. Rename operation is not permited between different partitions due to hard
126 link technology used (this will be avoided in the future).
127
128 4. Rotation process is available only on JPEG files.
129
130 5. It seems that for Perl v.5.8.7 and 5.8.8, at least on FreeBSD 6 the bug,
131 which cause crash of the renrot, exists. In case when total amount of the
132 files size to process is bigger than RAM amount, the renrot falls with error:
133
134 Out of memory during "large" request for XXXX bytes ...
135
136 This doesn't occure for Perl with external malloc implementation used (f.e.
137 Perl 5.6.1). Starting from version 1.0 RenRot has workaround for this.
138
139 6. Still no way to set the tags with the same name but located in the
140 different groups.
141
142 7. The colorization is started after the configuration files were parsed.
143 While that is not happened the messages will be colorized by default color
144 scheme.
145
146 8. The colorization is not working under Windows platform.
147
148 All bug reports are welcome to our bugzilla which is obtained here:
149 http://puszcza.gnu.org.ua/bugs/?group=renrot
150
151
152 DEBUGGING
153 ---------
154
155 For advanced users and developers renrot provides debug interface. Amount of
156 -v options in a command line defines level of verbosity. So script differs the
157 nine levels of debugging such as:
158 from 1 till 4 - internal levels
159 from 5 till 9 - equal to 1-5 levels for ExifTool plus maximum verbosity for
160 renrot
161
162 First word after DEBUG prefix in each message means function where the dbgmsg()
163 is called.
164
165
166 INSTALLATION
167 ------------
168
169 You can install RenRot to make it available for use by other users by typing
170 the following:
171 perl Makefile.PL PREFIX=/usr/local
172 make
173 make install PREFIX=/usr/local
174
175 Notes:
176 i) You need root access for the last step above.
177 ii) Some Perl installations (like the standard OSX installation) may not
178 contain the necessary files to complete the first step above. But no
179 worries: You can install script manually by moving 'renrot' to any
180 directory in your current PATH.
181 iii) You may choose any desired PREFIX by changing /usr/local at above
182 sample.
183
184 RenRot is shipped with the built-in spec file and rpm package. In RPM-based
185 distribution you may install package by next way:
186 rpmbuild -tb renrot-<version>.tar.gz
187 rpm -ivh /usr/src/redhat/RPMS/noarch/renrot-<version>-<release>.noarch.rpm
188
189
190 DEPENDENCIES
191 ------------
192
193 Requires Perl version 5.6.0 or later. No other special libraries are required,
194 except:
195 Image::ExifTool http://www.sno.phy.queensu.ca/~phil/exiftool/
196 Getopt::Long cpan:Getopt::Long (usually, it's included in
197 the perl distribution)
198 jpegtran (libjpeg6) http://www.ijg.org/
199
200 Contact Sheet Generator framework is depended to Image::Magick module at
201 run-time. The module is still optional to whole script.
202
203
204 LICENSING
205 ---------
206
207 RenRot is an Open Source project distributed under Artistic 2.0 license
208 You can find it here http://www.perlfoundation.org/artistic_license_2_0
209
210 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY
211 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
212 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
213 DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY
214 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
215 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
216 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
217 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
218 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
219 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
220
221 For more information, please, consult with the full license text placed on
222 http://opensource.org/licenses/.
223
224
225 THANKS AND CREDITS
226 ------ --- -------
227
228 People
229 ------
230 Phil Harvey (http://www.sno.phy.queensu.ca/~phil/exiftool/) for his valued
231 comments and suggestions.
232
233 Alex Zasypkin for his help with documentation writing.
234
235 Vyacheslav Garonin for his idea concerning the virtual aggregation.
236
237 Sergey Poznyakoff for help summary and manual style, English and code fixes.
238
239 Anthony Thyssen for his help with ImageMagick/PerlMagick related questions.
240
241 Slaven Rezic for his help with perl5.8.x "Out of memory ... sbrk()" on
242 FreeBSD-6.x
243
244 Teams
245 -----
246 ASPLinux company (http://www.asplinux.ru) has included RenRot to their
247 distribution.
248
249 Fedora Team for including RenRot to its repository.
250
251 Debian maintainers team for including RenRot to the pool.
252
253
254 ARE YOU WANT SOMETHING TO SAY?
255 --- --- ---- --------- -- ----
256
257 If you have notes, propositions, found bugs or something else do not hesitate
258 to contact us!

Properties

Name Value
svn:eol-style native
svn:keywords Author Date Id Revision

Send suggestions and bug reports to Sergey Poznyakoff
ViewVC Help
Powered by ViewVC 1.1.20