[WIP] FEATURE: Convenience functions for volume rendering transfer functions

[GenevieveBuckley]

I propose adding convenience functions for volume rendering transfer functions.

• [x] single color linear ramp transfer functions
• [x] matplotlib colormaps as transfer functions
• [x] function for easy loading of a number of predefined transfer functions
• [ ] function tests - still in progress
• [ ] notebook for example docs?

Example use

import ipyvolume as ipv
aquarius = ipv.datasets.aquariusA2.fetch()

Transfer function from single RGB value with linear opacity ramp

magenta = ipv.transferfunction.linear_transfer_function('magenta')
ipv.quickvolshow(aquarius.data, tf=magenta)

Transfer functions based on matplotlib colormaps

jet = ipv.transferfunction.matplotlib_transfer_function('jet')
ipv.quickvolshow(aquarius.data, tf=jet)

Load all predefined transfer functions to a dictionary

# You can also load all predefinied transfer functions into a dictionary,
# for quick and easy testing of multiple display options
my_transfer_functions = ipv.transferfunction.load_transfer_functions()
print(list(my_transfer_functions))  # all predefined transfer function names

['grey', 'grey_r', 'red', 'red_r', 'green', 'green_r', 'blue', 'blue_r', 'yellow', 'yellow_r', 'magenta', 'magenta_r', 'cyan', 'cyan_r', 'Accent', 'Blues', 'BrBG', 'BuGn', 'BuPu', 'CMRmap', 'Dark2', 'GnBu', 'Greens', 'Greys', 'OrRd', 'Oranges', 'PRGn', 'Paired', 'Pastel1', 'Pastel2', 'PiYG', 'PuBu', 'PuBuGn', 'PuOr', 'PuRd', 'Purples', 'RdBu', 'RdGy', 'RdPu', 'RdYlBu', 'RdYlGn', 'Reds', 'Set1', 'Set2', 'Set3', 'Spectral', 'Wistia', 'YlGn', 'YlGnBu', 'YlOrBr', 'YlOrRd', 'afmhot', 'autumn', 'binary', 'bone', 'brg', 'bwr', 'cividis', 'cool', 'coolwarm', 'copper', 'cubehelix', 'flag', 'gist_earth', 'gist_gray', 'gist_heat', 'gist_ncar', 'gist_rainbow', 'gist_stern', 'gist_yarg', 'gnuplot', 'gnuplot2', 'gray', 'hot', 'hsv', 'inferno', 'jet', 'magma', 'nipy_spectral', 'ocean', 'pink', 'plasma', 'prism', 'rainbow', 'seismic', 'spring', 'summer', 'tab10', 'tab20', 'tab20b', 'tab20c', 'terrain', 'viridis', 'winter', 'Accent_r', 'Blues_r', 'BrBG_r', 'BuGn_r', 'BuPu_r', 'CMRmap_r', 'Dark2_r', 'GnBu_r', 'Greens_r', 'Greys_r', 'OrRd_r', 'Oranges_r', 'PRGn_r', 'Paired_r', 'Pastel1_r', 'Pastel2_r', 'PiYG_r', 'PuBuGn_r', 'PuBu_r', 'PuOr_r', 'PuRd_r', 'Purples_r', 'RdBu_r', 'RdGy_r', 'RdPu_r', 'RdYlBu_r', 'RdYlGn_r', 'Reds_r', 'Set1_r', 'Set2_r', 'Set3_r', 'Spectral_r', 'Wistia_r', 'YlGnBu_r', 'YlGn_r', 'YlOrBr_r', 'YlOrRd_r', 'afmhot_r', 'autumn_r', 'binary_r', 'bone_r', 'brg_r', 'bwr_r', 'cividis_r', 'cool_r', 'coolwarm_r', 'copper_r', 'cubehelix_r', 'flag_r', 'gist_earth_r', 'gist_gray_r', 'gist_heat_r', 'gist_ncar_r', 'gist_rainbow_r', 'gist_stern_r', 'gist_yarg_r', 'gnuplot2_r', 'gnuplot_r', 'gray_r', 'hot_r', 'hsv_r', 'inferno_r', 'jet_r', 'magma_r', 'nipy_spectral_r', 'ocean_r', 'pink_r', 'plasma_r', 'prism_r', 'rainbow_r', 'seismic_r', 'spring_r', 'summer_r', 'tab10_r', 'tab20_r', 'tab20b_r', 'tab20c_r', 'terrain_r', 'viridis_r', 'winter_r']

And use them like so:

ipv.quickvolshow(aquarius.data, tf=my_transfer_functions['grey'])

Discussion

Now that it's possible to have multiple volumes displayed in the same figure, we need something like this to increase the useability (and it looks like this has been suggested before):

I think this can now be done using multivolume rendering. Render each channel as a separate volume, and give them 'ramp' transfer function, having a constant color (say red for the first, green for the second), and opacity increasing from 0 to 1. https://github.com/maartenbreddels/ipyvolume/issues/81#issuecomment-420551030

I've also seen this issue play out too, since the default choice is very non-standard for my field:

When I've explained the current system with the 3 RGB gaussians to my professors, it's always taken a minute for them to understand that red is low, green is medium, and blue is high. I think having a single linear color gradient from low to high could eliminate that confusion. https://github.com/maartenbreddels/ipyvolume/pull/76#issuecomment-336638057

Let me know what your thoughts are, happy to discuss etc.

[GenevieveBuckley]

Travis CI build is currently failing due to the issues with unpkg (https://github.com/unpkg/unpkg.com/issues/134)

[maartenbreddels]

I should also mention @vidartf 's work on ipyscales: https://ipyscales.readthedocs.io/en/latest/examples/colorbar.html would be really nice to integrate with that.

[GenevieveBuckley]

Thanks for the link, I didn't know that about @vidartf. So far I've thought exactly zero about how to display colorbars next to figures, but that will be a pretty necessary next step.

[GenevieveBuckley]

@maartenbreddels can you explain the difference between the four different transfer function classes in python?

Those python classes are:

1. TransferFunction
2. TransferFunctionJsBumps
3. TransferFunctionWidgetJs3
4. TransferFunctionWidget3

Found in ipyvolume/ipyvolume/transferfunctions.py

And on the javascript side, there's a. TransferFunctionModel b. TransferFunctionJsBumpsModel c. TransferFunctionWidgetJs3Model d. TransferFunctionView

Found in ipyvolume/js/tf.js