Islice and Mrcslice modules

Header to include: mrcslice.h (included by b3dutil.h and cfsemshare.h)

Basic Functions in islice.c (libcfshr)

Basic and Miscellaneous Functions in mrcslice.c

Scaling, Boxing, Mirroring and Wrapping Functions

Reading and Writing Functions

Filters and Transformations

Structures and Definitions for Islice Structures

Basic Functions in islice.c (libcfshr)

Islice *sliceCreate(int xsize, int ysize, int mode)

Creates an Islice structure of the given mode and allocates a data array appropriate for the size xsize, ysize.  Returns a pointer to the slice or the NULL for error

int sliceInit(Islice *s, int xsize, int ysize, int mode, void *data)

Initialize elements in the Islice structure s with the given size xsize, ysize and mode mode, and sets the data member to data. Returns -1 for an undefined mode.

void sliceFree(Islice *s)

Frees the Islice structure s and its data array if any.  s can be NULL.

void sliceClear(Islice *s, Ival val)

Sets the entire slice s to the value given by the Ival type val

int sliceMode(char *mst)

Returns a slice mode corresponding to the string in mst, which can contain either an MRC mode number or byte, short, float, complex, ushort, or rgb.  Returns SLICE_MODE_SBYTE (-2) for sbyte or SLICE_MODE_UBYTE (-3) for ubyte.

int sliceModeIfReal(int mrcMode)

For the MRC_MODE_... type in mrcMode, returns the corresponding defined SLICE_MODE_... value if the mode is byte, signed or unsigned short integer, or float, otherwise returns -1.

int sliceGetXSize(Islice *slice)

Returns the X size of slice

int sliceGetYSize(Islice *slice)

Returns the Y size of slice

int sliceGetVal(Islice *s, int x, int y, Ival val)

Gets the value of pixel at x, y in slice s and puts it into the value array val.  Returns -1 and puts the slice mean into the first element of val for a point out of bounds, and returns -1 if the slice mode is undefined.

int slicePutVal(Islice *s, int x, int y, Ival val)

Puts the value(s) in val into the pixel at x, y in slice s. Returns -1 if the point is out of bounds or the slice mode is undefined.

float sliceGetPixelMagnitude(Islice *s, int x, int y)

Returns the magnitude of the pixel at x, y in slice s: simply the value for one-channel data, the amplitude of complex data, or a weighted value for RGB data.

float sliceGetValMagnitude(Ival val, int mode)

Returns the magnitude of the value array val extracted from a slice of mode mode: simply the value for one-channel data, the amplitude of complex data, or a weighted value for RGB data.

Basic and Miscellaneous Functions in mrcslice.c

int sliceNewMode(Islice *s, int mode)

Converts the data in slice s from its current mode to mode, allocating a new data array as needed.  Complex values are converted to others by taking the magnitude.  Values are converted to complex modes by setting the real component to the value, and the imaginary component to 0.  RGB values are converted by taking a weighted sum of components.  When converting to a mode with integer or byte values, the data are truncated to fit within the range of the new mode.  Returns the new mode or -1 for error.

int sliceNewModeEx(Islice *s, int mode, int freeData)

Like sliceNewMode except that existing data in the slice are freed only if freeData is non-zero.

int sliceFloat(Islice *slice)

Converts the data in slice to float mode.  For complex data, the magnitude is taken; for RGB data, a weighed sum of the components is taken.  This is called by sliceNewMode for float mode.  Returns -1 for error.

int sliceFloatEx(Islice *slice, int freeData)

Like sliceNewMode except that existing data in the slice are freed only if freeData is non-zero.

int sliceComplexFloat(Islice *slice)

Converts the data in slice from modes 0-3 or 6 to complex float.  For modes 0-2 and 6, the value is placed in the real component and the imaginary component is set to 0.  This should be slightly more efficient than sliceNewMode is.  Returns -1 for error.

int sliceMMM(Islice *s)

Calculates the min, max, and mean of slice s and fills in the structure members.  Returns -1 for an empty slice.

Islice *mrc_slice_getvol(Istack *v, int sno, char axis)

Extracts a slice at section number sno from the volume in the Istack structure v, where axis is either x or X for a Y/Z slice or y or Y for an X/Z slice.  Returns NULL for error.

int mrc_slice_putvol(Istack *v, Islice *s, int sno, char axis)

Puts values from the slice s into the volume in the Istack structure v at coordinate sno along the axis given by axis, which must be one of x, X, y, Y, z, or Z.  For a Z slice, the existing slice is freed and the supplied slice becomes part of the stack, so it should not be freed separately from the stack.  Returns 0.

int corr_conj(float *g, float *h, int size)

Computes the product of the complex values in h and the complex conjugate of the values in g and places the results back in g.  The number of complex values in the arrays is given by size.  Returns 0.

Scaling, Boxing, Mirroring and Wrapping Functions

int sliceAddConst(Islice *slice, Ival c)

Adds the constant in the value array c to slice.  Returns 0.

int sliceMultConst(Islice *slice, Ival c)

Multiples all values in slice by the constants in the value array c. Returns 0.

int mrc_slice_valscale(Islice *s, double inScale)

Multiplies all values in slice s by scale factor inScale. Returns 0.

int mrc_slice_lie(Islice *sin, double fixed, double alpha)

Scales data in the slice by the factor alpha around the value fixed; i.e., a value of fixed is unchanged by the scaling.  Returns 0.

Islice *sliceBox(Islice *sl, int llx, int lly, int urx, int ury)

Extracts a subarea of slice sl into a new slice and returns the slice or NULL for error.  The coordinates of the subarea are from llx to urx - 1 in X and lly to ury -1 in Y, inclusive.  For areas where there is no image data, the slice mean is used to fill only the first channel.

int sliceBoxIn(Islice *sl, int llx, int lly, int urx, int ury)

Replaces the slice sl with a subarea from llx to urx - 1 in X and lly to ury -1 in Y, inclusive.  For areas where there is no image data, the slice mean is used to fill only the first channel.  Returns -1 for memory error.

int sliceResizeIn(Islice *sl, int x, int y)

Resizes the slice sl in place to the new size x, y, with the center at the old size placed in the center at the new size.  For areas where there is no image data, the slice mean is used to fill only the first channel.  Returns -1 for error.

Islice *mrc_slice_resize(Islice *slin, int nx, int ny)

Creates a new slice of size nx, ny and resizes the input slice slin into this slice, with the center of the old slice placed in the center of the new one.  Fills areas with no data from the old slice with the slice mean for every channel of multi-channel data.  Returns new slice or NULL for error.

int sliceMirror(Islice *s, char axis)

Mirrors the slice s about the given axis, where axis must be one of x, X, y, or Y.  Returns 1 for error.

int sliceWrapFFTLines(Islice *s, int direction)

Wraps the lines of an FFT in slice s to bring the origin to the center from the first line if direction is 0, or back otherwise.  Returns 1 for improper mode, 2 for memory error, or 3 for a complex short slice with odd size in Y.

int sliceReduceMirroredFFT(Islice *s)

Converts a slice with an old-style mirrored FFT to a standard FFT with line length nx/2 + 1.  Returns 1 if the slice is not complex float.

Reading and Writing Functions

int sliceWriteMRCfile(const char *filename, Islice *slice)

Writes the data from slice into a new MRC file whose name is given in filename.  Returns -1 for error opening the file, -2 for error writing header, or an error from mrc_write_slice if there is an error writing the data.

int mrcWriteImageToFile(const char *filename, void *array, int mode, int nx, int ny)

Writes the data in array of mode mode and size nx by ny into a new MRC file whose name is given in filename.  Calls sliceWriteMRCfile and returns its return value.

Islice *sliceReadMRC(MrcHeader *hin, int sno, char axis)

Returns a slice with one plane of data from the file described by the MrcHeader structure hin.  The coordinate of the plane is sno along the axis given by axis, which must be one of x, X, y, Y, z, or Z.  The file pointer in hin is used.  Bytes are swapped if necessary. Calls mrc_mread_slice.  Returns NULL for errors.

Islice *sliceReadSubm(MrcHeader *hin, int secNum, char axis, int xsize, int ysize, int xcen, int ycen)

Returns a slice with a subarea of one plane of data from the file described by the MrcHeader structure hin.  The coordinate of the plane is secNum along the axis given by axis, which must be one of x, X, y, Y, z, or Z.  The size of the subarea is given by xsize and ysize and its center is given by xcen, ycen.  The entire slice is read in by calling mrc_mread_slice and then the subarea is taken with sliceBoxIn. The file pointer in hin is used.  Bytes are swapped if necessary.  Returns NULL for errors.

Islice *sliceReadFloat(MrcHeader *hin, int secno)

Returns a slice with one Z plane of data at Z value secno from the file described by the MrcHeader structure hin. The file pointer in hin is used.  Calls mrcReadFloatSlice, where bytes are swapped if necessary.  Returns NULL for errors.

Filters and Transformations

Islice *sliceGradient(Islice *sin)

Returns a slice with the gradient of the input slice sin, or NULL for error.  The gradient is the absolute value of the difference between the current and next pixel, averaged over the X and Y direction.

int mrc_bandpass_filter(struct MRCslice *sin, double low, double high)

Filters the FFT data in slice sin with a bandpass filter specified by low and high, in cycles/pixel (range 0 to 0.5).  The attenuation at frequency rad is the product of 1/(1+(rad/low)**3) if low > 0 and 1/1+(high/rad)**3) if high > 0.  Returns -1 for mode not complex float.

Islice *slice_mat_filter(Islice *sin, float *mat, int dim)

Filters a slice sin by convolving with the square matrix mat of dimension dim and returns a float slice, or NULL for error.  Pixels outside the image bounds are obtained by replicated pixels on the edge, so there is no need to set the mean value of the slice.  For a float input slice, it calls applyKernelFilter , otherwise it uses slower GetVal and PutVal based operations.  Both approaches are parallelized with OpenMP, but the latter only for kernel sizes up to 9.

void mrc_slice_mat_getimat(Islice *sin, int x, int y, int dim, float *mat)

Extracts a square matrix of size dim from the slice sin, centered around position x, y and places the result into the array mat.

float mrc_slice_mat_mult(float *m1, float *m2, int dim)

Forms a dot product between the two vectors m1 and m2, which are square matrices of dimension dim

Islice *mrc_slice_rotate(Islice *slin, double angle, int xsize, int ysize, double cx, double cy)

Creates a slice of size xsize, ysize and rotates the input slice slin by the angle (in degrees) about the center point cx, cy.  Uses quadratic interpolation.  For areas where there is no image data, all channels will be filled with the slice mean.  Returns the new slice or NULL for error.

int mrc_slice_rotates(Islice *slin, Islice *sout, double angle, double cx, double cy)

Rotates the input slice slin by the angle (in degrees) about the center point cx, cy and places the result into the output slice sout. Uses quadratic interpolation.  For areas where there is no image data, all channels will be filled with the slice mean.  Returns 0.

Islice *mrc_slice_translate(Islice *sin, double dx, double dy, int xsize, int ysize)

Creates a slice of size xsize, ysize and translates the input slice sin by dx, dy using bilinear interpolation, putting the result in the new slice.  For areas where there is no image data, all channels will be filled with the slice mean.  Returns the new slice or NULL for error.

Islice *mrc_slice_zoom(Islice *sin, double xz, double yz, int xsize, int ysize, double cx, double cy)

Creates a slice of size xsize, ysize and expands the input slice sin by the factors xz in X and yz in Y about the center point cx, cy. Uses quadratic interpolation.  For areas where there is no image data, all channels will be filled with the slice mean Returns the new slice or NULL for error.

int mrc_slice_zooms(Islice *sin, Islice *sout, double xz, double yz, double cx, double cy)

Expands the input slice sin by the factors xz in X and yz in Y about the center point cx, cy and places the result in the slice sout. Uses quadratic interpolation.  For areas where there is no image data, the slice mean is used to fill only the first channel.  Returns the new slice or NULL for error.

void sliceQuadInterpolate(Islice *sl, double x, double y, Ival val)

Fills the value array val with the interpolated value from position x, y in slice sl, using quadratic interpolation.  For areas where there is no image data, the slice mean is used for all elements of val.

Structures and Definitions for Islice Structures

MRCslice definitions

#define SLICE_MODE_BYTE          0   /* type unsigned char                   */
#define SLICE_MODE_SHORT         1   /* type short                           */
#define SLICE_MODE_FLOAT         2   /* type float                           */
#define SLICE_MODE_COMPLEX_SHORT 3   /* 2 channels of short                  */
#define SLICE_MODE_COMPLEX_FLOAT 4   /* 2 channels of floats                 */
#define SLICE_MODE_USHORT        6   /* unsigned short                       */
#define SLICE_MODE_RGB           16  /* 3 channels of bytes                  */

/* Other modes */
#define SLICE_MODE_MAX           99  /* float data with max channels.        */
#define SLICE_MODE_UNDEFINED     -1  /* float data with max channels.        */
#define SLICE_MODE_SBYTE         -2  /* values for sliceMode to return when  */
#define SLICE_MODE_UBYTE         -3  /* user enters 'sbyte' or 'ubyte'       */

/* The maximum values for channels and bytes/channel */
#define SLICE_MAX_CSIZE          3   /* max channels.                        */
#define SLICE_MAX_DSIZE          4   /* max data size of pixel in bytes.     */

Ival type

typedef float Ival[SLICE_MAX_CSIZE];

Islice structure

union MRCdata
{
  unsigned char *b;
  b3dInt16      *s;
  b3dUInt16     *us;
  b3dFloat      *f;
};

/* The Islice structure */
typedef struct MRCslice
{
  union MRCdata data;              /* pointer to data: data.b, data.s, etc */
  b3dInt32 xsize;                  /* size of data.           */
  b3dInt32 ysize;
  b3dInt32 mode;                   /* type of storage         */
  b3dInt32 csize;                  /* number of data channels */
  b3dInt32 dsize;                  /* data size for pixel     */
  float  min, max, mean;
  b3dInt32 index;                  /* index of current value  */
  float  cval[SLICE_MAX_CSIZE];  /* value of current index  */
}Islice;

Istack structure

typedef struct MRCvolume
{
  struct MRCslice **vol;
  b3dInt32           zsize;
}Istack;