symmetry.h

Go to the documentation of this file.

/*
 * Author: David Woolford, 09/23/2008 (woolford@bcm.edu)
 * Copyright (c) 2000-2006 Baylor College of Medicine
 * 
 * This software is issued under a joint BSD/GNU license. You may use the
 * source code in this file under either license. However, note that the
 * complete EMAN2 and SPARX software packages have some GPL dependencies,
 * so you are responsible for compliance with the licenses of these packages
 * if you opt to use BSD licensing. The warranty disclaimer below holds
 * in either instance.
 * 
 * This complete copyright notice must be included in any revised version of the
 * source code. Additional authorship citations may be added, but existing
 * author citations must be preserved.
 * 
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 * 
 * */
#ifndef eman__symmetry_h__
#define eman__symmetry_h__ 1


#include "emobject.h"
#include "vec3.h"
#include "transform.h"

namespace EMAN {
                
        class Symmetry3D : public FactoryBase
        {
        public:
                typedef vector<vector<Vec3f> >::const_iterator cit;
                typedef vector<vector<Vec3f> >::iterator ncit;
                Symmetry3D();
                virtual  ~Symmetry3D();
                
                virtual Dict get_delimiters(const bool inc_mirror=false) const = 0;
                
                virtual Transform get_sym(const int n) const = 0;
                
                virtual int get_nsym() const = 0;
                
                virtual float get_az_alignment_offset() const { return 0.0; }
                
                
                
                virtual bool is_platonic_sym() const { return false; }
                
                virtual bool is_h_sym() const { return false; }
                
                virtual bool is_c_sym() const { return false; }
                
                virtual bool is_d_sym() const { return false; }
                
                virtual bool is_tet_sym() const { return false; }
                
                
                
                virtual int get_max_csym() const = 0;
                
                virtual vector<Vec3f> get_asym_unit_points(bool inc_mirror) const = 0;
                vector<Transform> gen_orientations(const string& generatorname="eman", const Dict& parms=Dict());
                
                virtual bool is_in_asym_unit(const float& altitude, const float& azimuth, const bool inc_mirror) const = 0;

                virtual Transform reduce(const Transform& t3d, int n=0) const;
                
                
                virtual int in_which_asym_unit(const Transform& t3d) const;
                
                virtual int point_in_which_asym_unit(const Vec3f& v) const;
                
                virtual vector<vector<Vec3f> > get_asym_unit_triangles(bool inc_mirror) const = 0;
                
                virtual vector<Transform> get_touching_au_transforms(bool inc_mirror = true) const;
                
                virtual vector<Transform> get_syms() const;
                static vector<Transform> get_symmetries(const string& symmetry);
        protected:
                mutable float** cached_au_planes;
                
                mutable int cache_size;
                mutable int num_triangles;
                mutable vector< vector<Vec3f> > au_sym_triangles;
                void cache_au_planes() const;
                
                void delete_au_planes();
        private:
                Symmetry3D(const Symmetry3D&);
                Symmetry3D& operator=(const Symmetry3D&);
};
        
        class CSym : public Symmetry3D
{
        public:
                CSym() {};
                virtual  ~CSym() {};
                
                static Symmetry3D *NEW()
                {
                        return new CSym();
                }
                
                virtual string get_name() const { return NAME; }

                virtual string get_desc() const { return "C symmetry support"; }
                
                virtual TypeDict get_param_types() const
                {
                        TypeDict d;
                        d.put("nsym", EMObject::INT, "The symmetry number");
                        return d;
                }
                
                virtual Dict get_delimiters(const bool inc_mirror=false) const;
                
                virtual Transform get_sym(const int n) const;

                virtual int get_nsym() const { return params["nsym"]; };
                
                
                virtual int get_max_csym() const { return params["nsym"]; }
                
                static const string NAME;
                
                virtual vector<Vec3f> get_asym_unit_points(bool inc_mirror = false) const;
                
                virtual bool is_in_asym_unit(const float& altitude, const float& azimuth, const bool inc_mirror) const;
                
                virtual bool is_c_sym() const { return  true; }
                
                
                virtual vector<vector<Vec3f> > get_asym_unit_triangles(bool inc_mirror) const;
        private:
                CSym(const CSym&);
                CSym& operator=(const CSym&);
                
};
        
        class DSym : public Symmetry3D
{
        public:
                DSym() {};
                virtual  ~DSym() {};
                
                static Symmetry3D *NEW()
                {
                        return new DSym();
                }
                
                virtual string get_name() const { return NAME; }
                
                virtual string get_desc() const { return "D symmetry support"; }
                
                virtual TypeDict get_param_types() const
                {
                        TypeDict d;
                        d.put("nsym", EMObject::INT, "The symmetry number");
                        return d;
                }
                
                virtual Dict get_delimiters(const bool inc_mirror=false) const;
                
                virtual Transform get_sym(const int n) const;
                
                virtual int get_nsym() const { return 2*(int)params["nsym"]; };
                
                
                virtual int get_max_csym() const { return params["nsym"]; }
                
                virtual vector<Vec3f> get_asym_unit_points(bool inc_mirror = false) const;
                
                virtual bool is_in_asym_unit(const float& altitude, const float& azimuth, const bool inc_mirror) const;
                
                static const string NAME;
                
                virtual bool is_d_sym() const { return  true; }
                
                virtual vector<vector<Vec3f> > get_asym_unit_triangles(bool inc_mirror) const;
        private:
                DSym(const DSym&);
                DSym& operator=(const DSym&);
};
        
        class HSym : public Symmetry3D
{
        public:
                HSym() {};
                virtual  ~HSym() {};
                
                static Symmetry3D *NEW()
                {
                        return new HSym();
                }
                
                virtual string get_name() const { return NAME; }

                virtual string get_desc() const { return "H symmetry support"; }
                
                virtual TypeDict get_param_types() const
                {
                        TypeDict d;
                        d.put("nsym", EMObject::INT, "The symmetry number of the helix, around the equator.");
                        d.put("equator_range", EMObject::FLOAT, "The amount altitude angles are allowed to vary above and below the equator. Default is 5");
                        d.put("tz", EMObject::FLOAT, "The translational distance (along z) between succesive identical subunits in angstrom (default a/pix is 1)");
                        d.put("daz", EMObject::FLOAT, "The rotational angle (about z) between successive identical subunits in degrees");
                        d.put("apix", EMObject::FLOAT, "Angstrom per pixel, default is one.");
                        return d;
                }
                
                virtual Dict get_delimiters(const bool inc_mirror=false) const;
                
                        
                virtual Transform get_sym(const int n) const;
        
                virtual int get_nsym() const {
                        float daz = params.set_default("daz",0.0f);
                        if ( daz <= 0 ) throw InvalidValueException(daz,"Error, you must specify a positive non zero d_az");
                        return static_cast<int>(360.0/daz);
                };
                        
                virtual int get_max_csym() const { return params["nsym"]; }
                
                static const string NAME;
                        
                virtual bool is_h_sym() const { return true; }
                        
                virtual bool is_in_asym_unit(const float& altitude, const float& azimuth, const bool inc_mirror) const;
                        
                virtual vector<Vec3f> get_asym_unit_points(bool inc_mirror = false) const;
                        
                virtual vector<vector<Vec3f> > get_asym_unit_triangles(bool inc_mirror) const;
        private:
                HSym(const HSym&);
                HSym& operator=(const HSym&);
};
        
        class PlatonicSym : public Symmetry3D
{
        public:
                PlatonicSym() {};
                virtual  ~PlatonicSym() {};
                
                virtual TypeDict get_param_types() const
                {
                        TypeDict d;
                        return d;
                }
                
                virtual Dict get_delimiters(const bool inc_mirror=false) const;
                
                virtual bool is_in_asym_unit(const float& altitude, const float& azimuth, const bool inc_mirror) const;
                
                virtual bool is_platonic_sym() const { return true; }
                
        protected:
                Dict platonic_params;

                void init();
                
                float platonic_alt_lower_bound(const float& azimuth, const float& alpha) const;
                
                virtual vector<Vec3f> get_asym_unit_points(bool inc_mirror = false) const;
                
                virtual vector<vector<Vec3f> > get_asym_unit_triangles(bool inc_mirror) const;
        private:
                PlatonicSym(const PlatonicSym&);
                PlatonicSym& operator=(const PlatonicSym&);
};
        
        class TetrahedralSym : public PlatonicSym
{
        public:
                TetrahedralSym()  {init();}
                virtual  ~TetrahedralSym() {}
                
                static Symmetry3D *NEW()
                {
                        return new TetrahedralSym();
                }
                
                virtual string get_name() const { return NAME; }


                virtual string get_desc() const { return "Tetrahedral symmetry support"; }

                virtual int get_max_csym() const { return 3; }
                
                virtual Transform get_sym(const int n) const;
                
                virtual bool is_in_asym_unit(const float& altitude, const float& azimuth, const bool inc_mirror) const;
                
                virtual int get_nsym() const { return 12; };
                
                virtual float get_az_alignment_offset() const;
                
                static const string NAME;
                
                virtual vector<Vec3f> get_asym_unit_points(bool inc_mirror = false) const;
                
                virtual bool is_tet_sym() const { return true; }
                
        private:
                TetrahedralSym(const TetrahedralSym&);
                TetrahedralSym& operator=(const TetrahedralSym&);
                
                
};
        
        class OctahedralSym : public PlatonicSym
{
        public:
                OctahedralSym()  {init();}
                virtual  ~OctahedralSym() {}
                
                static Symmetry3D *NEW()
                {
                        return new OctahedralSym();
                }
                
                virtual string get_name() const { return NAME; };

                virtual string get_desc() const { return "Octahedral symmetry support"; }

                virtual int get_max_csym() const { return 4; }
                
                virtual Transform get_sym(const int n) const;
                
                virtual int get_nsym() const { return 24; };
                
                static const string NAME;
        private:
                OctahedralSym(const OctahedralSym&);
                OctahedralSym& operator=(const OctahedralSym&);
};
        
        class IcosahedralSym : public PlatonicSym
{
        public:
                IcosahedralSym() {init(); }
                virtual  ~IcosahedralSym() { }
                
                static Symmetry3D *NEW()
                {
                        return new IcosahedralSym();
                }
                        
                virtual string get_name() const { return NAME; };
                
                virtual string get_desc() const { return "Icosahedral symmetry support"; }
        
                virtual int get_max_csym() const { return 5; }// 5 is the greatest symmetry
                
                virtual Transform get_sym(const int n) const;
                
                virtual int get_nsym() const { return 60; };
                
                virtual float get_az_alignment_offset() const;
                
                static const string NAME;
        private:
                IcosahedralSym(const IcosahedralSym&);
                IcosahedralSym& operator=(const IcosahedralSym&);
};
        template <> Factory < Symmetry3D >::Factory();
        template <> Symmetry3D* Factory < Symmetry3D >::get(const string & instancename);
        void dump_symmetries();
        map<string, vector<string> > dump_symmetries_list();
        
        class OrientationGenerator : public FactoryBase
{
        public:
                OrientationGenerator() {};
                virtual ~OrientationGenerator() {};
                
                virtual vector<Transform> gen_orientations(const Symmetry3D* const sym) const  = 0;
                
                virtual TypeDict get_param_types() const
                {
                        TypeDict d;
                        d.put("phitoo", EMObject::FLOAT,  "Specifying a non zero value for this argument will cause phi rotations to be included. The value specified is the angular spacing of the phi rotations in degrees. The default for this value is 0, causing no extra phi rotations to be included.");
                        d.put("random_phi", EMObject::BOOL,  "Causes the orientations to have a random phi. This occurs before the phitoo parameter is considered.");
                        return d;
                }
                
                bool add_orientation(vector<Transform>& v, const float& az, const float& alt) const;
                
                
                
                float get_optimal_delta(const Symmetry3D* const sym, const int& n) const;

                virtual int get_orientations_tally(const Symmetry3D* const sym, const float& delta) const = 0;

        protected:
                void get_az_max(const Symmetry3D* const sym, const float& altmax, const bool inc_mirror, const float& alt_iterator,const float& h,bool& d_odd_mirror_flag, float& azmax_adjusted) const;
        
        private:
                OrientationGenerator(const OrientationGenerator&);
                OrientationGenerator& operator=(const OrientationGenerator&);
};
        
        
                
class EmanOrientationGenerator : public OrientationGenerator
{
        public:
                EmanOrientationGenerator() {};
                virtual  ~EmanOrientationGenerator() {};
                
                static OrientationGenerator *NEW()
                {
                        return new EmanOrientationGenerator();
                }
                
                virtual string get_name() const { return NAME; }

                virtual string get_desc() const { return "Generate orientations distributed quasi-uniformaly over the asymmetric unit using an altitude-proportional strategy"; }
                
                virtual TypeDict get_param_types() const
                {
                        TypeDict d = OrientationGenerator::get_param_types();
                        d.put("delta", EMObject::FLOAT, "The angular separation of orientations in degrees. This option is mutually exclusively of the n argument.");
                        d.put("perturb", EMObject::BOOL, "Whether or not to perturb the generated orientations in a small local area, default is false.");
                        d.put("n", EMObject::INT, "The number of orientations to generate. This option is mutually exclusively of the delta argument.Will attempt to get as close to the number specified as possible.");
                        d.put("inc_mirror", EMObject::BOOL, "Indicates whether or not to include the mirror portion of the asymmetric unit. Default is false.");
                        return d;
                }
                
                virtual vector<Transform> gen_orientations(const Symmetry3D* const sym) const;
                
                static const string NAME;
        private:
                EmanOrientationGenerator(const EmanOrientationGenerator&);
                EmanOrientationGenerator& operator=(const EmanOrientationGenerator&);
                
                virtual int get_orientations_tally(const Symmetry3D* const sym, const float& delta) const;
                
                
                float get_az_delta(const float& delta,const float& altitude, const int maxcsym) const;
                
};      
        
class RandomOrientationGenerator : public OrientationGenerator
{
        public:
                RandomOrientationGenerator() {}
                virtual ~RandomOrientationGenerator() {}
                
                static OrientationGenerator *NEW()
                {
                        return new RandomOrientationGenerator();
                }
                
                virtual string get_name() const { return NAME; }

                virtual string get_desc() const { return "Generate random orientations within an asymmetric unit"; }
                
                virtual TypeDict get_param_types() const
                {
                        TypeDict d;
                        d.put("n", EMObject::INT, "The number of orientations to generate.");
                        d.put("inc_mirror", EMObject::BOOL, "Indicates whether or not to include the mirror portion of the asymmetric unit. Default is false.");
                        d.put("phitoo", EMObject::BOOL, "Makes phi random as well");
                        return d;
                }
                
                virtual vector<Transform> gen_orientations(const Symmetry3D* const sym) const;
                
                static const string NAME;
                
                virtual int get_orientations_tally(const Symmetry3D* const sym, const float& delta) const { (void)sym; (void)delta; return 0; }
        private:
                RandomOrientationGenerator(const RandomOrientationGenerator&);
                RandomOrientationGenerator& operator=(const RandomOrientationGenerator&);
};
        
        class EvenOrientationGenerator : public OrientationGenerator
{
        public:
                EvenOrientationGenerator() {}
                virtual ~EvenOrientationGenerator() {}
                
                static OrientationGenerator *NEW()
                {
                        return new EvenOrientationGenerator();
                }
                
                
                virtual string get_name() const { return NAME; }

                virtual string get_desc() const { return "Generate quasi-evenly distributed orientations within an asymmetric unit using Penczek's (94) approach"; }
                
                virtual TypeDict get_param_types() const
                {
                        TypeDict d = OrientationGenerator::get_param_types();
                        d.put("delta", EMObject::FLOAT, "The angular separation of orientations in degrees. This option is mutually exclusively of the n argument.");
                        d.put("inc_mirror", EMObject::BOOL, "Indicates whether or not to include the mirror portion of the asymmetric unit. Default is false.");
                        d.put("n", EMObject::INT, "The number of orientations to generate. This option is mutually exclusively of the delta argument.Will attempt to get as close to the number specified as possible.");
                        return d;
                }
                
                virtual vector<Transform> gen_orientations(const Symmetry3D* const sym) const;
                
                static const string NAME;
        private:
                EvenOrientationGenerator(const EvenOrientationGenerator&);
                EvenOrientationGenerator& operator=(const EvenOrientationGenerator&);
                virtual int get_orientations_tally(const Symmetry3D* const sym, const float& delta) const;
        
};
        
class SaffOrientationGenerator : public OrientationGenerator
{
        public:
                SaffOrientationGenerator() {}
                virtual ~SaffOrientationGenerator() {}
                
                static OrientationGenerator *NEW()
                {
                        return new SaffOrientationGenerator();
                }
                        
                virtual string get_name() const { return NAME; }

                virtual string get_desc() const { return "Generate quasi-evenly distributed orientations within an asymmetric unit using a spiraling method attributed to Saff"; }
                
                virtual TypeDict get_param_types() const
                {
                        TypeDict d = OrientationGenerator::get_param_types(); 
                        d.put("n", EMObject::INT, "The number of orientations to generate. This option is mutually exclusively of the delta argument.Will attempt to get as close to the number specified as possible.");
                        d.put("inc_mirror", EMObject::BOOL, "Indicates whether or not to include the mirror portion of the asymmetric unit. Default is false.");
                        d.put("delta", EMObject::FLOAT, "The angular separation of orientations in degrees. This option is mutually exclusively of the n argument.");
                        return d;
                }
                
                virtual vector<Transform> gen_orientations(const Symmetry3D* const sym) const;
                        
                static const string NAME;
        private:
                SaffOrientationGenerator(const SaffOrientationGenerator&);
                SaffOrientationGenerator& operator=(const SaffOrientationGenerator&);
                virtual int get_orientations_tally(const Symmetry3D* const sym, const float& delta) const;
                        
                // This was a function that paid special considerations to the overall algorithm in the
                // case of the Platonic symmetries, which have non trivial asymmetric units. But unfortunately
                // it was bug-prone, and the approach in place already seemed good enough
                //vector<Transform> gen_platonic_orientations(const Symmetry3D* const sym, const float& delta) const;
};
        
        
class OptimumOrientationGenerator : public OrientationGenerator
{
        public:
                OptimumOrientationGenerator() {}
                virtual ~OptimumOrientationGenerator() {}
                
                static OrientationGenerator *NEW()
                {
                        return new OptimumOrientationGenerator();
                }
                        
                virtual string get_name() const { return NAME; }

                virtual string get_desc() const { return "Generate optimally distributed orientations within an asymmetric using a basic optimization technique"; }
                
                virtual TypeDict get_param_types() const
                {
                        TypeDict d = OrientationGenerator::get_param_types(); 
                        d.put("n", EMObject::INT, "The number of orientations to generate. This option is mutually exclusively of the delta argument.Will attempt to get as close to the number specified as possible.");
                        d.put("inc_mirror", EMObject::BOOL, "Indicates whether or not to include the mirror portion of the asymmetric unit. Default is false.");
                        d.put("delta", EMObject::FLOAT, "The angular separation of orientations in degrees. This option is mutually exclusively of the n argument.");
                        d.put("use", EMObject::STRING, "The orientation generation technique used to generate the initial distribution on the unit sphere.");
                        return d;
                }
                
                virtual vector<Transform> gen_orientations(const Symmetry3D* const sym) const;
                        
                static const string NAME;
        private:
                OptimumOrientationGenerator(const OptimumOrientationGenerator&);
                OptimumOrientationGenerator& operator=(const OptimumOrientationGenerator&);
                virtual int get_orientations_tally(const Symmetry3D* const sym, const float& delta) const;
                        
                        
                vector<Vec3f> optimize_distances(const vector<Transform>& v) const;
};
        
        template <> Factory < OrientationGenerator >::Factory();
        void dump_orientgens();
        map<string, vector<string> > dump_orientgens_list();
} // namespace EMAN

#endif // eman__symmetry_h__