How-to

Compiling


There are 4 sources to compile:

  1. pyramidmaker ... creates a pyramid of compressed data
  2. pgen1 ... generates configuration files for pyramidmaker for a single image
  3. machinefilegen ... creates a machine file for MPI
  4. magicarpet ... renders datasets


Go to app/ folder and compile these one by one. Currently, this may require makefile tweaking (CFLAGS and LDFLAGS). Here is a list of libraries: 
- Graphics
	OpenGL (opengl.org)                           
	GLEW (http://glew.sourceforge.net)            
- Windowing 
	FLTK 1.17 (www.fltk.org)                      
	SAGE (http://www.evl.uic.edu/cavern/sage)     
- Fonts
	FreeType2 (freetype.org)                      
- Image
	TIFF (www.libtiff.org)                        
	JPEG (www.ijg.org)                            
	PNG (www.libpng.org)                          
	SQUISH (http://www.sjbrown.co.uk/)            
- Cluster
	MPI (mcs.anl.gov/mpi)                         
- Networking
	QUANTA (www.evl.uic.edu/cavern/quanta)        
- Joystick
	SDL (www.libsdl.org)


IMPORTANT: Before compiling Magic Carpet open up CONF.h in root directory.

There will be several definitions:

#define DO_MPI ... compile with mpi
#define DO_LAMBDATABLE ... use lambdatable tracker
#define DO_SAGE ... render to sage
#define SAGE_VERSION3 ... get ui messages from sage (version 3.0)
#define DO_UI ... draw ui on main display
#define DO_JOYSTICK ... use joystick connected to master
#define DEBUG_SAGE ... debug sage mode
#define WINDOW_BORDERS ... draw windows with borders

Comment or uncomment these as needed.

After compilation, executables should reside in bin/.

Image preparation


If the entire large image is not tiled, use pgen1 to create configuration files for pyramidmaker. Otherwise, do it by hand.

USING pgen1

pgen1 takes command line arguments: file name, width, height, bytes per pixels.

Example: ./pgen sceience.jpg 4096 1024 3

Files science.jpg.layout and science.jpg.conf will be created.



Input format: JPEG, TIFF
Output format: DXT

Need 2 files to create a pyramid for Magic Carpet: image layout file and configuration file.

Create a layout file for the image.
Example layout file (identical to JuxtaView layout file):

-----------------------------------------------------------------------------------------
total pixel dimensions: 
12523 12894
columns by rows: 
1 1
tile dimensions: 
12523 12894
list of image tiles: 
D:/dmitri-data/Europe/Europe.tif
Files should be listed in column by column order from frist to last, for example if your image consists of 3 x 4 tiles, and, say, each file has a name FILE_COLUMN#_ROW#, then the list would be:
FILE_0_0
FILE_0_1
FILE_0_2
FILE_0_3
FILE_1_0
FILE_1_1
FILE_1_2
FILE_1_3
FILE_2_0
FILE_2_1
FILE_2_2
FILE_2_3
 -----------------------------------------------------------------------------------------

Create a configuration file for pyramidmaker.
Example configuration file:

-----------------------------------------------------------------------------------------
name of the dataset as it would appear on disk (folder): 
eur
pixel dimensions and number of bytes per pixels: 
12523 12894 3
number of frames: 
1
list of layout files: 
D:/dmitri-data/Europe/layout.conf

-----------------------------------------------------------------------------------------

Make sure that names or directories contain NO spaces.

Launch pyramidmaker. Specify configuration file and output directory. Run. When done, there should be a folder with specified name in specified directory that contains data.

Dataset configuration


Open bin/appdata/magicarpet/datasets.conf and edit this file to point to the desired data.

Example:

-----------------------------------------------------------------------------------------
number of datasets followed by a list of datasets: 
Datasets 1 
Data
name of dataset (folder name): 
	NameOnDisk europe
path of the dataset / folder: 
	PathOnDisk D:/dmitri-data/Europe
scale: 
	Scale 1.0
translate: 
	Translate 0.0 0.0
this is for nesting datasets (specify parent dataset's NameOnDisk): 
	Parent none
polygonal data (OBJ) list: 
	PolyAttachments 1
x, y, scale, obj file: 
	    0.0 0.0 1.0 model.obj
list of text labels: 
	TextAttachments 1
x, y, label string (use underscore for spaces) : 
	    0.0 0.0 test_label

-----------------------------------------------------------------------------------------

In order to display a dataset using convensional ERSI world file , go to that dataset's folder and open world.dat. This file is generated automatically by pyramidmaker. By default, the image should appear at origin in its original pixel scale.

Example:

-----------------------------------------------------------------------------------------
horizontal scale: 
1.0
rotation about x-axis (not implemented): 
0.0
rotation about y-axis (not implemented): 
0.0
vertical scale 
-1.0
x-coordinate of upper left pixel: 
-6261
y-coordinate of upper left pixel: 
6447
-----------------------------------------------------------------------------------------

Runtime configuration


Open bin/appdata/magicarpet/conf/mconfig.conf or bin/appdata/magicarpet/conf/mconfig.sage.conf when rendering with SAGE and edit the following:



-----------------------------------------------------------------------------------------
loading data from ... put localdisk or nfs or pvfs: 
DataFetchStyle nfs
sync cluster display (requires compilation with MPI) ... on or off 
ClusterSync on
open up a window on the master ... on or off 
MasterWindow on
number of image blocks to keep in main memory: 
MainCacheMax 400
number of image blocks to keep in texture memory: 
TexCacheMax 200
number and diameter of magnifier(s): 
Magnifiers 1 1024
master's IP address: 
MasterIP 10.0.8.10

-----------------------------------------------------------------------------------------

Tile configuration


Example (format is almost identical Tile Configuration Library
NOTE: mullions field takes only 2 numbers ... horizontal and vertical): 
TileDisplay
	Dimensions 3 2
	Mullions 2.0 2.0
	Resolution 2560 1600
	PPI 72
	Machines 3

DisplayNode
	Name teiburu1-10
	IP 10.0.8.11
	Monitors 2 (2,1) (2,0)
	
DisplayNode
	Name teiburu2-10
	IP 10.0.8.12
	Monitors 2 (1,1) (1,0)
							
DisplayNode
	Name teiburu3-10
	IP 10.0.8.13
	Monitors 2 (0,1) (0,0)

User interface


When rendering on the local machine, use the mouse to navigate.

LEFT BUTTON pans view.
MOUSE WHEEL zooms.
RIGHT BUTTON pans pointer.

On a cluster, user inteface is the master window.
Mouse interaction is identical on the suface of this window.

JOYSTICK CONTROL

hat: control pointer and magnifier position
axis 1: pan
axis 2: zoom
button 1: toggle magnifier glass on/off and cycle through magnification values
button 2: toggle text on/off
button 3: center on current dataset under pointer
button 4: cycle through text sizes
button 7/8: flip through frames of an image
button 5/6: fly to previous and next image based on position of pointer
button 9: reset view
button 10: center pointer at closest dataset

LAMBDATABLE CONTROL

Open file appdata/magicarpet/pucks.conf and change IDs of pucks assigned to specific functionalities. Ignore the field "Inputs".

Example puck file:

-----------------------------------------------------------------------------------------
rotation puck ID: 
Rotate 2
panning puck ID: 
Pan 1
zooming puck ID: 
Zoom 3
list of other input IDs (may be used by Magic Carpet in future): 
Inputs 3  1 2 3
list of magnifier puck IDs: 
Magnifiers 1   4

-----------------------------------------------------------------------------------------

Scripts


Example w/o MPI:

machinefilegen tile.conf
magicarpet tile.conf

Example w/ MPI:

machinefilegen tile.conf
mpirun -np 4 -machinefile machinefile magicarpet tile.conf

Force quit:

sh killcarpet

SAGE


When in sage mode, the tile configuration file represents the size of the image buffer that Magic Carpet sends to SAGE. The number of monitors should be 1 per node. The performance with SAGE will depend on the size of this buffer.