path: root/README

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 its 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.

Starting from the version 0.21rc1 RenRot can write any EXIF tag given by
command line option or 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.

Although not all of these 100% truth now due to implementation of the Contact
Sheet Generator framework RenRot is worth to try.


GETTING
-------

RenRot's home page is the https://puszcza.gnu.org.ua/projects/renrot/. You can
download script package from the following sites:
 ftp://download.gnu.org.ua/pub/release/renrot/ (home)
 ftp://ftp.dn.farlep.net/pub/misc/renrot/ (mirror)
 http://www.smile.org.ua/~andy/prj/renrot/ (mirror)

Repositories:
 Fedora and any of its mirrors (use yum install renrot)
 Debian and any of its mirrors (use apt-get install renrot)
 Ubuntu (the same as for Debian)

To get notifications about new releases you could subscribe on the Freshmeat
page:
 http://freshmeat.net/projects/renrot/


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 treats 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 the 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 with external malloc implementation used (f.e.
Perl 5.6.1). Starting from version 1.0 RenRot has workaround for this.

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.

All bug reports are welcome to our bugzilla which is obtained here:
 http://puszcza.gnu.org.ua/bugs/?group=renrot


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

First word after DEBUG prefix in each message means function where the dbgmsg()
is called.


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
    				the perl distribution)
    jpegtran (libjpeg6)		http://www.ijg.org/

Contact Sheet Generator framework is depended to Image::Magick module at
run-time. The module is still optional to whole script.


LICENSING
---------

RenRot is an Open Source project distributed under Artistic 2.0 license
You can find it here http://www.perlfoundation.org/artistic_license_2_0

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 placed on
http://opensource.org/licenses/.


THANKS AND CREDITS
------ --- -------

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

  Alex Zasypkin for his help with documentation writing.

  Vyacheslav Garonin for his idea concerning the virtual aggregation.

  Sergey Poznyakoff for help summary and manual style, English and code fixes.

  Anthony Thyssen for his help with ImageMagick/PerlMagick related questions.

  Slaven Rezic for his help with perl5.8.x "Out of memory ... sbrk()" on
  FreeBSD-6.x

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

  Fedora Team for including RenRot to its repository.

  Debian maintainers team for including RenRot to the pool.


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

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