Using JaxoDraw

Terminology

Object
An object is the collection of points, with optional associated values, that makes up one entity of a Feynman diagram. Examples are blobs, lines, arcs, boxes, loops, etc. The associated values can be used to change the appearance of an object, like color, line width, photon amplitude, and several other features.
Group
Different objects may be collected to form a group, such that they may be moved/copied/edited together.
Graph
A graph is the collection of objects (lines, arcs, ...), together with titles, comments, layout options, etc. drawn to display the Feynman diagram.
Parameters
Parameters are the settings of symbols, line styles, colors, fonts, etc. used to define graphs and the display of the active objects.
Handles
When the program goes into Edit mode (any mode that allows the modification of any parameters of any object), little red squares are displayed on certain points of every object (for instance on the end points of lines). When the user clicks on one of these handles, the corresponding edit operation is being carried out on the chosen object.
Canvas tab (Tab)
Canvas tabs (Tabs) are different drawing areas that allow the user to work on several graphs at a time.
Clipboard
A virtual canvas tab that is used as a buffer to copy objects from one tab to another.

Execution

The most convenient way to start JaxoDraw depends on your operating system and on how you installed the program. See the installation section for generic instructions on compiling and running JaxoDraw.

If you want to compile JaxoDraw yourself from sources, you have to use the ant script build.xml to create the executable jaxodraw.jar file (see the section on ant). The binary distributions already contain a pre-compiled jaxodraw.jar file, which can then be executed with the command

java -jar jaxodraw-xxx.jar

in the current directory (xxx is the version number). Supposing you have a Java Runtime Environment installed and configured on your system, this will work on any platform.

Command line parameters

The current version JaxoDraw-2.0 supports the following command line parameters:

--version
Prints out the version number of JaxoDraw.
--help
Prints out some usage info on the standard output.
--info
Prints out some information about your system.
--convert
Used to convert a number of JaxoDraw xml files (given as parameters on the command line) to axodraw4j tex files (and vice versa) without the need of bringing up the user interface. Use like eg:
java -jar jaxodraw-xxx.jar --convert test1.xml test2.tex
converts test1.xml to test1.tex and test2.tex to test2.xml.
-verbose
Turns on verbose error messaging (default in the current version).
-debug
Same as -verbose.
-quiet
Turns off verbose error messaging.
-nosplash
Doesn't show the splash window at start up (default is to show it).

By default, all parameters starting with '--' do not pop up the graphical user interface of JaxoDraw.

Furthermore, if you have saved an XML file with a JaxoGraph in an earlier session, you may read in this graph directly on the command line by supplying the file name as an argument (the extension of the file has to be .xml).

Drawing

Drawing Feynman diagrams with JaxoDraw is pretty easy and self-explaining. The program has been designed with the main strategy to be easy to use. In particular, if you are familiar with the xfig program, you will have little problems to get used to JaxoDraw. In general, to draw an element of a Feynman diagram, you first choose the drawing mode by clicking on the corresponding button in the button panel, and then draw the object by left mouse-clicking and dragging on the canvas. Drawn objects may then be moved/resized or edited by choosing the corresponding button in the edit button panel and then clicking on one of the handles specifying the object.

A few things to note:

  • Arcs and triangular vertices are drawn in a three-click process, beziers in a four-click process. Any of the points may then be moved using the resize button.
  • Any operation that changes any attribute of an object (move, resize, edit, ...) will automatically put the object in the foreground.

Setting resources

JaxoDraw allows the permanent setting of preferences via the Preferences menu. If you press the "Save" button for the first time in the Preferences dialog, the current settings are stored in a specific preferences file. The exact name and location of this file depends on your operating system. It is read automatically every time JaxoDraw is started. Normally, you should not edit this file manually, but use the Preferences menu dialog of the graphical user interface. See the Preferences menu item of the menu bar for more information on the items that may be saved on a permanent basis.

Colors

There are two color spaces that may be chosen in the Preferences menu: the colordvi space that restricts colors to the ones defined by the colordvi LaTeX class; and the 'complete' space, that lets you choose any color. If you use the complete space and do a LaTeX export, the colors will be adjusted to the 'closest' colordvi values. The following information applies to the colordvi space.

In the current version of JaxoDraw, the user may choose from a set of 84 colors that are presented in a convenient color chooser panel if the user clicks an object in color mode. The colors include all the 68 colors defined by the colordvi LaTeX class (on a standard TeTeX distribution, these may be found in /usr/share/texmf/tex/plain/dvips/colordvi.tex) and 16 gray scales. If figures with color are produced via the latex -> dvips command of JaxoDraw, these colors will be used as defined in the colordvi style file. For direct Postscript output, we have tried to reproduce as closely as possible the RGB values of these colors, but since there are no complete RGB specifications (for free), the output will not be exactly the same as in the LaTeX case.

As a reference, there are two files in the source distribution of JaxoDraw, that illustrate the differences. The latexcolor.ps file in the JaxoDraw/doc/ directory gives a collection of all the colors present in colordvi as produced by latex -> dvips. The file pscolor.ps in the same directory gives the corresponding collection as produced by direct Postscript output.

Notice that when using Blob, Box or Triangle objects, if the fill color is a gray scale, the line color will always be black. If you want a different line color, the fill color must not be a gray scale (but it can be the Gray color). This is done to mimic the behavior of the axodraw LaTeX style.

Text

There are two ways of entering text in JaxoDraw: Postscript text mode and LaTeX text mode. Even though they may be used at the same time in a graph, they will appear mutually exclusive in any derived output (a warning message is displayed if a Postscript export/preview is attempted with some LaTeX text present in the graph, and vice versa).

Postscript text mode
When entering the Postscript text mode, the user may enter a text string that will appear directly on the screen and in any direct Postscript output (i.e., also in any printer output). It will not appear in any output created via latex -> dvips. In edit mode, the user may choose the text size and font of the text object. A set of Greek characters is available via a syntax that is derived from the corresponding LaTeX commands:
alpha \alpha lambda \lambda upsilon \upsilon Lambda \Lambda
beta \beta mu \mu phi \phi Xi \Xi
gamma \gamma nu \nu chi \chi Pi \Pi
delta \delta xi \xi psi \psi Sigma \Sigma
epsilon \epsilon $o o omega \omega Phi \Phi
zeta \zeta pi \pi vartheta \vartheta Psi \Psi
eta \eta rho \rho varphi \varphi Omega \Omega
theta \theta varsigma \varsigma Gamma \Gamma
iota \iota sigma \sigma Delta \Delta
kappa \kappa tau \tau Theta \Theta
Note that no $ signs are necessary for these commands (any $ signs will appear verbatim on the screen). If the user enters a string starting with a "\" that is not recognized as a valid Greek letter, it will be replaced by a question mark "?". Super- and subscripts are available in some rudimentary form via a syntax that is again derived from the corresponding LaTeX syntax, i.e., for A^\mu_\nu you would type A^{\mu}_{\nu}. Note again that no $ signs are necessary and that the brackets are always required even if there is just one character as an argument. Curly brackets are implemented via a syntax that is again inspired by LaTeX: \{ and \}.
LaTeX text mode
When entering the LaTeX text mode, the user may enter a text string that will appear only in the LaTeX output file and any files created from it via latex -> dvips. Like that all the commands known to LaTeX in math mode are available to the user. Notice that if a math symbol requires a dedicated LaTeX package to be displayed (such as the amssymb package, etc.), the user has to include it explicitly through the ``Add LaTeX package" entry of the Options menu (otherwise the LaTeX compilation will fail producing an ``Undefined control sequence" error). The position of the text will be marked on the screen by an icon that identifies it as a LaTeX text object. This icon does not appear in direct Postscript or printing output. If the icon is rolled over by the cursor, the corresponding LaTeX text is displayed in a pop-up window on top of the canvas. Note that the LaTeX text string will automatically be put between $ signs, so the text will always be in LaTeX math mode. If you want a normal font in LaTeX text mode, you should use {\rm }. Note also that your input here is the only possible source of errors in your LaTeX source code. If you get any LaTeX compilation errors, check your LaTeX text objects first. In edit mode, the user may choose the LaTeX font size and the alignment with respect to the current position of the text object. You can also specify rotation angles for LaTeX texts (rotations are implemented using the LaTeX pstricks package).

Grouping

JaxoDraw allows the grouping of different objects into a single one so that they can be moved, resized and edited at the same time. Grouping groups is also allowed, and the hierarchy is always respected. To build a group of objects, first select the desired objects, then right click and select 'Group' from the drop-down menu.

Apart from grouping objects using the Select mode, one can use also the ``faint box'' method. At any time, it is possible to click the right mouse button on the canvas and by dragging, there will appear a faint gray box. Once the button is released, all objects entirely located inside this box will be grouped together. This method may be used also when the program is not in select mode, i.e., without having the Select button pressed.

Tabbing

It is possible to work with several graphs at a time by using the tabs of JaxoDraw. At the first start-up, the program just contains one tab ("Untitled"), you may add tabs with the New tab entry in the File menu and tabs may be closed with the Close entry. These operation are also presented in a pop-up menu if the user right-clicks on a tab. Notice that new tabs sharing the same name with existing opened tabs, will be automatically numbered. Objects from one graph may be copied to other graphs, using a copy and paste procedure treated in the next section.

Using the clipboard

It is possible to copy objects from one canvas to another one, by first copying them to the clipboard, and pasting the clipboard content into the desired canvas tab afterwards. To copy objects to the clipboard, select them (using the Select button or the 'faint box' method) and choose 'Edit - Copy' (notice that the previous clipboard content will be lost). Next click on the canvas tab were you want to paste the clipboard content and then click on the paste icon of the tool bar (alternatively you can use the Paste item of the Option menu, or right click on the canvas tab and choose the Paste entry from the pop-up menu).

Importing LaTeX files

JaxoDraw allows to import existing LaTeX files, even if they were not originally created by JaxoDraw. However, only commands that are known to JaxoDraw are actually recognized (that are commands that are used when exporting to a LaTeX file), unknown commands will be silently ignored. The commands known to JaxoDraw are:

\ArrowArc \ArrowArcn \ArrowLine \CArc
\CBox \CCirc \COval \CTri
\DashArrowArc \DashArrowArcn \DashArrowLine \DashCArc
\DashLine \GBox \GCirc \GlueArc
\Gluon \GOval \GTri \Line
\PhotonArc \Photon \SetColor \SetWidth
\Text \usepackage \Vertex \ZigZag

(see the axodraw user guide for documentation on these commands [3]). In addition, the following LaTeX commands are required:

\documentclass \begin{document} \begin{picture}

If these ones are not found in the file to be imported, the import process is abandoned with a warning message.

Due to the specific algorithm internally used by JaxoDraw to draw triangles, the commands \GTri and \CTri will work only when the imported LaTeX file has been generated from JaxoDraw itself. Otherwise they will be ignored. Moreover, because of rounding errors in the export/import routines, sometimes the imported graphs may be slightly different from the original ones (possible differences being the number of wiggles/windings of photon/gluon objects and the position of objects). These differences are usually of one unit. Lines that start with %%\JaxoComment will be read in as a description of the graph while lines of the form %%\JaxoScale{scale} allow to read in a floating point value scale factor which is used internally by JaxoDraw to convert Java coordinates into LaTeX coordinates. If it is not given, the scale factor defaults to 1. Finally lines of the form %%\JaxoDrawID: are identifiers used by JaxoDraw to reconstruct some objects.

Watch file mode

The WatchFile mode is switched on and off via a button in the tool bar. When switched on, a postscript preview will only export the current graph into a temporary file, but will not open it with the current default postscript viewer. This has the advantage that if you have already a postscript viewer window open, no new window will pop up, you can just redraw the graph in the old window. Note that for this to work, you need to switch on the WatchFile mode after your first preview operation, otherwise no postscript window will be opened in the first place.

Plugins

Version 2.0 of JaxoDraw introduced a plugin architecture, in order to draw some functionality out of the JaxoDraw core. This makes it easy to use optional features, like export to uncommon formats, while keeping the size of the main program at a minimum.

Plugins are installed (and un-installed) using the Plugin Manager panel accessible from the Options menu. Once a plugin is installed, JaxoDraw will automatically recognize it at start-up and the corresponding functionality will be available for the session (eg export to some other file format).

Please check the JaxoDraw web site for a list of available plugins, at the time of this writing, there were plugins available for export to PDF and SVG format.

Note that it is also possible to write your own plugins for new export/import formats. A tutorial for doing that is available on the JaxoDraw web site.

Comments and bug reports

Please send your comments, questions or bug reports to the jaxodraw-discuss mailing list:

jaxodraw-discuss@lists.sourceforge.net

When reporting bugs, you should be as specific as possible about the problem so that we can easily reproduce it. Include some information about your operating system, the Java version and the version of JaxoDraw that you are using. Include for instance the output of the

java -jar jaxodraw-xxx.jar --info

and

java -jar jaxodraw-xxx.jar --version

commands (this information is also available under the Help menu of the graphical user interface). You should also try to run JaxoDraw in debug mode:

java -jar jaxodraw-xxx.jar -debug

and check for any relevant information.

If you are having problems with the LaTeX compilation process, also include detailed information about your LaTeX distribution, the version of dvips, your Postscript viewer and any other information that may be relevant.

We will try to make all messages of general interest available on our Web-site

http://jaxodraw.sourceforge.net/

Please check these pages and also the FAQ and Known problems sections of this document before reporting any bugs.


Prev Home Next