#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass book
\begin_preamble
\sloppy
\clubpenalty=10000
\widowpenalty=10000
\end_preamble
\language english
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 1
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\leftmargin 1.5in
\topmargin 1in
\rightmargin 1.5in
\bottommargin 1in
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title

JGimp User Manual
\newline 
version 0.8
\layout Author

Michael Terry
\newline 
scrumpty@sourceforge.net
\layout Standard


\begin_inset LatexCommand \tableofcontents{}

\end_inset 


\layout Chapter

Introduction
\layout Standard

JGimp is an architecture that allows developers to create Java- and Jython-based
 plug-ins and extensions for the GIMP.
 Plug-ins allow developers to add functionality to the GIMP (through "filters"
 that operate on a given image or layer), while extensions are Java or Jython
 applications that use the GIMP as a "back-end" service providing image
 manipulation capabilities.
\layout Section

Feature summary
\layout Standard

JGimp offers developers the following features:
\layout Itemize

Plug-ins for the GIMP can be written in Java or Jython, allowing developers
 to use the rich set of UI techniques, widgets, libraries, and language
 features available for these two languages.
 The Desaturate plug-in provides one example of a filter with a dialog box
 written completely in Java, including a preview.
\layout Itemize

Java/Jython code can use the GIMP as an image manipulation engine/service
 by implementing the 
\begin_inset Quotes eld
\end_inset 

JGimpExtension
\begin_inset Quotes erd
\end_inset 

 interface.
 This essentially gives Java/Jython developers the full power of the GIMP
 within their own application.
 Possible uses of this capability include:
\begin_deeper 
\layout Itemize

Developing Java/Jython-based image manipulation server applications for
 dynamically-generated graphics
\layout Itemize

Creating new image manipulation applications in Java/Jython using the GIMP
 as the engine
\end_deeper 
\layout Section

System requirements
\layout Standard

JGimp runs on the Linux or Windows platforms, and has the following requirements
:
\layout Itemize

JDK 1.4 or later
\layout Itemize

GIMP 1.2.2 or later
\layout Itemize

Optional: Jython 2.1 or later (http://www.jython.org)
\layout Itemize

A healthy amount of RAM :)
\layout Standard

To build it from source, you will also need:
\layout Itemize

Ant 1.5.1 or later (http://ant.apache.org)
\layout Itemize

GCC and GNU make for Linux, Microsoft Visual C++ 6.0 for Windows
\layout Standard

The versions listed above represent the development versions we use; you
 might be able to compile JGimp using other versions of the software.
 For example, there is not much dependent on JDK 1.4 at this point, so a
 port to versions JDK 1.2 or 1.3 could probably be made with minimal effort
 (you would have to change how the JVM is loaded in the JNI code in jgimp.c,
 and change any 1.4-specific code in the Java code itself).
\layout Section

Quick start
\layout Standard

Two sample Java plug-ins, ImageDividerPlugIn and DesaturatePlugIn, illustrate
 how to use this architecture to write Java-based plug-ins.
 The source for these plug-ins can be found in 
\family typewriter 
jgimp/src/java/edu/gatech/cc/mterry/plugin
\family default 
.
 Two Jython scripts, 
\family typewriter 
imagedividernaive.py
\family default 
 and 
\family typewriter 
imagedivider.py
\family default 
, show the equivalent in Jython.
 They are located in 
\family typewriter 
jgimp/src/jython
\family default 
.
\layout Standard

The included Java and Jython plug-ins demonstrate the basics of how to use
 this architecture: how to make PDB calls (the GIMP's procedural database,
 which keeps track of all functions and plug-ins), how to read and write
 pixels from images in the GIMP, how to install the plug-in in the GIMP,
 and so on.
 A README file in 
\family typewriter 
jgimp/src/java/edu/gatech/cc/mterry/plugin
\family default 
 provides a brief overview of the process for Java plug-ins, including where
 to copy your plug-ins once you have made them.
 The jython script directory, 
\family typewriter 
jgimp/src/jython
\family default 
 also has sample scripts and a README offering the type of information for
 Jython scripts.
 All examples are thoroughly commented and can easily serve as the basis
 for new plug-ins.
\layout Standard

Aside from these examples, there are two other resources included with this
 distribution: the javadocs and this manual.
 Most of the Java API is documented.
 To generate the javadocs, go to 
\family typewriter 
jgimp/src/java
\family default 
 and type 
\family typewriter 
ant javadocs
\family default 
.
 This will create the javadocs and place them in 
\family typewriter 
jgimp/src/java/dist/javadoc
\family default 
.
\layout Section

Project history
\layout Standard

This project was originally started to support research into alternative
 interfaces for image manipulation.
 The idea was to prototype novel interfaces in Java, using the GIMP as the
 image manipulation engine.
 For more information about this research, see the section entitled "Side
 Views and Supporting Open-Ended Tasks" at http://www.cc.gatech.edu/~mterry/papers.
\layout Standard

We are currently working on a version that integrates directly with the
 GIMP, rather than being loaded as a plug-in.
 By taking this tact, we can gain access to some internal GIMP information,
 such as the entire image rendering, which is not possible with the current
 plug-in architecture.
 Access to these data is essential to building full-fledged, standalone
 Java-based image manipulation applications that use the GIMP as their backend.
 This direct patch is still very alpha at this time.
\layout Section

Getting further help
\layout Standard

If you have a question that is not answered by the docs or code, you can
 send a question to our discussion list: jgimp-developers@lists.sourceforge.net
\layout Chapter

Installing JGimp
\layout Standard

At a minimum, to run (not compile) JGimp, you need JRE 1.4 or later and GIMP
 1.2.2 or later.
 Other versions of GIMP in the 1.2.X series may work as well.
 Platform-specific instructions follow for compiling and installing JGimp
 on Linux and Windows platforms.
\layout Standard

TBD: NEED INSTRUCTIONS FOR JYTHON COMPILATION later in this document
\layout Section

Linux installation
\layout Standard

To compile JGimp you need:
\layout Itemize

Ant 1.5.1 or later (http://ant.apache.org)
\layout Itemize

JDK 1.4 or later
\layout Itemize

a recent version of GCC (we use 3.2.2 as of this writing)
\layout Itemize

GNU make
\layout Itemize

optionally, Jython 2.1 (http://www.jython.org) or later
\layout Standard

Other versions of Ant, GCC, and Jython may work as well; these are the versions
 we use and thus know work.
\layout Standard

Once these tools are installed, follow these steps:
\layout Enumerate

From the root directory, run 
\family typewriter 
configure
\family default 
.
 You will probably need to pass in at least two flags: 
\family typewriter 
--prefix
\family default 
 and 
\family typewriter 
--with-jdk-prefix
\family default 
.
 If you want Jython support, add 
\family typewriter 
--with-jython
\family default 
 and make sure 
\family typewriter 
jython.jar
\family default 
 (the main jar file distributed with Jython 2.1) is in your CLASSPATH (or
 it simply won't compile):
\begin_deeper 
\layout Enumerate


\family typewriter 
--prefix
\family default 
 should point to the base directory of your GIMP installation
\layout Enumerate


\family typewriter 
--with-jdk-prefix
\family default 
 should point to the base directory of your Java installation
\newline 

\newline 
For example: 
\family typewriter 

\newline 
./configure --prefix=/usr/local/gimp 
\backslash 
 
\newline 
\SpecialChar ~
\SpecialChar ~
--with-jdk-prefix=/usr/local/java
\layout Enumerate

or, with Jython support:
\newline 

\newline 

\family typewriter 
./configure --prefix=/usr/local/gimp 
\backslash 
 
\newline 
\SpecialChar ~
\SpecialChar ~
--with-jdk-prefix=/usr/local/java --with-jython
\end_deeper 
\layout Enumerate

Type 
\family typewriter 
make
\family default 
.
 If all goes well, both the Java code and C code will compile into their
 respective libraries.
\layout Enumerate

Next, type 
\family typewriter 
make install
\family default 
.
 This will install JGimp within the GIMP's directory, so be sure you have
 permissions for that directory.
\layout Enumerate

If you compiled with Jython support, make sure 
\family typewriter 
jython.jar
\family default 
 is in your CLASSPATH, or simply copy it to the same location as the other
 JGimp jar files (
\family typewriter 
GIMP/lib/gimp/1.2/jgimp/javafiles
\family default 
, where GIMP is the base directory of your GIMP installation).
\layout Section

Windows installation
\layout Standard

This section provides instructions for installing JGimp using the installer,
 compiling the source, and installing the binaries by hand.
 In all cases, you must follow the step in the next section.
\layout Subsection


\begin_inset LatexCommand \label{sub:jvm.dll}

\end_inset 

Putting jvm.dll's directory in your PATH
\layout Standard

Whether you are using an installer or installing the binaries by hand, you
 
\emph on 
must
\emph default 
 have the parent directory of 
\family typewriter 
jvm.dll
\family default 
 in your PATH.
 This dll is needed by 
\family typewriter 
jgimp.exe
\family default 
 to start up the Java virtual machine.
 
\family typewriter 
jvm.dll
\family default 
 is part of the Java package, and is typically found in 
\family typewriter 
JAVA_BASE_DIR
\backslash 
jre
\backslash 
bin
\backslash 
client
\family default 
 (e.g., 
\family typewriter 
c:
\backslash 
j2sdk1.4.1_01
\backslash 
jre
\backslash 
bin
\backslash 
client
\family default 
 for the SDK,
\family typewriter 
 c:
\backslash 
Program Files
\backslash 
Java
\backslash 
j2re1.4.1_01
\backslash 
bin
\backslash 
client
\family default 
 for the JRE only).
 Locate this file and note the directory in which it resides.
 Then go to the Control Panel, open up the System Control Panel, go to the
 "Advanced" tab, click on "Environment Variables" and then add the path
 to 
\family typewriter 
jvm.dll
\family default 
 to the System-wide PATH variable (making sure that it is separated by the
 other paths with a ";").
\layout Subsection

Using the installer
\layout Standard

TDB
\layout Subsection

Compiling from source
\layout Standard

To compile JGimp from source, you need the following:
\layout Itemize

Microsoft Visual C++ 6.0
\layout Itemize

JDK 1.4 or later 
\layout Itemize

Ant 1.5.1 or later (http://ant.apache.org/)
\layout Itemize

GIMP, version 1.2.2 or later
\layout Itemize

gimp-dev and glib-dev libraries (http://www.gimp.org/~tml/gimp/win32/downloads.html
; at the time of this writing, these files are http://www.gimp.org/~tml/gimp/win32
/gimp-dev-1.2.4-20030115.zip and http://www.gimp.org/~tml/gimp/win32/glib-dev-2.2.1)
\layout Itemize

optionally, Jython 2.1 or later (http://www.jython.org) 
\layout Standard

Once you have everything, you will build the library in two steps: first,
 the Java portion, then the C-library.
 You must follow the steps in the order given, since the Java build process
 creates files the C-library depends on.
 To compile everything:
\layout Enumerate

Create the directory 
\family typewriter 
jgimp/Windows_port/support_files
\family default 
.
\layout Enumerate

Unzip the gimp-dev and glib-dev zip files into 
\family typewriter 
jgimp/Windows_port/support_files/gimp_dev
\family default 
 and 
\newline 

\family typewriter 
jgimp/Windows_port/support_files/glib_dev
\family default 
, respectively.
 You should end up with a set of directories under 
\family typewriter 
gimp_dev
\family default 
 that include 
\family typewriter 
bin
\family default 
, 
\family typewriter 
include
\family default 
, 
\family typewriter 
lib
\family default 
, and 
\family typewriter 
man
\family default 
, with a similar set of directories under 
\family typewriter 
glib_dev
\family default 
.
\layout Enumerate

From a command prompt, change into 
\family typewriter 
jgimp/src/java
\family default 
 and if:
\begin_deeper 
\layout Enumerate

you 
\emph on 
do not 
\emph default 
want Jython support, just type 
\family typewriter 
ant
\family default 
.
 
\layout Enumerate

you 
\emph on 
do 
\emph default 
want Jython support, first make sure 
\family typewriter 
jython.jar
\family default 
 is in your CLASSPATH.
 jython.jar must be in your CLASSPATH at both compile and runtime, so you
 should add it to the environment variables for the entire system.
 Once it is in your CLASSPATH, type 
\family typewriter 
ant all-jython
\family default 
.
 
\end_deeper 
\layout Enumerate

To build the javadocs, type 
\family typewriter 
ant javadocs
\family default 
.
\layout Enumerate

With the Java portion built, you can now build the C-portion of the library.
 Open up the project workspace: 
\family typewriter 
jgimp/Windows_port/Windows_port.dsw
\family default 
.
\layout Enumerate

You will need to set up some paths within the project to customize to your
 own particular system:
\begin_deeper 
\layout Enumerate

Open up the project settings (Project->Settings)
\layout Enumerate

Select "All Configurations" in the "Settings For:" drop-down box
\layout Enumerate

Go to the C/C++ tab and select "Preprocessor" from the Category drop-down
\layout Enumerate

Make sure your "Additional include directories" include the following paths:
 
\begin_deeper 
\layout Enumerate

the path to the gimp development include directory (should be something
 like 
\family typewriter 
..
\backslash 
support_files
\backslash 
gimp_dev
\backslash 
include
\family default 
)
\layout Enumerate

the path to the glib development include directory (should be something
 like 
\family typewriter 
..
\backslash 
support_files
\backslash 
glib_dev
\backslash 
include
\backslash 
glib-2.0
\family default 
)
\layout Enumerate

the path to the glib development lib include directory (should be something
 like 
\family typewriter 
..
\backslash 
support_files
\backslash 
glib_dev
\backslash 
lib
\backslash 
glib-2.0
\backslash 
include
\family default 
)
\layout Enumerate

the path to the JNI include directory (something like 
\family typewriter 
c:
\backslash 
j2sdk1.4.1_01
\backslash 
include
\family default 
)
\layout Enumerate

the path to the JNI win32-specific directory (something like 
\family typewriter 
c:
\backslash 
j2sdk1.4.1_01
\backslash 
include
\backslash 
win32
\family default 
)
\end_deeper 
\layout Enumerate

Once you have configured all those paths, the final set of include directories
 should look something like this: 
\newline 

\newline 

\family typewriter 
..
\backslash 
support_files
\backslash 
gimp_dev
\backslash 
include,
\newline 
..
\backslash 
support_files
\backslash 
glib_dev
\backslash 
include
\backslash 
glib-2.0,
\newline 
..
\backslash 
support_files
\backslash 
glib_dev
\backslash 
lib
\backslash 
glib-2.0
\backslash 
include,
\newline 
c:
\backslash 
j2sdk1.4.1_01
\backslash 
include,
\newline 
c:
\backslash 
j2sdk1.4.1_01
\backslash 
include
\backslash 
win32
\end_deeper 
\layout Enumerate

Make sure that JGIMP_COMPILE_AS_PLUGIN is defined by the preprocessor in
 the Preprocessor definitions text box (in the same tab as in the above
 step).
\layout Enumerate

Make sure you have put 
\family typewriter 
jvm.dll
\family default 
's parent directory in your 
\family typewriter 
PATH
\family default 
.
 See Section 
\begin_inset LatexCommand \ref{sub:jvm.dll}

\end_inset 

.
\layout Enumerate

Set the active configuration to 
\begin_inset Quotes eld
\end_inset 

jgimp - Win32 Release
\begin_inset Quotes erd
\end_inset 

 (in Build -> Set Active Configuration...).
\layout Enumerate

Build all.
 There will be some warnings, but everything should compile if you have
 all the paths set up correctly.
\layout Subsection

Installing the compiled binaries by hand
\layout Standard

To manually install the binaries you have built, you need to copy the files
 into the GIMP program directory.
 GIMP will be installed in some place like 
\family typewriter 
c:
\backslash 
Program Files
\backslash 
GIMP
\family default 
.
 We'll abbreviate that to 
\family typewriter 
GIMP
\family default 
 in the following instructions.
\layout Enumerate

It's assumed you have built (or have the binaries for) 
\family typewriter 
jgimp.exe
\family default 
,
\family typewriter 
 jgimp.jar
\family default 
, 
\family typewriter 
desaturate.jar
\family default 
, and 
\family typewriter 
image_divider.jar
\family default 
.
 If you compiled all this by hand (as described above), then the jar files
 will be in the 
\family typewriter 
jgimp/src/java/dist
\family default 
 directory.
 
\family typewriter 
jgimp.exe
\family default 
 will be in the 
\family typewriter 
jgimp/Windows_port/jgimp/Release
\family default 
  directory.
\layout Enumerate

Copy 
\family typewriter 
jgimp.exe
\family default 
 to the plug-ins directory of the GIMP (e.g., 
\family typewriter 
GIMP
\backslash 
lib
\backslash 
gimp
\backslash 
1.2
\backslash 
plug-ins
\family default 
).
\layout Enumerate

Make a directory under 
\family typewriter 
GIMP
\backslash 
lib
\backslash 
gimp
\backslash 
1.2
\family default 
 called 
\family typewriter 
jgimp
\family default 
.
\layout Enumerate

Under 
\family typewriter 
jgimp
\family default 
, make a directory named 
\family typewriter 
javafiles
\family default 
.
\layout Enumerate

If you want Jython support (and you compiled it in), create another directory
 off of 
\family typewriter 
jgimp
\family default 
 called 
\family typewriter 
jython_scripts
\family default 
.
 
\layout Enumerate

It is important to get the name and punctuation correct when creating these
 directories, as JGimp will look here to load its various support files.
\layout Enumerate

Copy 
\family typewriter 
jgimp.jar
\family default 
, 
\family typewriter 
desaturate.jar
\family default 
, and 
\family typewriter 
image_divider.jar
\family default 
 to 
\family typewriter 
GIMP
\backslash 
lib
\backslash 
gimp
\backslash 
1.2
\backslash 
jgimp
\backslash 
javafiles
\family default 
.
 Optionally, you can also copy 
\family typewriter 
jython.jar
\family default 
 to the same directory, if you don't want to put it in your CLASSPATH.
\layout Enumerate

For Jython support, copy the scripts from 
\family typewriter 
jgimp
\backslash 
src
\backslash 
jython_scripts
\family default 
 to 
\family typewriter 
GIMP
\backslash 
lib
\backslash 
gimp
\backslash 
1.2
\backslash 
jgimp
\backslash 
jython_scripts
\family default 
.
\layout Enumerate

Make sure jvm.dll's directory is in your PATH.
 See Section 
\begin_inset LatexCommand \ref{sub:jvm.dll}

\end_inset 

.
\layout Section

Testing the installation
\layout Enumerate

Try starting up the GIMP and cross your fingers :) If everything went well,
 then you should have some new Java-based filters installed.
 Open up an image, then right-click on it.
 Check to see if Filters->Digital Cameras->Nikon Image Divider is there,
 and check if Filters->Colors->Desaturation Tools->Desaturation Dialog...
 is there.
 If those two items are there, then you've installed everything correctly!
 If you've installed Jython support, then there will also be Jython versions
 of the Nikon Image Divider plug-in.
\layout Enumerate

Now you can install your own Java-based plug-ins and extensions in the 
\family typewriter 
GIMP/lib/gimp/1.2/jgimp/javafiles
\family default 
 directory.
 You can also put Jython scripts in the 
\family typewriter 
GIMP/lib/gimp/1.2/jgimp/jython_scripts
\family default 
 directory.
 
\layout Chapter

Making Your Own Plug-Ins and Extensions
\layout Standard

More information will be available here, time permitting...
 In the meantime:
\layout Itemize

To create a plug-in, implement the 
\family typewriter 
org.gimp.jgimp.plugin.JGimpPlugIn
\family default 
 interface and use the sample Java plug-ins in 
\family typewriter 
jgimp/src/java/edu/gatech/cc/mterry/plugin
\family default 
 as a guide on how to construct your own Java-based plug-ins.
\layout Itemize

To write a Jython script, check out the 
\family typewriter 
README
\family default 
 in 
\family typewriter 
jgimp/src/jython
\family default 
 and use the sample Jython scripts in that directory as a guide.
\layout Itemize

Be sure to check out the javadocs for the library.
 You can build these by 
\family typewriter 
cd
\family default 
'ing into 
\family typewriter 
jgimp/src/java
\family default 
 and typing 
\family typewriter 
ant javadocs
\family default 
.
 They will be placed in 
\family typewriter 
jgimp/src/java/dist/javadoc
\family default 
.
\layout Standard

Some random notes until better documentation comes along:
\layout Itemize

You can place any support jar/class files needed by your plug-in in the
 same directory as your plug-ins (
\family typewriter 
GIMP/lib/gimp/1.2/jgimp/javafiles
\family default 
).
 JGimp will automatically load them.
\layout Itemize

JGimp will add the environment's CLASSPATH to its own CLASSPATH when searching
 for classes.
\layout Itemize

JGimp sets two keys in the 
\family typewriter 
gimprc
\family default 
 file: 
\family typewriter 
jgimp_javafiles_dir
\family default 
 and 
\family typewriter 
jgimp_jython_script_dir
\family default 
.
 You can customize these to point to other directories, if you wish.
\layout Itemize

The javadocs for JGimp use an extra javadoc tag, @pdb, which is used to
 indicate which GIMP PDB functions are directly called by that method.
 This information is listed in the generated javadocs.
\layout Itemize

Jython automatically converts return parameter lists having a single element
 into an atomic element (rather than as a 1-element list).
\layout Standard

Some notes on the interactive Jython interpreter:
\layout Itemize

It does not allow you to install plug-ins at this time.
\layout Itemize

It always appears when booting up if you have Jython support installed (no
 menu entry yet).
\layout Itemize

It automatically sets the variable 
\family typewriter 
gimpApp
\family default 
 to point to a org.gimp.jgimp.GimpApp object.
 From this object you can do everything else.
 For example:
\begin_deeper 
\layout Itemize


\family typewriter 
myImage = gimpApp.createRGBImage(100, 100)
\family default 
 creates a new RGB image of 100x100 pixels
\end_deeper 
\layout Itemize

You can type 
\family typewriter 
importPlugInNames()
\family default 
 at the prompt and it will import all PDB names into the namespace.
 Then you can do things like:
\begin_deeper 
\layout Itemize


\family typewriter 
myImage = gimp_image_new(100, 100, 0) # don't need to go through gimpApp
 object, can call PDB functions directly
\the_end
