Xmipp Conventions


Euler Angles
Filenames
Logical access
Image center
Physical access
Here you are the main conventions and design choices selected in the Xmipp development. Some of them as the filenames are not crucial for the Xmipp development, but others are of high relevant importance in the design of future algorithms as could be the Euler angles choice and the physycal or logical access to multidimensional arrays.
 


Euler Angles

Any space rotation can be expressed as a combination of 3 rotations around given axes, but not any 3 rotations. Euler showed that there are only a few combinations of axes such that you can express any rotation.
Graphical Interpretation
To know more about Euler angles
To know even more
Back to the beginning

Filenames

In general, Xmipp can manage any Filename you can think of. However, there are some ideas that could help you to organize your data, and which might tell you more about the file only by its name. We could divide files in several classes:
 
Data type  Suggested extension  Suggested filenames 
Images  .xmp  g1ta00001.xmp 
Volumes  .vol  art00001.vol, wbp00001.vol, sirt00001.vol 
Volumes  .xmp  art00001.xmp, wbp00001.xmp, sirt00001.xmp 
Selection Files  .sel  g1t.sel 
Document Files  .xmp  angles.xmp 
 
The class FileName assumes a filename structure as in g1ta00001.xmp, ie, a filename root (g1ta), a number (00001) and an extension (xmp) ("<root><number>.<extension>"); although it can also manage names as g1ta00001 or g1ta00001.xmp.bak. To mantain compatibility with Spider it is required that image numbers start at 1, and if possible that all images have got correlative numbers, but these last conditions are not compulsory within Xmipp, it's just for compatibility with Spider.

Notice also that Spider requires all data files (volumes, images, document files, ...) to have the same extension. You might prefer this other convention if you don't want to make copies of the files, or to have to rename the files before entering in Spider.

Back to the beginning


Logical access

The basic multidimensional classes implemented in this library admit two kinds of access: physical and logical. The physical positions are those indexes of the pixel inside the C matrix. Just an example, suppose we have a 65x65 image, then the physical indexes range from 0 to 64, being I[0][0] (if this could be written) the first pixel stored. However, we might be interested in writing procedures in a more mathematical fashion trying to access negative indexes (or even fractional ones!! See ImageOver) This conception is very useful when you want to represent a discretized plane whose origin is at the center of the image, for instance. So, you can express in a simpler way your algorithms without having to make a by hand translation from the logical positions to the physical ones.

Suppose now that we are interested to have the logical origin at the center of the image 65x65, ie, at physical position [32][32]. This would mean that the physical position [0][0] is now at logical position (-32,-32), and the logical indexes range now from -32 to 32.

This logical index defintion is done by means of the starting indexes of matrices (see matrix2D) where you can define which logical position is occupying the first physical pixel, ie,
I().startingY()=-32;
I().startingX()=-32;

From now on you can start to access to logical positions even with negative indexes. The usual way of establishing loops inside this logical images is by using the starting and finishing information of its axes
 

    Image I(65,65);
    I().init_random();
    float sum=0;
    for (int i=STARTINGY(I()); i<=FINISHINGY(I()); i++)
        for (int j=STARTINGX(I()); j<=FINISHINGX(I()); j++) {
               sum += I(i,j);
            // sum += IMGPIXEL(i,j);
        }
Although the previous example has been used using the class Image, the logical access rely on the classes matrix1D, matrix2D, and matrix3D, and all the concepts explained for images are extensible for vectors and volumes. The related functions are STARTINGX, STARTINGY, STARTINGZ, FINISHINGX, FINISHINGY, FINISHINGZ, IMGPIXEL, DIRECT_IMGPIXEL, VOLVOXEL, DIRECT_VOLVOXEL, VEC_ELEM, MAT_ELEM, VOL_ELEM, DIRECT_VEC_ELEM, DIRECT_MAT_ELEM, DIRECT_VOL_ELEM

Pay attention to the index order when pointing to a pixel, first you have to give the most outer coordinate (which is the less varying one in the actual implementation), and then increase the coordinate. For volumes the usual way of making a loop is

    Volume V(65,65,65);
    V().init_random();
    float sum=0;
    for (int k=STARTINGZ(V()); k<=FINISHINGZ(V()); k++)
       for (int i=STARTINGY(I()); i<=FINISHINGY(I()); i++)
           for (int j=STARTINGX(I()); j<=FINISHINGX(I()); j++) {
               sum +=V(k,i,j);
        }
Notice that if you don't modify the origin of the multidimensional array then the physical and logical accesses are the same.

Back to the beginning 


Image center
There is a special case for the logical access when the origin is set just at the center of the image, volume or vector. There are several definitions of center of the image, the one used here is the physical position ((int)ydim/2, (int)xdim/2). This is the same convention used in Spider and has been chosen to mantain compatibility with that package. Remember that in C (int) takes the integer part of the number, for example, for 2.3 and 2.8 the integer part is 2, while for -2.3 and -2.8 the integer part is -2.

This means that for images with an even dimension, the center will be "displaced" in that direction. Let's have a look on the following two diagrams of cell indexes.

3x3 matrix with its center 4x4 matrix with its center

For volumes the idea is more or less the same. The benefit from this origin choice is that the origin is always at a pixel point, but as a disadvantage the volume might not be symmetrical with respect to the center.

Back to the beginning 


Physical access

Regarding the physical origins and axis directions, the convention used is the following

For Vectors: (0) index at the left of the vector

    Origin for vectors
For Matrices: (0,0) index at the top-left corner of the matrix
   Origin for matrices
For Volumes: (0,0,0) index at the rear-top-left corner of the volume
   Origin for volumes
Physical loops are based on a different set of functions than logical ones. For instance the former sum of image values could be rewritten in a physical fashion (but remember always that the logical access is preferred).

    Image I(65,65);
    I().init_random();
    float sum=0;
    for (int i=0; i<=YSIZE(I()); i++)
        for (int j=0; j<=XSIZE(I()); j++) {
            sum +=DIRECT_IMGPIXEL(I,i,j);
        }

Back to the beginning


xmipp_logo.gif (4792 bytes)