=======================
PyVib2 Hints and Tricks
=======================

* :ref:`gif_windows`
* :ref:`new_elements`

.. _gif_windows:
    
Animated GIFs under Windows
===========================

Please make sure that you have properly installed Netpbm and Gifsicle.
There are Windows versions of the programs and the Cygwin ports available.
The following executables must be accessible from the command prompt
(be on PATH):

    * :command:`ppmcolormap`
    * :command:`pnmremap`
    * :command:`ppmtogif`
    * :command:`gifsicle`

.. note::

    PyVib2 1.0 requires the :command:`which` command to be accessible
    as well (installed by default with Cygwin). As of PyVib2 1.1,
    it is not a requirement anymore.

.. warning::

    If you are going to use Netpbm from GnuWin32, the author of PyVib2 does
    **not** recommend to install version 10.27. Version 10.18.4 has been
    found to work properly.

To check if the executables are on PATH:
    
    * start a command prompt (:command:`cmd.exe`)
    * invoke the aformentioned executables

If at least one of the executable has not been found:

    * find where the executables physically on the disc are and note their
      parent directories
    * go to :menuselection:`Start --> Control Panel --> System --> System properities`
      and select the *Advanced* tab
    * add the directories (separated by ;) to the *PATH* variable
      (create one if necessary)
    * apply these changes
    * open a new command prompt and repeat the tests. Do **not** use a command
      prompt started before the changes have been applied.

Finally, test if gifs can be produced properly:

    * save `benzene_test.ppm <http://pyvib2.sourceforge.net/res/benzene_test.ppm>`_
      to any directory, the background color of this image is ``#646464``
    * start a command prompt and change to that directory
    * perform the following two calls::

        c:\> pnmcolormap 256 benzene_test.ppm > palette
        c:\> pnmremap -mapfile palette benzene_test.ppm | ppmtogif --transparent=#646464 > benzene_test.gif

    * the produced transparent :file:`benzene_test.gif` should look like this:

        .. image:: img/benzene_test.gif

.. _new_elements:
    
Adding new chemical elements to PyVib2
======================================

If you are opening a file and the program is complaining "Unknown element XX",
then you have to *introduce* that element to PyVib2 by adding the relevant
line to the :file:`pse.dat` and :file:`isotopes.dat` files.

If you are using either of the "frozen" program versions available
for Mac OS X/Windows, then the two files are to be found in
the :file:`pyviblibdata/util` subdirectory of where the correspondent
distribution archive has been unpacked.

Otherwise, please execute a couple of Python statements that should print
the directory where the files are::

    >>> import pyviblib, sys, os
    >>> sys.stdout.write(os.path.join(pyviblib.get_rootdir(), 'util', '\n'))

Please refer to the :doc:`manual <manual>`
(version 1.0: section 4.13 on page 67) to learn how to add the necessary
data to the files.