so3
Author: Jason McEwen / Design by Andreas Viklund - http://andreasviklund.com/
Description: so3: Wigner transforms
Keywords: so3, SO3, rotation group, transforms, fourier, fast, algorithms, mcewen, wiaux

Introduction | Installation | Source | Matlab | Download | Referencing | License | Authors

| # so3 Wigner transforms

## Introduction

The SO3 code provides functionality to perform fast and exact Wigner transforms based on the sampling theorem on the rotation group derived in McEwen et al (2015).

This documentation outlines the various harmonic transforms supported in SO3, before describing installation details and documenting the C, and Matlab source code. Reference, version, and license information then follows.

## Installation

The SO3 package contains a C implementations and a Matlab interface to the C implementation.

#### Dependencies

SO3 requires the FFTW and the SSHT package. Obviously suitable C compilers will be required to build the implementation. Both C and Matlab mex compilers will be required to build the Matlab interface to the C implementation.

#### Compiling

A makefile is provided to build the code. Before compiling you will need to edit the makefile to specify your compiler and to link with the appropriate libraries.

Once you have set the makefile up for your system, SO3 may be compiled by running:

     >> make all

This will build the library, unit tests, test program and Matlab interface. If your system is configured to build all of these components then you are done. If you prefer to build only a subset of these components then read on.

You may alternatively build the individual components of SO3. To build the library only run:

     >> make lib

To build the unit tests run:

     >> make unittest

To build the test program run:

     >> make test

To build the Matlab interface run (which will also build the library if it has not already been built):

     >> make matlab

#### Testing

Run the test program to verify your installation. A default test may be performed by running:

     >> make runtest

If SO3 is installed correctly the test program should run and print test results to the terminal. The test program performs an inverse Wigner transform of a random signal, followed by a forward transform. The error between the original and recovered Wigner coefficients is computed and displayed. All errors should be of the order of numerical precision.

Alternatively, you may run the test program directly by running:

     >> ./bin/c/so3_test <L> <N> <L0>

where `<L>` and `<N>` are the harmonic and orientational band-limit, respectively, and `<L0>` is the lower harmonic band-limit of your test.

To check the version and build numbers of your version run:

     >> ./bin/c/so3_about

#### Documentation

The SO3 code is self documenting. Although the package ships with source documentation, you may generate html source documentation by running:

     >> make doc

Documentation is generated using doxygen, thus you must have doxygen installed on your system to generate the source documentation.

#### Cleaning up

To clean up your version of the SO3 code and remove all builds run:

     >> make clean

To remove all source documentation run:

     >> make cleandoc

## Source code documentation

SO3 ships with source documentation that is generated by doxygen. Documentation is available here for the C implementation. The Matlab routines that interface with the C implementation are self documenting (documentation can be access through the help command in Matlab), as discussed below.

## Matlab interface

Once the Matlab interface is built, you must have `so3/src/matlab` in your path in order to run the Matlab functions. A number of Matlab functions and demos illustrating their use are provided.

#### Functions

Usage of the SO3 Matlab interface will most frequently require only the functions to perform forward and inverse Wigner transforms (`so3_forward` and `so3_inverse` respectively). However, a number of additional functions are also provided. A full list of Matlab functions, with brief descriptions are given here:

      so3_elmn2ind
      Convert harmonic indices to vector index

      so3_forward
      Compute forward Wigner transform

      so3_forward_direct
      Compute forward Wigner transform using direct method

      so3_ind2elmn
      Convert vector index to harmonic indices

      so3_inverse
      Compute inverse Wigner transform

      so3_inverse_direct
      Compute inverse Wigner transform using direct method

      so3_sampling
      Compute sample positions

To access the documentation for each function in Matlab, simply run:

     >> help <function>

where `<function>` is the function name.

#### Demos

A number of demos are provided to illustrate the use of the Matlab interface:

      so3_demo_error_timing
      Create timing and error plots of round-trip transform.

      so3_demo_plot_wigner
      Use SO3 to plot Wigner functions on SO(3).

      so3_demo_basic
      Simple demo to compute inverse and forward transform of complex
      scalar function, using simplest interface with default options.

      so3_demo_basic_direct
      Simple demo to compute inverse and forward transform of complex
      scalar function, using direct method with simplest interface
      with default options.

      so3_demo_real_signal
      Simple demo to compute inverse and forward transform of real
      scalar function, using simplest interface with default options.

      so3_demo_real_signal_direct
      Simple demo to compute inverse and forward transform of real
      scalar function, using direct method with simplest interface
      with default options.

      so3_demo_compact_storage
      Demo to compute inverse and forward transform of complex
      scalar function, using compact storage.

      so3_demo_storage_order
      Demo to compute inverse and forward transform of complex
      function, storing the flmn for n = -N+1 first.

      so3_demo_lower_band_limit
      Demo to compute inverse and forward transform of complex
      function, using a non-zero lower harmonic band-limit - i.e. only
      harmonic coefficients with L greater than or equal to some L0
      are non-zero.

      so3_demo_even_n
      Demo to compute inverse and forward transform of complex
      function, using only harmonic coefficients with even n.

      so3_demo_symmetric_sampling
      Demo to compute inverse and forward transform of complex
      function, using a symmetrically sampled signal.

      so3_demo_covariance
      This demo runs a series of forward transforms from random coefficients
      and compares the transformed signal's covariance with the theoretical
      prediction.

To access the documentation for each demo in Matlab, simply run:

     >> help <demo>

where `<demo>` is the demo name.

## Download

We make the source code of the SO3 package available under the license described below. It can be downloaded from the following site:

## Referencing

If you use SO3 for work that results in publication, please reference this site (http://www.jasonmcewen.org/) and our related academic paper:

> A novel sampling theorem on the rotation group. J. D. McEwen, M. Büttner, B. Leistedt, H. V. Peiris, Y. Wiaux

## License

> SO3 package to perform Wigner transforms
> Copyright (C) 2014-2015 Martin Büttner, Jason McEwen, and Boris Leistedt

> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

> This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details (LICENSE.txt).

> You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

## About the authors

SO3 was developed by Martin Büttner, Jason McEwen, and Boris Leistedt at University College London (UCL).