Introduction to the :mod:`~ost.img` Module
================================================================================

For the course of this tutorial, we assume that you have :ref:`DNG up and running<start-dng>`.


Loading Images and Density Maps
--------------------------------------------------------------------------------

Openstructure features a :mod:`~ost.img` module that is dedicated to the 
manipulation of images/density maps. The images or density maps can either be 
one-, two- or three-dimensional. The most common formats used in X-ray and 
electron  crystallography and atomic force microscope are supported in addition 
to several general purpose image formats. See `supported file formats` for 
details. The :mod:`~ost.img` module was originally developed as part of the 
Image Processing Library & Toolbox IPLT. More documentation and examples can 
also be found on the `IPLT website <http://www.iplt.org>`_.

To load a density map, type

.. code-block:: python

   map=io.LoadImage('/path/to/examples/map/1ppt.map')

This will load the fragment density map from the specified file 'fragment.map' 
and store the result in map. 

Now let's inspect what we just loaded:

.. code-block:: python

  print map.GetPixelSampling(), map.GetSize()
    
We can see that the sampling is set to 1.0 Angstroems in all three dimensions. The loaded map is an instance of :class:`~ost.img.ImageHandle`, a class to represent images in 1, 2 and 3 dimensions.

Manipulating Images and Density Maps
--------------------------------------------------------------------------------

The algorithms used for manipulation of an image are found in the 
:mod:`img.alg <ost.img.alg>` module. Therefore before using an algorithm we 
first have to import the :mod:`img.alg <ost.img.alg>` module.

.. code-block:: python

  from ost.img import alg


The :mod:`img.alg <ost.img.alg>` module provides a wide range of algorithm to 
manipulate image data. Here for example we use a LowPassFilter to restrict the 
resolution of the density map to frequencies lower than a treshold.

.. code-block:: python

   map_filtered=map.Apply(alg.LowPassFilter(3.0))

The filtered map is stored in a new variable called `fragment_map_filtered`. A complete list of algorithms is available on the  :doc:`img/alg/alg` page.


Displaying Images and Density Maps
--------------------------------------------------------------------------------

Now that we have a filtered map it's time to have a look at it. There are 
fundamentally two ways to visualize 3-dimensional density maps. One is by 
drawing isocontour surfaces. These are conceptually similar to contour lines 
used in cartography: every point on an isosurface has the same density value. 
Isosurfaces are easy to create in OpenStructure:

.. code-block:: python

   go=gfx.MapIso("filtered", map_filtered,0.5)
   scene.Add(go)

The other way to visualize a 3-dimensional map is by showing one 2-dimensional 
density slice at a time, allowing the user to move through the slices. In 
OpenStructure this is achieved using a DataViewer). 
A DataViewer showing the filtered map is created using the following command:

.. code-block:: python

  gui.CreateDataViewer(map_filtered)

This command displays a panel showing one slice of the density map lying on a 
particular (x,y) plane in the coordinate reference system.
The `z` and `x` keys can be used to move to slices lying at a lower or higher 
coordinate along the `z` axis, allowing the examination of
the full 3-dimensional volume.

A more detailed explanation of the :mod:`~ost.img` module can be found in the 
tutorial section for :mod:`~ost.img`.


Continue with :doc:`part three <intro-03>` of the tutorial.