##########################################################################
# 
# Mapivi - Martin's Picture Viewer
#
##########################################################################

Picture Viewer and Organizer for UNIX/X11, Mac OS X, Windows written in
Perl/Tk.
Mapivi supports adding, viewing and editing of JPEG meta informations like:
EXIF, IPTC/IIM and JPEG comments.

File INSTALL last modified: 21.02.2008

Mapivi latest version can be found at: http://mapivi.de.vu
and http://sourceforge.net/projects/mapivi (download)

##########################################################################
# 
# Requirements
#
##########################################################################

You need:

o a computer running UNIX (Linux, Solaris, Mac OS X) and X11 or Windows
  (mapivi also works at least with Windows 2000 and WinXP, but maybe also
  with Windows 98)

and for the perl distribution (recommended for non-Windows computers):

o Perl 5.005 or better
o Perl/Tk 800.015 or better
o jpegtran to do the loss-less rotation. They are included e.g. in the
  The Independent JPEG Group's JPEG software release 6b (this program is
  part of most Linux distributions as part of the libjpg package)
o jhead - for auto rotation of pictures
  homepage: http://www.sentex.net/~mwandel/jhead/
o the command line tools convert, mogrify and composite (or combine)
  from Image Magick (this is also part of most Linux distributions)
  see http://www.imagemagick.org
o Perl module Image::MetaData::JPEG
o Perl module Image::Info
o Perl/Tk module Tk::JPEG (not needed if you have Perl/Tk 804.025 or newer)
o optional: Perl module Proc::ProcessTable
o optional: gimp-remote (for UNIX etc.) or gimp-win-remote (for Windows)

You will find all the perl modules at http://search.cpan.org/

for the Windows distribution (mapiviXXX_Win32.zip) you need:

o jpegtran to do the loss-less rotation. They are included e.g. in the
  The Independent JPEG Group's JPEG software release 6b (this program is
  part of most Linux distributions as part of the libjpg package)
o jhead - for auto rotation of pictures
  homepage: http://www.sentex.net/~mwandel/jhead/
o the command line tools convert, mogrify and composite (or combine)
  from Image Magick (this is also part of most Linux distributions)
  see http://www.imagemagick.org
o optional: gimp-remote (for UNIX etc.) or gimp-win-remote (for Windows)

##########################################################################
#
# Installation of Perl modules
#
##########################################################################

To install a Perl module you may either try cpan (a) or for Windows ppm (b) or do a manual (c) install.

(a)
Cpan will download a module (and all modules it depends on), build and
install it. All you have to do is open a shell and type:

    cpan module_name

Example to install the Perl module Image::Info: 

    cpan Image::Info 

You may need root permissions for this step, try e.g.

    sudo cpan Image::Info

(b)
ppm is the Perl Package Manager for Windows it will download a
module (and all modules it depends on), build and install it.
All you have to do is open a DOS box (cmd) and type:

    ppm install module_name

Example to install the Perl module Image::Info: 

    ppm install Image::Info 

(c)
For a manual install you must download the Perl module at e.g.
http://search.cpan.org/, unzip and unpack it.
The module can now be built using this sequence of commands:

    perl Makefile.PL
    make
    make test

To install the module, run the command below:

    make install

You may need root permissions for this step, try e.g.

    sudo make install

##########################################################################
# 
# Installation of Perl distribution for UNIX
#
##########################################################################

File name mapiviXXX.tgz (or mapiviXXX.tar.bz2)

in short:

unzip, unpack, change to the mapivi directory and run mapivi with:
perl mapivi

in long:

("-> " is the command line prompt)

unzip the archive (XXXX is the version number):

-> gunzip mapiviXXXX.tgz 
or
-> bunzip mapiviXXXX.tar.bz

extract the tar-ball:

-> tar xvf mapiviXXXX.tar

go into the directory

-> cd mapiviXXXX/   (where ever you extracted mapivi to ...)

run mapivi

-> perl mapivi    (you only have to do this the first time
                   for the mapivi install process)

later Mapivi is started like this: 

-> mapivi

Hint: For Ubuntu users there is some more help available here:
http://ubuntuforums.org/showthread.php?t=130912&highlight=mapivi

##########################################################################
# 
# Installation of Linux executable distribution
#
##########################################################################

File name mapiviXXX_Linux.exe.bz2

1. Unzip the package to a new folder anywhere using bunzip2
   (e.g. to ~/progs/mapivi)
2. Download and install jhead and jpegtran, if not already installed.
3. Start MapiviXXX_Linux.exe with a double click in your file manager or
   in a shell (if this doesn't work you may need to adjust the file
   permissions: chmod a+x ~/mapivi/MapiviXXX_Linux.exe).

That's all.

##########################################################################
# 
# Installation of Perl distribution for Mac OS X
#
##########################################################################

File name mapiviXXX.tgz (or mapiviXXX.tar.bz2)

[Unfortunately, I did not keep track of all the things I had to install
to make mapivi work.  If you are the next person to install mapivi on
Mac OS X, please make a list and tell Martin. -- Dan Eble]

Follow installation instructions for UNIX.

macosx-preview

  Mapivi comes with a shell script, macosx-preview, which opens the
  Preview application to serve the "open picture in external viewer"
  feature.  To use this feature, make sure the script is in a directory
  that is in the PATH, or instead open the mapivi options (Ctrl-o), go to
  the Advanced tab, and change the setting to include the full path to
  macosx-preview.

  The macosx-preview script attempts to use full-screen view, but this
  requires the feature "access for assistive devices".  To enable this
  feature, run System Preferences, select the Universal Access pane,
  and check the box labeled "Enable access for assistive devices".

##########################################################################
# 
# Installation of Windows executable distribution
#
##########################################################################

File name mapiviXXX_Win32.zip

1. Unzip the package to a new folder anywhere (e.g. C:\Program files\Mapivi)
2. Download and install ImageMagick, jhead and jpegtran.
3. Start MapiviXXX_Win32.exe with a double click or in a dos box.

That's all.

##########################################################################
# 
# Installation of Perl distribution for Windows
#
##########################################################################

File name: mapiviXXX.tgz (or mapiviXXX.tar.bz2)

Installation order:
1. Active State Perl
2. Perl module String::IO
3. Perl module Image::Info
4. Perl module Image::MetaData::JPEG
5. Perl module Tk::JPEG (needed only for Perl/Tk versions < 804.025) 
6. ImageMagick, jhead, jpegpixi, ...
7. Mapivi

Install perl e.g. the Active State Perl (www.activestate.com)
Try also to get the needed perl modules from there.

Install Image magick, jhead etc.
Suggestion:
Create a new directory e.g. C:\Programs\Graphics
and install all backend tools in this directory.
Don't forget to add this directory to the PATH variable
(System->Environment variables->Path).

unzip, unpack mapivi (e.g. with winzip)

change to the mapivi directory in a DOS-box and run mapivi with:

perl mapivi

I recommend renaming mapivi to mapivi.pl (or mapivi.wpl), so the windows
explorer is able to recognize it as a perl file. After renaming it's
possible to start it with a double click, or via the start menu or the
quick launch bar.
You may also change the default perl icon to the MapiviIcon32.ico icon
(see directory .../mapiviXXXX/pics/).

If you have problems with Win Xp and Tk::JPEG, maybe this link is a help
for you: http://perlmonks.thepen.com/195691.html

Hint:       If you have problems with convert from ImageMagick, this may
            be due to the fact, that there is a windows program with the
            same name.
Workaround: the path to the ImageMagick convert tool must be in front of
            the windows convert tool in the PATH variable.

#################################

Perl Installation Update for Win32 (Nov 2004):

Install perl e.g. the Active State Perl (www.activestate.com
download here:
http://www.activestate.com/Products/Download/Download.plex?id=ActivePerl)
e.g. ActivePerl 5.8.3 build 809 (I usually use the file with the MSI suffix)

Open a DOS box, start ppm (enter ppm and press return) and download the actual
Perl/Tk 804.027:
ppm> repository add BdP http://www.bribes.org/perl/ppm
ppm> install http://www.bribes.org/perl/ppm/Tk.ppd -force
This new version already includes Tk::JPEG

Now you just need to install Image-Info and Image-MetaData-JPEG:
ppm> install Image-Info
ppm> install Image-MetaData-JPEG
 
##########################################################################
# 
# Installation of other Mapivi files and PlugIns
#
##########################################################################

Most of the files provided in the Mapivi Perl package should be copied to
the configuration folder of Mapivi (UNIX: ~/.maprogs/mapivi/PlugIns,
Windows: C:\Documents and Setting\<user_name>\Application Data\maprogs\mapivi).
Mapivi will run without this step, but it will provide more features and look better if you do!  :)

Copy the files Changes.txt, FAQ, License,txt, Tips.txt to the configuration folder.
Copy all pictures from the subfolder pics (like EmptyThumb.jpg, logo.jpg, MiniPic.jpg, add.gif)
to the configuration folder (no subfolder here).

Copy the complete icon folder (containing edit-copy.png, folder.png, go-next.png, ...)
to the configuration folder.
Copy the complete PlugIns folder (containing Channel-Separator, Join-RGB, ...)
to the configuration folder.

Plug-Ins are executable applications which are stored in the Mapivi configuration
sub folder PlugIns (UNIX: ~/.maprogs/mapivi/PlugIns, windows see above and add \PlugIns).
They are called by Mapivi with the selected pictures (each with complete
path) as arguments.
The example PlugIns contained in the Mapivi distributions are written in
Perl. To get them running on your system it may be necessary to adjust
the first line of each PlugIn (e.g. filelist-plugin).
The first line must contain the chars #! and the full path to your perl
executable.
Example:
#!/usr/bin/perl

(To get the full path of perl try:
which perl
in your shell.)

##########################################################################
# 
# Help
#
##########################################################################

You will find a lot of help to Perl and Perl/Tk in this newsgroup:
news:comp.lang.perl.tk

The newsgroup may be searched using this link at google.com:
http://groups.google.com/groups?hl=en&group=comp.lang.perl.tk

If this won't help, try to start mapivi from perl and read the output 
carefully

-> perl mapivi

You may also set the $verbose variable to 1 to get more information.
To do this, press Ctrl-v while running mapivi or by opening mapivi in a
text editor and searching for this line:
my $verbose = 0;   # boolean (1 = print debug infos, 0 = be quiet)
and changing it to:
my $verbose = 1;   # boolean (1 = print debug infos, 0 = be quiet)
then save mapivi and restart it:

-> perl mapivi

Send me an email if it you have problems, questions, feature requests,
patches or comments:

Martin-Herrmann@gmx.de (german or english spoken)