Project

!Project

Purpose

This program allows you to generate projections from a 3D Xmipp volume or from a mathematical phantom. The projection parameters are given through a parameter file, and you may change the projection dimension, the noise in the Euler angles (this is generated as follows, the projection is produced using some Euler angles, and then some Gaussian noise is added to the values written in the projection file), pixels and image center (the image is physically shifted according to a Gaussian random generator). The projection angles can be given either from a Document File or manually describing the ranges or values we want. The angle definition is fully compatible with Spider, ie. the same phantom in both programs with the same angles provides the same projections.

Usage

$ project -i ...

Parameters

• ``
• ``
• ``
• `` This parameter is only used when even distributions of projections are to be taken. If the particle is symmetric and this option is provided, only the non repeated projections are generated. The symmetry file must have the structure described inSymmetrize
• -sampling_rate [Ts1] = Sampling rate in Angstroms/pixel. This parameter is only used when projecting PDB files.
• `` Show a document file with the projection angles at the same time that the volume is projected. Even when this option is not chosen, this program always save a file called[projection_seed]_movements.txt with a docfile with the perfect angles, the noisy angles and the shifts applied to the center
• `` Show a document file with the projection angles but the projections are not generated

The structure of projection description file:

# Volume and projection files

# Volume description file, PDB file (with extension PDB), or volume file

`` MUST HAVE EXTENSION descr (since xmipp 3.0)

# Projection seed, first projection number (by default, 1) and extension

[first projection number1] [extension=""] =

# Y and X projection dimensions

``

# Angle Definitions

# Option 1: ANGLE SOURCE FILE

# Docfile, angle order (rot, tilt, psi). "NULL" for no external file

``

# Option 2: RANGE DEFINITIONS
# Use NULL for not generating internal angles. Describe ranges and modes (random, random_group) for the 3 angles:
# Usually:
#     rotational = 0 ... 2PI
#     tilting    = 0 ... PI/2
#     3rd euler  = 0 ... 2PI 
#
# RANGE MODE: Angles are taken in degrees
#
# --- FIXED MODE ---
# In this mode, the angle is fixed to some value, and all projections
# have got the same rotational angle, tilting angle or psi. The
# structure to do this is

``

# --- LINEAR MODE ---
# The mode is usually linear, if you specify the rotational angle to be
# between 0 and 360 with 4 different angles, these angles would be 0,
# 120, 240 and 360. This is accomplished with the following structure
# for the angles

``

# --- EVEN MODE ---
# This mode makes an even distribution of samples within the region
# specified by tilt and rot. The separation among tilt samples is fixed
# by the number of samples in tilt. However, the number of samples in rot
# is determined using the number of samples provided by the user divided
# by the sine of tilt. This makes the equator to have the number of samples
# specified by the user, but samples move farther away as they depart
# from the equator. Use this flag only in the rotational line,
# since it will affect both, rot and tilt. In this mode, the number of
# projections cannot be computed as Nrot*Ntilt*Npsi.

``

# --- RANDOM MODE BY GROUPS ---
# But you may prefer these four angles to be uniform randomly distributed
# in the range, for example, 13.56, 90.54, 190.1, 260.5. This is
# accomplished by adding the suffix 'random_group' to the initial angle
# descriptor. The random group idea is the following, suppose that we
# have the 4 random rotational angles listed before, and we have also
# 3 tilting angles (say, -10, 0 and 10). Then there are 12 (=4x3)
# combinations of angles, then groups are formed using the random angles
# (rot,tilt)=(13.56,-10),(13.56,0),(13.56,10),(90.54,-10),(90.54,0),
# (90.54,10), ... As you see the rotational angles are ranfom but, once
# they are inside a group then they are deterministic.

``

# --- COMPLETELY RANDOM ---
# You may also want an angle to be random (uniform) for every projection
# You can do this by adding the suffix 'random' to the initial angle
# descriptor. In the previous example the 12 projections would have
# 12 different rotational angles.

``

# ANGLE ORDER:
# You must use the just defined way of indicating the angle range to
# set the rotational, tilting and psi ranges (in this order)

``

``

``

# NUMBER OF PROJECTIONS:
# If you describe the angle set in this way, the number of projections
# will be n_rot*n_tilt*n_psi, where n_rot is the number of different
# rotational angles, and so on.
#
# COLLECTION GEOMETRIES:
# - Single axis series are modelled by fixed rotational and psi angles
#   while a varying the tilting angle.
# - Conical tilting series are represented by constant tilt angle and
#   varying rotational and psi ones 

# Noise description

# In the following lines deviation is the true power of noise added
# to that variable, while average is like a bias directly added to
# the variable. Noise for angles are taken as degrees. The added
# noise is gaussian

# Noise (and bias) applied to rotational angle

[rot bias0] =

# Noise (and bias) applied to tilting angle

[tilt bias0] =

# Noise (and bias) applied to psi angle

[psi bias0] =

# Noise (and bias) applied to pixels

[pixel bias0] =

# Noise (and bias) applied to particle center coordenates
# IMPORTANT: This option ONLY works when using a phantom described as a set of geometrical objects 
# That is, It does NOT work when the volume is defined using voxels

[center bias0] =

Structure of crystal description file:

# Crystal Parameters

# Crystal dimensions

``

# Lattice vector a

``

# Lattice vector b

``

# Shift noise

[shift bias0] =

# Disappearing threshold (1=All features appear)

``

# Orthogonal projections

__OR__

# File with shifts, put null if not available

``

Examples and notes

• INDEX SYMMETRY: Due to the Xmipp definition of center, images are symmetrical (with respect to the size, ie, are defined between -xi and +xi) for odd dimensions (for instance, 65x65, in this case the image is defined between [-32,+32] for the two directions)
• EULER ANGLES: Euler angles cause projections to be taken from different points of view, here you have some useful Euler combinations to obtain projections with the "illuminating source" in the direction marked as "from" and the "recording film" in the direction marked as "to". The last column in the table shows the volume axis as they are seen in the picture (remember that the picture alone has always the axes as the ones shown in the entry "from +Z to -Z"
• EVEN DISTRIBUTIONS: There are two ways of generating even distributions. The first one is manually given by the user by providing the range within which he wants to generate the projections. For instance for generating even projections in the upper half of the sphere with a separation of 5 degrees provide the angular limits # Internally generated angles (upper half of the sphere) # The rot angular step is (360-0)/(73-1)5 # The tilt angular step is ( 90-0)/(19-1)5 0 360 73 even 0 90 19 0 For generating projections in a given portion of the sphere

   # Internally generated angles (upper half portion of the sphere)
   # The rot  angular step is ( 55-0)/(11-1)=5
   # The tilt angular step is ( 90-0)/(19-1)=5
   0 50 11 even
   0 90 19
   0
   

Alternatively if the phantom has symmetry, you may let the program to find those projections lying in the assymetrical unit by simply specifying the rotational step at the equator and providing a symmetry file with the -sym option

   # Internally generated angles (only in the assymetrical unit)
   # The rot  angular step is (360-0)/(73-1)=5
   0 360 73 even
   0
   0
   

In the following table the real example has been produced using the following phantom

   # General Volume Parameters:
   #      Xdim      Ydim      Zdim   Background
           65        65        65    0.000000e+00
   # Feature Parameters:
   ell + 1  0   0 20  5  5 15   0  0  0    ; Ellipsoid in Z
   cyl + 1 15   0  0  5  5 15   0 90  0    ; Cylinder  in X
   sph + 1  0  10  0  8                    ; Sphere    in Y
   

Direction	rot	tilt	psi	Volume Axis seen	Real Example
from -X to +X	180	90	0	/from_X.gif	/from_X2.gif
from +X to -X	0	90	0	/fromX.gif	/fromX2.gif
from -Y to +Y	270	90	0	/from_Y.gif	/from_Y2.gif
from +Y to -Y	90	90	0	/fromY.gif	/fromY2.gif
from -Z to +Z	0	180	0	/from_Z.gif	/from_Z2.gif
from +Z to -Z	0	0	0	/fromZ.gif	/fromZ2.gif

• ORTHOGONAL PROJECTIONS: This option is only valid for crystal projections. The concept is like this, imagine you have a crystal wuth lattice vectors in R²a andb. Whe you project it from any direction these two vectors are projected into the projection plane asa_proj andb_proj, and the angle between them could be any one. The projection taken as it is now is the non-orthogonal projection of the crystal. However, for ART+crystals you can select to do orthogonal projections, this means that it doesn't matter whicha_proj andb_proj are, a matrix transformation is applied such thata_proj becomes (<Xdim>,=0=) andb_proj becomes (0,==). This matrix transformation is performed without interpolation and so the deformed projection is perfect. The following gallery of pictures are taken from a phantom which is formed by a big cylinder aligned withZ, and two very thin ones which representX (double density) andY axis. Notice the difference between orthogonalizing the projections or not. The top projection of the phantom is shown to have an idea of how the crystal is. | Top view of crystal | /crystal_orthogonal.gif |

Here you have another two examples to generate projections from the two_rings volume, in the first example taking the angles from a document file, and in the second manually given as ranges.

projection1.param Project taking angles from a document file

# Volume and projection files --------------------------------
# volume description file or volume file
two_rings.descr

# Projection seed, first projection number (by default, 1) and extension
# (the two last are optional)
g1ta 1 spi

# Y and X projection dimensions
65 65

# Angle Definitions ------------------------------------------
# Externally generated angles
angle.doc rot tilt psi

# Internally generated angles
NULL

# Noise description ------------------------------------------
# Noise (and bias) applied to rotational angle
10 3

# Noise (and bias) applied to tilting angle
10 3

# Noise (and bias) applied to psi angle
10 3

# Noise (and bias) applied to pixels
20

# Noise (and bias) applied to particle center coordenates
5

projection2.param Project taking angles from given ranges to generate a "realistic" random conical tilting. Generate 1000 projections

# Volume and projection files --------------------------------
# volume description file or volume file
two_rings.descr

# Projection seed, first projection number (by default, 1) and extension
# (the two last are optional)
g1ta 1 spi

# Y and X projection dimensions
65 65

# Angle Definitions ------------------------------------------
# Externally generated angles
NULL

# Internally generated angles
# Rotational range: <init> <final> <samples> random
0 360 10 random

# Tilting range: <init> <final> <samples> random_group
55 65 10 random_group

# Psi range: <init> <final> <samples> random
0 360 10 random

# Noise description ------------------------------------------
# Noise (and bias) applied to rotational angle
10 3

# Noise (and bias) applied to tilting angle
10 3

# Noise (and bias) applied to psi angle
10 3

# Noise (and bias) applied to pixels
20

# Noise (and bias) applied to particle center coordenates
5

The command to generate the projections would be

$ project -i projection1.param -o g1ta.sel

Used to project a crystal

# Crystal Parameters --------------------------------------------
# Crystal dimensions
512 512

# Lattice vector a
0 64

# Lattice vector b
64 0

# Shift noise
2

# Disappearing threshold (1=All features appear)
0.9

# Orthogonal projections
No

# File with shifts, put null if not available
NULL

And with a phantom composed by only big sphere, projecting from rot=45 and tilt=60, you get the following image

/crystal_projection.gif

We can include a is used to simulate a 3D crystal distorsion. The file format is as follows:

Index h	Index k	Ideal_x_coord	Ideal_y_coord	Diff_x_coord	Diff_y_coord	Diff_z_coord	Normal_x_dim	Normal_y_dim	Normal_z_dim
-4	-4	-256	-256	17.17	17.17	114	0.39	0.39	0.82
-4	-3	-256	-192	14	10.5	91.5	0.41	0.31	0.85
-4	-2	-256	-128	11.93	5.96	74.4	0.42	0.21	0.87
-4	-1	-256	64	10.17	2.54	64.2	0.43	0.10	0.89
-4	0	-256	0	9.67	0	60.6	0.44	0.00	0.89
-4	1	-256	64	10.17	-2.54	64.2	0.43	-0.10	0.89

where:

• contain the indexes of the lattice point.
• are the cartesian coordinates of this point in the plane surface
• are the differences between the coordinates of the lattice point in the plane surface and in the mapped surface.
• we can distinguish two differents effects of the 3D distorsion on the lattice:
• The unit cell center is shifted from their regular positions an amount
• The unit cell center is rotated owed to this 3D distorsion. We can calculate this rotation using the

In the two images shown below we can appreciate the differences between the projection of a regular lattice (left) and the projection of a deformed lattice (right)

/project0007_joined.jpeg

USER's COMMENTS

Param file example for an even projection /proj_even.param	Main.RafaelNunezRamirez	04 Jan 2008 - 12:02
Param file example for a single projection /proj_single.param	Main.RafaelNunezRamirez	04 Jan 2008 - 12:02
Param file for a docfile-based projection /proj_doc.param SeeFileFormats#Document_Files for a the description of the angle file	Main.RafaelNunezRamirez	04 Jan 2008 - 12:04

http://xmipp.cnb.uam.es/twiki/bin/view/Xmipp/FileFormats#Document_Files