Index

ascl:1704.003 astropy

Shwirl is a custom standalone Python program to visualise spectral data cubes with ray-tracing volume rendering. The program has been developed to investigate transfer functions and graphics shaders as enablers for scientific visualisation of astronomical data. Details about the transfer functions and shaders developed and implemented in shwirl can be found in a full length article by Vohl, Fluke, Barnes & Hassan (2017).

Disclaimer: While the software is available for download and ready to visualise data, this is not intended as a full software release just yet.

Shwirl is licensed under the terms of the (new) BSD license.

About

Shwirl is a custom standalone Python program to visualise spectral data cubes with ray-tracing volume rendering. The program has been developed to investigate transfer functions and graphics shaders as enablers for scientific visualisation of astronomical data. Details about transfer functions and shaders developed and implemented in shwirl can be found in a full length article by Vohl, Fluke, Barnes & Hassan (2017).

A transfer function is an arbitrary function that combines volumetric elements (or voxels) to set the colour, intensity, or transparency level of each pixel in the final image. A graphics shader is an algorithmic kernel used to compute several properties of the final image such as colour, depth, and/or transparency. Shaders are particularly suited to computing transfer functions, and are an integral part of the graphics pipeline on Graphics Processing Units.

The code is available at https://github.com/macrocosme/shwirl. The program is built on top of Astropy to handle FITS files and World Coordinate System, Qt (and PyQt) for the user interface, and VisPy, an object-oriented Python visualisation library binding onto OpenGL. We implemented the algorithms in the fragment shader using the GLSL language.

The software has been used on Linux, Mac, and Windows machines, including remote desktop on cloud computing infrastructure.

GPUs

Up to now, we have tested the code on NVIDIA GeForce GTX TITAN X, NVIDIA GeForce GT 750M, and NVIDIA GRID K1. Rendering speed will vary depending on your hardware.

Issues, requests and general inquiries

Please send issues, feature requests and/or general inquiries to Dany Vohl via http://macrocosme.github.io/#contact. You can also simply open a new issue on github directly.

Want to contribute?

As mentioned above, shwirl is not intended to be a finished product yet. If you would like to contribute, GitHub pull requests are welcomed.

Installation

Prerequisites

Shwirl utilises Astropy to handle FITS files and World Coordinate System, Qt (and PyQt) for the user interface, and VisPy, an object-oriented Python visualisation library binding onto OpenGL.

These are pre-requisites to be able to use the software.

In particular, current version relies on Python 3 and PyQt5. A bundled version of VisPy is included in the extern repository as custom modifications have been made that are not readily available via the official version.

Example installation procedure

Depending on your operating system and your current configuration, installation steps may vary. In general, you can install it using the following:

First, install Qt5. It can be downloaded via the Qt website. You also need PyQt5, which can be installed via a package manager like pip, brew, etc. E.g.

pip3 install PyQt5

Install with pip

You can install shwirl with pip:

pip3 install shwirl

Once installed, in your terminal, you can launch shwirl by typing:

shwirl

Python 2.7 / PyQt4 users

PyQt4 (and Python 2.7) are also supported.

Installing PyQt5 from scratch (example)

N.B. The following will vary depending on your OS and your different setings.

Download sip here.

cd sip-4.19.1/
python3 configure.py
sudo make
sudo make install

Download PyQt5 from the same location.

cd PyQt5_gpl-5.8.1/
sudo python3 configure.py --qmake /home/ubuntu/Qt5.7.0/5.7/gcc_64/bin/qmake --sip-incdir /usr/include/python3.4m py_inc_dir=/usr/include/python3.4m
sudo make
sudo make install

Usage and snapshots

Graphical User Interface (GUI)

Upon start of the software, you will need to open a new spectral cube (currently supports FITS 3D image files only) using the GUI by clicking the Load Spectral Cube button at the top right corner.

_images/1-load.png

Visualisation and colour bar

Once you have successfully loaded a spectral cube, the 3D volume can be rotated, panned and zoomed using a mouse or a trackpad. To rotate the cube, simply click and move. Panning can be achieved by click-n-move while pressing the shift key. Zooming in and out is achieved using the wheel, or using trackpad interactions like using two fingers (depending on device).

The colour bar information is based on the FITS header and will vary depending on the colouring method. If you find any oddities, please let me know.

Widgets

The widgets can be used to interact and modify the visualisation outcome. Usage is straight forward: click, slide, select. See what happens!

Cameras and transform

You can set the field of view of the camera:

_images/2-fov0.png _images/3-fov60.png

You can scale axes (e.g. if the spectral axis does not have as many elements as the spatial axes):

_images/4-stretch.png

Other options include:

  • Choice of different cameras (VisPy’s cameras)
  • Turntable (Default)
  • Argball
  • Fly (using keyboard’s arrows)
  • Autorotate

Colour

Shwirl includes different transfer functions and colouring methods.

  • Transfer functions

    • Maximum Intensity Projection (MIP)
    • Local Maximum Intensity Projection (LMIP)
    • Accumulated Voxel Intensity Projection (AVIP)
    • Iso surface

  • Colouring methods

  • Moment 0 (maps voxel intensity to colour)
  • Moment 1 (maps velocity to colour and voxel intensity to transparency)
  • RGB cube (maps voxel xyz position to rgb, and voxel intensity to transparency)

Example of AVIP + Moment 0:

_images/10-wsp-mom0.png

Example of AVIP + Moment 1:

_images/11-wsp-mom1.png

Example of AVIP + RGB cube:

_images/12-wsp-rgb.png _images/rgb_cube.png

MIP is used in the other examples.

Filter

  • Intensity clipping (Filter out)
  • Intensity domain scaling (Rescale)

No Filter:

_images/5-moment1.png

Intensity clipping:

_images/6-filter.png

Smooth

  • Box smoothing
  • Gaussian smoothing

Intensity clipping + Gaussian smoothing

_images/7-smooth.png

Export

The visualisation can be exported to an image:

_images/8-export.png

Metadata

The information of the Primary Header is available in the metadata tab:

_images/9-metadata.png

Computing an emission line ratio in 3D space

The functionalities to compute an emission line ratio can currently be found in the dev branch on github. See Vohl, Fluke, Barnes & Hassan (2017) for more details. More to come soon.

Axis labels

Axis labels are currently under development. Coming soon.

Example data

Spectral cubes used in Vohl, Fluke, Barnes & Hassan (Submitted) are the following:

Neutral Hydrogen (HI) cube of NGC 2903

The HI spectral cube of NGC 2903 (as shown in usage examples) is taken from The HI Nearby Galaxy Survey (THINGS). This cube, along with all other cubes from THINGS can be downloaded at http://www.mpia.de/THINGS/Data.html.

Cube of the carbon monoxide (CO) in the Antennae galaxies

The CO spectral cube of the Southern mosaic pattern taken from the ALMA Science Verification data targeting the CO 3-2 line in the Antennae galaxy can be downloaded at https://almascience.nao.ac.jp/alma-data/science-verification/antennae-galaxies