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

Mapivi is an open-source and cross-platform picture manager.

Mapivi is written in Perl/Tk and runs under all important operating
systems, like UNIX/Linux, Mac OS X and Windows.

Mapivi supports adding, viewing and editing of JPEG meta informations like:
EXIF, IPTC/IIM and JPEG comments.

File INSTALL last modified: 2016-08-16

Mapivi latest version can be found at: http://mapivi.de.vu
and http://mapivi.sourceforge.net/mapivi.shtml

##########################################################################
# 
# 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, WinXP and Vista)

and for the Perl variant of Mapivi:

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 only for old Perl/Tk before version 804.025: Perl module Tk::JPEG
o optional: Perl module Proc::ProcessTable

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

  

##########################################################################
# 
# Install Mapivi version 1.0 and newer
#
##########################################################################

First check if Mapivi is available as a package for your operating system.
Linux Ubuntu e.g. offers Mapivi as a package which may be installed using
the package manager. This is the easiest and safest way to install Mapivi.

If this is not possible or you want to try the newsest version, follow
these instructions:

Download Mapivi from the sourceforge subversion repository:
http://mapivi.svn.sourceforge.net/viewvc/mapivi/
as a GNU tarball.

Unzip and unpack the tarball mapivi.tar.gz

Windows:
Move all extracted files and folders to any folder e.g.
"C:\Program Files\Mapivi\"

UNIX/Linux or Mac OS X:
Move mapivi.pl to e.g. "/usr/local/bin"
and all other files and folders to "/usr/share/mapivi"   

Open a DOS box or shell and start Mapivi:
Windows: "C:\Program Files\Mapivi\mapivi.pl" or
Linux:   "/usr/local/bin/mapivi.pl".

If Mapivi doesn't start read chapter "Install Perl and Perl Modules"

##########################################################################
# 
# Install/Upgrade Mapivi version 1.0 and newer for Ubuntu Linux
#
##########################################################################

Install older version of Mapivi as available in the Ubuntu package manager.

Download newest Mapivi version from
http://sourceforge.net/p/mapivi/code/HEAD/tree/
Use "Download Snapshot" to download all files as Zip archive.
Unzip archive into any folder in your home directory.

Or do a SVN checkout (in this example to /home/user/foldername):
svn checkout https://svn.code.sf.net/p/mapivi/code /home/user/foldername

Change to this folder:
"cd foldername"

Update icons:
"sudo cp icons/* /usr/share/mapivi/icons"
(Alternative way for icons if you e.g. have a SVN snapshot:
"sudo rm -r /usr/share/mapivi/icons/"
"sudo ln -s /home/user/foldername/icons/ /usr/share/mapivi"
the same can be done for languages and docs folder)

Start Mapivi with
"./mapivi.pl"

To install optional perl modules (the missing modules are shown in Mapivi
in menu Help->System Information), use CPAN:
"cpan Tk::MatcheEntry"
"cpan Tk::ResizeButton"
"cpan Tk::Splash"
...

##########################################################################
# 
# Install Perl and Perl Modules
#
##########################################################################

Install Perl: See http://www.perl.org/get.html
Note: Under Windows Mapivi has only be tested using ActivePerl. 

Install Perl Modules:
If Mapivi doesn't start, read the errors in the DOS box or shell.
If the error looks like "Can't locate Tk.pm in @INC ..." then a Perl
module, in this case the Perl module (pm) named "Tk", is missing.
Other errors in the same category may be:
"Can't locate Image/MetaData/JPEG.pm in @INC ..."
or
"Can't locate Image/Info.pm in @INC ..."

The installation process for Perl modules depends on your Perl distribution.
If you are under Windows and use ActivePerl you just need to type:
"ppm install Image-Info" to install the module Image/Info.pm.
Under UNIX/Linux you may use CPAN: "cpan Image::Info" to install the same
module (see also http://www.cpan.org/modules/INSTALL.html).

Some Linux distributions like Ubuntu offer Perl modules as a package
(e.g. the Perl module Tk as package perl-tk), use the Ubuntu package
manager to install the modules.

##########################################################################
# 
# WARNING: Outdated documentation!!!!!!
#
# The installation hints below are only partly valid for Mapivi Version
# 1.0 and newer!
#
# WARNING: Outdated documentation!!!!!!
#
##########################################################################

##########################################################################
# 
# 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

##########################################################################
# 
# 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 Mapivi PlugIns
#
##########################################################################

Plug-Ins are executable applications which are stored in the Mapivi config
sub folder PlugIns (on UNIX: ~/.maprogs/mapivi/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)
