Some notes about the coordinate systems
=======================================

Different systems
-----------------

* "World" coordinates refer to (x,y,z) positions, typically expressed
  in millimeters (according to the DICOM conventions), which allows to
  define volumes and 3D cutting planes.

  As explained below, those coordinates actually correspond to
  "patient" coordinates if rendering DICOM images.

  The "world" coordinates are *not* used by the Stone Web viewer,
  because the latter is a 2D application.

* "Scene" coordinates refer to (x,y) positions, typically expressed in
  millimeters (as a byproduct of world coordinates), which allows to
  define the 2D geometric elements that are part of the scene, and
  Y-axis pointing downward.

* "Canvas" coordinates refer to (x,y) subpixel positions that will be
  blitted by a compositor onto a drawing canvas. The units are
  floating-point pixels, with (0,0) corresponding to the center of the
  display surface, and Y-axis pointing downward. The "canvas"
  coordinates modify the "scene" coordinates according the zoom/pan
  specified by the user.

* "Pixels" coordinates refer to standard integer (x,y) coordinates of
  the surface in memory. (0,0) is the top-left pixel.


Relations between 2D and 3D
---------------------------

* The 3D coordinates are expressed in the PATIENT system, *not* the
  "gantry" coordinates. As a consequence, the tags "Image Position
  Patient" (0020,0032) and "Image Orientation Patient" (0020,0037)
  describe the 3D geometry of a slice.

* The tag "Patient Position" (0018,5100) could be used to convert from
  patient coordinates to gantry coordinates, but this would be useful
  to device manufacturers, whereas Stone primarly deals with users of
  modalities.

* The "Image Position Patient" gives the 3D coordinates of the CENTER
  of the top-left voxel of slice.

* In 2D compositors, the origin of a texture corresponds to the CORNER
  of the top-left pixel of the texture (*not* to the center of this
  pixel). Roughly speaking, the operation "floor()" must be applied to
  move from canvas coordinates (floating-point numbers) to pixel
  coordinates in the image buffer (integer numbers).

* The classes deriving from "IVolumeSlicer" must pay to attention to
  convert from centers of 3D voxels to bounding boxes of 2D pixels.