EMAN2
Public Member Functions | Protected Member Functions | Private Member Functions
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:
Inheritance graph
[legend]
Collaboration diagram for EMAN::OrientationGenerator:
Collaboration graph
[legend]

List of all members.

Public Member Functions

 OrientationGenerator ()
virtual ~OrientationGenerator ()
virtual vector< Transformgen_orientations (const Symmetry3D *const sym) const =0
 generate orientations given some symmetry type
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.
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).
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.

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.
OrientationGeneratoroperator= (const OrientationGenerator &)
 Disallow assignment.

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

EMAN::OrientationGenerator::OrientationGenerator ( ) [inline]

Definition at line 1002 of file symmetry.h.

{};
virtual EMAN::OrientationGenerator::~OrientationGenerator ( ) [inline, virtual]

Definition at line 1003 of file symmetry.h.

{};
EMAN::OrientationGenerator::OrientationGenerator ( const OrientationGenerator ) [private]

Disallow copy construction.


Member Function Documentation

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.

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:
vthe vector to add Transform objects to
azthe azimuth to be used as a basis for generated Transform objects (in degrees)
altthe 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 271 of file symmetry.cpp.

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

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

{
        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;
}
virtual vector<Transform> EMAN::OrientationGenerator::gen_orientations ( const Symmetry3D *const  sym) const [pure virtual]

generate orientations given some symmetry type

Parameters:
symthe symmetry which defines the interesting asymmetric unit
Returns:
a vector of Transform objects containing the generated set of orientations

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

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

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 185 of file symmetry.cpp.

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().

{

        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

}
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:
symthe symmetry which defines the interesting asymmetric unit
nthe 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 234 of file symmetry.cpp.

References get_orientations_tally().

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

{

//      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;
}
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:
symthe symmetry which defines the interesting asymmetric unit
deltathe desired angular spacing of the orientations
Returns:
the number of orientations that will be generated using these parameters

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

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

virtual TypeDict EMAN::OrientationGenerator::get_param_types ( ) const [inline, virtual]
Returns:
a TypeDict defining and describing the feasible parameters of this class

Implements EMAN::FactoryBase.

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

Definition at line 1011 of file symmetry.h.

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

                {
                        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;
                }
OrientationGenerator& EMAN::OrientationGenerator::operator= ( const OrientationGenerator ) [private]

Disallow assignment.


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