## Geometry and Conventions

Bsoft deals with real space objects, whether they are densities (encoded in images) or molecular structures. Understanding the conventions adopted in Bsoft is important to doing image and molecular processing effectively.

## Coordinate system

Orthogonal/Cartesian (exceptions are periodic cases such as crystals or helices, and spherical or cylindrical coordinate systems).

Right-handed (implicitly defining a right-handed rotation convention).

Default view is down the z-axis (vector {0,0,1}, with z values decreasing with distance from the viewer.

The use of an orthogonal coordinate system may seem obvious, but non-orthogonal systems are used in fields such as crystallography, where certain mathematical operations are simplified by using non-orthogonal coordinate systems. Other alternatives include spherical and cylindrical coordinate systems. In the absence of mathematical utility, the simplest choice is an orthogonal or Cartesian system. The options of right-handed and left-handed coordinate systems are equivalent, with the choice going to the most commonly used one. The right-handed rotation implicit in a right-handed coordinate system is defined as a clockwise rotation around an axis, with the viewer looking in the positive direction of the axis. There are an infinite number of possibilities for the default view. Defining one of the major axes of the coordinate system as the default view direction, and placing the other two axes in vertical and horizontal directions, offers a finite number of possibilities. Two such views are common, both using the z-axis, but in opposite directions, and placing the x-axis horizontally and the y-axis vertically. The first convention views space in the positive z direction, i.e., z values increase with distance from the viewer (up the axis {0,0,1}). This convention is consistent with conventions in text and the arrangement of pixels on a computer monitor, i.e., start in the top-left corner and read row-by-row. The second convention views space in the negative z direction, which is a 180 degree rotation around the x-axis with respect to the first viewing convention (thus down the axis {0,0,1}). The worth of this convention is that it orients the x and y axes in the same way as one would do to plot a curve on a graph. Mathematical operations therefore become easier to understand from the user's point of view.

## Discretization/digitization/sampling of space

Independent sampling intervals along all the major axes are always defined {unit_x, unit_y, unit_z}.

The origin of any reference object is always considered to be {0,0,0} in real space.

The sampling unit is angstrom/voxel edge length.

The origin of this object within the image is therefore given as the location in voxel units, so that the real space coordinates in angstroms are always given by: real_x = ( x - origin_x ) * unit_x.

Independent sampling intervals are supported because assumptions such as isotropic sampling are restrictive and does not allow a sensible treatment of cases where for instance the z-direction is not as well sampled as the other directions.

## Rotations and views

The direction of rotations is given as a change in the viewing orientation with respect to the scene or object coordinate frame.

The unit vector describing the viewing orientation is related to the reference vector as: view = R * ref_view, where the ref_view = {0,0,1}. Additionally, the rotation angle around the view vector needs to be given.

The Euler angles defined as R(psi,theta,phi) = R(psi)*R(theta)*R(phi) with the individual angles taken around the z-, y- and z-axes, respectively, are related to the view vector and rotation angle around that vector as:

phi = arctan(view_y/view_x)

theta = arccos(view_z)

psi = angle - phi

Given Euler angles, the view vector and rotation angle is calculated as:

view_x = cos(phi) * sin(theta)

view_y = sin(phi) * sin(theta)

view_z = cos(theta)

angle = psi + phi

All calculations are passed through quaternion intermediates to avoid numerical instabilities in using Euler angles directly.

## Origin: Placement of objects

The origin of objects is always related to whatever symmetry it has:

An object with any form of symmetry is oriented such that a symmetry axis is parallel to the z-axis.

The origin is defined as the point where several symmetry axes intersect, expressed as the offset from the first pixel or voxel in the image.

### Point group symmetry

A symmetry axis lies on the z-axis in all cases, in most it is the major symmetry axis.

The origin is defined as the point in the image grid where symmetry axes intersect and has pixel or voxel units.

Schoenflies notation is used to identify point groups.

Symmetry | Notation | Origin | Orientation |
---|---|---|---|

Asymmetric | C1 | User-defined | user-defined |

Cyclic | C<n> | On symmetry axis | n-fold axis on z-axis |

Dihedral | D<n> | Intersection of symmetry axes | n-fold axis on z-axis, 2-fold axis on x-axis |

Tetrahedral | T | Intersection of symmetry axes | 2-fold axes on x, y, and z-axes |

Octahedral/Cubic | O | Intersection of symmetry axes | 4-fold axes on x, y, and z-axes |

Icosahedral/Dodecahedral | I | Intersection of symmetry axes | 2-fold axes on x, y, and z-axes, front 5-fold axes in yz plane |

where <n> is the symmetry order of the major axis of the cyclic and dihedral point groups.

Icosahedral symmetry have two commonly used orientations: The front most 5-fold axes may lie in the yz plane (consistent with X-ray crystallographic convention), or they may lie in the xz plane (consistent with some EM packages, notably PFT and EM3DR). The first is the preferable orientation, indicated by the symbol I, while the second is 90 degrees rotated from the first and indicated by I90.

### Helical symmetry

Helical symmetry is indicated by up to five parts:

Rise per asymmetric unit (translation along the helical axis oriented on the z-axis)

Rotation angle around the helical axis per asymmetric unit

Presence of a dyad axis (perpendicular to the helical axis and oriented on the x-axis)

Cyclic symmetry around the helical axis

Presence of seam and shift along the seam

The notation is: H<rise>,<angle>,<dyad>,<n>,<seam>

### Crystallographic symmetry

Schoenflies notation and International Table numbers are used to identify space groups.