A Manual for Giv

The G(reat|tk|NU) Image and Vector viewer


Version 0.9.18
Dov Grobgeld
Homepage: http://giv.sourceforge.net/giv
dov.grobgeld@gmail.com
Last modified: 2011-04-05

1. Description

giv is an image viewer with the following features:

1.1. Images

Images are loaded through gdk_pixbuf and giv supports all the formats supported by it. The image may be scrolled and zoomed with the mouse or the keyboard.

Here is an example of the image display:
Normal scale Zoom in

1.2. The giv files

giv has the cabability to read files describing vector annotations that are drawn on top of the image, or make up a drawing on their own. The annotations are loaded in file known as giv files. The giv files contains one or more data sets. A data set consists of properties, followed by the list of data points.

A few of the properties are global and they effect not only the dataset, e.g. the $image property that is used to load a different image.

The properties all start with the $ sign. Here is a list of all the properties supported:

Property Example Description
$color $color pink3
$color gold/0.2
$color #ff0080/0.5 		The color of the data set. If the color has a trailing "/num" then it is considered to be the alpha transperancy of the color.
$outline_color $color green The outline color of a polygon
$noline $noline Indicates that the no lines should be drawn for the data set.
$marks $marks circle The type of the mark. Valid marks are:
  • circle
  • fcircle
  • square
  • fsquare
$scale_marks $scale_marks Indicates whether the marks should be scaled together with the image. Default is not to scale.
$noline $noline Don't draw line between the coordinates.
$linedash $linedash 10 5 Specifies that lines should be drawn with dashes. The numbers indicate the dash and the spacing size. There may be multiple pairs, indicating sequential shapes.
$mark_size $mark_size 15 Specify the size of the marks in pixels.
$lw $lw 3 Line width. This also affects the width of the outline marks (e.g. circle and square).
$image $image maja.pgm Reference image to be shown below the image. Several images lines may be given. The user may rotate between the different images through the shift-Up and shift-down key bindings.
$arrow $arrow start Indicate that arrows should be added to the lines. Arrows may be drawn at the start, of the line, the end of the line, or both by giving the keywords "start", "end", "both" after $arrow.
$font $font Monospace 24 Font to be used for drawing text. The name of the font is according to requirements of pango font string representation.
$balloon $balloon Suspect Adds another line to the popup balloon that is shown when the balloon popups have been turned on (in the view menu) and the mouse hovers over the dataset.
$polygon $polygon Indicates that the dataset should be filled.
$def_style $def_style Ref $color green Defines a new style that may be referenced through the $style keyword.
$style $style Ref Imports all dataset properties from the names style. This is simply a shortcut to explicitely writing all style properties.
$path $path reference/pads Creates a hierarchical name of the dataset that will be used in the dataset browser. Each slash indicates another branch in the name.
$quiver_color $color green The color of a quiver arrow
$quiver_scale $quiver_scale 100 The original scale of the quiver plot

1.3. Text annotations

Text is drawn by adding the "T" control character in front of a line. The "T" may have a number 1-9 appended describing the anchoring of the text. This numbers corresponds to their position on the numerical keyboard. The default alignment is 1, i.e. lower left.

The following example illustrates the various anchor options.
text-align.giv
  1:  # Show the text alignment relative to the alignment number 
  2:  $marks fcircle 
  3:  $color red 
  4:  $noline 
  5:  100 100 
  6:  200 100 
  7:  300 100 
  8:  100 200 
  9:  200 200 
 10:  300 200 
 11:  100 300 
 12:  200 300 
 13:  300 300 
 14:   
 15:  $color blue 
 16:  T7 100 100 T7 
 17:  T8 200 100 T8 
 18:  T9 300 100 T9 
 19:  T4 100 200 T4 
 20:  T5 200 200 T5 
 21:  T6 300 200 T6 
 22:  T1 100 300 T1 
 23:  T2 200 300 T2 
 24:  T3 300 300 T3

The following screenshot shows the various alignments relative to the anchor points.

1.4. Giv file example

Here is an extensive giv file example showing off the various features of giv. The result is shown in the screenshow below.
example.giv
  1:  # Comments start with the hash character 
  2:   
  3:  $balloon Circles are great! 
  4:  $path circles 
  5:  $lw 3 
  6:  $noline 
  7:  $marks circle 
  8:  $scale_marks 1 
  9:  $color midnightblue 
 10:  110 110 
 11:  120 110 
 12:  120 120 
 13:  110 120 
 14:  110 110 
 15:   
 16:  $path squares 
 17:  $marks square 
 18:  $mark_size 12 
 19:  $lw 5 
 20:  $path squares 
 21:  $color green 
 22:  120 120 
 23:  150 150 
 24:  120 150 
 25:  120 120 
 26:   
 27:  $PATH Two lines with a move 
 28:  $color red 
 29:  270 120 
 30:  300 150 
 31:  m 270 150 
 32:  270 120 
 33:   
 34:  $path another simple line 
 35:  $balloon this line 
 36:  $balloon has a multi-line 
 37:  $balloon popup! 
 38:  $color orange 
 39:  320 130 
 40:  320 180 
 41:   
 42:  $path a dashed line 10,5 
 43:  $color purple 
 44:  $linedash 10,5 
 45:  $lw 2 
 46:  350 130 
 47:  350 180 
 48:   
 49:  $path a dashed line 5,3 with an arrow 
 50:  $linedash 5,3 
 51:  $LW 2 
 52:  $color blue 
 53:  $arrow 
 54:  380 130 
 55:  380 180 
 56:   
 57:  $polygon 
 58:  $color pink3 
 59:  $outline_color black 
 60:  $path A closed polygon  
 61:  $lw 3 
 62:  200 300 
 63:  250 300 
 64:  200 200 
 65:   
 66:  $marks fcircle 
 67:  $color blue 
 68:  0 0 
 69:   
 70:  $path blue text 
 71:  $color blue 
 72:  $font Sans 15 
 73:  T 0 0 Origin 
 74:   
 75:  $polygon 
 76:  $color none 
 77:  $lw 5 
 78:  $balloon Fonts 
 79:  0 250 
 80:  300 250 
 81:  300 400 
 82:  0 400 
 83:   
 84:  $path font Monospace  
 85:  $color black 
 86:  $font Monospace 20 
 87:  T 0 300 Monospace 
 88:   
 89:  $path font Serif  
 90:  $color black 
 91:  $font Sans Bold Italic 18 
 92:  T 0 330 Sans Bold Italic 18 
 93:   
 94:  $path font Serif  
 95:  $color black 
 96:  $font Serif 20 
 97:  T 0 360 Serif 
 98:   
 99:  $path frame 
100:  $color red 
101:  400 0 
102:  500 0 
103:  500 100 
104:  400 100 
105:  400 0 
106:   
107:  $path arrow both 
108:  $arrow both  
109:  $color green 
110:  $lw 2 
111:  410 10 
112:  490 90 
113:   
114:  $path arrow start 
115:  $arrow start 
116:  $color green 
117:  $lw 2 
118:  445 40 
119:  465 20 
120:   
121:  $path arrow end 
122:  $arrow end 
123:  $color green 
124:  $lw 1 
125:  455 50 
126:  475 30 
127:   
128:  $path font Serif  
129:  $color gray 
130:  $font Serif Bold 50 
131:  T 140 0 GIV 
132:   
133:  $path font Serif  
134:  $color purple3 
135:  $font Serif Bold 50 
136:  T 136 4 GIV


Marks at default zoom Marks zoomed in. The balloon popup has been turn on.
Note: The example above contains just a few points. Giv very easily supports several hundred thousand points. The only limitations are the physical memory and the speed of the CPU.

2. Interaction

Option Description
q Quit
=
Ctrl-B1 		Zoom in by a factor of 2
-
Ctrl-B3 		Zoom out by a factor of 2
Scroll wheel up Zoom in by a factor of 1.1
Scroll wheel down Zoom out by a factor of 1.1
Shift+scroll wheel up Zoom in of quiver vectors by a factor of 1.1
Shift+Scroll wheel down Zoom out of quiver vectors by a factor of 1.1
f Fill data to window
B3 Popup options menu.
c Toggle cross hair.
m Toggle overlay.
o Popup dataset browser.
1 Sets one image pixel equal to one screen pixel.
s Shrink wrap
v Vertical flip
h Horizontal flip
i Show information window
Left/Space Show next image in directory.
Right/BackSpace Show previous image in directory.
Shift-Down Choose next image when several $image references are given
Shift-Up Choose previous $image image

3. Gallery

A heavy dataset from the CIA world map data of Europe comprising more than 400,000 vector elements.

Zoom-in of Shetland and Orkney islands off the coast of Scotland.

The result of a contour finding algorithm shown on top of the image. The overlay may be toggled by the key 'm'.

Zoom in of image shows contour sub pixel accuracy.

A quiver plot. giv showing a Voronoi diagram. The dataset browser is also shown.

Pseudo color of a gray level image. Overlays may be painted with transparency as in this "annotation" of the Lena image.
The Contrast Tool with a 16-bit image
The measurement caliper and the calibration tool

4. Plugins

Giv supports plugins for loading 8-bit, 16-bit, 32-bit and floating point images. Currently there are loaders for the following formats:

5. Future plans

Here is a list of possible future development. The direction taken depends on user feedback!