EMAN2
mrcio.h
Go to the documentation of this file.
00001 
00005 /*
00006  * Author: Steven Ludtke, 04/10/2003 (sludtke@bcm.edu)
00007  * Copyright (c) 2000-2006 Baylor College of Medicine
00008  * 
00009  * This software is issued under a joint BSD/GNU license. You may use the
00010  * source code in this file under either license. However, note that the
00011  * complete EMAN2 and SPARX software packages have some GPL dependencies,
00012  * so you are responsible for compliance with the licenses of these packages
00013  * if you opt to use BSD licensing. The warranty disclaimer below holds
00014  * in either instance.
00015  * 
00016  * This complete copyright notice must be included in any revised version of the
00017  * source code. Additional authorship citations may be added, but existing
00018  * author citations must be preserved.
00019  * 
00020  * This program is free software; you can redistribute it and/or modify
00021  * it under the terms of the GNU General Public License as published by
00022  * the Free Software Foundation; either version 2 of the License, or
00023  * (at your option) any later version.
00024  * 
00025  * This program is distributed in the hope that it will be useful,
00026  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00027  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
00028  * GNU General Public License for more details.
00029  * 
00030  * You should have received a copy of the GNU General Public License
00031  * along with this program; if not, write to the Free Software
00032  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
00033  * 
00034  * */
00035 
00036 #ifndef eman__mrcio_h__
00037 #define eman__mrcio_h__ 1
00038 
00039 #include "imageio.h"
00040 
00041 namespace EMAN
00042 {
00048         class MrcIO:public ImageIO
00049         {
00050         public:
00051                 explicit MrcIO(const string & filename, IOMode rw_mode = READ_ONLY);
00052                 ~MrcIO();
00053 
00054                 DEFINE_IMAGEIO_FUNC;
00055 
00056                 int read_ctf(Ctf & ctf, int image_index = 0);
00057                 void write_ctf(const Ctf & ctf, int image_index = 0);
00058 
00059                 static bool is_valid(const void *first_block, off_t file_size = 0);
00060                 static int get_mode_size(int mm);
00061                 static int to_em_datatype(int mrcmode);
00062                 static int to_mrcmode(int em_datatype, int is_complex);
00063 
00064                 int get_nimg();
00065 
00066         private:
00067                 enum MrcMode {
00068                         MRC_UCHAR = 0,
00069                         MRC_SHORT,
00070                         MRC_FLOAT,
00071                         MRC_SHORT_COMPLEX,
00072                         MRC_FLOAT_COMPLEX,
00073                         MRC_USHORT = 6,         //non-standard
00074                         MRC_UCHAR3 = 16,        //unsigned char * 3, for rgb data, non-standard
00075                         MRC_CHAR,
00076                         MRC_UNKNOWN
00077                 };
00078 
00079                 enum {
00080                         MRC_NUM_LABELS = 10,
00081                         MRC_LABEL_SIZE = 80,
00082                         NUM_4BYTES_PRE_MAP = 52,
00083                         NUM_4BYTES_AFTER_MAP = 3
00084                 };
00085 
00086                 /* updated to MRC Image2000 format which is compatible with CCP4 format */
00087                 struct MrcHeader
00088                 {
00089                         int nx;                         /* number of columns */
00090                         int ny;                         /* number of rows */
00091                         int nz;                         /* number of sections */
00092 
00093                         int mode;                       /* See modes above. */
00094 
00095                         int nxstart;            /* No. of first column in map, default 0. */
00096                         int nystart;            /* No. of first row in map, default 0. */
00097                         int nzstart;            /* No. of first section in map,default 0. */
00098 
00099                         int mx;                         /* Number of intervals along X. */
00100                         int my;                         /* Number of intervals along Y. */
00101                         int mz;                         /* Number of intervals along Z. */
00102 
00103                         /* Cell: treat a whole 2D image as a cell */
00104                         float xlen;                     /* Cell dimensions (Angstroms). */
00105                         float ylen;                     /* Cell dimensions (Angstroms). */
00106                         float zlen;                     /* Cell dimensions (Angstroms). */
00107 
00108                         float alpha;            /* Cell angles (Degrees). */
00109                         float beta;                     /* Cell angles (Degrees). */
00110                         float gamma;            /* Cell angles (Degrees). */
00111 
00112                         /* axis X => 1, Y => 2, Z => 3 */
00113                         int mapc;                       /* Which axis corresponds to Columns.  */
00114                         int mapr;                       /* Which axis corresponds to Rows.     */
00115                         int maps;                       /* Which axis corresponds to Sections. */
00116 
00117                         float amin;                     /* Minimum density value. */
00118                         float amax;                     /* Maximum density value. */
00119                         float amean;            /* Mean density value.    */
00120 
00121                         int ispg;                       /* Space group number (0 for images). */
00122 
00123                         int nsymbt;                     /* Number of chars used for storing symmetry operators. */
00124 
00125                         int user[25];
00126 
00127                         float xorigin;          /* X origin. */
00128                         float yorigin;          /* Y origin. */
00129                         float zorigin;          /* Z origin. */
00130 
00131                         char map[4];            /* constant string "MAP "  */
00132                         int machinestamp;       /* machine stamp in CCP4 convention:
00133                                                                    big endian=0x11110000 little endian=0x44440000 */
00134                                                 /* There is an ambiguity in the specification, using 0x11111111 & 4 instead */
00135 
00136                         float rms;                      /* rms deviation of map from mean density */
00137 
00138                         int nlabels;            /* Number of labels being used. */
00139                         char labels[MRC_NUM_LABELS][MRC_LABEL_SIZE];
00140                 };
00141 
00154                 struct FeiMrcHeader
00155                 {
00156                         int nx;                         /* The number of pixels in the x direction of the image */
00157                         int ny;                         /* The number of pixels in the y direction of the image */
00158                         int nz;                         /* The number of pixels in the z direction of the image
00159                                                                  Effectively in the tomography tilt series this means the
00160                                                                  number of images in the tilt series. */
00161 
00162                         int mode;                       /* Defines the data type. Should always be 1 (2-byte integer)
00163                                                                  in the case of tomography*/
00164 
00165                         int nxstart;            /* set to 0: not used; lower bound of columns */
00166                         int nystart;            /* set to 0: not used; lower bound of rows */
00167                         int nzstart;            /* set to 0: not used; lower bound of sections */
00168 
00169                         int mx;                         /* set to nx: not used; grid size x */
00170                         int my;                         /* set to ny: not used; grid size y */
00171                         int mz;                         /* set to nz: not used; grid size z */
00172 
00173                         float xlen;                     /* set to mx: not used; cell size in x Angstroms (pixel spacing=3Dxlen/mx) */
00174                         float ylen;                     /* set to mx: not used; cell size in y Angstroms (pixel spacing=3Dxlen/my) */
00175                         float zlen;                     /* set to mx: not used; cell size in z Angstroms (pixel spacing=3Dxlen/mz) */
00176 
00177                         float alpha;            /* set to 90: not used; cell angles in degrees */
00178                         float beta;                     /* set to 90: not used; cell angles in degrees */
00179                         float gamma;            /* set to 90: not used; cell angles in degrees */
00180 
00181                         /* axis X => 1, Y => 2, Z => 3 */
00182                         int mapc;                       /* set to 1: not used; mapping columns, rows, sections on axis (x=3D1, y=3D2, z=3D3) */
00183                         int mapr;                       /* set to 2: not used; mapping columns, rows, sections on axis (x=3D1, y=3D2, z=3D3)     */
00184                         int maps;                       /* set to 3: not used; mapping columns, rows, sections on axis (x=3D1, y=3D2, z=3D3) */
00185 
00186                         float amin;                     /* minimum pixel value of all images in file */
00187                         float amax;                     /* maximum pixel value of all images in file */
00188                         float amean;            /* mean pixel value of all images in file */
00189 
00190                         short ispg;                     /* set to 0: not used; space group number (0 for images) */
00191 
00192                         short nsymbt;                   /* set to 0: not used; number of bytes used for storing symmetry operators */
00193 
00194                         int     next;                   /* This value gives the offset (in bytes) from the end
00195                                                                 of the file header to the first dataset (image).
00196                                                                 Thus you will find the first image at 1024 + next bytes. */
00197                         short dvid;                     /* set to 0: not used; creator id */
00198                         char extra[30];         /* set to 0: not used, extra 30 bytes data */
00199                         short numintegers;      /* set to 0: not used */
00200                         short numfloats;        /* set to 32; we always expect a extended header of 32 floats */
00201 
00202                         short sub;
00203                         short zfac;
00204                         float min2;
00205                         float max2;
00206                         float min3;
00207                         float max3;
00208                         float min4;
00209                         float max4;
00210                         short idtype;
00211                         short lens;
00212                         short nd1;
00213                         short nd2;
00214                         short vd1;
00215                         short vd2;
00216                         float tiltangles[9];    /* set to 0; not used; used to rotate model to match rotated image */
00217 
00218                         float zorg;                     /* set to 0: not used; origin of image */
00219                         float xorg;
00220                         float yorg;
00221 
00222                         int nlabl;                      /* number of labels */
00223                         char labl[MRC_NUM_LABELS][MRC_LABEL_SIZE];      /* Arrays of characters that can be used for description.
00224                                                                                                                          Label0 is used for copyright information, always start with "Fei"*/
00225                 };
00226 
00231                 struct FeiMrcExtHeader
00232                 {
00233                         float a_tilt;           /* Alpha tilt, in degrees */
00234                         float b_tilt;           /* beta tilt, in degrees */
00235 
00236                         float x_stage;          /* Stage x position. Normally in SI units (meters), but some older files may be
00237                                                                  in micrometers. Check by looking at values for x,y,z. If one of these exceeds 1,
00238                                                                  it will be micrometers. */
00239                         float y_stage;          /* Stage y position. For testing of units see x_stage */
00240                         float z_stage;          /* Stage z position. For testing of units see x_stage */
00241 
00242                         float x_shift;          /* Image shift x. For testing of units see x_stage */
00243                         float y_shift;          /* Image shift y. For testing of units see x_stage */
00244 
00245                         float defocus;          /* Defocus as read from microscope. For testing of units see x_stage */
00246                         float exp_time;         /* Exposure time in seconds */
00247                         float mean_int;         /* Mean value of image */
00248 
00249                         float tilt_axis;        /* The orientation of the tilt axis in the image in degrees.
00250                                                                  Vertical to the top is 0=B0, the direction of positive rotation is anti-clockwise */
00251                         float pixel_size;       /* The pixel size of the images in SI units (meters) */
00252                         float magnification;    /*The magnification used in SI units (volts) */
00253                         float ht;                       /* Value of the high tension in SI units (volts) */
00254                         float binning;          /* The binning of the CCD or STEM acquisition */
00255                         float appliedDefocus;   /* The intended application defocus in SI units (meters),
00256                                                                  as defined for example in the tomography parameters view. */
00257 
00258                         float remainder[16];    /* not used */
00259                 };
00260 
00261                 static const char *CTF_MAGIC;
00262                 static const char *SHORT_CTF_MAGIC;
00263 
00264         private:
00265                 string filename;
00266                 IOMode rw_mode;
00267                 FILE *mrcfile;
00268                 int mode_size;
00269 
00270                 union {
00271                         MrcHeader mrch;
00272                         FeiMrcHeader feimrch;
00273                 };
00274 
00275                 /* the extended MRC format for tomography, used by FEI */
00276                 bool isFEI;
00277 
00278                 /* for MRCS (MRC stack) format */
00279                 bool is_stack;
00280                 int stack_size;
00281 
00282                 int is_ri;
00283                 bool is_big_endian;
00284                 bool is_new_file;
00285                 bool initialized;
00286                 bool is_transpose;
00287                 
00289                 static int generate_machine_stamp();
00290                 void swap_header(MrcHeader& mrch);
00291                 
00296                 void update_stats(void* data, size_t size);
00297 
00298                 int read_mrc_header(Dict & dict, int image_index = 0, const Region * area = 0, bool is_3d = false);
00299                 int read_fei_header(Dict & dict, int image_index = 0, const Region * area = 0, bool is_3d = false);
00300 
00301                 //utility funciton to tranpose x and y dimension in case the source mrc image is mapc=2,mapr=1
00302                 int transpose(float *data, int nx, int ny, int nz) const;
00303         };
00304 }
00305 
00306 #endif  //eman__mrcio_h__