PIGALE User Manual

Using Pigale

Overview

Starting Pigale

Pigale first reads the settings that have been saved or the default ones
The input and output files can be overridden by the arguments passed to Pigale.
The valid flags are:

-i	`input-filename`
-o	`output-filename`
-m	`macro-filename`
-s	to start Pigale as a server.

The filenames must include the paths, which will determine the directories where the files are loaded and saved.
The first time you execute Pigale, you may be asked to give a location of input files and the location of this manual.
Graphs are either coded as tgf files or ASCII files.

The arrows of the tool bar let you load the next or previous graph of the current tgf file or reload the current one.

On the lowest band of the main window is displayed the current tgf input and output file.
In Pigale there always one active graph which is displayed in the Graph editor window. That graph can be saved, modified or displayed by different algorithms. A copy is created for any display except forthe Graph editor window.

Windows

Under the menus, there is a tool bar that you can move around or hide.
Notice that some menus are not available if the current graph does not fulfill the right properties for a given algorithm.
If you see a small manual " xman

" at the left of a menu item, you can get a small help using the WhatisThis button xman

The windows next, to the Graph editor window, are used to show different views of a graph and this short manual.
They can be printed (except the one for 3d embeddings) or exported as png images.
The top right window is for messages (properties of the graph, warnings, etc.). Just under are displayed the main properties of the graph, all of them are maintained in real time.

Pigale settings

Among other things, the Settings menu allows you to:

enable debug to increase the verbosity of Pigale and print more messages in log.txt,
enable or disable the undo feature,
define the Pigale colors used by Pigale
define the limits of Pigale: i.e. define the maximum number of vertices above which graph are not displayed and slow algorithms are not performed
define what the vertex show i.e. their labels or their index (or whatever the user programmed),
define some embed options.
define the distance used to embed the graph in R^n-1.
save the following:
- all the settings of this menu,
- the generator settings,
- the macro playback settings,
- the macro pause delay setting,
- the input and output tgf files,
- the documentation directory,
- the image directory,
- the geometry and colors of the screen,
- the transparency of facets and opacity of images,
- the printer settings.

The dashed line at the top of the settings menu, is used to create a floating settings menu.
top

Using the editor

Mouse Actions

By default, the left button of the mouse is use to move vertices.
Other actions can be selected, by clicking on the radio buttons (Left Button).

Col/Thick: Color (edges and vertices) or thickness (edges)
Add/Del: Add or delete (edges and vertices)
Orient: Orient (edges)
Move: Move (vertices)
Bis./Con.: Bisect or contract (edges)
Ext.Face/extbrin: Define the exterior face or the extbrin
Label/Reset all: Redefine the label of a vertex/Reset all labels as the indices

If the shift key is pressed, the actions are toggled the following way:

Add / Del
Orient / Suppress the orientation
Move a vertex /Move all vertices of a given color
Bisection / Contraction
Exterior face / extbrin

If the alt key is pressed, the action is always Move a vertex

Other actions:

Mouse

Add + Control left button to duplicate the colored subgraph
Add + Shift Control left button to duplicate the colored subgraph and add edges between corresponding vertices.
middle button to move vertices of the current color
right button to display some information on edges and vertices

Trackpad

Add + Command to duplicate the colored subgraph
Add + Control + Command to duplicate the colored subgraph and add edges between corresponding vertices
Move + Shift to move vertices of the current color
Control + clic to display some information on edges and vertices

Mac COMMAND <-> Windows CONTROL
Mac CONTROL <-> Windows ALT

Colors and Thickness

The 16 upper small colored squares at the right of the editing window, defines the brush color which appears with a bigger square.
The brush color defines the color of the vertices when they are created, re colored or define the ones to be deleted.
The 16 lower squares have the same functionality for edges.
The last 3 squares are used to define the thickness of the edges.

Drawing on a grid

The grid size is defined by the slider position.
When a graph is loaded, Pigale computes the minimum size grid on which the graph can be drawn, without moving the vertices. When you click on Force G, Pigale will force all the vertices to fall on grid points, checking overlapping of vertices and checking that the map is unchanged. The undo G button, let you come back to the previous state. When you click on Fit grid, you are forced to move or create vertices on grid points.

Load Image

A picture (of a graph) is loaded in the background of the editor. Its size is adjusted to fit the editor window. The left slider lets you reduce the image opacity so that you can easily create graph corresponding to the picture. You may have to remove isolated vertices, isthmus and parallel edges.

Clear Image

Removes the background image.

Undo/Redo

If this function is enabled, a copy of the current graph is appended each time a program adds or delete edges or one manually delete vertices.
One can always Redo an undo.
When a new graph is loaded, all the copies are destroyed and the current graph is saved.
The save icon let you manually append a copy.


Undo	Save	Redo

There is no limit of the number of copies which are placed in a temporary file, which name is written in log.txt.

Zoom

You can use the mouse Wheel or move on the trackpad with two fingers or use the keyboard up and down arrows.
Use home (Mac: Fn + left) to reset the zoom.
top

Macro

You can record any number of functions from the menus Augment, Remove, Dual/Angle, Algo, Orient, Generate and UserMenu.
These macros can be saved as text files.
When you execute a macro, the recording is stopped but you can restart it.

Play macro

If the first record is not a graph generator, the macro will start loading the next graph of the current file.
If the repeat macro value is 0, the macro will be repeated until you quit by typing ESC, or if an error occurs.
top

Embedding a graph in space

The user have the choice among the following distances:

Czekanovski-Dice has been shown effective for graph partitioning,
Bisect is such that the isometries of the graph are in a one to one correspondence with its automorphisms,
Adjacence is not a Euclidean distance,
Adjacence M is a modification of the previous one and is Euclidean,
Laplacian is defined by the laplacian of the complemented graph and is Euclidean,
Oriented is a generalization to directed graphs of the Czekanovski-Dice distance,
R2 is the one used by the drawing in the editor an is used for experiments.

The axes X,Y,Z are respectively colored Red,Green,Blue

Mouse Action

Left button:
- Moving along X axis -> Rotate around Y
- Moving along Y axis -> Rotate around X
- Double Click -> Start/Stop Rotate (depends on vertical slider)
Right button:

Moving along X axis -> Rotate around Y
Moving along Y axis -> Rotate around Z

Middle Button:
- Moving along X axis -> Translate along X
- Moving along Y axis -> Translate along Y
Middle+Shift Button: Translate along X and Z
- Moving along X axis -> Translate along X
- Moving along Y axis -> Translate along Z
- Wheel: Zoom

Trackpad

Moving along X axis -> Rotate along Y
Moving along Y axis -> Rotate along X
ALT + Moving along X axis -> Rotate along Z
SHIFT + Moving along X axis -> Translate along X
SHIFT + Moving along Y axis -> Translate along Y
COMMAND + Moving along Y axis -> Translate along Z

Mac COMMAND <-> Windows CONTROL
Mac CONTROL <-> Windows ALT

Other Interactions

Facet button draw the facets if the graph is planar.
Label button turns on/off vertices label.
Color button turns on/off the original vertices color.
Fog button turns on/off the fog.
the spin boxes Ew Vw set the width of edges and vertices.
the buttons X Y Z set the fixed axis for animation.
the three rightmost spin boxes X Y Z let you select the projection space.
the left slider sets the rotation speed around the chosen axis.
the right slider sets the transparency of the facets.

top

Generating graphs

The planar graph generators are based on the algorithms of Gilles Schaeffer. They produce random planar graphs with prescribed properties.
The size input of these algorithms is either the number of edges or the number of vertices.
The program automatically modified this value if unacceptable (e.g. a cubic graph has a number of edges divisible by three).
Depending on the prescribed properties, the algorithms, consume more or less memory and time. To get reasonable performance, we allow the algorithms to generate graphs with slightly different size than the prescribed one.
Loops are always erased (1-connected graphs get less edges than asked).
If the option Erase multiple edges is on, we erase multiple edges after the generation process, therefore we do not maintain the degree property.
top

Tgf, GRAPHML and ASCII files

We use a general proprietary format TGF.
A TGF file contains records, here corresponding to graphs. Each record consisting of a variable number of fields.
One of its main advantage is that we can write and read any complex data structure. But it is dependent of the processor type (Low or High indian etc).

We partially implemented the GRAPHML file format (cf. http://graphml.graphdrawing.org/), which is now the only way in Pigaleto add text labels to the vertices

We use a very simple ASCII file structure to store graphs.
For example, the following file defines a graph called Triangle with three vertices labeled 10,20,30 and three edges. The first 0 at the last line indicates the end of the list of edges, the second one indicates the end of the graph data. PIG:0 Triangle 10 20 20 30 30 10 0 0
top
Last modified: 05/20/2019