Volumetric data formats supported by SBA Composer are:

- Nifti1 (.nii, .nii.gz; https://nifti.nimh.nih.gov/nifti-1/)
- NRRD (.nrrd; http://teem.sourceforge.net/nrrd)
- ITK MetaImage (.mha, .zip; https://itk.org/Wiki/ITK/MetaIO/Documentation#MetaImage)
- Freesurfer (.mgh, .mgz; https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat)
- (experimental: MINC-2 (.minc; https://en.wikibooks.org/wiki/MINC/SoftwareDevelopment/MINC2.0_File_Format_Reference))
- TIFF image stack (.tiff; https://www.adobe.io/open/standards/TIFF.html)

From every supported volume file format we can extract at least the following:

- A 3-dimensional array that contains the image voxels (each having 1 or more channels)
- An augmented linear transformation matrix that affinely transforms (i,j,k)-voxel indices to real-world physical coordinates.

Let's call the augmented (4x4) linear transformation matrix `A`

.
What we need to know in addition to place this data in atlas space is:

- the name of the atlas that the image is registered to
- the anatomical orientation of the brain before applying the affine transform
- the length units of the physical space
- the choice of origin of the physical space, specified as the name of a landmark. Each atlas defines a set of landmarks for this purpose.

Part of this information is available in the volume file, but it is represented differently in each file format,
and it is often wrong or left out. In Nifti files for example, the orientation of the physical space is required to be RAS,
and the units are specified in the `xyzt_units`

field. The choice of origin cannot be specified at all. In practice we often find that the orientation is not RAS, and/or that the `xyzt_units`

field is not set.

We deal with this issue in several ways. For manually imported files, the user is presented with a dialog in which our best guess for the missing information can be adjusted. For automated imports, adjusted values can be specified via the 'brain addressing system' (BAS) meta data. In either case, we assume for the moment that the data fits the atlas in which the user tries to import the file.

Obtaining the best guess starts with decomposing the matrix `A`

into the product of four matrices:
`A = T R S Q`

, where

- T is a translation matrix, consisting of a unit diagonal and a translation vector in its fourth column
- R is an orthonormal rotation matrix
- S is a scaling matrix, with scaling/mirroring factors on its diagonal
- Q is the orthonormal 'scale-orientation matrix': the rotation to be applied before scaling.

If we assume that R indeed rotates the data to RAS orientation (or for non-Nifti1 files, the specified orientation),
then we can apply the inverse rotation to find the orientation axes that align best with the brain in its original space.
We then define a matrix R* that re-orients data from these orientation axes to RAS, and use it to find the 'remainder matrix' Z:

`A = T R* S Z => Z = inv(T R* S) A`

, where

- R* is the rotation matrix that reorients the data from its original orientation to RAS. It uses only axis flips and multiples-of-90-degree rotations.
- Z is the 'remainder' matrix that contains all components of A that cannot be represented by translation, re-orientation and scaling.

When either the user or the BAS meta data overrides the detected orientation, scaling and/or origin landmark, then A is recomputed by constructing T, R* and S from the new values, while keeping Z as is.

This is one of the most confusing aspects of image alignment. In the ideal world it is very simple. SBA Composer defines for each supported atlas an *enclosing box* that consists of three pairs of values that contain the minimum and maximum coordinate along each anatomical axis. The origin of the real-world space is defined as the point (0,0,0) in this enclosing box. The confusion arises due to the fact that SBA Composer makes a particular choice on the meaning of the point (0,0,0), while a dataset that is said to be aligned to the atlas may have a different idea of what the point (0,0,0) represents. The most common case is that one of the eight corners of the enclosing box acts as the origin, in particular the corner that corresponds to voxel (0,0,0) of the untransformed image. Other common choices are the center of the enclosing box, a stereotaxic landmark like bregma or interaural, or a point that marks an easily identifyable structure like anterior commissure.
To deal with this, SBA Composer defines for each atlas a set of landmarks that can be used as the origin. The landmarks 'zero' and 'center' are always defined and refer to point (0,0,0) and the center of the enclosing box, respectively. The corner landmark is also defined for all atlases and represents the corner of the enclosing box that opposes the anatomical orientation of the untransformed image (i.e. closest to the first voxel of the image). In addition, a list of atlas-specific landmarks is defined as a list of key-value pairs. The landmark that is selected to represent the origin is called *origin landmark*.

None of the file formats caters for specifying the choice of origin, and this is one of the reasons that we developed the BAS supplementary meta data scheme. When SBA Composer imports an image, it derives the origin landmark from either the file import dialog or from the BAS meta data. In absence of these, it assumes the 'corner' landmark if the affine transformation has no translation component. Otherwise, the 'zero' landmark is chosen. Once the origin landmark of the imported data is known, SBA Composer adds a translation to the affine transformation to align the data with the default atlas origin.

Notes to obtain voxel-perfect alignments:

- Voxel indices start from 0.
- The value of voxel (i,j,k) applies to the center of the voxel. It covers the area that starts at (i-0.5,j-0.5,k-0.5) and ends at (i+0.5,j+0.5,k+0.5)
- For an atlas that is defined by means of an image volume, and for which the affine transformation does not involve any oblique angles, the enclosing box is computed by taking the real-world coordinate of voxel (-0.5,-0.5,-0.5) as one corner of the box and the real-world coordinate of voxel ((n
_{i}-1)+0.5, (n_{j}-1)+0.5 and ((n_{k}-1)+0.5) as the other corner, where n_{i}, n_{j}and n_{k}are the number of voxels in each dimension.

Two-dimensional image data formats supported by SBA Composer are:

- PNG (.png; https://en.wikipedia.org/wiki/Portable_Network_Graphics)
- JPEG (.jpg; https://en.wikipedia.org/wiki/JPEG)
- GIF (.gif; https://en.wikipedia.org/wiki/GIF)
- TIFF single image (.tiff; https://www.adobe.io/open/standards/TIFF.html)

We treat 2d-images as 3d-volumes with a cardinality of 1 in the 3rd dimension. Note that for two-dimensional images, there is no reasonable way to derive from the file contents what is their anatomical orientation and and origin; the best we can hope for is that the pixel resolution is specified. The other properties have to be specified in the dialog or via BAS meta data.