MapDepthMatrix - MapDepthMatrix maintains a 5D matrix. [Supporting Modules]

Data Structures
struct	MAP_DEPTH_MATRIX
Enumerations
enum	DataSpace { REAL_SPACE, WAVE_SPACE }
Functions
MAP_DEPTH_MATRIX	newMapDepthMatrix (int x, int y, int z, int t, bool shift)
MAP_DEPTH_MATRIX	newMapDepthMatrixV (int x, int y, int z, int t, int v, bool shift)
void	destroyMapDepthMatrix (MAP_DEPTH_MATRIX td)
bool	isEmptyMapDepthMatrix (const MAP_DEPTH_MATRIX *td)
MATRIX	extractMapDepth (int kx, int ky, MAP_DEPTH_MATRIX td)
void	insertMapDepth (int kx, int ky, MATRIX m, MAP_DEPTH_MATRIX *tdptr)
MATRIX	extractXYPlaneFromMapDepthMatrix (int map, int depth, MAP_DEPTH_MATRIX td)
MATRIX	extractXYPlaneFromMapDepthMatrixV (int map, int depth, int v, MAP_DEPTH_MATRIX td)
MATRIX	extractXYPlaneFromDoubleArray (int map, int depth, int v, int nX, int nY, int nZ, int nT, int nV, Float *td)
void	insertXYPlaneIntoMapDepthMatrix (MATRIX xyPlane, int map, int depth, MAP_DEPTH_MATRIX *tdptr)
void	insertXYPlaneIntoMapDepthMatrixV (MATRIX xyPlane, int map, int depth, int v, MAP_DEPTH_MATRIX *tdptr)
void	insertXYPlaneIntoDoubleArray (MATRIX xyPlane, int map, int depth, int v, int nX, int nY, int nZ, int nT, int nV, Float *tdptr)
MATRIX	extractXYPlaneColMajorMapDepthMatrix (int map, int depth, const MAP_DEPTH_MATRIX *td)
MATRIX	extractXYPlaneColMajorMapDepthMatrixV (int map, int depth, int v, const MAP_DEPTH_MATRIX *tdptr)
void	insertXYPlaneColMajorMapDepthMatrix (MATRIX xyPlane, int map, int depth, MAP_DEPTH_MATRIX *tdptr)
void	insertXYPlaneColMajorMapDepthMatrixV (MATRIX xyPlane, int map, int depth, int v, MAP_DEPTH_MATRIX *tdptr)
MAP_DEPTH_MATRIX	readMapDepthMatrixKernel (char *basedir, char *filenames[], int nFiles, bool useFT)
MAP_DEPTH_MATRIX	readMapDepthMatrix (char *basedir, char *filenames[], int nFiles, bool useFT)
MAP_DEPTH_MATRIX	readMapDepthMatrixV (char *basedir, char *filenames[], int nFiles, int vdim, bool useFT)
void	writeMapDepthMatrix (char *filenames[], int nFiles, MAP_DEPTH_MATRIX tdm, bool useFT, FITSParameters headerParameters)
MASK	readMasks (char *basedir, char *filenames[], int nFiles)
MATRIX	extractMapZ1FromMask (int kx, int ky, const MASK *masks)

---

Enumeration Type Documentation

enum DataSpace

DataSpace

Enumerator:

REAL_SPACE
WAVE_SPACE

---

Function Documentation

void destroyMapDepthMatrix

(

MAP_DEPTH_MATRIX

td

)

Free memory used to store data in 4d matrix

Parameters:

[in]

td

A 4d matrix

MATRIX extractMapDepth	(	int	kx,
		int	ky,
		MAP_DEPTH_MATRIX	td
	)

Extract a 2d sub matrix from a 4d matrix. Really, this returns a pointer to a 2d matrix inside the 4d matrix. The pointer is wrapped by a 2d matrix object.

Parameters:

[in]	kx	Row index in xy-plane
[in]	ky	Column index in xy-plane
[in]	td	4d matrix from which to extract.

Returns:

2d matrix indexed by map (rows) and depth (columns). MATRIX(map, depth). MATRIX.data is a pointer into the 4d matrix. No data is copied, only a pointer is provided.

MATRIX extractMapZ1FromMask	(	int	kx,
		int	ky,
		const MASK *	masks
	)

Extract a 2d sub matrix from a 4d matrix. Really, this returns a pointer to a 2d matrix inside the 4d matrix. The pointer is wrapped by a 2d matrix object.

Parameters:

[in]	kx	Row index in xy-plane
[in]	ky	Column index in xy-plane
[in]	masks	3D matrix from which to extract.

Returns:

2D matrix indexed by map (rows) and depth (columns). MATRIX(map, depth). MATRIX.data is a pointer into the 3D matrix. No data is copied, only a pointer is provided.

MATRIX extractXYPlaneColMajorMapDepthMatrix	(	int	map,
		int	depth,
		const MAP_DEPTH_MATRIX *	td
	)

Extract a 2d sub matrix from a 4d matrix. Here, data values are copied because the xy-plane values are dispersed throughout the 4d matrix.

Parameters:

[in]	map	Row index in td-plane
[in]	depth	Column index in td-plane
[in]	td	4d matrix from which to extract.

Returns:

2d matrix indexed by x (rows) and y (columns). MATRIX(x,y). A new matrix is created to hold the copied data and keep it contiguous.

MATRIX extractXYPlaneColMajorMapDepthMatrixV	(	int	map,
		int	depth,
		int	v,
		const MAP_DEPTH_MATRIX *	tdptr
	)

MATRIX extractXYPlaneFromDoubleArray	(	int	map,
		int	depth,
		int	v,
		int	nX,
		int	nY,
		int	nZ,
		int	nT,
		int	nV,
		Float *	td
	)

MATRIX returned is Float Extract a 2d sub matrix from a linear array of Floats. Use the same data layout in the Float array as in a MAP_DEPTH_MATRIX. Here, data values are copied because the xy-plane values are dispersed.

Parameters:

[in]	map	Row index in td-plane
[in]	depth	Column index in td-plane
[in]	v	number of scatterers (3 for vector problems, 1 otherwise)
[in]	nX,nY,nZ,nT,nV	dimensions of the linear array of Floats.
[in]	td	linear array of Floats from which to extract.

Returns:

2d matrix indexed by x (rows) and y (columns). MATRIX(x,y). A new matrix is created to hold the copied data and keep it contiguous.

MATRIX extractXYPlaneFromMapDepthMatrix	(	int	map,
		int	depth,
		MAP_DEPTH_MATRIX	td
	)

Extract a 2d sub matrix from a 4d matrix. Here, data values are copied because the xy-plane values are dispersed throughout the 4d matrix.

Parameters:

[in]	map	Row index in td-plane
[in]	depth	Column index in td-plane
[in]	td	4d matrix from which to extract.

Returns:

2d matrix indexed by x (rows) and y (columns). MATRIX(x,y). A new matrix is created to hold the copied data and keep it contiguous.

MATRIX extractXYPlaneFromMapDepthMatrixV	(	int	map,
		int	depth,
		int	v,
		MAP_DEPTH_MATRIX	td
	)

void insertMapDepth	(	int	kx,
		int	ky,
		MATRIX	m,
		MAP_DEPTH_MATRIX *	tdptr
	)

Insert a 2d sub matrix into a 4d matrix. Here, memory is copied to keep 2d sub matrix in tact, i.e. in contiguous memory.

Parameters:

[in]	kx	Row index in xy-plane
[in]	ky	Column index in xy-plane
[in]	m	A 2d matrix indexed by map (rows) and depth (columns) to insert.
[in,out]	tdptr	Pointer to 4d matrix in which to copy 2d matrix data. Need to send pointer to 4d matrix because we are changing values in the 4d matrix structure.

void insertXYPlaneColMajorMapDepthMatrix	(	MATRIX	xyPlane,
		int	map,
		int	depth,
		MAP_DEPTH_MATRIX *	tdptr
	)

Insert a 2d sub matrix into a 4d matrix. Here, data values are copied because the xy-plane values are dispersed throughout the 4d matrix.

Parameters:

[in]	map	Row index in td-plane
[in]	depth	Column index in td-plane
[in]	xyPlane	A 2d matrix indexed by x (rows) and y (columns) to insert.
[in,out]	tdptr	Pointer to 4d matrix in which to copy 2d matrix data. Need to send pointer to 4d matrix because we are changing values in the 4d matrix structure.

void insertXYPlaneColMajorMapDepthMatrixV	(	MATRIX	xyPlane,
		int	map,
		int	depth,
		int	v,
		MAP_DEPTH_MATRIX *	tdptr
	)

void insertXYPlaneIntoDoubleArray	(	MATRIX	xyPlane,
		int	map,
		int	depth,
		int	v,
		int	nX,
		int	nY,
		int	nZ,
		int	nT,
		int	nV,
		Float *	tdptr
	)

MATRIX is Float Insert a 2d map-depth matrix into a linear array of Floats. Use the same data layout in the Float array as in a MAP_DEPTH_MATRIX. Here, data values are copied because the xy-plane values are dispersed.

Parameters:

[in]	xyPlane	MATRIX of Floats to insert into linear array of Floats.
[in]	map	Row index in td-plane
[in]	depth	Column index in td-plane
[in]	v	number of scatterers (3 for vector problems, 1 otherwise)
[in]	nX,nY,nZ,nT,nV	dimensions of the linear array of Floats.
[in]	tdptr	pointer to linear array of Floats.

void insertXYPlaneIntoMapDepthMatrix	(	MATRIX	xyPlane,
		int	map,
		int	depth,
		MAP_DEPTH_MATRIX *	tdptr
	)

Insert a 2d sub matrix into a 4d matrix. Here, data values are copied because the xy-plane values are dispersed throughout the 4d matrix.

Parameters:

[in]	map	Row index in td-plane
[in]	depth	Column index in td-plane
[in]	xyPlane	A 2d matrix indexed by x (rows) and y (columns) to insert.
[in,out]	tdptr	Pointer to 4d matrix in which to copy 2d matrix data. Need to send pointer to 4d matrix because we are changing values in the 4d matrix structure.

void insertXYPlaneIntoMapDepthMatrixV	(	MATRIX	xyPlane,
		int	map,
		int	depth,
		int	v,
		MAP_DEPTH_MATRIX *	tdptr
	)

bool isEmptyMapDepthMatrix

(

const MAP_DEPTH_MATRIX *

td

)

check if MapDepthMatrix is null

Parameters:

[in]

td

A 4d matrix

Returns:

True if matrix is null, False otherwise

MAP_DEPTH_MATRIX newMapDepthMatrix	(	int	x,
		int	y,
		int	z,
		int	t,
		bool	shift
	)

Create a new 4d matrix by allocating space for data and setting internal parameters.

Parameters:

[in]	x	number of rows in xy-plane
[in]	y	number of columns in xy-plane
[in]	z	depth dimension
[in]	t	number of measurements (map dimension)
[in]	shift	boolean; if output from inverse FT needs to be shifted.

Returns:

new 4d matrix

MAP_DEPTH_MATRIX newMapDepthMatrixV	(	int	x,
		int	y,
		int	z,
		int	t,
		int	v,
		bool	shift
	)

Create a new 5d matrix by allocating space for data and setting internal parameters.

Parameters:

[in]	x	number of rows in xy-plane
[in]	y	number of columns in xy-plane
[in]	z	depth dimension
[in]	t	number of measurements (map dimension)
[in]	v	dimension of vector data (usually set to 3)
[in]	shift	boolean; if output from inverse FT needs to be shifted.

Returns:

new 5d matrix

MAP_DEPTH_MATRIX readMapDepthMatrix	(	char *	basedir,
		char *	filenames[],
		int	nFiles,
		bool	useFT
	)

MAP_DEPTH_MATRIX readMapDepthMatrixKernel	(	char *	basedir,
		char *	filenames[],
		int	nFiles,
		bool	useFT
	)

MAP_DEPTH_MATRIX readMapDepthMatrixV	(	char *	basedir,
		char *	filenames[],
		int	nFiles,
		int	vdim,
		bool	useFT
	)

Opens and reads FITS files, then stores the data in a new MAP_DEPTH_MATRIX.

Parameters:

[in]	basedir	base directory for all filenames
[in]	filenames	list of FITS files to read.
[in]	nFiles	number of files to read
[in]	vdim	The vector dimension; for 3d, vdim = 1; for 5d, vdim = 3.
[in]	useFT	Boolean; whether to Fourier transform the data before inserting into MAP_DEPTH_MATRIX.

Returns:

new map depth matrix containing data from files.

HERE -- if 3dv, then read 3 x kernel file names

MASK readMasks	(	char *	basedir,
		char *	filenames[],
		int	nFiles
	)

Opens and reads FITS files, then stores the data in a new MASK.

Parameters:

[in]	basedir	base directory for all filenames
[in]	filenames	list of FITS files to read.
[in]	nFiles	number of files to read

Returns:

new MASK containing data from files.

void writeMapDepthMatrix	(	char *	filenames[],
		int	nFiles,
		MAP_DEPTH_MATRIX	tdm,
		bool	useFT,
		FITSParameters	headerParameters
	)

Opens and writes MAP_DEPTH_MATRIX to FITS files. Each t-dimension is written to a separate FITS file.

Parameters:

[in]	filenames	list of FITS files to write; NOTE: each filename must already have directory path, i.e. the filenames are complete paths.
[in]	nFiles	number of files to write.
[in]	tdm	map depth matrix containing data for output.
[in]	useFT	Boolean; whether to Fourier transform the data before inserting into MAP_DEPTH_MATRIX.
[in]	headerParameters	Names, values and comments of the lambda parameters for FITS header.