Writing Gamera toolkits ======================= (c) 2004 Michael Droettboom What is a toolkit? ------------------ A toolkit is a way to distribute code that uses Gamera but is not included in the Gamera source tree. This could be entire applications that process images and return symbolic results (eg. an OCR package), or simply a library of utility functions (eg. for color image processing). The Gamera toolkit framework actually provides very little beyond the standard Python package and module system on which it is based: - A special Python distutils-based framework for building Gamera plugins more conveniently. - Support for adding a toolkit-specific drop-down menu to the Gamera GUI. If neither of these features is necessary for your project, you may decide to simply release your application or library as a standard Python package. Creating a toolkit ------------------ The directory heirarchy ``````````````````````` Toolkits require a number of different files in a directory heirarchy. Here we assume the toolkit is called ``my_toolkit``. +----------+----------------------------------------------------------------+ | ./ | Basic information files for building the toolkit | | +---------------+------------------------------------------------+ | | setup.py | A Python ``distutils``-based build script. | +----------+---------------+------------------------------------------------+ | gamera/ | All the files needed by Gamera at runtime. | | | Since Python is interpreted, these means | | | Python source files. | | +---------------+------------------------------------------------+ | | toolkits/ | This is where the Python source code of the | | | my_toolkit | toolkit goes. | | +---------------+------------------------------------------------+ | | toolkits/ | This is where the Gamera plugins for the | | | my_toolkit/ | toolkit go. | | | plugins/ | | +----------+---------------+------------------------------------------------+ | include/ | C++ header (``.hpp``) files. | | +---------------+------------------------------------------------+ | | plugins/ | Source code for the C++-based plugins. | +----------+---------------+------------------------------------------------+ Some toolkits may go beyond this, of course, by including ``.cpp`` files in a ``src/`` directory or documentation in a ``doc/`` directory. .. note:: At present, toolkit documentation does not compile along with the main Gamera documentation. I have not yet decided whether this should be considered a feature or a bug. The aruspix toolkit ```````````````````` For convenience, a minimal aruspix of a toolkit is provided and available from the files section of the `Gamera SourceForge site`__. .. __: http://gamera.sf.net/ This aruspix provides the very minimum needed to create a toolkit. You will need to change all the references to the toolkit name (Aruspix) throughout its source. The ``rename.py`` script is provided for this purpose. For example:: python rename.py my_toolkit will rename and edit all of the files to create a new toolkit called ``my_toolkit``. Editing the files ````````````````` The files included in the aruspix toolkit are self-documenting. They should require only minimal editing. Mainly, toolkit authors will be adding their own Python modules and Gamera plugins to the toolkit. setup.py '''''''' You only need to edit this file if you are doing anything more complex than installing Python modules and building Gamera plugins. For instance, if you are building and linking to a third-party library. Since this script is based on Python distutils, the distutils documentation is the best resource for how to do that. MANIFEST.in ''''''''''' If you need to include more data files to your toolkit distrubution, you will need to edit this file. The format is described in the distutils documentation. gamera/toolkits/my_toolkit/__init__.py '''''''''''''''''''''''''''''''''''''' If you want to add a drop-down menu to the Gamera GUI shell, you can edit this file. It is self-documenting. You will probably want to remove the example menu items that are included in the aruspix. Plugins ''''''' Writing plugins is described in detail here__. The Python metadata files for a toolkit go in ``gamera/toolkits/my_toolkit/plugins/``, and the C++ source code goes in ``include/plugins/``. .. __: writing_plugins.html Python modules '''''''''''''' The Python modules in your toolkit should go in ``gamera/my_toolkit/aruspix``. Building and installing a toolkit --------------------------------- Building and installing toolkits is very similar to building and installing Gamera itself. **You must ensure that Gamera is installed and working before attempting to build and install a Gamera toolkit.** The complete instructions for building Gamera toolkits is included in the aruspix example in the INSTALL file. You should redistribute this file with your toolkit.