HEALPix Viewer program

This is a simple HEALPix viewer, which uses the mplot::HealpixVisual class from mathplot.

It plots your scalar-valued HEALPix dataset on the sphere using a colour map and optionally relief to indicate value. There is a wide choice of colour maps (including those from CET, matplotlib and Fabio Crameri) which, along with the relief scaling, can be configured via a simple JSON file.

Dependencies

If you are using Debian or Ubuntu, the following apt command should install the mathplot dependencies as well as the official Healpix C library.

sudo apt install build-essential cmake git wget  \
                 nlohmann-json3-dev librapidxml-dev \
                 freeglut3-dev libglu1-mesa-dev libxmu-dev libxi-dev \
                 libglfw3-dev libfreetype-dev libchealpix-dev

On Arch Linux, this should be the pacman command:

sudo pacman -S vtk lapack blas freeglut glfw-wayland nlohmann-json chealpix

On Fedora Linux, the following dnf command should install the dependencies:

sudo dnf install gcc cmake libglvnd-devel mesa-libGL-devel glfw-devel \
                 json-devel rapidxml-devel \
                 freetype-devel cfitsio-dev chealpix-dev

If you're building on a Mac, you can refer to the Mac README for help. You only need to obtain and build glfw3; OpenGL and Freetype should already be installed by default.

On Windows, you will hopefully in future use vcpkg to install mathplot and its dependencies and you should be able to compile with Visual Studio (this worked with morphologica but at time of writing has not been set up for mathplot). If the program runs slowly, try rebuilding in Release mode rather than Debug mode.

Building

To build and run the viewer:

git clone --recurse-submodules git@github.com:sebsjames/healpixviewer

cd healpixviewer
mkdir build
cd build
cmake ..
make
./viewer path/to/fitfile.fit

Finding some example data

Topographic data of the Earth makes lovely example data:

wget https://www.sfu.ca/physics/cosmology/healpix/data/earth-2048.fits
./build/viewer earth-2048.fits

Note that there is a JSON config file that matches this filename.

You can open the Bayestar data that @lpsinger uses in his viewer (there's a .json file for this one too) Note: this file is currently unavailable:

wget --no-check-certificate http://ligo.org/science/first2years/2015/compare/18951/bayestar.fits.gz
./build/viewer bayestar.fits.gz

I also managed to open cosmic microwave background data from the Planck Legacy Archive. Again, this uses a JSON file to set up the input data scaling.

wget http://pla.esac.esa.int/pla-sl/data-action?MAP.MAP_OID=13486 -O cmb.fits
./build/viewer cmb.fits

These skymaps from the Planck Legacy Archive also appear to work

wget http://pla.esac.esa.int/pla-sl/data-action?MAP.MAP_OID=13749 -O skymap.fits
./build/viewer skymap.fits

wget http://pla.esac.esa.int/pla-sl/data-action?MAP.MAP_OID=13612 -O skymap2.fits
./build/viewer skymap2.fits

The Config file

This small application has no user interface. As in all my scientific visualization programs, I use a simple configuration file to set options, using the JSON format. When you run the program for file.fits it will attempt to open file.fits.json and read parameters from that file.

The earth-2048.fits.json example looks like this (without the comments in the file):

{
    "colourmap_input_range" : [ -400, 8000 ],
    "colourmap_type" : "Batlow",
    "use_relief" : true,
    "reliefmap_input_range" : [ -400, 8000 ],
    "reliefmap_output_range" : [-0.00065, 0.0013 ],
    "order_reduce" : 1
}

Briefly, you use colour/reliefmap_input_range and reliefmap_output_range to control the colour and relief data scaling. Here, a range of values from -400 to 8000 are scaled to [0, 1] for the colourmap (this is never changed) and to [-0.00065, 0.0013] for relief (assuming use_relief is true). The units for relief are in arbitrary length units in the 3D scene. These should relate to the base radius of the HEALPix sphere, which is 1.

order_reduce allows you to reduce the order of the visualization with respect to your data. Here, I reduce from an 11th order/nside=2048 HEALPix dataset to a 10th order/nside=1024 visualization. This averages the values in groups of 4 pixels down to 1. If your GPU and RAM can do it, you can change this to 0, or you can order_reduce by more.

colourmap_type allows you to choose from about 80 colour maps in mathplot, which includes maps from Crameri, CET, matplotlib and W Lenthe. To find out the names you can use, see ColourMap documentation and enum class ColourMapType in the code.

You can override any of the fields on the command line. Try:

./build/viewer earth-2048.fits -co:colourmap_type=inferno

Take a look at the example files cmb.fits.json, bayestar.fits.gz.json and earth-2048.fits.json. It should be easy to see how to adapt these to your chosen data.