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

texture_trafo, texture_adjoint, itexture_before_loop and itexture_loop_one_step as transform functions,
texture_precompute and texture_precompute_advanced as precomputation functions and
texture_init and texture_init_advanced as initialisation functions.

You have to bear in mind the following two points:

Precomputation
- State 1:
  - The behaviour of the transform functions is undefined.
  - texture_forget has no effect.
  - The precomputation functions cause a state change to state 2 and initialise the precomputed data.
  - There is no memory allocated for precomputed data.
- State 2:
  - The transform functions yield the correct result, if the bandwidth of the transform plan is in the valid range according to the precomputed data. Otherwise their behaviour is undefined.
  - The precomputation functions change the precomputed data.
  - texture_forget causes a state change to state 1 and frees all memory for precomputed data.
  - There is some memory allocated for precomputed data.
Manipulation of Transform Plans
- Before using the transform functions with a cerain plan, you have to initialise it with one of the initialisation functions.
- After the initialisation you can apply the transform functions as often as you want. But the only way you may read or manipulate elements of the plan is using the utility functions described in Texture: Utility Functions.
- After the usage of a plan you must destroy its temporary data with texture_finalize to avoid memory leaks.

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:

$\omega_{l, m, n} =$ omega[texture_flat_index (l, m, n)],
$x_{i, j} =$ x[i * N2 + j],
the latitude $\phi$ of $h_{i} =$ h_phi[i],
the longitude $\theta$ of $h_{i} =$ h_theta[i],
the latitude $\phi$ of $r_{i, j} =$ r[2 * (i * N2 + j)] and
the longitude $\theta$ of $r_{i, j} =$ r[2 * (i * N2 + j) + 1]

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:

texture_precompute or texture_precompute_advanced must have been called with appropriate arguments.
The plan hast to be initialised with texture_init or texture_init_advanced.

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:

texture_precompute or texture_precompute_advanced must have been called with appropriate arguments.
The plan hast to be initialised with texture_init or texture_init_advanced.

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

1.4.4

Texture

Modules

Data Structures

Defines

Typedefs