1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
Phatch Contributors Guide
=========================
image::images/splashscreen2.png[Phatch Logo]
.Phatch = Photo & Batch!
**********************************************************************
Phatch is a simple to use cross-platform GUI Photo Batch Processor which handles all popular image formats and can duplicate (sub)folder hierarchies. Phatch can batch resize, rotate, rename, ... and more in minutes instead of hours or days if you do it manually. Phatch will also support a console version in the future to batch photos on webservers.
**********************************************************************
Introduction
------------
Welcome
~~~~~~~
Thanks for contributing to Phatch!
* You might have exciting ideas how to extend the functionality with new features. The good news is that Phatch was designed from the ground up to make the development of actions as easy as possible.
* Or you might want to write some documentation or tutorial.
Required Skills
~~~~~~~~~~~~~~~
Developping Action plugins
^^^^^^^^^^^^^^^^^^^^^^^^^^
To develop actions for Phatch you only need to know http://www.python.org[Python] and http://www.pythonware.com/products/pil[PIL] (Python Image Library). Although Phatch uses http://www.wxpython.org[wxPython] for its cross-platform GUI, you don't need at all wxPython to write actions. Phatch will do all the GUI work automatically for you behind the scenes, so you can fully concentrate on the image manipulation. Also don't worry about internationalisation, Phatch will take care of that too.
Writing documentation
^^^^^^^^^^^^^^^^^^^^^
Can you work with notepad, gedit or kate? Fine, that is all you need. The documentation is generated from plain text files, which follow the http://www.methods.co.nz/asciidoc[asciidoc] format. They can be translated afterwards in a lot of different formats, such as html and pdf. You don't need to install asciidoc to write documentation. You can send the plain text files to the Phatch development team and we will take care of it. However if you are curious, you will find instructions in this manual on how to install asciidoc on Ubuntu Feisty to generate pdfs. This might be usefull as well to install asciidoc on other operating systems.
Translating
^^^^^^^^^^^
* Translating the application Phatch is done through https://translations.launchpad.net/phatch/trunk/+pots/phatch[launchpad].
* Translating of documentation is done with plain text asciidoc files. Be sure to keep a copy of the source file on which you base your translation. This will allow you to quickly see what has changed with a diff viewer when new documentation is available for translation.
Developping Action Plugins
--------------------------
Getting Started: Invert
~~~~~~~~~~~~~~~~~~~~~~~
Introduction
^^^^^^^^^^^^
The best way to start is first to develop an PIL function which handles the manipulation. Afterwards you create input fields in order to pass the required parameters to the PIL function. 'Invert' is taken as a first case study as it doesn't require any parameters except for the image itself. Let's look at the source code:
.Invert Action Source Code
[python]
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
from core import models # <1>
from core.translation import _t
def init():
#lazy import
global Image, ImageChops
import Image, ImageChops
#--- PIL function
def invert(image,amount=100): # <2>
inverted = ImageChops.invert(image)
if amount < 100:
inverted = Image.blend(image, inverted, amount/100.0)
if image.mode == 'RGBA':
inverted.putalpha(image.split()[-1])
return inverted
#--- Phatch Action
class Action(models.Action): # <3>
label = _t('Invert')
author = 'Stani'
email = 'spe.stani.be@gmail.com'
init = staticmethod(init) # <4>
pil = staticmethod(invert) # <5>
version = '0.1'
tags = [_t('colours')]
__doc__ = _t('Invert the colors of an image') # <6>
def interface(self,fields): # <7>
fields[_t('Amount')] = self.SliderField(100,1,100)
icon = \ # <8>
'x\xda\x01\x91\nn\xf5\x89PNG\r\n\x1a\n\x00\x00\x00...'
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<1> Importing Modules.
<2> Defining The PIL Function.
<3> Defining The Action.
<4> Linking The init function.
<5> Linking The pil function.
<6> Describing The Action.
<7> Defining The Interface.
<8> Adding An Icon
Importing Modules
^^^^^^^^^^^^^^^^^
For every action you need to add the first two lines which import the basic functionality for writing action plugins. The module models provide the architecture for the plugin: the `class Action` and the input fields.Every other module you need to import with the function `init()`, in which you declare them as global. For example to invert an image with PIL you need the `ImageChops` module.
NOTE: Why do modules have to be imported in a seperate method? The reason is that Phatch at startup imports all actions to extract the information it needs about the actions. If the imports would be declared normally, the startup would be delayed by maybe unneeded modules.
Defining The PIL function
^^^^^^^^^^^^^^^^^^^^^^^^^
The PIL function should be defined separately from the action. This is a design choice, similar to splitting the Model from the View in the MVC approach.
Defining The Action
^^^^^^^^^^^^^^^^^^^
You need to create a new `class Action` which is derived from `models.Action`. You need to define the action with the `label`, `author`, `email`, `init`, `pil`, `version`, `tags` and `__doc__` properties. `label` and `__doc__` will appear translated in the 'Add Action' dialog box. That is why you need to mark them with the `_t` function. We link our init and pil function as static methods to the class. (At the moment `tags` and `description`, which can contain a longer description than the `__doc__` one-liner, are not exposed yet.)
Describing The Action
^^^^^^^^^^^^^^^^^^^^^
In the description property you can describe the action more elaborately. Use triple quotes for multi-line text.
Adding An Icon
^^^^^^^^^^^^^^
As in the example no specific icon was added, Phatch will use a default one. In the wxPython demo package (python-wxtools) there is an utility `img2py.py`. With the following command you can convert any image (eg.png) to a python file:
$ python img2py.py fileName icon.py
This will generate an `icon.py` file, in which you will find the following code:
[python]
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
def getData():
return zlib.decompress('icon data')
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can add now the 'icon data' to your action source file to define the icon:
[python]
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
class Action(models.Action):
description = """Invert the colors of the image."""
icon = 'icon data'
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
NOTE: Internally Phatch works with 'photos'. 'Photos' consist of multiple 'layers'. Every 'layer' contains an 'image', but also has its own offset postion. Phatch doesn't expose this functionality yet, but will later support full layered photos, just like in Gimp. The hierarchy to remember is: Photo>Layer>Image. Luckily you don't have to worry about this in the beginning as Phatch provides you an easy method to apply a PIL function the current layer image: `apply_to_current_layer_image`.
Further Study
~~~~~~~~~~~~~
Probably looking at the source code of the actions, will teach you the most. You find all the actions in the folder `phatch/actions`
[icon="./images/icons/ubuntu.png"]
NOTE: If you installed Phatch on Ubuntu, probably the actions are in the folder: `/usr/lib/python2.5/site-packages/phatch/actions`
Read the tutorial on the http://photobatch.wikidot.com/writing-actions[wiki].
Writing Documentation
---------------------
Introduction
~~~~~~~~~~~~
The mechanism used for documentation is asciidoc. You can find more information here: http://www.methods.co.nz/asciidoc/[]
You can send plain text files which will be translated into pdf an html. The html will be published on the Phatch website, which might include some advertisements. The pdf version will be a present to anyone who donates. If you contribute documentation, you agree with these conditions
Installing AsciiDoc
~~~~~~~~~~~~~~~~~~~
Ubuntu Feisty
^^^^^^^^^^^^^
1) Install from the repositories
You need to install these packages:
sudo apt-get install asciidoc docbook-xml docbook-xsl source-highlight
2) Install FOP (for pdf)
To generate pdfs you will need http://xmlgraphics.apache.org/fop/[FOP], which unfortunately is not available as a package. Also we need an older version, as the current one is not compatible with the Ubuntu packages. Therefore download http://archive.apache.org/dist/xmlgraphics/fop/binaries/fop-0.20.5-bin.zip[fop-0.20.5-bin.zip].
Unzip this folder to where you want, for example `/opt/fop`. Make a symbolic link so fop.sh is recognized as a command:
sudo ln -s /opt/fop/fop.sh /usr/local/bin/fop.sh
Add this line to fop.sh so that it can find your java version:
JAVA_HOME=/usr/lib/jvm/java-6-sun
Of course if you use another java-version, link to that file instead. To add support for PNG images, you need to download the JIMI library from SUN. Because of licensing issues, the JIMI image library is not included in the FOP distribution. First, download http://java.sun.com/products/jimi[JIMI]. Then unzip the folder and copy the file `JimiProClasses.zip` from the archive to {fop-install-dir}/lib/jimi-1.0.jar. Please note that FOP binary distributions are compiled with JIMI support, so there is no need for you to build FOP to add the support. If jimi-1.0.jar is installed in the right place, it will automatically be used by FOP, otherwise it will not.
3) Source highlighting
Copy the filter (`./examples/source-highlight-filter/source-highlight-filter.conf`) to one of the standard AsciiDoc filter locations typically `/etc/asciidoc/filters/` or `~/.asciidoc/filters/`. Unfortunately source highlighting only works with the command `asciidoc` and not with `a2x`.
(C) copyright 2007 http://www.stani.be[www.stani.be]
|
