
wmphoto+ 1.1.1
----------------------------------------------------------------------------

wmphoto+ displays the images in the dockable application window.  You can
switch the images manually or display them as a slide show.  Each image
accepts up to two related commands.  You can run them using mouse buttons
when the application displays the image.  Using the alternative
configuration directories you can run a few instances of the program which
display the different sets of the images.

By default wmphoto reads the pictures and the commands from ~/.wmphoto+
directory.  The file to display should be in *.xpm.gz format, have 54x54
pixels in size, and use no more than 256 colors.  The corresponding optional
text file using the same name as the picture but without .xpm.gz extension
includes the commands invoked by the mouse actions.

The wmphoto requires the identify and the montage programs from the
ImageMagick package.  The montage program is used to scale and convert the
images to the format required by wmphoto; the identify program is used to
establish the size of the original image in order to perform the adequate
clipping.


The installation
----------------------------------------------------------------------------

To install the program use the following procedure:

      cd wmphoto
      make
      make install

If you prefer to install wmphoto in /usr directory rather than /usr/local
one go to Makefile file and before the installation change the variable:

      PREFIX=/usr/local

to:

      PREFIX=/usr

During the installation the complete documents set including contrib and
sample+? directories is copied to the /usr/local/doc/wmphoto+-1.1.1 or
/usr/doc/wmphoto+-1.1.1 directory.

If the compilation breaks with the following error message:

      wmphoto.h:13:21: fatal error: X11/xpm.h: No such file or directory

install the libXpm, or libxpm-dev, or similar library specific for your
system.

If the compilation breaks with the following error message:

      wmphoto.h:14:34: fatal error: X11/extensions/shape.h: No such file or directory

install the libXext, or libxext-dev, or similar library specific for your
system.


The pictures
----------------------------------------------------------------------------

In order to perform the images conversions with wmphoto or the related
scripts you need the montage program from the ImageMagick package.

To put the file.jpg image into the ~/.wmphoto+ directory automatically use
the following command:

      wmphoto -a file.jpg

For the best results crop the image to the square format before adding it.

To put the file.jpg image into ~/.wmphoto+ directory manually do the
following tasks:

1. Prepare ~/.wmphoto+ directory.

2. Edit the image file and crop it to the square format for the best
   results.

3. Convert the image to *.xpm.gz format, having 54x54 pixels in size, and
   using up to 256 colors.  To achieve that use the command such as:

      montage file.jpg -background gray -colors 256 -geometry 54x54 -size 54x54 -unsharp 0.125 +adjoin 'file.xpm.gz'

   If you are interested in the clipping of the file.jpg you should add at
   the beginning of the above command the switch such as -crop
   162x162+284+146 which crops the square fragment from the original image. 
   In the given example it has 162x162 pixels and uses the 284+146 pixels
   offset from the left top corner of the original image.  The modified
   command looks like:

      montage file.jpg -crop 162x162+284+146 -background gray -colors 256 -geometry 54x54 -size 54x54 -unsharp 0.125 +adjoin 'file.xpm.gz'

It is possible to convert the rectangular images instead of the square ones. 
In such a case the montage command adds the gray background filling the
empty left and right or top and bottom margins.

In order to process the directories that contain a lot of the images read
about the batch conversions below.


The commandline
----------------------------------------------------------------------------

The wmphoto can be run in five ways:

1. The command `wmphoto' runs the program and displays the first image in
   *.xpm.gz format from ~/.wmphoto+ directory.  To see the other images press
   the third mouse button.  To run the command press the first or the second
   mouse buttons.  This is the interactive mode.

2. The command `wmphoto -t 10' runs the program and changes the image every
   second.  The number after the -t switch is the tenth of the second.  So
   1 means 1/10 of the second, 10 means one second, 50 means 5 seconds etc. 
   You can run the commands in that mode as well.  This is the slide show
   mode.

3. The command `wmphoto -a /home/johndoe/images/picture.jpg' scales and
   converts the picture.jpg file to *.xpm.gz format, having 54x54 pixels in
   size and using up to 256 colors.  It also asks you about the commands
   associated with the first and the second mouse buttons.  The new image is
   added to the ~/.wmphoto+ directory.  Instead of type the whole path you
   can go to /home/johndoe/images directory and use the command `wmphoto -a
   picture.jpg'.

4. The command `wmphoto -c 3' tells the program to use the configuration
   from the ~/.wmphoto+3 directory.  That command used with the mentioned
   above -t or -a switches uses ~/.wmphoto+3 directory instead of
   ~/.wmphoto+ default one.

5. The command `wmphoto -h' displays the short help.


The configuration
----------------------------------------------------------------------------

Let us assume there are the following files in the ~/.wmphoto+ directory:

      john.xpm.gz
      mary.xpm.gz
      john
      mary

The first and the second files are the images displayed by the wmphoto
dockapp.  The third and the fourth files are the configuration files.  These
files include the commands to run with the first and the second mouse
buttons when the appropriate image is displayed.

The sample john configuration file can look like:

      xterm -e mutt john.doe@gmail.com
      

The first command starts mutt in the writing mode -- the default e-mail
address is john.doe@gmail.com.  The other command is not defined so it does
nothing.

The ~/.wmphoto+ directory contain the default configuration.  You can use
the other directories such as ~/.wmphoto+1 and ~/.wmphoto+2 in order to run
a few instances of wmphoto that display the different sets of the images. 
To achieve that use the commands such as:

      wmphoto -c 1 &
      wmphoto -c 2 &

The parameters of the -c option are the numbers or letters appended to the
default ~/.wmphoto+ configuration directory name in order to get the
alternative directory names.


The mouse buttons and the keyboard shortcuts
----------------------------------------------------------------------------

The first mouse button runs the first command related with the current
image.

The second mouse button runs the second command related with the current
image.

The third mouse button changes the displayed image.  It is particularly
useful in the interactive mode of the work of the program.

The Backspace keyboard shortcut switches the order of the displayed images
back and forth.

The Enter keyboard shortcut switches between the manual and the slide show
modes on the fly.  If the program was started without the defined period
between the images and you switch it to the slide show mode it uses the
default 1.5 second long period.

The Tab keyboard shortcut switches the configuration directories on the fly. 
The direction set by the Backspace key influence the direction of the
directories searching.

Thanks to that last switch you can open just one wmphoto instance and switch
the configuration directories back and forth if necessary.  That saves more
space on your desktop for the other dockable applications.

Thanks to Tab and Enter keyboard shortcuts you do not have to remember the
names of your configuration directories nor use the sophisticated commands
to run the program.  Instead of that use the simple command:

      wmphoto &

Then use the Tab key to select the valid configuration and use the Enter key
to run the slide show.

Before using the keyboard shortcuts you have to put the mouse cursor above
the application window.  As a result some keyboard shortcuts may not work
because the program checks the keyboard actions intercepting them.


The batch conversions
----------------------------------------------------------------------------

The contrib directory includes the scale script which does the batch images
conversion.  To use it copy it to the directory containing some image files
and then customize the configuration section of the script.  Default
settings are:

      SourceDirectory="`pwd`"
      FileType="jpg"
      TargetDirectory="$HOME/.wmphoto+"

In such a case the scale script reads the directory where it was copied
seeking for *.jpg files and writes *.xpm.gz files to $HOME/.wmphoto+
directory.

To run the script use the following command:

      ./scale

It is possible to set the FileType variable to the "*" value.  In such a
case the script processes all files from the source directory but instead of
replace the file names extensions it appends the new ones to the former
ones.  Let us assume there are three image files: picture1.gif,
picture2.jpg, and picture3.png.  The scale script used with FileType set to
"*" converts them to: picture1.gif.xpm.gz, picture2.jpg.xpm.gz, and
picture3.png.xpm.gz files and puts in the target directory three empty
files: picture1.gif, picture2.jpg, and picture3.png.  These files are not
the images but the configuration files.  You can fill them with the commands
associated with the first and the second mouse buttons.

                                      *
                                    *   *

The other method of batch conversion relies on the script named mywmphoto
such as:

      #!/bin/bash
      wmphoto -a "$1" <<EOF
      
      
      
      EOF

To run the above script use the mywmphoto-run script:

      #!/bin/bash
      for f in * ; do if [ "`grep -E 'mywmphoto|scale' "$f"`" == "" ] ; then ./mywmphoto "$f" ; fi ; done

To use these scripts copy them to the directory containing the image files
and run the mywmphoto-run script.

To use the other directory than ~/.wmphoto+ put in the first script the
switch such as -c 3.  To process some kind of files replace in the second
script the `for f in *' string with the `for f in *.jpg' one or similar.

The mywmphoto-run script runs the mywmphoto script for each image file in
the directory and the latter script passes three end of line characters to
the wmphoto command emulating three pressings of the Enter key.

                                      *
                                    *   *

The main difference between the scale script and the mywmphoto-run and
mywmphoto scripts is in the convention of naming of the files.  The scale
script uses the names derived from the original file names while the
mywmphoto-run and mywmphoto scripts use the numbers such as: 0001, 0002,
0003, etc.


The sample directories
----------------------------------------------------------------------------

The sample+1 directory includes an example configuration of wmphoto.  The
core part of the sample configuration are five scripts:

      maps
      scale.europe
      scale.poland
      scale.lower_silesia
      scale.wroclaw

Copy all of them to ~/.wmphoto+1 directory.

The maps script downloads four forecast maps of Europe which show: the cloud
cover, the surface temperature, the precipitation, and the surface wind. 
The script checks whether the maps on the server are newer than the
downloaded ones and downloads the new set of the maps if necessary.  These
maps change roughly every six hours.  The names of the downloaded files are:

      Austria.cloud.12.cc23.jpg
      Austria.lapse.12.cc23.jpg
      Austria.prec.12.cc23.jpg
      Austria.wind.12.cc23.jpg

These maps most of the time show the weather forecast a few hours ahead --
approximately 5 hours ahead when downloaded.

The scale.* scripts run the maps script, recognize the changed maps, and
crop the clippings of the maps customizing them to the format acceptable by
wmphoto.  Each consecutive script uses the bigger scale.  The scale.europe
one shows the Europe; the scale.poland one shows the neighborhood of Poland;
the scale.lower_silesia one shows the neighborhood of Lower Silesia, Poland;
the scale.wroclaw one shows the neighborhood of Wroclaw, Poland.  The names
of the converted files are:

      Austria.cloud.12.cc23.xpm.gz
      Austria.lapse.12.cc23.xpm.gz
      Austria.prec.12.cc23.xpm.gz
      Austria.wind.12.cc23.xpm.gz

You can use these scripts in a creative way with the help of the additional
configuration files and scripts.

The sample+1 directory contains four following configuration files:

      Austria.cloud.12.cc23
      Austria.lapse.12.cc23
      Austria.prec.12.cc23
      Austria.wind.12.cc23

All of them have the same contents:

      /home/USERNAME/.wmphoto+1/command1
      /home/USERNAME/.wmphoto+1/command2

You should copy them to ~/.wmphoto+1 directory and then replace the USERNAME
string in those files with your user name.  Do not try to use the paths such
as ~/.wmphoto+1 or $HOME/.wmphoto+1 in these files because the substitution
does not work when wmphoto runs the commands.

The above configuration files use the following scripts:

command1:

      cd ~/.wmphoto+1 ; rm *.xpm.gz ; ./scale.poland

command2:

      cd ~/.wmphoto+1 ; rm *.xpm.gz ; ./scale.lower_silesia

Copy these scripts to ~/.wmphoto+1 directory as well.  The substitutions
used in those scripts work well.

In such a configuration after you click the first mouse button wmphoto runs
the command1 script and as a result it starts to display the images that
show the close neighbourhood of Poland and after you click the second mouse
button wmphoto runs the command2 script and as a result it starts to display
the images that show the close neighbourhood of Lower Silesia, Poland.

The recommended command to run wmphoto in the above configuration is the
following:

      wmphoto -c 1 -t 15 &

To automate the updates of the images used by wmphoto add to your crontab
the entry such as:

      */15 * * * * cd ~/.wmphoto+1 ; ./scale.poland

or:

      */15 * * * * cd ~/.wmphoto+1 ; ./scale.lower_silesia

In each of the above cases the other region is displayed by wmphoto by
default.

Go to http://www.weather-forecast.com/static_maps/Poland to see these maps
on the website.

                                      *
                                    *   *

The sample+2 directory includes the example configuration of wmphoto which
is similar to the configuration from the sample+1 directory.

To test it copy all files from the sample+2 directory to the ~/.wmphoto+2
directory.

Then edit the following files:

      web_intl_europe_fcstt2_hi_600
      web_intl_europe_fcstt2_lo_600
      europe_pollutionrisk_day1_600_en
      web_intl_europe_painindex_day1_600
      web_intl_europe_winds_day1_600

and change the USERNAME string to your user name.

To use that configuration run the following command:

      wmphoto -c 2 -t 20 &

To automate the updates of the images add to your crontab the following
entry:

      */30 * * * * cd ~/.wmphoto+2 ; ./scale.central_europe1

The maps used in that configuration show: high and low temperature forecasts
as well as air stagnation forecast (pollution risk), aches and pains
forecast (pain index), and wind forecast.  These maps change from one time a
day (the pollution risk) to two times a day (the other maps).

Go to http://uk.weather.com/regional to see these maps on the website.

                                      *
                                    *   *

The cron tasks in the above cases check for the new maps every 15 or 30
minutes.  If you would like to check the maps on demand just click the first
or the second mouse button in the appropriate wmphoto window.

Using the other clippings of these maps or using the other maps from these
websites you can monitor weather forecasts for any selected region.  If you
are really interested in the maps from those two sites download the
http://linux-bsd-unix.strefa.pl/wmphoto-maps-legends.zip file that contain
the legends to these maps.

                                      *
                                    *   *

Two following configurations -- sample+3 and sample+4 -- are similar.  First
gets the images from http://www.rottentomatoes.com movie website while the
other gets the images from http://www.filmweb.pl Polish-language movie
website.  Both of them create the configuration files which open the content
related to the images in the selected browser.

To use them copy command, index, and scale.rottentomatoes.com scripts from
sample+3 directory to ~/.wmphoto+3 directory and copy command, index, and
scale.filmweb.pl scripts from sample+4 directory to ~/.wmphoto+4 directory.

The configuration sections of both scale.* scripts use the following
settings:

      Configuration=".wmphoto+3"
      Browser="firefox"
      Backup="no"

and:

      Configuration=".wmphoto+4"
      Browser="firefox"
      Backup="no"

If you use the other configuration directory or if you prefer the other
browser change the respective values.

By default the scale.* scripts remove the images and the related
configuration files that are older than one day.   If you need backups of
the old content switch the respective value in the configuration sections of
the scale.* scripts to the "yes" value.


Then run both scale.* scripts at least once or register them in your
crontab:

      */30 * * * * cd ~/.wmphoto+3 ; ./scale.rottentomatoes.com
      */30 * * * * cd ~/.wmphoto+4 ; ./scale.filmweb.pl

Finally run two instances of wmphoto:

      wmphoto -c 3 -t 15 &
      wmphoto -c 4 -t 15 &

To open the content related to the image in the browser use the first mouse
button when the image appears.  To refresh the images on demand use the
second mouse button.  To display the index of the available content run the
index script.

Instead of the numbers you can use in the directories names more meaninful
names such as ~/.wmphoto+filmweb or ~/.wmphoto+rottentomatoes.  In such a
case you have use these names also in the configuration sections of the main
scripts, in the command scripts, crontab tasks, and the commands used to run
wmphoto.


                                      *
                                    *   *

The sample+5 directory includes the scale.youtube.com script that gets the
images from http://www.youtube.com as well as the other scripts.  Copy all
of them to ~/.wmphoto+5 directory.

By default the scale.youtube.com script checks the music channel.  To use
the main page instead comment the setting for that channel in the
configuration section of the script.  To use the other channel uncomment the
selected one or set up your own.

You can also set in the configuration section of that script the valid
configuration directory and the browser used to display the YouTube pages. 
The default settings are the following:

      Configuration=".wmphoto+5"
      Browser="firefox"
      Backup="no"

By default the scale.youtube.com script removes the images and the related
configuration files that are older than one day.  If you need backups of the
old content switch the respective value in the configuration section of the
scale.youtube.com script to the "yes" value.

Run the scale.youtube.com script at least once or register it in your
crontab:

      */30 * * * * cd ~/.wmphoto+5 ; ./scale.youtube.com

Finally run wmphoto:

      wmphoto -c 5 -t 15 &

Instead of the number in the directory name you can use more meaninful name
such as ~/.wmphoto+youtube.  In such a case you have use that name also in
the configuration section of the main script, in the command script, crontab
task, and the command used to run wmphoto.

The scale.youtube.com script tries to manage with the different images sizes
available at http://www.youtube.com.  The images named default.jpg have
120x90 pixels in size while the images named mqdefault.jpg have 320x180
pixels in size.  These two types of the images require the other cropping
and unsharping methods.

The index script displays the titles of the clips or their durations when
the title is not available.  The browse script allows to open the given
YouTube page from the command line.


The customization
----------------------------------------------------------------------------

Using the other images or scripts you can customize the content displayed by
the wmphoto to your needs.  Thanks to the alternative configuration
directories you can run a few instances of wmphoto which display the
different sets of the images.  The keyboard shortcuts allow you to change
the behavior of the program on the fly.

