intro-02.rst

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 an :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/ electron crystallography and atomic force microscopy are supported in addition to several general purpose image formats. See :doc:`supported file formats <io/image_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

map = io.LoadImage('/path/to/examples/code_fragments/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:

print map.GetPixelSampling(), map.GetSize()

We can see that the sampling is set to 1.0 Angstrom in all three dimensions. The loaded map is an instance of :class:`~ost.img.ImageHandle`, a class to represent images in one, two and three 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.

from ost.img import alg

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

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

The filtered map is stored in a new variable called 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:

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:

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.