Editing STIR FAQ (section)

== How does the STIR coordinate system work (e.g. for generate_image) ==
Details on orientation etc are given in the STIR Developer's guide. Here we attempt to give some
more info on the origin and how this works for images. This is somewhat complicated because the
relation with the scanner needs to be considered.

STIR coordinates are currently related to the scanner, i.e. not to the patient (as in DICOM).
A peculiarity is that STIR coordinates are ordered (z,y,x) (with z along the scanner axis,
y vertical and x horizontal).

=== Images ===
Currently, STIR does not support rotated coordinate systems. Therefore, we only need to give the 
location of the origin. Inside STIR, this origin can be shifted around using the offset. However,
we will first assume that you did not do this ("zero offset").

:'''For an image with zero offset, the origin is assumed to coincide with the centre of the first plane.'''

Let's say you want to use '''generate_image''' to create a cylinder in
the centre of the (3D) image (and we use zero offsets for the image and an odd-number of pixels in x,y, see below). 
Then we need to compute the STIR coordinates of the
centre. Given that (0,0,0) is at center of the first plane, the
center of the last plane is at ((num_planes-1)*z_voxel_size,0,0). And
therefore, the middle of the image is at
((num_planes-1)*z_voxel_size/2,0,0). 

There's a small complication. When you have an odd number of voxels in x (or
y), the 0 coordinate is indeed in the centre of the image. But if you have
an even number, it's actually half a pixel off. This convention is probably different from other 
programs, therefore

:'''We recommend to use odd number of voxels in all 3 directions'''.

For an existing image, you can use the '''list_image_info''' utility to get some information 
on geometry.

When developing code in STIR, you want to use the functions
<code>DiscretisedDensity::get_physical_coordinates_for_indices()</code> etc to find out what the location
of the centre of a particular voxel is.

=== Projection data ===
This coordinate system is currently never exposed to the user, but only the developers. Functions like
<code>ProjDataInfo::get_m()</code> use a coordinate system where (0,0,0) is the centre of the (gantry of the) scanner.
There's unfortunately also a set of obsolete function (which will be removed) that use a coordinate system 
where (0,0,0) in the centre of the first ring of the scanner (e.g. <code>find_cartesian_coordinates_of_detection</code>).

For all "segments" (see the STIR glossary), the data is assumed to be centred to the scanner (taking their
average ring different into account).

=== Combining images and projection data ===
When you are forward projecting an image or reconstructing projection, you need to know what the relation
between the 2 conventions is. Unfortunately, STIR does not support different "bed positions" yet. For
backwards compatibility, the following convention is used.

:'''For images with zero offset, the middle of the scanner is assumed to coincide with the middle plane of the image.'''

So, for the generate_image example above, the cylinder would be located in the centre of the scanner.

:<strong>WARNING: the combination of these conventions means that if you change the number of planes in the image, you also have to change the "origin" of the shape such that it would forward project into the same projection data.</strong>

You can see this clearly from the formulas used in the generate_image example above.

However, this convention is confusing and therefore might be changed in the future. 
Together with a current limitation of the STIR projectors, this leads us to 
the following:

:'''We recommend that you use images which have  2*(num_rings-1) planes with z-voxel-size equal to ring_spacing/2.'''

=== Using images with non-zero offset ===
It is possible to create images where a different origin is used. How you do this depends on the file format, but for
Interfile, this can be done by changing the <tt>first pixel offset (mm)</tt> keywords. This is not recommended of course.

The only STIR utility that creates images with non-zero offset is '''zoom_image'''. It is designed such that if
you specify '''zero offsets and all image sizes are odd''', the object will remain in the same physical location compared to the scanner.
Its usage is
<pre>
zoom_image <output filename> <input filename> \
   sizexy [zoomxy [offset_in_mm_x [offset_in_mm_y \
     [sizez [zoomz [offset_in_mm_z]]]]]]]
</pre>
If you need to zoom an image (e.g. for estimate_scatter), it is therefore highly recommended to use zoom_image
(as opposed to trying to figure out yourself where the objects will go).

As a developer, you can create images with non-zero offset using the <code>VoxelsOnCartesianGrid</code> constructor with non-zero origin. This is '''not recommended''' however for future compatibility. The <code>stir::zoom_image</code> function should be safe.