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 (                           
	GLEW (            
- Windowing 
	FLTK 1.17 (                      
	SAGE (     
- Fonts
	FreeType2 (                      
- Image
	TIFF (                        
	JPEG (                            
	PNG (                          
	SQUISH (            
- Cluster
	MPI (                         
- Networking
	QUANTA (        
- Joystick
	SDL (


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:
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:

Create a configuration file for pyramidmaker.
Example configuration file:

name of the dataset as it would appear on disk (folder):
pixel dimensions and number of bytes per pixels:
12523 12894 3 
number of frames:
list of layout files:


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.


number of datasets followed by a list of datasets:
Datasets 1 

name of dataset (folder name):
	NameOnDisk europe 
path of the dataset / folder:
	PathOnDisk D:/dmitri-data/Europe
	Scale 1.0
	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.


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

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:


Tile configuration

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

	Name teiburu1-10
	Monitors 2 (2,1) (2,0)
	Name teiburu2-10
	Monitors 2 (1,1) (1,0)
	Name teiburu3-10
	Monitors 2 (0,1) (0,0)

User interface

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

LEFT BUTTON pans view.
RIGHT BUTTON pans pointer.

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


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


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



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


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.