// The following text is included in the main documentation page by doxygen
/*! \mainpage vil3d : 3D image library
* A set of classes to represent and manipulate 3D images
*
*
* The core class is vil3d_image_view<T> which gives a view of an image in memory.
* The only way to get at the pixel data in an image is through a vil3d_image_view<T>.
*
* The vil3d_image_view<T> represents a view of a multi-plane image of given type.
* A pointer is stored to the top-left pixel in the first plane of the image
* (top_left_ptr()) and integers indicating how to get to neighbours in
* the i (istep()), j (jstep()), k (kstep()) and plane (planestep()) directions.
*
*
* \subsection copying Copying
* Since the vil3d_image_view<T> is a `view' of the actual image data, copying one
* only copies the `view', not the image data itself - you get two views looking at
* the same chunk of memory.  Some cunning smart pointer stuff is used to ensure
* that the actual data remains as long as a valid view is looking at
* it.  (Note that this may not always be the case, since the view can be of
* a chunk of memory that the view does not have direct control of, such as a video
* buffer). This view copying will work between different types of view
* if it is possible to reconfigure the view very cheaply.
* If you wish to copy the image data itself, then use the vil3d_copy_deep(src_im)
* function. This copies the raw data into a newly created space, and returns
* a new view of it.  Alternatively, use the method dest_im.deep_copy(src_im),
* or the function vil3d_copy_reformat(src_im, dest_im).
*
*
* Example of loading, copying then processing:
* \verbatim
vil3d_image_view<vxl_byte> image;
image = vil3d_load("test_image.jpg");
vil3d_image_view<vxl_byte> image2 = vil3d_copy_deep(image);
my_invert_image(image2);
vil3d_save(image2,"output_image.jpg");
\endverbatim
*
* Example of creating an image in memory
* \verbatim
unsigned ni=256;
unsigned nj=256;
unsigned nk=256;
unsigned nplanes=3;
vil3d_image_view<vxl_byte> image(ni,nj,nk,nplanes);
for (unsigned p=0;p<nplanes;++p)
  for (unsigned k=0;k<nk;++k)
    for (unsigned j=0;j<nj;++j)
      for (unsigned i=0;i<ni;++i)
        image(i,j,k,p) = vxl_byte(i+j+k+p);
\endverbatim
*
* Example of creating an image in memory, using pointer arithmetic
* \verbatim
  unsigned ni=256;
  unsigned nj=256;
  unsigned nk=256;
  unsigned nplanes=3;
  vil3d_image_view<vxl_byte> image(ni,nj,nk,nplanes);
  vxl_byte* plane = image.top_left_ptr();
  for (unsigned p=0;p<nplanes;++p,plane += image.planestep())
  {
    vxl_byte* slice = plane;
    for (unsigned k=0;k<nk;++k,slice += image.kstep())
    {
      vxl_byte* row = slice;
      for (unsigned j=0;j<nj;++j,row += image.jstep())
      {
        vxl_byte* pixel = row;
        for (unsigned i=0;i<ni;++i,pixel+=image.istep())
          *pixel = vxl_byte(i+10*j+3*k+100*p);
      }
    }
  }
\endverbatim
*
* \subsection resize Resizing
* When one resizes (using set_size) a vil3d_image_view<T> the view disconnects from the data
* (which may then be deleted if no other views are connected), allocates a new
* chunk of memory for the new image and sets the view to look at it.
*
* Note that if the set_size does not change the image size, then nothing is done
* and the view remains unchanged.
*
* \subsection view_manipulation Manipulating Views
* There are a variety of ways one can view the same data, allowing one to appear
* to change the data simply by changing ones view of it.
*
* For instance,
* - vil3d_crop : Create sub-image
* - vil3d_plane : Get plane of image
* - vil3d_slice_ij : Get 2D image which is a slice in i-j of a 3D image
* - vil3d_slice_jk : Get 2D image which is a slice in j-k of a 3D image
* - vil3d_slice_ki : Get 2D image which is a slice in k-i of a 3D image
* - (see also vil3d_slice_ji,vil3d_slice_kj,vil3d_slice_ik)
*
* \subsection utility_fns Utility Functions
* A variety of useful functions are provided:
* - vil3d_threshold_above(src_im,dest_im,t)
* - vil3d_threshold_below(src_im,dest_im,t)
* - vil3d_threshold_inside(src_im,dest_im,tlo,thi)
* - vil3d_threshold_outside(src_im,dest_im,tlo,thi)
* - vil3d_grad_1x3(...)  : Compute gradients in 3D using (-1 0 1) filter
* - vil3d_grad_3x3x3     : Compute gradients using Sobel like 3x3x3 filter
* - vil3d_smooth_121     : Smooth using 1-2-1 shape filter
* - vil3d_quad_distance_function : Cunning square distance filtering
* - vil3d_distance_function : Efficient distance function computation
*
* Morphological functions  (using vil3d_structuring_element)
* - vil3d_binary_erode
* - vil3d_binary_dilate
* - vil3d_binary_opening
* - vil3d_binary_closing
*
*
*/
