EMData

UNDER CONSTRUCTION

Each instance of this object will contain a single 'image'. This is in quotes because the data may be 1, 2 or 3 dimensional.

Supported file formats include Imagic, MRC, Spider and standard 8 bit formats like GIF, TIFF, etc. (through the netpbm package). Note that 12 bit TIFFs are not currently supported. The EMAN object will automatically compensate for byte-order differences. Files can be read in either byte-order and are always written in the byte-order of the native machine.

Note:

Many of the routines in the object will assume that the object is square. Most will produce an error if this condition is not met, some will just act unexpectedly.
The FFT routine is radix 19. Factors of the image size may NOT include primes larger than 19, and must ALWAYS include 2.
Image rotation and translation is a little tricky. Be sure to read the sections on setRAlign, setTAlign and RotateAnd Translate before trying this.

EMData Functions

File IO

int readImage(char *filespec, int n,int nodata=0) Reads a single image from a file (any format)

int fileCount(char *filespec) NOT a member function. Counts # images in a file.

List *readImages(char *filespec,int n0,int n1,int nodata=0) NOT a member function. Reads multiple images. Returns a List of EMData objects (which may be empty in case of error)

int readIMAGIC(char *filespec, int n,int nodata=0)
int writeIMAGIC(char *filespec, int n) These routines are responsible for reading & writing the individual image formats. They are usually called indirectly by readImage() or readImages(). The PGM reading routine reads GIFs, TIFFs, etc. as well as PBMs.

int readIMAGIC3d(char *filespec,int nodata=0)

int readMRC(char *filespec,int nodata=0)
int writeMRC(char *filespec)

int readSPIDER(char *filespec,int nodata=0)
int writeSPIDER(char *filespec)

int readSAL(char *filespec,int nodata=0)

int readPGM(char *filespec,int nodata=0)
int writePGM(char *filespec,float gmin,float gmax)

int readEMIM(char *filespec, int n,int nodata=0)
int writeEMIM(char *filespec, int n)

Information

char *Name()
void setName(char *name) Returns/sets the name of the image

EMData *Parent()
void setParent(EMData *data) Returns/sets the name of the image

char *Path()
void setPath(char *path) Returns/sets the path the image was read from

int xSize()
int ySize()
int zSize()
int setSize(int x,int y, int z) Returns/sets the size of the image in pixels

float Dx()
float Dy()
float Dz()
void setTAlign(float dx,float dy,float dz) Returns/sets the translation of the current image

float alt()
float az()
float phi()
void setRAlign(float alt,float az,float phi) Returns/sets the orientation of the current image. Use alt for in-plane rotation of images

Euler *getEuler() Returns a pointer to the Euler object which stores orientation

int NImg()
void setNImg(int n) Returns/sets the number of images used to generate this image

int getFlags() Raw access to the image flags. See EMData.h

int isComplex() Returns true if the image is complex

int hasCTF()
float *getCTF()
void setCTF(float *c)
float *ctfCurve(int type=0) Functions dealing with the Contrast Transfer Function parameters. Used to perform corrections

Statistical

void update() Called when something in the image changes. getData/doneData automatically calls this.

float Min()
float Max()
float Mean()
float Sigma() Standard statistical functions

float edgeMean() Returns the mean value around the edge of the image

Simple Image Processing

EMData *copy() Returns a copy of an image

EMData *copyHead() Returns a new image with the same header as the current image

EMData *clip(int x0,int y0,int w,int h)
EMData *clip(int x0,int y0,int z0,int w,int h,int d) Returns a new image which contains a portion of the current image. New image will be zero padded if larger than original

void zero()
void one() Fills the entire image with 0 or 1

void rotateAndTranslate(float scale=1.0,float dxc=0,float dyc=0,float dzc=0) This routine performs actual rotation/translation after shift/rotation has been set with setTAlign/setRAlign. NOTE: If this image has a 'parent', the parent is rotated/translated instead of the current image. Used to prevent multiple interpolations.

float transAlign(EMData *with,int useparent=0,int intonly=0)
float transAlign3d(EMData *with,int useparent=0,int intonly=0) Calculates translational alignment of 2 images. Result is set in dx and dy, but rotateAndTranslate is not called.

float rotAlign(EMData *with)
float rotAlignTI(EMData *with,int usedot=0) Calculates rotational alignment of 2 images. rotAlignTI calculates translationally independant rotational alignment with 180 degree ambiguity. Result stored to Euler of current image.

EMData *RTAlign(EMData *with,int usedot=0)
EMData *RTFAlign(EMData *with,EMData *flip=NULL,int usedot=0)
void refineAlign(EMData *with,int usedot) Returns a new image which is rotationally/translationally aligned to 'with'. RTFAlign also allows flips. refineAlign may be called immediately after this to 'fine tune' the alignment.

void cmCenter() Set dx/dy to center the image (center of mass, positive values only)

void applyMask(int r,int type) Masks the image at a given radius. Several different modes, see EMData.C for details

Fourier Processing

EMData *doFFT()
EMData *doIFT()
void gimmeFFT() Returns a new image which is the FFT or IFT of the current image. New image is 'owned' by current image unless gimmeFFT() is called after this call. Radix 19 FFTs.

void ri2ap()
void ap2ri() Changes the representation of a complex image from real/imaginary to/from amplitude/phase. Ok to call even if representation would be unchanged

EMData *calcCCF(EMData *with) Returns a new image which is the cross correlation of the current image and 'with'. Source images may be real or complex.

void calcRCF(EMData *with,float *sum,int NS) Calculates an azimuthal cross correlation function between 2 images. Used for rotational alignments

EMData *makeRFP() Generates a 'rotational footprint' for the current image. This is a new image wh

2d <-> 3d

EMData *project3d(float alt,float az, float phi, int mode) Generates a projection of a 3d volume

void setup4Slice(int redo=1)
EMData *fftSlice(float alt,float az,float phi,int mode=5) Cuts a slice from a 3d Fourier volume. Call setup4Slice once before cutting slices.

void setup4IS(int size)
float normSlice(EMData *slice,float alt,float az,float phi,float *phaseresid=NULL)
void insertSlice(EMData *slice, float alt,float az,float phi,int mode=5,float weight=1.0)
void doneSlice() These routines allow a 3d volume to be reconstructed from a set of slices. See make3d.C for details.

float Pixel()
void setPixel(float pix) Returns/sets angstroms/pixel

Parallelization & Raw Data Access

long getATime() Last time the data set was accessed

float *getDataRO() Gets a pointer to the raw data for shared read-only access. Read only is NOT enforced, but should be observed. Waits if image is busy.

float *getData() Gets a pointer to the raw data for exclusive read/write access. update() called automatically when released.

void doneData() ALWAYS call once for each getData() or getDataRO()

int Busy()
int waitReady(int ro)
void Wait() Used by the above to ensure legal access

Undocumented

void interpFT3d(float x,float y,float z,float *ret,int mode)

void setComplex(int i)
void setRI(int i)

void calcHist(float hmin,float hmax)
float *getHist()
float histMin()
float histMax()
void realCalcHist()

void setFlipped(int f)

void setPathN(int n)

int swapout()
int swapin()

void doDWT(int basis, int level)
void doIWT(int basis, int level)
void DWTFilt(int basis, int level, float thresh)

void rotateAndTranslateFast(float scale=1.0)

Statistical

Image processing

3d <-> 2d

int readImage(char *filespec, int n,int nodata=0); // reads a single image, 0 on sucess
EMData *copy(); // returns an exact copy of itself
EMData *copyHead(); // copies descriptive info, but not data
EMData *clip(int x0,int y0,int w,int h); // inclusive clip. Pads if larger than data
EMData *clip(int x0,int y0,int z0,int w,int h,int d);

// read routines for specific formats
int readSAL(char *filespec,int nodata=0); //scans-a-lot
int readPGM(char *filespec,int nodata=0); //portable greymap (and other pix formats)
int readMRC(char *filespec,int nodata=0);
int readIMAGIC(char *filespec, int n,int nodata=0);
int readIMAGIC3d(char *filespec,int nodata=0);
int readEMIM(char *filespec, int n,int nodata=0);
int readSPIDER(char *filespec,int nodata=0);

// write routines for specific formats
int writeIMAGIC(char *filespec, int n); // n=-1 appends
int writeMRC(char *filespec);
int writePGM(char *filespec,float gmin,float gmax);
int writeSPIDER(char *filespec);
int writeEMIM(char *filespec, int n); // n=-1 appends

// update statistics
void calcHist(float hmin,float hmax);
void realCalcHist();
float *getHist();
void update();

// general parameter set/gets
void setPixel(float pix);
float Pixel();
float Min();
float Max();
float Mean();
float Sigma();
float edgeMean();
float histMin();
float histMax();
void setParent(EMData *data);
EMData *Parent();
void setName(char *name);
char *Name();
void setPath(char *path);
char *Path();
void setPathN(int n);
int xSize();
int ySize();
int zSize();
int setSize(int x,int y, int z);
void setRI(int i); // sets/resets the RI flag, does not modify data
// use ap2ri() for conversion
void setComplex(int i);
int isComplex();
int hasCTF();
int getFlags();
void setFlipped(int f); // !!!! DOESN'T FLIP IMAGE !!!!
float Dx();
float Dy();
float Dz();
float alt();
float az();
float phi();
Euler *getEuler();
void setTAlign(float x,float y,float z);
void setRAlign(float Alt,float Az,float Phi);
void setNImg(int n);
int NImg();
long getATime();

// Access to raw data, swapping
float *getData(); // This returns a pointer to the raw float data
float *getDataRO(); // Returns data pointer for reading only
void doneData(); // MUST be called when the data is no longer being
     // modified. Another getData while the data is
     // out will return NULL
int Busy();   // Returns 1 if data is checked out
int waitReady(int ro); // waits for data to be available
void Wait(); // Why 2 ?    don't recall...
int swapout(); // offloads the data to disk when mem is tight
int swapin(); // reloads the data when necessary

void zero(); // clears the image to zero
void one(); // makes a 'unit' image

// Rendering
int renderAmp8( unsigned char * data , int x , int y, int xsize, int ysize,
int bpl, float scale, int mingray, int maxgray,float renMin, float renMax);
int renderPha24( unsigned char * data , int x , int y , int xsize , int ysize ,
int bpl , float scale, float renMin, float renMax);

// for complex images
void ri2ap(); // converts real/imaginary to amp/pha (complex only)
void ap2ri(); // the opposite

// fourier ops
EMData *doFFT(); // obvious, note that result is initially R,I not A,P
EMData *doIFT(); // obvious
void gimmeFFT(); // This gives the caller ownership of the
// recently obtained fft so it won't be freed automatically
// this means a new fft will be calculated next time

// wavelet ops
void doDWT(int basis, int level); // in place DWT, basis/level defined elsewhere
void doIWT(int basis, int level); // inverse wavelet x-form
void DWTFilt(int basis, int level, float thresh);
// in place nonlinear threshold wavelet filter
// thresh is with respect to the 'ideal' threshold

EMData *calcCCF(EMData *with); // cross correlation between 2 images
// mirror ACF if with=NULL

// if parent is set, each new interpolation will be done from the
// original parent's data, and additional calls to *Align will modify
// dx,dy,daz cumulatively. With no parent dx,dy,daz are reset each time

float transAlign(EMData *with,int useparent=0,int intonly=0); // translational alignment using CCF

float transAlign3d(EMData *with,int useparent=0,int intonly=0); // translational alignment using CCF

float rotAlign(EMData *with); // rotational alignment using angular correlation
// pretranslates by dx,dy

float rotAlignTI(EMData *with,int usedot=0); // rotation alignment with translational
// independance, +180 degree ambiguity

void refineAlign(EMData *with,int usedot);

EMData *makeRFP();

void calcRCF(EMData *with,float *sum,int NS);

EMData *RTFAlign(EMData *with,EMData *flip=NULL,int usedot=0);
// rotational, translational and flip alignment
EMData *RTAlign(EMData *with,int usedot=0);
// rotational, translational alignment used by RTF

void rotateAndTranslate(float scale=1.0,float dxc=0,float dyc=0,float dzc=0);
// rotate and translate using current settings
// behavior changes if parent is/not set

void rotateAndTranslateFast(float scale=1.0);
// rotate and translate using current settings
// behavior changes if parent is/not set

void cmCenter(); // center at center of mass, ignores old dx,dy

// other maniuplations
void applyMask(int r,int type); // applies a circular mask to the data
// type=0 is a step cutoff to the mean value
// type=1 fills in with flatband random noise

void applyRadFn(int n,float x0,float dx,float *y,int interp=1);
// multiplies by a radial function in
// fourier space

void addRadNoise(int n,float x0,float dx,float *y,int interp);
// adds random noise with sigma defined
// by the radial function

void subtract(EMData *data); // subtracts 'data' from the current set

void vFlip(); // flips image vertically

void normalize(); // mean -> 0, std dev -> 1

void normalizeMax(); // mean -> 0, std dev -> 1

void invert(); // multiply by -1

void edgeNormalize(); // same, but uses 1 pixel rectangle border

void calcRadDist(int n,float x0,float dx,float *y);
void calcRadDist(int n,float x0,float dx,float *y,float acen,float amwid);
      // calculates radial distribution, works for real
      // and imaginary images. x must be defined on input
      // and y must be allocated. amin,amax are in radians

void calcAzDist(int n,float a0,float da,float *d,float rmin,float rmax);

void radialAverage(); // makes image circularly symmetric

void toCorner(); // Translates a centered image to the corner

float dot(EMData *data,int evenonly=0); // dot product of 2 images (same size !)

float lcmp(EMData *data); // linear comparison of 2 data sets (smaller better)

void filter(float highpass,float lowpass,int type);
      // fourier filters an image, real or imaginary
void makeAverage(List *in,EMData *sigma=NULL);
      // averages the images in the list, result in 'this'
      // optionally makes a sigma image as well

void makeAverageIter(List *in);

void makeAverageCTFC(List *in,float filtr);
// averages the images in the list with CTF correction
// filtr is in angstroms,

void makeMedian(List *in);
// Median of the images in the list, result in 'this'

void add(EMData *in); // adds 'in' to 'this'

void addIncoherent(EMData *in); // adds 'in' to 'this'

void mult(EMData *in); // multiplies 'in' by 'this'

void multConst(float const); // multiply by constant

void medianShrink(int i); // reduces the size of the image by a factor of i
// using a local median filter

void commonLines(EMData *d1,EMData *d2,int mode=0);
    // finds common lines between 2 complex images
    // mode 0 is a summed dot-product
    // mode 1 is weighted phase residual

EMData *project3d(float alt,float az, float phi, int mode);
    // makes a 3d projection of a volume, mode=-1 does real space
    // projection, 1-5 use fftslice for fourier projection
    // see EMData.h for other important notes

EMData *fftSlice(float alt,float az,float phi,int mode=5);
// takes a slice from a 3d complex image
// for generating projections
// Supplementary functions for fftSlice
void setup4Slice(int redo=1);
void interpFT3d(float x,float y,float z,float *ret,int mode);

// this initializes a new image to receive 'insertSlice' operations
// for fourier volume inversion. If the image has a parent, it will also
// be affected. WARNING: will use 8*size^3 bytes of memory.
void setup4IS(int size);

// This will try to make sure the slice is normalized properly
float normSlice(EMData *slice,float alt,float az,float phi,float *phaseresid=NULL);

// this inserts a complex slice into an image that has been setup4IS()
void insertSlice(EMData *slice, float alt,float az,float phi,int mode=5,float weight=1.0);

// once all of the slices have been added with insertSlice(), this routine
// does a normalization and returns a real 3d volume
void doneSlice();

float *ctfCurve(int type=0); // calculates a CTF curve
float *getCTF();
void setCTF(float *c);

void subNoise();

// This does an IFT of a volume reconstructed from slices. Includes a
// real-space correction for the linear interpolation in Fourier space
EMData *iftSlice();

Last modified 9/28/98

File IO
int readImage(char *filespec, int n,int nodata=0)	Reads a single image from a file (any format)
int fileCount(char *filespec)	NOT a member function. Counts # images in a file.
List readImages(char filespec,int n0,int n1,int nodata=0)	NOT a member function. Reads multiple images. Returns a List of EMData objects (which may be empty in case of error)
int readIMAGIC(char filespec, int n,int nodata=0) int writeIMAGIC(char filespec, int n)	These routines are responsible for reading & writing the individual image formats. They are usually called indirectly by readImage() or readImages(). The PGM reading routine reads GIFs, TIFFs, etc. as well as PBMs.
int readIMAGIC3d(char *filespec,int nodata=0)
int readMRC(char filespec,int nodata=0) int writeMRC(char filespec)
int readSPIDER(char filespec,int nodata=0) int writeSPIDER(char filespec)
int readSAL(char *filespec,int nodata=0)
int readPGM(char filespec,int nodata=0) int writePGM(char filespec,float gmin,float gmax)
int readEMIM(char filespec, int n,int nodata=0) int writeEMIM(char filespec, int n)
Information
char Name() void setName(char name)	Returns/sets the name of the image
EMData Parent() void setParent(EMData data)	Returns/sets the name of the image
char Path() void setPath(char path)	Returns/sets the path the image was read from
int xSize() int ySize() int zSize() int setSize(int x,int y, int z)	Returns/sets the size of the image in pixels
float Dx() float Dy() float Dz() void setTAlign(float dx,float dy,float dz)	Returns/sets the translation of the current image
float alt() float az() float phi() void setRAlign(float alt,float az,float phi)	Returns/sets the orientation of the current image. Use alt for in-plane rotation of images
Euler *getEuler()	Returns a pointer to the Euler object which stores orientation
int NImg() void setNImg(int n)	Returns/sets the number of images used to generate this image
int getFlags()	Raw access to the image flags. See EMData.h
int isComplex()	Returns true if the image is complex
int hasCTF() float getCTF() void setCTF(float c) float *ctfCurve(int type=0)	Functions dealing with the Contrast Transfer Function parameters. Used to perform corrections


Statistical
void update()	Called when something in the image changes. getData/doneData automatically calls this.
float Min() float Max() float Mean() float Sigma()	Standard statistical functions
float edgeMean()	Returns the mean value around the edge of the image
Simple Image Processing
EMData *copy()	Returns a copy of an image
EMData *copyHead()	Returns a new image with the same header as the current image
EMData clip(int x0,int y0,int w,int h) EMData clip(int x0,int y0,int z0,int w,int h,int d)	Returns a new image which contains a portion of the current image. New image will be zero padded if larger than original
void zero() void one()	Fills the entire image with 0 or 1
void rotateAndTranslate(float scale=1.0,float dxc=0,float dyc=0,float dzc=0)	This routine performs actual rotation/translation after shift/rotation has been set with setTAlign/setRAlign. NOTE: If this image has a 'parent', the parent is rotated/translated instead of the current image. Used to prevent multiple interpolations.
float transAlign(EMData with,int useparent=0,int intonly=0) float transAlign3d(EMData with,int useparent=0,int intonly=0)	Calculates translational alignment of 2 images. Result is set in dx and dy, but rotateAndTranslate is not called.
float rotAlign(EMData with) float rotAlignTI(EMData with,int usedot=0)	Calculates rotational alignment of 2 images. rotAlignTI calculates translationally independant rotational alignment with 180 degree ambiguity. Result stored to Euler of current image.
EMData RTAlign(EMData with,int usedot=0) EMData RTFAlign(EMData with,EMData flip=NULL,int usedot=0) void refineAlign(EMData with,int usedot)	Returns a new image which is rotationally/translationally aligned to 'with'. RTFAlign also allows flips. refineAlign may be called immediately after this to 'fine tune' the alignment.
void cmCenter()	Set dx/dy to center the image (center of mass, positive values only)
void applyMask(int r,int type)	Masks the image at a given radius. Several different modes, see EMData.C for details




Fourier Processing
EMData doFFT() EMData doIFT() void gimmeFFT()	Returns a new image which is the FFT or IFT of the current image. New image is 'owned' by current image unless gimmeFFT() is called after this call. Radix 19 FFTs.
void ri2ap() void ap2ri()	Changes the representation of a complex image from real/imaginary to/from amplitude/phase. Ok to call even if representation would be unchanged
EMData calcCCF(EMData with)	Returns a new image which is the cross correlation of the current image and 'with'. Source images may be real or complex.
void calcRCF(EMData with,float sum,int NS)	Calculates an azimuthal cross correlation function between 2 images. Used for rotational alignments
EMData *makeRFP()	Generates a 'rotational footprint' for the current image. This is a new image wh


2d <-> 3d
EMData *project3d(float alt,float az, float phi, int mode)	Generates a projection of a 3d volume
void setup4Slice(int redo=1) EMData *fftSlice(float alt,float az,float phi,int mode=5)	Cuts a slice from a 3d Fourier volume. Call setup4Slice once before cutting slices.
void setup4IS(int size) float normSlice(EMData slice,float alt,float az,float phi,float phaseresid=NULL) void insertSlice(EMData *slice, float alt,float az,float phi,int mode=5,float weight=1.0) void doneSlice()	These routines allow a 3d volume to be reconstructed from a set of slices. See make3d.C for details.
float Pixel() void setPixel(float pix)	Returns/sets angstroms/pixel



Parallelization & Raw Data Access
long getATime()	Last time the data set was accessed
float *getDataRO()	Gets a pointer to the raw data for shared read-only access. Read only is NOT enforced, but should be observed. Waits if image is busy.
float *getData()	Gets a pointer to the raw data for exclusive read/write access. update() called automatically when released.
void doneData()	ALWAYS call once for each getData() or getDataRO()
int Busy() int waitReady(int ro) void Wait()	Used by the above to ensure legal access



Undocumented
void interpFT3d(float x,float y,float z,float *ret,int mode)
void setComplex(int i) void setRI(int i)
void calcHist(float hmin,float hmax) float *getHist() float histMin() float histMax() void realCalcHist()
void setFlipped(int f)
void setPathN(int n)
int swapout() int swapin()
void doDWT(int basis, int level) void doIWT(int basis, int level) void DWTFilt(int basis, int level, float thresh)
void rotateAndTranslateFast(float scale=1.0)