Main Page | Modules | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

Texture

This module provides the basic functions for the Texture Transforms. More...


Modules

 Texture: Private Functions
 This module containes the private functions used for the implementation of the texture transforms.
 Texture: Utility Functions
 This module provides functions that perform some basic operations on the texture_plan data structur.

Data Structures

struct  texture_plan_
 Definition of the texture_plan. More...
struct  texture_plan_
 Definition of the texture_plan. More...

Defines

#define TEXTURE_MAX_ANGLE   (2*3.1415926535897932384)
 Constant for the period length of sine (default: $2 \pi$ ).

Typedefs

typedef texture_plan_ texture_plan
 Stores all data for a direct and adjoint transformation.

Functions

void texture_precompute (int N)
 Performes precomputations with default values for all parameters.
void texture_precompute_advanced (int N, unsigned int texture_precompute_flags, unsigned int nfsft_precompute_flags, double nfsft_threshold)
 Performes precomputations.
void texture_init (texture_plan *ths, int N, int N1, int N2, complex *omega, complex *x, const double *h_phi, const double *h_theta, const double *r)
 Initialisation of a plan with default values for all parameters.
void texture_init_advanced (texture_plan *ths, int N, int N1, int N2, complex *omega, complex *x, const double *h_phi, const double *h_theta, const double *r, unsigned int texture_init_flags, unsigned int nfsft_init_flags, int nfft_cutoff)
 Initialisation of a plan.
void texture_trafo (texture_plan *ths)
 Carries out the direct transform.
void texture_adjoint (texture_plan *ths)
 Carries out the adjoint transform.
void texture_finalize (texture_plan *ths)
 Frees all memory allocated by texture_init or texture_init_advanced.
void texture_forget ()
 Frees all memory allocated by texture_precompute or texture_precompute_advanced.

Detailed Description

This module provides the basic functions for the Texture Transforms.

Author:
Matthias Schmalz

Texture Transforms

In the following we describe the Direct Texture Transform and the Adjoint Texture Transform. For the definition of the spherical harmonics $ Y_l^n $ please see Spherical Harmonics in NFSFT.

Direct Texture Transform

The Direct Texture Transform is defined as follows:

\[ \begin{array}{rcll} \text{\textbf{Input}} & : & \text{frequency coefficients (frequencies): } & \omega_{l, m, n} \in \mathbb{C} \quad \text{for } l \in [0 \ldots N],\ m \in [-l \ldots l],\ n \in [-l \ldots l],\\[1ex]&& \text{pole figures: } & h_i \in \mathbb{S}^2 \quad \text{for } i \in [1 \ldots N_1] \text{ and }\\[1ex]&& \text{nodes: } & r_{i, j} \in \mathbb{S}^2 \quad \text{for } i \in [1 \ldots N_1],\ j \in [1 \ldots N_2].\\[1em] \text{\textbf{Output}} & : & \text{sample values (samples): }& x_{i, j} \in \mathbb{C} \quad \text{for } i \in [1 \ldots N_1],\ j \in [1 \ldots N_2], \text{ where } \\[1ex]&&& x_{i, j} = \sum_{l = 0}^{N} \sum_{m = -l}^{l} \sum_{n = -l}^{l} \omega_{l, m, n} \overline{Y_l^n(h_i)} Y_l^m(r_{i, j}). \end{array} \]

Adjoint Texture Transform

The Adjoint Texture Transform is defined as follows:

\[ \begin{array}{rcll} \text{\textbf{Input}} & : & \text{sample values (samples): }& x_{i, j} \in \mathbb{C} \quad \text{for } i \in [1 \ldots N_1],\ j \in [1 \ldots N_2], \\[1ex]&& \text{pole figures: } & h_i \in \mathbb{S}^2 \quad \text{for } i \in [1 \ldots N_1] \text{ and }\\[1ex]&& \text{nodes: } & r_{i, j} \in \mathbb{S}^2 \quad \text{for } i \in [1 \ldots N_1],\ j \in [1 \ldots N_2].\\[1em] \text{\textbf{Ouput}} & : & \text{frequency coefficients (frequencies): } & \omega_{l, m, n} \in \mathbb{C} \quad \text{for } l \in [0 \ldots N],\ m \in [-l \ldots l],\ n \in [-l \ldots l], \text{ where}\\[1ex]&&& \omega_{l, m, n} = \sum_{i = 1}^{N_1} \sum_{j = 1}^{N_2} x_{i, j} Y_l^n(h_i) \overline{Y_l^m(r_{i, j})}. \end{array} \]

States of the Transformation

For reasons of performance this module has some state based behaviour, i.e. certain functions only yield the correct result, if other certain functions have been called before. For ease of notation we denominate

You have to bear in mind the following two points:

  1. Precomputation
  2. Manipulation of Transform Plans

Data Representation

Spherical coordinates are represented by two angles $\phi$ (latitude) and $\theta$ (longitude) as described in Spherical Coordinates. Their normalisation has to be defined in TEXTURE_MAX_ANGLE before compiling the library. Hence $\phi$ and $\theta$ have to satisfy the following conditions:

\[ \phi \in [- \frac{TEXTURE\_MAX\_ANGLE}{2}, \frac{TEXTURE\_MAX\_ANGLE}{2}) \quad and \quad \theta \in [0, \frac{TEXTURE\_MAX\_ANGLE}{2}]. \]

In the following we describe, how the input and output data $\omega,\ x,\ h \text{ and } r$ is stored in the arguments for texture_init or texture_init_advanced. Formally the following conditions hold:

for all $l \in [0 \ldots N],\ m \in [-l \ldots l],\ n \in [-l \ldots l],\ i \in [1 \ldots N_1] \text{ and } j \in [1 \ldots N_2].$

To get a better feeling what texture_flat_index does, see the following fragment of code:

 int l, m, n;
 for(l = 0; l <= N; l++) {
   for(m = -l; m <= l; m++) {
     for(n = -l; n <= l; n++) {
       printf("%d\n", texture_flat_index(l, m, n));
     }
   }
 }
It will print a list of succeeding numbers from 0.

Function Documentation

void texture_adjoint texture_plan ths  ) 
 

Carries out the adjoint transform.

Maps the samples on the frequencies. Therefor the frequencies change, everything else is preserved.

ths - Points to the transformation plan.
Precondition:

void texture_init texture_plan ths,
int  N,
int  N1,
int  N2,
complex *  omega,
complex *  x,
const double *  h_phi,
const double *  h_theta,
const double *  r
 

Initialisation of a plan with default values for all parameters.

The arguments after ths will be stored in the plan ths.

ths - Points to the transformation plan.
N - the bandwidth
N1 - the number of pole figures
N2 - the number of samples per pole figure
omega - the frequencies
x - the samples
h_phi - the latitudes of the pole figures
h_theta - the longitudes of the pole figures
r - the samples of the pole figures
Attention:
  • texture_init performes only a flat copy. If you change the storage referenced to by any of the pointer arguments, the plan can get an inconsistent state.
  • Use texture_finalize to free allocated memory.
Precondition:
All pointer arguments have to point to allocated memory. omega, x, h_phi, h_theta and r have to refer to arrays of appropriate lengths.
Note:
For details about data representation see Data Representation.

void texture_init_advanced texture_plan ths,
int  N,
int  N1,
int  N2,
complex *  omega,
complex *  x,
const double *  h_phi,
const double *  h_theta,
const double *  r,
unsigned int  texture_init_flags,
unsigned int  nfsft_init_flags,
int  nfft_cutoff
 

Initialisation of a plan.

The arguments after ths will be stored in the plan ths.

ths - Points to the transformation plan.
N - the bandwidth
N1 - the number of pole figures
N2 - the number of samples per pole figure
omega - the frequencies
x - the samples
h_phi - the latitudes of the pole figures
h_theta - the longitudes of the pole figures
r - the nodes of the pole figures
texture_init_flags - does not have any effect
nfsft_init_flags - flags to use for the initialisation of the nfsft
nfft_cutoff - a parameter for the initialisation of the nfsft
Attention:
  • texture_init_advanced performes only a flat copy. If you change the storage referenced to by any of the pointer arguments, the plan can get an inconsistent state.
  • Use texture_finalize to free allocated memory.
Remarks:
Use texture_init instead if you do not know, what you are doing.
Precondition:
All pointer arguments have to point to allocated memory. omega, x, h_phi, h_theta and r have to refer to arrays of appropriate lengths.
Note:
For details about data representation see Data Representation.

void texture_precompute int  N  ) 
 

Performes precomputations with default values for all parameters.

Afterwards texture_trafo and texture_adjoint will work with any plans having a bandwidth equal or less than N.

Attention:
To free allocated memory texture_forget has to be called.
Parameters:
N - the maximum bandwidth
See also:
TEXTURE_DEF_PRECOMPUTE_FLAGS

TEXTURE_DEF_NFSFT_PRECOMPUTE_FLAGS

TEXTURE_DEF_NFSFT_THRESHOLD

void texture_precompute_advanced int  N,
unsigned int  texture_precompute_flags,
unsigned int  nfsft_precompute_flags,
double  nfsft_threshold
 

Performes precomputations.

Afterwards texture_trafo and texture_adjoint will work with any plans having a bandwidth equal or less than N.

Attention:
To free allocated memory texture_forget has to be called.
Remarks:
Use texture_precompute instead if you do not know, what you are doing.
Parameters:
N - the maximum bandwidth
texture_precompute_flags - does not have any effect
nfsft_precompute_flags - flags for the precomputation of the nfsft
nfsft_threshold - a parameter for the precomputation of the nfsft

void texture_trafo texture_plan ths  ) 
 

Carries out the direct transform.

Maps the frequencies on the samples. Therefore the samples will be changed, everything else will be preserved.

ths - Points to the transformation plan.
Precondition:


Generated on Wed May 10 20:39:39 2006 for NFFT by  doxygen 1.4.4