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 
00188         //  I corrected this as there is no such thing as "variance between two images"
00189         //  I corrected naive coding to avoid square
00190         //  Also, the equation in return statement was incorrect, grrrr!!!
00191         //  Finally, I added mask option  PAP 04/23/06
00192         class SqEuclideanCmp:public Cmp
00193         {
00194           public:
00195                 SqEuclideanCmp() {}
00196 
00197                 float cmp(EMData * image, EMData * with) const;
00198 
00199                 string get_name() const
00200                 {
00201                         return NAME;
00202                 }
00203 
00204                 string get_desc() const
00205                 {
00206                         return "Squared Euclidean distance (sum(a - b)^2)/n.";
00207                 }
00208 
00209                 static Cmp *NEW()
00210                 {
00211                         return new SqEuclideanCmp();
00212                 }
00213 
00214                 TypeDict get_param_types() const
00215                 {
00216                         TypeDict d;
00217                         d.put("mask", EMObject::EMDATA, "image mask");
00218                         d.put("zeromask", EMObject::INT, "If set, zero pixels in either image will be excluded from the statistics");
00219                         d.put("normto",EMObject::INT,"If set, 'with' is normalized to 'this' before computing the distance");
00220                         return d;
00221                 }
00222 
00223                 static const string NAME;
00224         };
00225 
00226 
00234         class DotCmp:public Cmp
00235         {
00236           public:
00237                 float cmp(EMData * image, EMData * with) const;
00238 
00239                 string get_name() const
00240                 {
00241                         return NAME;
00242                 }
00243 
00244                 string get_desc() const
00245                 {
00246                         return "Dot product (default -1 * dot product)";
00247                 }
00248 
00249                 static Cmp *NEW()
00250                 {
00251                         return new DotCmp();
00252                 }
00253 
00254                 TypeDict get_param_types() const
00255                 {
00256                         TypeDict d;
00257                         d.put("negative", EMObject::INT, "If set, returns -1 * dot product. Set by default so smaller is better");
00258                         d.put("normalize", EMObject::INT, "If set, returns normalized dot product (cosine of the angle) -1.0 - 1.0.");
00259                         d.put("mask", EMObject::EMDATA, "image mask");
00260                         return d;
00261                 }
00262                 
00263                 static const string NAME;
00264         };
00265 
00271         class TomoDotCmp:public Cmp
00272         {
00273           public:
00274                 virtual float cmp(EMData * image, EMData * with) const;
00275 
00276                 virtual string get_name() const
00277                 {
00278                         return NAME;
00279                 }
00280 
00281                 virtual string get_desc() const
00282                 {
00283                         return "straight dot product with consideration given for the missing wedge - normalization is applied by detecting significantly large Fourier amplitudes in the cross correlation image";
00284                 }
00285 
00286                 static Cmp *NEW()
00287                 {
00288                         return new TomoDotCmp();
00289                 }
00290 
00291                 TypeDict get_param_types() const
00292                 {
00293                         TypeDict d;
00294                         d.put("threshold", EMObject::FLOAT,"Threshold applied to the Fourier amplitudes of the ccf image - helps to correct for the missing wedge.");
00295                         d.put("norm", EMObject::BOOL,"Whether the cross correlation image should be normalized. Default is false.");
00296                         d.put("ccf", EMObject::EMDATA,"The ccf image, can be provided if it already exists to avoid recalculating it");
00297                         d.put("tx", EMObject::INT, "The x location of the maximum in the ccf image. May be negative. Useful thing to supply if you know the maximum is not at the phase origin");
00298                         d.put("ty", EMObject::INT, "The y location of the maximum in the ccf image. May be negative. Useful thing to supply if you know the maximum is not at the phase origin");
00299                         d.put("tz", EMObject::INT, "The z location of the maximum in the ccf image. May be negative. Useful thing to supply if you know the maximum is not at the phase origin");
00300 
00301                         return d;
00302                 }
00303                 
00304                 static const string NAME;
00305         };
00306 
00314         class QuadMinDotCmp:public Cmp
00315         {
00316           public:
00317                 float cmp(EMData * image, EMData * with) const;
00318 
00319                 string get_name() const
00320                 {
00321                         return NAME;
00322                 }
00323 
00324                 string get_desc() const
00325                 {
00326                         return "Caclultes dot product for each quadrant and returns worst value (default -1 * dot product)";
00327                 }
00328 
00329                 static Cmp *NEW()
00330                 {
00331                         return new QuadMinDotCmp();
00332                 }
00333 
00334                 TypeDict get_param_types() const
00335                 {
00336                         TypeDict d;
00337                         d.put("negative", EMObject::INT, "If set, returns -1 * dot product. Default = true (smaller is better)");
00338                         d.put("normalize", EMObject::INT, "If set, returns normalized dot product -1.0 - 1.0.");
00339                         return d;
00340                 }
00341                 
00342                 static const string NAME;
00343         };
00344 
00345 
00358         class OptVarianceCmp:public Cmp
00359         {
00360           public:
00361                 OptVarianceCmp() : scale(0), shift(0) {}
00362 
00363                 float cmp(EMData * image, EMData * with) const;
00364 
00365                 string get_name() const
00366                 {
00367                         return NAME;
00368                 }
00369 
00370                 string get_desc() const
00371                 {
00372                         return "Real-space variance after density optimization, self should be noisy and target less noisy. Linear transform applied to density to minimize variance.";
00373                 }
00374 
00375                 static Cmp *NEW()
00376                 {
00377                         return new OptVarianceCmp();
00378                 }
00379 
00380                 TypeDict get_param_types() const
00381                 {
00382                         TypeDict d;
00383                         d.put("invert", EMObject::INT, "If set, 'with' is rescaled rather than 'this'. 'this' should still be the noisier image. (default=0)");
00384                         d.put("keepzero", EMObject::INT, "If set, zero pixels will not be adjusted in the linear density optimization. (default=1)");
00385                         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)");
00386                         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)");
00387                         d.put("radweight", EMObject::INT, "Upweight variances closer to the edge of the image. (default=0)");
00388                         d.put("debug", EMObject::INT, "Performs various debugging actions if set.");
00389                         return d;
00390                 }
00391 
00392                 float get_scale() const
00393                 {
00394                         return scale;
00395                 }
00396 
00397                 float get_shift() const
00398                 {
00399                         return shift;
00400                 }
00401                 
00402                 static const string NAME;
00403 
00404         private:
00405                 mutable float scale;
00406                 mutable float shift;
00407         };
00418         class PhaseCmp:public Cmp
00419         {
00420           public:
00421                 float cmp(EMData * image, EMData * with) const;
00422 
00423                 string get_name() const
00424                 {
00425                         return NAME;
00426                 }
00427 
00428                 string get_desc() const
00429                 {
00430                         return "Mean phase difference";
00431                 }
00432 
00433                 static Cmp *NEW()
00434                 {
00435                         return new PhaseCmp();
00436                 }
00437 
00438                 TypeDict get_param_types() const
00439                 {
00440                         TypeDict d;
00441                         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)");
00442                         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)");
00443                         d.put("ampweight", EMObject::INT, "If set, the amplitude of 'with' will be used as a weight in the averaging'. (default=0)");
00444                         d.put("zeromask", EMObject::INT, "Treat regions in either image that are zero as a mask");
00445                         d.put("minres", EMObject::FLOAT, "Lowest resolution to use in comparison (soft cutoff). Requires accurate A/pix in image. <0 disables. Default=500");
00446                         d.put("maxres", EMObject::FLOAT, "Highest resolution to use in comparison (soft cutoff). Requires accurate A/pix in image. <0 disables.  Default=10");
00447                         return d;
00448                 }
00449                 
00450                 static const string NAME;
00451 
00452 #ifdef EMAN2_USING_CUDA
00453                  float cuda_cmp(EMData * image, EMData *with) const;
00454 #endif //EMAN2_USING_CUDA
00455         };
00456 
00463         class FRCCmp:public Cmp
00464         {
00465           public:
00466                 float cmp(EMData * image, EMData * with) const;
00467 
00468                 string get_name() const
00469                 {
00470                         return NAME;
00471                 }
00472 
00473                 string get_desc() const
00474                 {
00475                         return "Computes the mean Fourier Ring Correlation between the image and reference (with optional weighting factors).";
00476                 }
00477 
00478                 static Cmp *NEW()
00479                 {
00480                         return new FRCCmp();
00481                 }
00482 
00483                 TypeDict get_param_types() const
00484                 {
00485                         TypeDict d;
00486                         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)");
00487                         d.put("ampweight", EMObject::INT, "If set, the amplitude of 'this' will be used to weight the result (default=0)");
00488                         d.put("sweight", EMObject::INT, "If set, weight the (1-D) average by the number of pixels in each ring (default=1)");
00489                         d.put("nweight", EMObject::INT, "Downweight similarity based on number of particles in reference (default=0)");
00490                         d.put("zeromask", EMObject::INT, "Treat regions in either image that are zero as a mask");
00491                         d.put("minres", EMObject::FLOAT, "Lowest resolution to use in comparison (soft cutoff). Requires accurate A/pix in image. <0 disables. Default=500");
00492                         d.put("maxres", EMObject::FLOAT, "Highest resolution to use in comparison (soft cutoff). Requires accurate A/pix in image. <0 disables.  Default=10");
00493                         return d;
00494                 }
00495                 
00496                 static const string NAME;
00497         };
00498 
00499         template <> Factory < Cmp >::Factory();
00500 
00501         void dump_cmps();
00502         map<string, vector<string> > dump_cmps_list();
00503 }
00504 
00505 
00506 #endif
00507 
00508 /* vim: set ts=4 noet: */

Generated on Tue May 25 17:34:08 2010 for EMAN2 by  doxygen 1.4.4