A Manual for Giv

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


Version 0.9.38
Dov Grobgeld
Homepage: http://giv.sourceforge.net/giv
Development: http://github.com/dov/giv
Chat room: Gitter Giv Chat room
dov.grobgeld@gmail.com
Last modified: 2024-05-12 Sun

1. Description

giv is an image viewer with the following features:

1.1. Images

Images are loaded through gdk_pixbuf and through additional image loaders. 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 a list of data points.

A few of the properties are global and they effect not only the dataset but the entire display, e.g. the $image, and the $vflip.

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

Property Example Description
$color $color pink3. The color of the data set (See color section below). 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.
$line $line Lines should be drawn for the data set (default).
$marks $marks circle The type of the mark. Valid marks are:
  • circle
  • fcircle
  • square
  • fsquare
$svgmarks $svgmarks drop.svg Reference an external svg file as a marker.
$hide $hide Initially hide the dataset. It may be turned on by the marks viewer.
$scale_marks $scale_marks Indicates whether the marks should be scaled together with the image. Default is not to scale.
$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.
$text_style $text_style shadow The style used to draw the text. The only valid style is "shadow".
$shadow_color $shadow_color black/0.3 For the shadow style, the color of shadows.
$shadow_offset $shadow_offset 1 1 For the shadow style, the x and y offsets of the shadow.
$pango_markup $pango_markup Indicates that the text should be interpreted as a pango markup string. See: http://developer.gnome.org/pango/stable/PangoMarkupFormat.html
$scale_font $scale_font 1 Indicates that the text should be scaled with the current zoom level. Default is not to zoom up text.
$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 Add an additional property to a style. (See style section)
$style $style Ref Imports all dataset properties from the namedo 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 hierarchy tree.
$quiver_color $quiver_color green The color of a quiver arrow
$quiver_scale $quiver_scale 100 The original scale of the quiver plot
$vflip $vflip Flip the vertical axis of the marks and images.
$novflip $novflip Turn off the vertical flip.
$hflip $hflip Flip the horizontal axis of the marks and images.
$nohflip $nohflip Turn off the horizontal flip.
$vlock $vlock Lock the vertical axis zoom. Useful e.g. for exploring time plots.
$title $title Set the window title.
$pixelsize $pixelsize 5 µm Set the pixelsize for the measurement tool

1.3. Lines and Bezier Curves

After the header of the dataset, follows its data points. giv follows the SVG model of drawing curves. A line is composed of a letter followed by the coordinates. By default the action is lineto, but the following are also supported:
Letter Meaning Number parameters Comment
M move to 2 Implicit for first point
L line to 2 Optional
Z line to 2 Close path
C curve to 6 A cubic Bezier
R quadratic curve to 4 A cubic Bezier

1.4. Text annotations

Text is drawn by adding the letter "T" 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. To write multiline text add string "\n".

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.

The encoding of giv files is always utf8. Bidi is supported through pango.

The backslash character is used as an escape character, so to get a literal backslash two slashes must be used. "\n" is used to indicate aline break.

1.5. Colors

For all the properties that take colors as arguments the color may be given in several ways: Here are some valid color names:

1.6. Styles

Instead of explicitly listing all properties for a dataset, this may be done inderectly by the creation of a style. A style is created and has properties added to it through the $def_style keyword. Each use of $def_style adds one property to the style. A style is then referenced in the beginning of a dataset with the $style keyword followed by the style name.
style-ex.giv
  1:  $def_style my-frame color blue 
  2:  $def_style s1 color red 
  3:  $def_style s1 lw 10 
  4:  $def_style s2 color green 
  5:  $def_style s2 lw 2 
  6:   
  7:  $style my-frame 
  8:  0 0 
  9:  0 200 
 10:  200 200 
 11:  200 0 
 12:  0 0 
 13:   
 14:  $style s1 
 15:  0 50 
 16:  200 50 
 17:   
 18:  $style s2 
 19:  0 150 
 20:  200 150

1.7. 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.

1.8. Balloons and paths

One of the features of giv is that each dataset may have a tooltip popup attached to it. These popups are knows as "balloons". This allows adding auxilliary information to the display that is revealed only when the cursor hovers above the dataset. In addition, a dataset may be given a hiearchical path. This path is referenced in the marks viewer, and may be used to toggle on and off datasets. If no balloon was explicitely set for a dataset, then the dataset name is used for the balloon. Balloons are toggled by the "b" popup.

2. Interaction

Option Description
1 Sets one image pixel equal to one screen pixel.
a Toggle anti aliasing
b Toggle the balloon popup.
c Reduce contrast. Useful for viewing overlay on binary images.
i Show information window
f Fill data to window
g Toggle the pixel grid. (Only shown at high zoom ratios).
h Horizontal flip
m Toggle overlay.
o Popup dataset browser.
q Quit
s Shrink wrap
v Vertical flip
Shift-V Toggle vertical zoom locking.
Control+c Copy contents of balloon text to clip board
Control+d Copy contents of the last measurement to the clipboard.
Control+x Copy XY coordinate to the to clip board
Esc Abort remote command pick points
=
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.4
Scroll wheel down Zoom out by a factor of 1.4
Shift+Scroll wheel up Zoom in by a factor of 1.1
Shift+Scroll wheel down Zoom out by a factor of 1.1
Control+Scroll wheel up Zoom in by a factor of 2
Control+Scroll wheel down Zoom out by a factor of 2
Alt + Scroll wheel up Zoom in of quiver vectors by a factor of 1.2
Alt + Scroll wheel down Zoom out of quiver vectors by a factor of 1.2
B3 Popup options menu.
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 or next image for multi depth images.
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 A gray level image with transparent overlay
Example use of svgmarks
where the markers are read from an
external svg file.
The Contrast Tool with a 16-bit image
 
Dicom XRay image of a
pregnant bitch
 		 After contrast stretching and coloring
 
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. Remote access protocol

giv can be remote controlled through json-rpc commands. The parameters of the commands are always given in an array. Here is an example in python calling the pick_coordinate command:
pick-coordinate.py
  1:  #!/usr/bin/python 
  2:  import httplib,json 
  3:   
  4:  conn = httplib.HTTPConnection('localhost:8448') 
  5:   
  6:  request = {'method':"pick_coordinate", 
  7:             'params':[]} 
  8:   
  9:  conn.request("POST", url='', body= json.dumps(request)) 
 10:  response = json.loads(conn.getresponse().read()) 
 11:  if 'error' in response: 
 12:    print response['error']['message'] 
 13:  else: 
 14:    print response['result'] 
 15:

giv also contains an embedded JSONRPC client that come in two forms, the simplified and the full forms.

The simplified form splits the arguments on whitespace and takes the first argument as the name of the remote method and the rest as the parameters. 

  giv --remote "load_file /home/dov/pictures/maja.pgm"
The full forms allows specifying the parameters in json syntax. The following command is equivalent to the above code: 
  ./giv --json_method load_file -json_params '["/home/dov/github/giv/examples/lena.pgm"]'

For windows there is a command line tool called giv-remote-client.exe that provides a simple remote client: 

giv-remote-client.exe load_file "c:/Program Files/Giv/examples/lena.pgm"

6. Future plans/Todo

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