Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members

cmp.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_cmp__h__
00037 #define eman_cmp__h__ 1
00038 
00039 
00040 #include "emobject.h"
00041 
00042 namespace EMAN
00043 {
00044 
00045         class EMData;
00085         class Cmp
00086         {
00087           public:
00088                 virtual ~ Cmp()
00089                 {
00090                 }
00091 
00100                 virtual float cmp(EMData * image, EMData * with) const = 0;
00101 
00105                 virtual string get_name() const = 0;
00106 
00107                 virtual string get_desc() const = 0;
00108 
00112                 virtual Dict get_params() const
00113                 {
00114                         return params;
00115                 }
00116 
00120                 virtual void set_params(const Dict & new_params)
00121                 {
00122                         params = new_params;
00123                 }
00124 
00131                 virtual TypeDict get_param_types() const = 0;
00132 
00133         protected:
00134                 void validate_input_args(const EMData * image, const EMData *with) const;
00135 
00136                 mutable Dict params;
00137         };
00138 
00155         class CccCmp:public Cmp
00156         {
00157           public:
00158                 float cmp(EMData * image, EMData * with) const;
00159 
00160                 string get_name() const
00161                 {
00162                         return NAME;
00163                 }
00164 
00165                 string get_desc() const
00166                 {
00167                         return "Cross-correlation coefficient (default -1 * ccc)";
00168                 }
00169 
00170                 static Cmp *NEW()
00171                 {
00172                         return new CccCmp();
00173                 }
00174 
00175                 //param mask Image mask
00176                 TypeDict get_param_types() const
00177                 {
00178                         TypeDict d;
00179                         d.put("negative", EMObject::INT, "If set, returns -1 * ccc product. Set by default so smaller is better");
00180                         d.put("mask", EMObject::EMDATA, "image mask");
00181                         return d;
00182                 }
00183 
00184                 static const string NAME;
00185         };
00186 
00187 
00188         /* Compues the L^1 difference, after normalization.*/
00189         class LodCmp:public Cmp
00190         {
00191           public:
00192                 float cmp(EMData * image, EMData * with) const;
00193 
00194                 string get_name() const
00195                 {
00196                         return NAME;
00197                 }
00198 
00199                 string get_desc() const
00200                 {
00201                         return "L^1 normalized difference (positive by default)";
00202                 }
00203 
00204                 static Cmp *NEW()
00205                 {
00206                         return new LodCmp();
00207                 }
00208 
00209                 //param mask Image mask
00210                 TypeDict get_param_types() const
00211                 {
00212                         TypeDict d;
00213                         d.put("negative", EMObject::INT, "If set (which is the default), returns Lod. (The smaller the better)");
00214                         d.put("normalize", EMObject::INT, "If set, normalizes maps prior to computing the difference. Default=0 (no normalization)");
00215                         d.put("mask", EMObject::EMDATA, "image mask");
00216                         return d;
00217                 }
00218 
00219                 static const string NAME;
00220         };
00221 
00222 
00224         //  I corrected this as there is no such thing as "variance between two images"
00225         //  I corrected naive coding to avoid square
00226         //  Also, the equation in return statement was incorrect, grrrr!!!
00227         //  Finally, I added mask option  PAP 04/23/06
00228         class SqEuclideanCmp:public Cmp
00229         {
00230           public:
00231                 SqEuclideanCmp() {}
00232 
00233                 float cmp(EMData * image, EMData * with) const;
00234 
00235                 string get_name() const
00236                 {
00237                         return NAME;
00238                 }
00239 
00240                 string get_desc() const
00241                 {
00242                         return "Squared Euclidean distance (sum(a - b)^2)/n.";
00243                 }
00244 
00245                 static Cmp *NEW()
00246                 {
00247                         return new SqEuclideanCmp();
00248                 }
00249 
00250                 TypeDict get_param_types() const
00251                 {
00252                         TypeDict d;
00253                         d.put("mask", EMObject::EMDATA, "image mask");
00254                         d.put("zeromask", EMObject::INT, "If set, zero pixels in either image will be excluded from the statistics");
00255                         d.put("normto",EMObject::INT,"If set, 'with' is normalized to 'this' before computing the distance");
00256                         return d;
00257                 }
00258 
00259                 static const string NAME;
00260         };
00261 
00262 
00270         class DotCmp:public Cmp
00271         {
00272           public:
00273                 float cmp(EMData * image, EMData * with) const;
00274 
00275                 string get_name() const
00276                 {
00277                         return NAME;
00278                 }
00279 
00280                 string get_desc() const
00281                 {
00282                         return "Dot product (default -1 * dot product)";
00283                 }
00284 
00285                 static Cmp *NEW()
00286                 {
00287                         return new DotCmp();
00288                 }
00289 
00290                 TypeDict get_param_types() const
00291                 {
00292                         TypeDict d;
00293                         d.put("negative", EMObject::INT, "If set, returns -1 * dot product. Set by default so smaller is better");
00294                         d.put("normalize", EMObject::INT, "If set, returns normalized dot product (cosine of the angle) -1.0 - 1.0.");
00295                         d.put("mask", EMObject::EMDATA, "image mask");
00296                         return d;
00297                 }
00298                 
00299                 static const string NAME;
00300         };
00301 
00314         class TomoCccCmp:public Cmp
00315         {
00316           public:
00317                 virtual float cmp(EMData * image, EMData * with) const;
00318 
00319                 virtual string get_name() const 
00320                 {
00321                         return NAME;
00322                 }
00323 
00324                 virtual string get_desc() const
00325                 {
00326                         return "Ccc with consideration given for the missing wedge";
00327                 }
00328 
00329                 static Cmp *NEW()
00330                 {
00331                         return new TomoCccCmp();
00332                 }
00333 
00334                 TypeDict get_param_types() const
00335                 {
00336                         TypeDict d;
00337                         d.put("norm", EMObject::BOOL,"Whether the cross correlation image should be normalized (should be for normalized images). Default is true.");
00338                         d.put("ccf", EMObject::EMDATA,"The ccf image, can be provided if it already exists to avoid recalculating it");
00339                         d.put("searchx", EMObject::INT, "The maximum range of the peak location in the x direction. Default is sizex/4");
00340                         d.put("searchy", EMObject::INT, "The maximum range of the peak location in the y direction. Default is sizey/4");
00341                         d.put("searchz", EMObject::INT, "The maximum range of the peak location in the z direction. Default is sizez/4");
00342                         d.put("zeroori", EMObject::FLOAT,"When using the ccc.tomo aligner, use the peak at origin (use only with refine3D aligner).");
00343                         return d;
00344                 }
00345                 
00346                 static const string NAME;
00347         };
00348 
00356         class QuadMinDotCmp:public Cmp
00357         {
00358           public:
00359                 float cmp(EMData * image, EMData * with) const;
00360 
00361                 string get_name() const
00362                 {
00363                         return NAME;
00364                 }
00365 
00366                 string get_desc() const
00367                 {
00368                         return "Caclultes dot product for each quadrant and returns worst value (default -1 * dot product)";
00369                 }
00370 
00371                 static Cmp *NEW()
00372                 {
00373                         return new QuadMinDotCmp();
00374                 }
00375 
00376                 TypeDict get_param_types() const
00377                 {
00378                         TypeDict d;
00379                         d.put("negative", EMObject::INT, "If set, returns -1 * dot product. Default = true (smaller is better)");
00380                         d.put("normalize", EMObject::INT, "If set, returns normalized dot product -1.0 - 1.0.");
00381                         return d;
00382                 }
00383                 
00384                 static const string NAME;
00385         };
00386 
00387 
00400         class OptVarianceCmp:public Cmp
00401         {
00402           public:
00403                 OptVarianceCmp() : scale(0), shift(0) {}
00404 
00405                 float cmp(EMData * image, EMData * with) const;
00406 
00407                 string get_name() const
00408                 {
00409                         return NAME;
00410                 }
00411 
00412                 string get_desc() const
00413                 {
00414                         return "Real-space variance after density optimization, self should be noisy and target less noisy. Linear transform applied to density to minimize variance.";
00415                 }
00416 
00417                 static Cmp *NEW()
00418                 {
00419                         return new OptVarianceCmp();
00420                 }
00421 
00422                 TypeDict get_param_types() const
00423                 {
00424                         TypeDict d;
00425                         d.put("invert", EMObject::INT, "If set, 'with' is rescaled rather than 'this'. 'this' should still be the noisier image. (default=0)");
00426                         d.put("keepzero", EMObject::INT, "If set, zero pixels will not be adjusted in the linear density optimization. (default=1)");
00427                         d.put("matchfilt", EMObject::INT, "If set, with will be filtered so its radial power spectrum matches 'this' before density optimization of this. (default=1)");
00428                         d.put("matchamp", EMObject::INT, "Takes per-pixel Fourier amplitudes from self and imposes them on the target, but leaves the phases alone. (default=0)");
00429                         d.put("radweight", EMObject::INT, "Upweight variances closer to the edge of the image. (default=0)");
00430                         d.put("debug", EMObject::INT, "Performs various debugging actions if set.");
00431                         return d;
00432                 }
00433 
00434                 float get_scale() const
00435                 {
00436                         return scale;
00437                 }
00438 
00439                 float get_shift() const
00440                 {
00441                         return shift;
00442                 }
00443                 
00444                 static const string NAME;
00445 
00446         private:
00447                 mutable float scale;
00448                 mutable float shift;
00449         };
00460         class PhaseCmp:public Cmp
00461         {
00462           public:
00463                 float cmp(EMData * image, EMData * with) const;
00464 
00465                 string get_name() const
00466                 {
00467                         return NAME;
00468                 }
00469 
00470                 string get_desc() const
00471                 {
00472                         return "Mean phase difference";
00473                 }
00474 
00475                 static Cmp *NEW()
00476                 {
00477                         return new PhaseCmp();
00478                 }
00479 
00480                 TypeDict get_param_types() const
00481                 {
00482                         TypeDict d;
00483                         d.put("snrweight", EMObject::INT, "If set, the SNR of 'this' will be used to weight the result. If 'this' lacks CTF info, it will check 'with'. (default=0)");
00484                         d.put("snrfn", EMObject::INT, "If nonzero, an empirical function will be used as a radial weight rather than the true SNR. (1 - exp decay)'. (default=0)");
00485                         d.put("ampweight", EMObject::INT, "If set, the amplitude of 'with' will be used as a weight in the averaging'. (default=0)");
00486                         d.put("zeromask", EMObject::INT, "Treat regions in either image that are zero as a mask");
00487                         d.put("minres", EMObject::FLOAT, "Lowest resolution to use in comparison (soft cutoff). Requires accurate A/pix in image. <0 disables. Default=500");
00488                         d.put("maxres", EMObject::FLOAT, "Highest resolution to use in comparison (soft cutoff). Requires accurate A/pix in image. <0 disables.  Default=10");
00489                         return d;
00490                 }
00491                 
00492                 static const string NAME;
00493 
00494 #ifdef EMAN2_USING_CUDA
00495                  float cuda_cmp(EMData * image, EMData *with) const;
00496 #endif //EMAN2_USING_CUDA
00497         };
00498 
00505         class FRCCmp:public Cmp
00506         {
00507           public:
00508                 float cmp(EMData * image, EMData * with) const;
00509 
00510                 string get_name() const
00511                 {
00512                         return NAME;
00513                 }
00514 
00515                 string get_desc() const
00516                 {
00517                         return "Computes the mean Fourier Ring Correlation between the image and reference (with optional weighting factors).";
00518                 }
00519 
00520                 static Cmp *NEW()
00521                 {
00522                         return new FRCCmp();
00523                 }
00524 
00525                 TypeDict get_param_types() const
00526                 {
00527                         TypeDict d;
00528                         d.put("snrweight", EMObject::INT, "If set, the SNR of 'this' will be used to weight the result. If 'this' lacks CTF info, it will check 'with'. (default=0)");
00529                         d.put("ampweight", EMObject::INT, "If set, the amplitude of 'this' will be used to weight the result (default=0)");
00530                         d.put("sweight", EMObject::INT, "If set, weight the (1-D) average by the number of pixels in each ring (default=1)");
00531                         d.put("nweight", EMObject::INT, "Downweight similarity based on number of particles in reference (default=0)");
00532                         d.put("zeromask", EMObject::INT, "Treat regions in either image that are zero as a mask");
00533                         d.put("minres", EMObject::FLOAT, "Lowest resolution to use in comparison (soft cutoff). Requires accurate A/pix in image. <0 disables. Default=500");
00534                         d.put("maxres", EMObject::FLOAT, "Highest resolution to use in comparison (soft cutoff). Requires accurate A/pix in image. <0 disables.  Default=10");
00535                         return d;
00536                 }
00537                 
00538                 static const string NAME;
00539         };
00540 
00541         template <> Factory < Cmp >::Factory();
00542 
00543         void dump_cmps();
00544         map<string, vector<string> > dump_cmps_list();
00545 }
00546 
00547 
00548 #endif
00549 
00550 /* vim: set ts=4 noet: */

Generated on Thu Dec 9 13:45:44 2010 for EMAN2 by  doxygen 1.3.9.1