README (18/03/2006)

for more information about CMBview go to: 
http://www-astro.physics.ox.ac.uk/~jamiep/cmbview.html


CMBview 0.2.1
=============

Here are some notes on basic usage of the application.

1) Loading files

Load a HEALPix FITS file using "Open FITS..." in the File menu. If the FITS file contains only one HEALPix map, it is assumed this is a T map. If there are 2 maps, as in some WMAP files, the first map is assigned to T and the second to N (number of counts). If it contains three maps, they are assumed to contain T,Q,U in that order as in the output of synfast). In v0.2.1, if the file contains 4 maps, as in many of the maps in the WMAP 3-year release, the first 3 maps are assigned to T,Q,U, and the 4th map (N) is discarded. 

On extracting the pixel data from the FITS file, "cubemap" textures are generated for interactive viewing (by projecting onto the faces of a cube circumscribing the sphere). The number of texels in each texture/face can be changed in Preferences/Texture.  

Buttons for switching between all the available maps will become active. The T map appears first by default. Click and drag the mouse on the viewport to rotate the sphere (left/right motion rotates about the polar axis, up/down motion rotates about the horizontal axis). Right click on the sphere to show the map values under the clicked point (in the panel at the bottom right of the window). For help with viewing Stokes vectors see the section Preferences panel/Stokes below.  


2) Color range selection

The box on the right hand side of the window shows a 256 bin histogram of the values assigned to the texels in the currently selected map. The minimum and maximum values are indicated in text fields above and below the histogram. The lin/log radio buttons select a linear or logarithmic horizontal scale (with the highest value clamped to the right edge of the histogram box). The color/grey button toggles between the current colormap  (selected in Preferences/Colormap) and greyscale. 

Clicking anywhere above the green-yellow dotted line in the vertical midpoint of the histogram will move the indicated upper bound of the color range. Clicking below the green-yellow line moves the lower bound. The corresponding map values are displayed in the text fields as you drag the color range bounds. To re-generate the
colors/greyscale in the currently shown map, click the large "remap colors" button below the histogram.  


3) Switching modes

After loading a map, the radio buttons with "interactive mode", "render mode", and "presentation mode" become active, with interactive mode selected first by default. Clicking the "render mode" button
generates and displays a rendered image of the sphere in the orientation currently selected in interactive mode. This rendered image is made by projecting each pixel center in the viewport into the corresponding point on the sphere, and assigning the pixel a color according to which HEALpix pixel contains that point. These pixels are composited on the the underlying lit sphere drawn by OpenGL to get the lighting effects.  

In render mode the sphere cannot be rotated or zoomed. To move the sphere you have to go back to interactive mode. However the color range can still be changed, as well as the lighting, grid, Stokes vectors, etc. Note that the histogram in render mode shows the distribution of values assigned to the pixels in the current
viewport. So details which are swamped by the peak values in the full sky map may be revealed by render mode on zooming in.   
 
The "presentation mode" button generates the same image as the render mode, but displays it reduced in size with a border, and with a color scale shown beneath. You have the same control over the image as in render mode, in addition you can change the background color in Preferences/General.  

Admittedly this is probably not really good enough for publications since it's a bitmap and the text will look crummy on resizing. Partly I included this mode so that you can take a screen-shot of the whole  viewport without the metal texture interfering with the edges as in render mode (to take a screen-shot in OS X, incidentally, do command-shift-4). In the next version I'd like to implement rendering to a pdf.  
 

4) Export texture

Selecting "Save Raw Texture" in the File menu will generate and export a rendered image, generated by the same method as the render mode computation. However the OpenGL lighting effects will not be applied to the image, i.e. lighting is disabled. The dimensions of the image (in pixels) can be set in Preferences/General, but be warned a large image may take a long time to render. You can make some huge (e.g. 4096x4096) images of maps this way, albeit just the raw texture with no lighting.  

(I implemented a facility to export the current framebuffer but I didn't include it in this release because of a bug which leads to a corrupted image file, which I have yet to resolve. Since you can take a screen-shot easily in OS X I don't think it's a major omission.  When I clear up the bug, it will take further work to render an
arbitrarily large lit rendered image (larger than the maximum OpenGL viewport dimensions say) since that requires moving the viewport around to render different portions of the image and stitching the images together in memory.)  
 
5) Preferences panel</span> 

It'd be too boring to go through all the buttons and widgets in the preferences,
and mostly they're self explanatory, but I'll point out a few things. 

    i) General:

    The "field of view" slider controls the angular width of the observer
    view frustum. A high field of view simulates the effect of moving
    close to the sphere, so less than a hemisphere is visible. The
    observer distance is scaled as the field of view changes to keep the
    sphere size almost constant. Orthographic projection has the effect of
    moving the observer to infinity, i.e. a full hemisphere is visible.

    ii) Textures:

    Select the amount of detail you want in the interactive mode by
    changing the number of texels. This takes effect the next time a map
    is loaded. Note that generation of the textures at N=1024 takes about
    40 sec on a 1Ghz G4, and correspondingly longer for higher N. Also
    cards with 64MB of VRAM will not be able to render the textures at
    interactive frame-rates at N>1024. I recommend you do not use N>1024
    unless you have a top-end machine. Use the render mode to see detail. 

    iii) Lighting:

    The "color" colorwells control the colors of the ambient, diffuse and
    specular emitted light and the "material" colorwells control how the
    sphere reflects that light. If you're familiar with the OpenGL
    lighting model you'll understand what's going on in detail, but if not
    you can just try fiddling with the parameters and you'll see how it
    works. The size of the specular highlight is controlled with
    "shininess" parameter. 

    iii) Colormap:

    I modeled these colormaps on some of the ones available in
    MATLAB. Note that you can  reverse each colormap using the check box. 

    iv) Stokes:

    After loading a file containing T,Q, and U maps, the "gen vec" and
    "vec" buttons become active. "gen vec" draws the Stokes vectors
    arranged in a square grid in the current viewport (having projected
    each grid point down onto the sphere to find Q,U). The number of
    vectors per side of the grid is selectable in the preferences pane (it
    takes effect on the next click of "gen vec").  After generating a set
    of vectors you can zoom in and out and rotate freely to examine them
    of course, but the distribution of vectors will look odd if you change
    the viewpoint too much. The "vec" button just toggles the display
    of the current set of vectors. 


6) Known bugs/issues

Some people reported that in the last release (v0.1) on resizing the window to a fairly large size, the main view sometimes fills with garbage (or possibly just freezes), but clears up on resizing back. I can see the effect on my system (15in Albook) only when resizing to much larger than the screen size, so I thought this was probably to do with exceeding the framebuffer size. But I recently heard it may also occur even without resizing off the screen, so I don't know what the problem is yet.