EMAN::OrientationGenerator Class Reference

An orientation generator is a kind of class that will generate orientations for a given symmetry If one needs to generate orientations in the unit sphere, one simply uses the C1 symmetry. More...

#include <symmetry.h>

Inheritance diagram for EMAN::OrientationGenerator:

Collaboration diagram for EMAN::OrientationGenerator:

Public Member Functions
	OrientationGenerator ()
virtual	~OrientationGenerator ()
virtual vector< Transform >	gen_orientations (const Symmetry3D *const sym) const =0
	generate orientations given some symmetry type More...
virtual TypeDict	get_param_types () const
bool	add_orientation (vector< Transform > &v, const float &az, const float &alt) const
	This functions adds one or more Transform objects to the vector v, depending on the parameters stored in the dictionary (which the inheriting class may include by initializing the typedict in get_param_types by calling. More...
float	get_optimal_delta (const Symmetry3D *const sym, const int &n) const
	This function gets the optimal value of the delta (or angular spacing) of the orientations based on a desired total number of orientations (n). More...
virtual int	get_orientations_tally (const Symmetry3D *const sym, const float &delta) const =0
	This function returns how many orientations will be generated for a given delta (angular spacing) It should general do this by simulating the function gen_orientations. More...
Public Member Functions inherited from EMAN::FactoryBase
	FactoryBase ()
virtual	~FactoryBase ()
virtual string	get_name () const =0
	Get the unique name of this class (especially for factory based instantiation access) More...
virtual string	get_desc () const =0
	Get a clear, concise description of this class. More...
Dict	get_params () const
	get a copy of the parameters of this class More...
void	set_params (const Dict &new_params)
	Set new parameters. More...
void	set_param (const string key, const EMObject val)
void	insert_params (const Dict &new_params)
	Insert parameters. More...
Dict	copy_relevant_params (const FactoryBase *const that) const

Protected Member Functions
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 Member Functions
	OrientationGenerator (const OrientationGenerator &)
	Disallow copy construction. More...
OrientationGenerator &	operator= (const OrientationGenerator &)
	Disallow assignment. More...

Additional Inherited Members
Protected Attributes inherited from EMAN::FactoryBase
Dict	params
	This is the dictionary the stores the parameters of the object. More...

Detailed Description

An orientation generator is a kind of class that will generate orientations for a given symmetry If one needs to generate orientations in the unit sphere, one simply uses the C1 symmetry.

It inherits from a factory base, making it amenable to incorporation in EMAN2 style factories. Objects that inherit from this class must write a gen_orientations function, in addition to fulfilling the responsibilities of the FactoryBase class

Author

David Woolford

Date

Feb 2008

Definition at line 999 of file symmetry.h.

Constructor & Destructor Documentation

OrientationGenerator() [1/2]

EMAN::OrientationGenerator::OrientationGenerator ( )

inline

Definition at line 1002 of file symmetry.h.

{};

~OrientationGenerator()

virtual EMAN::OrientationGenerator::~OrientationGenerator ( )

inlinevirtual

Definition at line 1003 of file symmetry.h.

{};

OrientationGenerator() [2/2]

EMAN::OrientationGenerator::OrientationGenerator ( const OrientationGenerator &  )

private

Disallow copy construction.

Member Function Documentation

add_orientation()

bool OrientationGenerator::add_orientation	(	vector< Transform > &	v,
		const float &	az,
		const float &	alt
	)		const

This functions adds one or more Transform objects to the vector v, depending on the parameters stored in the dictionary (which the inheriting class may include by initializing the typedict in get_param_types by calling.

TypeDict d = OrientationGenerator::get_param_types();

to initialize. If phitoo is no zero, this cause extra orientations to be included in phi (in steps of phitoo). If random_phi is true, the phi of the Transform object is randomized. This function is for internal convenience of child classes.

Parameters

v	the vector to add Transform objects to
az	the azimuth to be used as a basis for generated Transform objects (in degrees)
alt	the altitude to be used as a basis for generated Transform objects (in degrees)

Returns

and indication of success (true or false). False is only ever return if phitoo is less than 0.

Definition at line 273 of file symmetry.cpp.

{
        bool randphi = params.set_default("random_phi",false);
        float phi = 0.0f;
        if (randphi) phi = Util::get_frand(0.0f,359.99999f);
        float phitoo = params.set_default("phitoo",0.0f);
        if ( phitoo < 0 ) throw InvalidValueException(phitoo, "Error, if you specify phitoo is must be positive");
        Dict d;
        d["type"] = "eman";
        d["az"] = az;
        d["alt"] = alt;
        d["phi"] = phi;
        Transform t(d);
        v.push_back(t);
        if ( phitoo != 0 ) {
                if (phitoo < 0) return false;
                else {
                        for ( float p = phitoo; p <= 360.0f-phitoo; p+= phitoo )
                        {
                                d["phi"] = fmod(phi+p,360);
                                Transform t(d);
                                v.push_back(t);
                        }
                }
        }
        return true;
}

References EMAN::Util::get_frand(), InvalidValueException, EMAN::FactoryBase::params, and EMAN::Dict::set_default().

Referenced by EMAN::EmanOrientationGenerator::gen_orientations(), EMAN::EvenOrientationGenerator::gen_orientations(), EMAN::SaffOrientationGenerator::gen_orientations(), and EMAN::OptimumOrientationGenerator::gen_orientations().

gen_orientations()

virtual vector< Transform > EMAN::OrientationGenerator::gen_orientations ( const Symmetry3D *const  sym ) const

pure virtual

generate orientations given some symmetry type

Parameters

sym	the symmetry which defines the interesting asymmetric unit

Returns

a vector of Transform objects containing the generated set of orientations

Implemented in EMAN::EmanOrientationGenerator, EMAN::SingleOrientationGenerator, EMAN::RandomOrientationGenerator, EMAN::EvenOrientationGenerator, EMAN::SaffOrientationGenerator, and EMAN::OptimumOrientationGenerator.

Referenced by EMAN::Symmetry3D::gen_orientations(), and EMAN::OptimumOrientationGenerator::gen_orientations().

get_az_max()

void OrientationGenerator::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

protected

Definition at line 187 of file symmetry.cpp.

{
 
        if ( sym->is_d_sym() && alt_iterator == altmax && ( (sym->get_nsym())/2 % 2 == 1 )) {
                if (inc_mirror) {
                        azmax_adjusted /= 4.0f;
                        d_odd_mirror_flag = true;
                }
                else azmax_adjusted /= 2.0f;
        }
        else if (sym->is_d_sym() && alt_iterator == altmax && ( (sym->get_nsym())/2 % 2 == 0 ) && inc_mirror) {
                azmax_adjusted /= 2.0f;
        }
        // if this is odd c symmetry, and we're at the equator, and we're excluding the mirror then
        // half the equator is redundant (it is the mirror of the other half)
        else if (sym->is_c_sym() && !inc_mirror && alt_iterator == altmax && (sym->get_nsym() % 2 == 1 ) ){
                azmax_adjusted /= 2.0f;
        }
        // at the azimuthal boundary in c symmetry and tetrahedral symmetry we have come
        // full circle, we must not include it
        else if (sym->is_c_sym() || sym->is_tet_sym() ) {
                azmax_adjusted -=  h/4.0f;
        }
        // If we're including the mirror then in d and icos and oct symmetry the azimuthal
        // boundary represents coming full circle, so must be careful to exclude it
        else if (inc_mirror && ( sym->is_d_sym() || sym->is_platonic_sym() ) )  {
                azmax_adjusted -=  h/4.0f;
        }
        // else do nothing - this means that we're including the great arc traversing
        // the full range of permissable altitude angles at azmax.
        // This happens in d symmetry, and in the icos and oct symmetries, when the mirror
        // portion of the asymmetric unit is being excluded
 
}

References EMAN::Symmetry3D::get_nsym(), EMAN::Symmetry3D::is_c_sym(), EMAN::Symmetry3D::is_d_sym(), EMAN::Symmetry3D::is_platonic_sym(), and EMAN::Symmetry3D::is_tet_sym().

Referenced by EMAN::EmanOrientationGenerator::gen_orientations(), and EMAN::EmanOrientationGenerator::get_orientations_tally().

get_optimal_delta()

float OrientationGenerator::get_optimal_delta	(	const Symmetry3D *const	sym,
		const int &	n
	)		const

This function gets the optimal value of the delta (or angular spacing) of the orientations based on a desired total number of orientations (n).

It does this using a bifurcation strategy, calling get_orientations_tally (which must be supplied by the child class) using the next best guess etc. The solution may not exist (simply because the orientation generation strategy does not contain it), so a best guess may be returned.

The inheriting class must supply the get_orientations_tally function, which returns the number of orientations generated (an int), for a given delta.

Parameters

sym	the symmetry which defines the interesting asymmetric unit
n	the desired number of orientations

Returns

the optimal value of delta to ensure as near to the desired number of orientations is generated

Definition at line 236 of file symmetry.cpp.

{
 
//      float delta_soln = 360.0f/sym->get_max_csym();
        float delta_soln = 180.0f;
        float delta_upper_bound = delta_soln;
        float delta_lower_bound = 0.0f;
 
        int prev_tally = -1;
        // This is an example of a divide and conquer approach, the possible values of delta are searched
        // like a binary tree
 
        bool soln_found = false;
 
        while ( soln_found == false ) {
                int tally = get_orientations_tally(sym,delta_soln);
                if ( tally == n ) soln_found = true;
                else if ( (delta_upper_bound - delta_lower_bound) < 0.0001 ) {
                        // If this is the case, the requested number of projections is practically infeasible
                        // in which case just return the nearest guess
                        soln_found = true;
                        delta_soln = (delta_upper_bound+delta_lower_bound)/2.0f;
                }
                else if (tally < n) {
                        delta_upper_bound = delta_soln;
                        delta_soln = delta_soln - (delta_soln-delta_lower_bound)/2.0f;
                }
                else  /* tally > n*/{
                        delta_lower_bound = delta_soln;
                        delta_soln = delta_soln  + (delta_upper_bound-delta_soln)/2.0f;
                }
                prev_tally = tally;
        }
 
        return delta_soln;
}

References get_orientations_tally().

Referenced by EMAN::EmanOrientationGenerator::gen_orientations(), EMAN::EvenOrientationGenerator::gen_orientations(), EMAN::SaffOrientationGenerator::gen_orientations(), and EMAN::OptimumOrientationGenerator::gen_orientations().

get_orientations_tally()

virtual int EMAN::OrientationGenerator::get_orientations_tally ( const Symmetry3D *const  sym, const float &  delta  ) const

pure virtual

This function returns how many orientations will be generated for a given delta (angular spacing) It should general do this by simulating the function gen_orientations.

Parameters

sym	the symmetry which defines the interesting asymmetric unit
delta	the desired angular spacing of the orientations

Returns

the number of orientations that will be generated using these parameters

Implemented in EMAN::EmanOrientationGenerator, EMAN::SingleOrientationGenerator, EMAN::RandomOrientationGenerator, EMAN::EvenOrientationGenerator, EMAN::SaffOrientationGenerator, and EMAN::OptimumOrientationGenerator.

Referenced by get_optimal_delta(), and EMAN::OptimumOrientationGenerator::get_orientations_tally().

get_param_types()

virtual TypeDict EMAN::OrientationGenerator::get_param_types ( ) const

inlinevirtual

Returns

a TypeDict defining and describing the feasible parameters of this class

Implements EMAN::FactoryBase.

Reimplemented in EMAN::EmanOrientationGenerator, EMAN::SingleOrientationGenerator, EMAN::RandomOrientationGenerator, EMAN::EvenOrientationGenerator, EMAN::SaffOrientationGenerator, and EMAN::OptimumOrientationGenerator.

Definition at line 1011 of file symmetry.h.

                {
                        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;
                }

References EMAN::EMObject::BOOL, EMAN::EMObject::FLOAT, and EMAN::TypeDict::put().

Referenced by EMAN::EmanOrientationGenerator::get_param_types(), EMAN::SingleOrientationGenerator::get_param_types(), EMAN::EvenOrientationGenerator::get_param_types(), EMAN::SaffOrientationGenerator::get_param_types(), and EMAN::OptimumOrientationGenerator::get_param_types().

operator=()

OrientationGenerator & EMAN::OrientationGenerator::operator= ( const OrientationGenerator &  )

private

Disallow assignment.

---

The documentation for this class was generated from the following files:

• symmetry.h
• symmetry.cpp